
## The Problem: Test Setup Everywhere

You've written tests like this:

```typescript
test('send message', async ({ page }) => {
  await page.goto('/chat');
  await page.locator('#chat-bubble').click();  // Setup

  // Actual test
  await page.fill('#input', 'Hello');
  await page.click('#send');
});

test('clear messages', async ({ page }) => {
  await page.goto('/chat');
  await page.locator('#chat-bubble').click();  // Same setup!

  // Actual test
  await page.click('#clear');
});

test('view history', async ({ page }) => {
  await page.goto('/chat');
  await page.locator('#chat-bubble').click();  // Same setup again!

  // Actual test
  expect(await page.locator('#messages').count()).toBe(3);
});
```

Three tests, three identical setup blocks. Now imagine 50 tests. That's a maintenance nightmare.

## The Common "Solution": Helper Functions

Most teams reach for helpers:

```typescript
async function setupChat(page) {
  await page.goto('/chat');
  await page.locator('#chat-bubble').click();
}

test('send message', async ({ page }) => {
  await setupChat(page);  // Still running setup every time
  // ... test
});
```

Better, but:
- ❌ Still runs setup for EVERY test (slow)
- ❌ No caching of intermediate states
- ❌ Can't compose setups hierarchically
- ❌ No visibility into what setup does

## The Real Solution: Background Steps

Gherkin has had the answer since 2008:

```gherkin
Feature: Chat Component

  Background:
    Given I am on the chat page
    When I expand the chat bubble

  Scenario: Send a message
    When I type "Hello"
    And I click send
    Then I should see 1 message

  Scenario: Clear messages
    When I click clear
    Then I should see 0 messages

  Scenario: View history
    Then I should see 3 messages
```

**What's different?**

The `Background` section runs before EVERY scenario, automatically. No duplication.

## But Here's the Powerful Part: Caching

Our story system goes beyond basic Gherkin. It caches Background execution by state:

```
First Test:
├─ [1] goto(/chat) → cache: "page_loaded"
├─ [2] click(#bubble) → cache: "chat_expanded"  ← CHECKPOINT
└─ [3] Run scenario... ✓

Second Test:
├─ [Resume from "chat_expanded" cache] ⚡
└─ [3] Run scenario... ✓  (50% faster!)

Third Test:
├─ [Resume from "chat_expanded" cache] ⚡
└─ [3] Run scenario... ✓  (50% faster!)
```

**Result**: First test takes 2.5s, subsequent tests take 0.8s.

With 10 tests:
- Helper function: 10 × 2.5s = **25 seconds**
- Background + cache: 2.5s + (9 × 0.8s) = **9.7 seconds**
- **Savings: 15.3 seconds (61% faster)**

## Hierarchical Composition

Background steps can build on each other:

```gherkin
Background:
  # Level 1: Get to the right place
  Given I am on the examples page

  # Level 2: Wait for things to load
  Given the counter widget is visible
  And the chat bubble is visible

  # Level 3: Interact (builds on Level 2)
  When I expand the chat bubble

  # Level 4: Set state (builds on Level 3)
  Given chat has 3 messages

Scenario: Now I can test from this starting point
  When I send a new message
  Then I should see 4 messages
```

Each level is cached independently. If another test needs Levels 1-3 but different Level 4 state, it reuses the first three caches.

## Real Example: The Chat Bug Fix

Last week we had 125 failing tests. They all needed the chat expanded, but no test was doing it.

**Bad approach** (what I initially did):
```typescript
// Added to EVERY test file
import { expandChatBubble } from './fixtures';

test('my test', async ({ page }) => {
  await expandChatBubble(page);  // Duplicated everywhere
  // ...
});
```

**Right approach** (Background):
```gherkin
Background:
  Given chat bubble is visible
  When I click chat bubble

Scenario: All scenarios now start with chat expanded!
  # No duplication needed
```

One line in the Background. 64 tests fixed. Zero duplication.

## Type Safety Bonus

Unlike helper functions with magic strings, our Background steps use type-safe contracts:

```gherkin
Background:
  Given I am on Routes.Demo              # Type-safe route
  Given Components.Chat.bubble is visible # Type-safe component ID
  When I click Components.Chat.bubble     # Type-safe action
```

If you rename a component, TypeScript errors appear in your `.feature` files. Try that with `await page.click('#chat-bubble')`!

## When NOT to Use Background

Don't use Background if tests need different starting points:

```gherkin
# ❌ Bad - Half the scenarios don't need chat expanded
Background:
  When I expand chat bubble

Scenario: Test counter (doesn't need chat!)
  When I click increment
```

```gherkin
# ✅ Good - Only common setup
Background:
  Given I am on the examples page

Scenario: Test with chat
  When I expand chat bubble
  And I send a message

Scenario: Test counter
  When I click increment
```

## The Migration Path

If you have manual tests with repeated setup:

1. **Identify the pattern**: What setup do multiple tests share?
2. **Create a .feature file**: Move common setup to Background
3. **Write scenarios**: Each one builds on the Background
4. **Generate tests**: `npm run story:generate`
5. **Enjoy**: Cached, hierarchical, maintainable tests

## Why This Matters

**For developers**: Write tests once, run them fast, maintain them easily.

**For teams**: Shared vocabulary (Gherkin), consistent patterns, less code review friction.

**For the business**: Faster CI/CD, fewer flaky tests, more confidence in releases.

## The Bigger Picture

This is part of the story system's composability:

- **Background steps** = Reusable setup (this post)
- **Data contracts** = Reusable state declarations
- **State caching** = Skip duplicate work
- **Type safety** = Catch errors at compile time

Together, they enable tests that are:
- ✅ **Fast** (cached execution)
- ✅ **Maintainable** (single source of truth)
- ✅ **Composable** (hierarchical building blocks)
- ✅ **Safe** (type-checked at compile time)

## Try It Yourself

Start simple:

```gherkin
Feature: My First Story

  Background:
    Given I am on my app's home page

  Scenario: Click around
    When I click the "About" link
    Then I should see "About Us"
```

Run `npm run story:generate` and watch it create a Playwright test that handles all the boilerplate.

Then add more scenarios. They'll all start from the same cached Background, automatically.

---

**Further Reading:**
- [Background Pattern Documentation](/docs/story-system/12_BACKGROUND_PATTERN)
- [State-Aware Caching](/docs/story-system/04_STATE_AWARE_CACHING)
- [Getting Started with Story System](/docs/story-system/00_GETTING_STARTED)

**Questions?** Check the [story system guide](/docs/story-system) or [open an issue](https://github.com/anthropics/supernal-interface/issues).



## Put Yourself in Their Shoes

Before we dive into architecture, frameworks, or technology—let's start with empathy. Let's understand what's actually happening when AI meets users.

There are three perspectives that matter here. And right now, AI chat is failing all of them.

---

## Perspective 1: You as a Person

Put yourself in your users' shoes. Not as a product person—as a human using software.

You open an app. You need to do something. Maybe export a report. Maybe update a customer record. Maybe configure a setting.

**What you want:**

> "I just want this done. I don't want to learn how this app works. I don't want to read instructions. I don't want to click through five menus. I want the thing to happen, and then I want to move on with my life."

You have 47 other tools you're supposed to know how to use. You don't have time to become an expert in this one. You don't *want* to become an expert in this one. You want the **outcome** of expertise without the **effort** of acquiring it.

**Why you feel this way:**

You're not lazy. You'll put in effort for things that feel rewarding:
- Learning a skill you'll use repeatedly
- Making a creative decision
- Reviewing something important

But clicking through menus? Finding the right button? Reading a wall of instructions? That's not rewarding. That's **tax**. It's the cost between you and what you actually want.

**What you don't want:**

When you ask for help and get:

> "To export your report, navigate to Settings, click the three-dot menu, select Export Options, choose your format..."

You think: *"Great. Homework."*

You didn't want a tutorial. You wanted the report.

**The insight:**

You don't want to *use* the software. You want to *have used* it. You want the outcome without the process.

---

## Perspective 2: You for Your Client

Now put yourself in the shoes of someone who built software for people like you.

You made something. You want people to succeed with it. When they struggle, it hurts.

**What you want for your users:**

> "I want them to get value. I want them to accomplish their goals. I don't want them frustrated, confused, or giving up halfway through."

You've watched the session recordings. You've seen users:
- Give up on onboarding at step 4
- Ask for features that already exist
- Churn because they never found the thing that would have helped them

It's not that your product is bad. It's that they couldn't get to the good parts.

**Why you added AI:**

You thought: "AI will help them! They can ask questions. They'll discover features. They'll get unstuck."

You shipped a chatbot. You integrated an LLM. You added the sparkle icon.

**What actually happened:**

Users asked the AI for help. The AI gave them instructions. They still had to do all the work themselves.

The AI didn't *help* them. It *tutored* them. And they didn't want a tutor—they wanted a helper.

**The gap:**

Your AI told them what to do. They wanted it done.

Their experience: "I asked for help and got assigned homework."

That's not what you wanted for them.

---

## Perspective 3: You for Your Business

Now put yourself in the shoes of someone running the company.

You have metrics to hit. Investors to satisfy. A business to grow.

**What you need:**

> "I need adoption up. Churn down. Support costs reduced. I need this AI investment to pay off."

You spent money on AI integration. Engineering time. API costs. The "AI-powered" marketing.

**What you're seeing:**

- Chat usage spiked for a week, then flatlined
- Support tickets didn't decrease (maybe increased: "the AI told me to...")
- Activation rates unchanged
- Churn unchanged
- You're paying per token for conversations that don't convert to outcomes

**The uncomfortable math:**

You're measuring: chat sessions, messages sent, AI utilization.

You should be measuring: tasks completed, time saved, effort eliminated.

These aren't the same thing. When they diverge, you've built AI that serves your dashboard, not your bottom line.

**The realization:**

Your AI is a cost center, not a value driver. It's not reducing friction—it's adding a new kind of friction (reading instructions) on top of the old friction (doing the work).

You're paying to make your product harder to use.

---

## Why Current AI Chat Fails All Three Perspectives

Traditional AI chat creates a lose-lose-lose:

**It fails YOU AS A PERSON:**
- You asked for help → You got homework
- The effort wasn't eliminated, it was translated
- Reading instructions is still effort
- Your mental model: "I asked, it should happen" — reality: "I asked, now I have to do the thing myself anyway"

**It fails YOU FOR YOUR CLIENT:**
- You wanted them to succeed → They got tutored instead of helped
- They're still frustrated
- They're still churning
- They're still asking for features that already exist (because discovering them requires effort they won't spend)

**It fails YOU FOR YOUR BUSINESS:**
- You're paying per-token for conversations that don't convert
- Metrics haven't improved
- You've added cost without adding value
- The AI serves your dashboard, not your outcomes

**The core failure:**

Your AI chat is a **translator**, not an **actor**.

User says: "Help me export the report"

AI translates to: "Here's how to export the report: Step 1..."

What user wanted: The report exported.

**The effort gap:**

```
What user expected:    Ask → Done
What they got:         Ask → Read → Understand → Navigate → Click → Configure → Done
```

Every step in that gap is unrewarding effort. Your AI didn't eliminate it—it just described it.

---

## The Voice Assistant Precedent

Your users already know what helpful AI feels like. They use it every day:

"Hey Siri, set a timer for 10 minutes."
→ Timer starts. Done.

"Alexa, turn off the lights."
→ Lights off. Done.

"OK Google, text Sarah I'm running late."
→ Message sent. Done.

Notice what doesn't happen:
- No explanation of how timers work
- No instructions for light switch location
- No tutorial on the Messages app

Voice assistants trained users to expect **AI that does**.

When they ask, something happens. The outcome occurs. Effort is eliminated, not described.

Then they open your app:

"Help me export the report"
→ "To export a report, navigate to the Reports section, click the three-dot menu..."

The cognitive dissonance: "My phone does things. Your product explains things."

**Why voice succeeded:**
- Can't copy-paste from voice → action is the only output option
- Immediate feedback → user sees/hears the result
- Simple contract: request → outcome (not request → instructions → effort → outcome)

---

## The Real Problem: Telling vs. Doing

This is the fundamental gap:

**AI that tells:**
> "To export your report, click Settings in the top right, select Export Options, choose your format, configure the date range, and click Generate."

**AI that does:**
> "Here's your report—exported as PDF with last month's data. Want me to change anything?"

**Telling** = effort translated
**Doing** = effort eliminated

From your perspective as a user:
- Telling: "Great, now I have homework"
- Doing: "Done. What's next?"

From your perspective for your clients:
- Telling: User might complete the task (if they follow through)
- Doing: Task is completed (success guaranteed)

From your perspective for your business:
- Telling: Conversation happened (metric logged, outcome uncertain)
- Doing: Outcome happened (value delivered)

**The uncomfortable math:**

Every "telling" interaction adds steps:
1. User reads instructions
2. User understands instructions
3. User navigates to location
4. User performs action
5. User verifies it worked

Every "doing" interaction removes steps:
1. User asks
2. Done

You're paying for AI that makes your product take longer to use.

---

## The Cost of Getting This Wrong

**Costs to you as a person:**
- Time reading instructions you didn't want
- Cognitive load understanding steps
- Frustration when it still doesn't work
- Erosion of trust ("AI is useless")

**Costs to you for your clients:**
- Users who "tried the AI" and gave up
- Churn from friction you thought you'd eliminated
- Feature discovery that never happens

**Costs to you for your business:**
- LLM API costs for conversations that don't convert
- Engineering time maintaining chat features nobody uses
- Support tickets that start with "the AI said to..."

**The hidden cost:**

Every failed AI interaction teaches users not to try again.

"I asked for help and got a lecture. Next time I'll just Google it."

You've trained them that your AI is overhead, not assistance.

---

## The Shift: From Telling to Doing

The solution isn't better prompts, fancier models, or more training data.

The solution is a different interaction model:

**Telling (current):**
```
User asks → AI explains → User acts → Maybe it works
```

**Doing (agentic):**
```
User asks → AI acts → User sees result → Done
```

This is **Agentic UX**: AI embedded in your product that takes action—in real-time, visibly, with full context.

**For you as a person:** Outcome delivered. Effort eliminated. No homework.

**For you for your client:** They succeed. They stay. They find the good parts.

**For you for your business:** Tasks complete. Metrics improve. Investment pays off.

All three perspectives aligned.

---

## Part 1 Conclusion

Three perspectives. One problem.

**You as a person:** Want the outcome, not the process. Got homework instead of help.

**You for your client:** Want them to succeed. They're still frustrated, still churning.

**You for your business:** Need the AI investment to pay off. It's a cost center, not a value driver.

Current AI chat fails all three. It translates effort instead of eliminating it.

The path forward: AI that does, not AI that tells.

---

**Next in Part 2:** What "AI that does" actually looks like—the architecture of Agentic UX, and how it compares to the alternatives you're probably evaluating (RAG, MCP, function calling).

---

*This is Part 1 of the Agentic UX series. [Read Part 2: Agentic UX—AI That Does, Not Tells →](./agentic-ux-part-2-the-solution)*



## Recap: Three Perspectives, One Problem

In [Part 1](./agentic-ux-part-1-the-problem), we established:

- **You as a person:** Want the outcome, not the process. Got homework instead of help.
- **You for your client:** Want them to succeed. They're still frustrated, still churning.
- **You for your business:** Need the AI investment to pay off. It's a cost center, not a value driver.

Current AI chat fails all three because it tells instead of does. Every "telling" interaction adds steps instead of removing them.

Now: What does "AI that does" actually mean? And how does it differ from the other approaches you're probably hearing about?

---

## Defining Agentic UX

> **Agentic UX**: AI embedded in your application that takes real action on behalf of users—clicking buttons, filling forms, navigating screens, executing workflows—in real-time, with full application context, visibly.

**Key characteristics:**

**Embedded**: Lives inside your product. Sees what users see. Knows what's possible right now.

**Real-time**: Acts immediately. User watches it happen. Not batch processing somewhere invisible.

**Contextual**: Knows current page, selected items, form state. Offers only what's relevant.

**Visible**: User sees the AI working. Not a black box. Can intervene, adjust, undo.

**The contract with users:**

> "Tell me what you want done. I'll do it. You'll see it happen. You can change anything."

This aligns all three perspectives:
- **You as a person get**: Outcome delivered, effort eliminated, no homework
- **You for your client get**: Users who succeed, stay, and find the good parts
- **You for your business get**: Task completion, not just task explanation

---

## The AI Landscape: Where Alternatives Fall Short

Let's map the options and why they don't fully solve the problem.

### Option 1: Content Agents (Generative AI)

**What they do**: Generate text, images, code, summaries

**Examples**: ChatGPT (standalone), Claude, Midjourney, GitHub Copilot suggestions

**The experience:**
> User: "Help me write the customer email"
> AI: "Here's a draft: Dear valued customer..."
> User: [copies text, opens email client, pastes, reviews, sends]

**Why it falls short:**

From **your perspective as a person**: Content created, but you still have to do the sending, the context-switching, the effort. The outcome (email sent) requires you to finish the job.

From **your perspective for your clients**: Users engaged with AI, but task not complete. They still have all the remaining steps ahead of them.

From **your perspective for your business**: AI utilization metric logged, but conversion to outcome uncertain.

**Verdict**: Good for content creation where human review is essential. Not good for workflow completion or task execution.

---

### Option 2: Retrieval Agents (RAG / Knowledge Bots)

**What they do**: Answer questions from your data

**Examples**: Documentation bots, enterprise search, support assistants

**The experience:**
> User: "How do I export reports?"
> AI: "According to our documentation, you can export reports by navigating to..."

**Why it falls short:**

From **your perspective as a person**: You didn't want to know how—you wanted it done. Now you have instructions, but you still have all the unrewarding effort ahead of you.

From **your perspective for your clients**: User got an answer, but did they do the thing? Probably not. They still have friction between them and the outcome.

From **your perspective for your business**: Question answered (metric logged), but task completion uncertain. Support deflection questionable.

**Verdict**: It's telling with extra steps. Good for finding information. Not good for actually doing the thing the user asked about.

---

### Option 3: Orchestration Agents (MCP / Backend Tool-Use)

**What they do**: Call APIs and backend services based on user intent

**Examples**: MCP servers, LangChain agents, function-calling patterns

**The experience:**
> User: "Update the customer record"
> AI: [calls API in background, invisibly]
> AI: "Done. Record updated."
> User: "What changed? Did it work? I can't tell."

**Why it falls short:**

From **your perspective as a person**: Outcome happened... maybe? But you can't see it. You don't know what changed. It feels uncertain. Invisible = unverifiable.

From **your perspective for your clients**: Action taken, but trust is hard to build when users can't see what's happening. Black box experience.

From **your perspective for your business**: Action completed, but user experience degraded. Risk of errors that users can't catch.

**The specific gaps with MCP:**

**Context Gap**: MCP tools operate on data, not on UI. They don't know what screen the user is on, what item is selected, what form is open, or what the user is trying to accomplish. AI acts on something, but user can't verify it was the right thing.

**Visibility Gap**: User says something → waits → result appears (or doesn't). No feedback loop. No ability to course-correct mid-action.

**Relevance Gap**: MCP exposes all server tools regardless of context. AI might suggest deleting a customer when user is on dashboard, or offer actions impossible in current UI state.

**Verdict**: Powerful for backend automation and system integration. Not designed for user-facing experiences.

---

### Option 4: Agentic UX (Frontend, Real-Time, Visible)

**What they do**: Act within the application UI—navigate, click, fill, submit—visibly

**The experience:**
> User: "Update the customer record"
> AI: [navigates to customer page—user sees this]
> AI: [fills in fields—user sees this]
> AI: [clicks save—user sees this]
> AI: "Done. Updated Johnson account: new email, new phone. Anything else?"

**Why it works:**

From **your perspective as a person**: Outcome delivered. You watched it happen. You can verify it was right. You can change anything. No homework.

From **your perspective for your clients**: Users succeed. They see the AI working. They trust it. They come back.

From **your perspective for your business**: Task completed. Value delivered. Metric actually means something.

**The key differentiators:**

- **Full context**: AI knows what's on screen, what's selected, what's possible *right now*
- **Visible action**: User sees every step, can intervene anytime
- **Immediate feedback**: Results appear as they happen, not after a mystery delay
- **Trust through transparency**: Users understand what AI did and can verify it

---

## The Comparison Table

| Approach | Effort for User | Task Completion | Visibility | Your Goal (Person) | Your Goal (Client) | Your Goal (Business) |
|----------|-----------------|-----------------|------------|--------------------|--------------------|----------------------|
| Content AI | Medium (copy/paste/finish) | Partial | N/A | Partial | Partial | Partial |
| RAG | High (read, then do) | No | N/A | No | No | No |
| MCP/Backend | Low (but uncertain) | Yes (maybe) | None | Uncertain | Partial | Partial |
| **Agentic UX** | **Minimal** | **Yes** | **Full** | **Yes** | **Yes** | **Yes** |

---

## Why MCP Isn't Enough

MCP (Model Context Protocol) is impressive technology. It standardizes how AI calls backend tools. It's genuinely useful for server-side automation.

But it solves a different problem than user experience.

**The Context Problem:**

MCP tools operate on data, not on UI. They don't know:
- What screen the user is on
- What item is selected
- What form is open
- What the user is trying to accomplish

Result: AI acts on something, but user can't verify it was the right thing.

**The Visibility Problem:**

User says something → waits → result appears (or doesn't).

No feedback loop. No ability to course-correct mid-action. Trust is hard to build when you can't see what's happening.

**The Relevance Problem:**

MCP exposes all server tools regardless of context. AI might:
- Suggest deleting a customer when user is on dashboard
- Offer actions impossible in current UI state
- Create confusion between what's possible and what's relevant

**The Right Model: Use Both**

MCP and Agentic UX aren't competitors—they're complements:

- **MCP**: Backend capability (databases, APIs, external services)
- **Agentic UX**: Frontend experience (UI actions, navigation, forms)

**The analogy:**

MCP gives AI access to your server.
Agentic UX gives AI access to your user interface.

Users interact with your interface.

---

## The Business Case Aligned

Let's reconnect to all three perspectives:

### For You as a Person

| Experience | Telling AI | Doing AI |
|------------|-----------|----------|
| Effort required | Read, understand, execute | Confirm |
| Outcome certainty | Maybe | Yes |
| Feeling | "Homework assigned" | "Done" |

### For You for Your Client

| Outcome | Telling AI | Doing AI |
|---------|-----------|----------|
| User success | Uncertain | Guaranteed |
| User frustration | Likely | Minimal |
| Feature discovery | Requires effort | Just happens |
| Trust | Low (black box) | High (visible) |

### For You for Your Business

| Metric | Telling AI | Doing AI |
|--------|-----------|----------|
| Activation | User might complete setup | User completes setup |
| Feature adoption | User learns about features | User uses features |
| Support deflection | User has instructions | User has outcome |
| Churn reduction | User still frustrated | User successful |
| ROI | Cost center | Value driver |

**The alignment:**

All three perspectives converge when AI does instead of tells.

---

## What Agentic UX Looks Like in Practice

**Onboarding:**

Traditional: "Welcome! Here's how to set up your account: Step 1, Step 2, Step 3..."

Agentic: "Welcome! I'll help you get set up. Creating your workspace now... done. Want me to import your data from Google Drive or start fresh?"

**Configuration:**

Traditional: "To enable dark mode, go to Settings > Appearance > Theme > Dark"

Agentic: "Switching to dark mode now... done. Looks good?"

**Complex Workflows:**

Traditional: "To generate a monthly report, first select the date range, then choose the metrics, then pick the format, then click Export..."

Agentic: "Here's your monthly report—same format as last time, with this month's data. Want me to change anything before I send it to the team?"

**The pattern:**

User expresses intent → AI executes → User sees result → User confirms or adjusts

No homework. No translation. No gap between wanting and having.

---

## The Voice Assistant Model, Applied to Visual Interfaces

Remember the voice precedent from Part 1:

"Hey Siri, set a timer" → Timer set
"Alexa, turn off lights" → Lights off

Voice assistants succeeded because:
1. Action is the only output (can't copy-paste from voice)
2. Feedback is immediate and visible
3. The contract is: request → outcome

Agentic UX brings this model to visual interfaces:

"Help me export the report" → Report exported, user sees it happen
"Update the customer info" → Customer updated, user watches the changes
"Set up my account" → Account set up, user sees each step

Same contract. Same immediacy. Same value.

---

## Part 2 Conclusion

The AI landscape has options. Most solve the wrong problem:

- **Content AI** creates, but doesn't complete
- **RAG** answers, but doesn't act
- **MCP** automates backends, but ignores frontends

**Agentic UX fills the gap**: AI that acts in your UI, visibly, contextually, in real-time.

It serves all three perspectives:

- **You as a person**: Outcomes, not homework
- **You for your client**: Success, not frustration
- **You for your business**: Value, not cost

This isn't about adding another AI feature. It's about changing how your product works.

---

**Next in Part 3:** The architectural principles behind Agentic UX, and a pragmatic path to implementation—how to start small, prove value, and expand.

---

*This is Part 2 of the Agentic UX series. [Read Part 3: Building AI That Does →](./agentic-ux-part-3-the-path-forward)*



## Recap: Three Perspectives, One Solution

In [Part 1](./agentic-ux-part-1-the-problem), we established the problem:
- AI chat fails users (homework instead of help)
- AI chat fails clients (frustration instead of success)
- AI chat fails businesses (cost center instead of value driver)

In [Part 2](./agentic-ux-part-2-the-solution), we defined the solution:
- Agentic UX = AI that acts in your UI, visibly, in real-time
- Different from Content AI, RAG, and MCP (which all fall short)
- Aligns all three perspectives

Now: What makes Agentic UX work? And how do you start building it?

---

## Architectural Principles

You don't need implementation details yet. You need to understand what makes this work.

### Principle 1: Tool Registry

AI can only do what it knows about.

A **Tool Registry** is a central catalog of available actions:
- What actions exist in this app
- What each action does
- What parameters each action needs
- When each action is available (context-dependent)
- How risky each action is

As users navigate your app, the registry updates dynamically. AI always knows what's possible *right now*.

**Example:**

On the dashboard, AI knows:
- View reports
- Create new project
- Access settings

On the customer detail page, AI knows:
- Update customer info
- View purchase history
- Send message to customer

The available actions change based on where the user is.

**Why it matters:** No registry → AI guesses → errors → distrust. With a registry, AI only offers what's actually possible.

---

### Principle 2: Context Awareness

AI should only offer what's relevant.

**Context** means:
- Current page/screen
- Selected items
- Form values
- User permissions
- Application state

With context, AI filters actions to what makes sense *right now*.

**Without context:**
> "Would you like to delete this customer?" (when user is on dashboard, not viewing any customer)

**With context:**
> "I can see you have Johnson's record open. Want me to update their email address?"

**Why it matters:** Relevance builds trust. Irrelevance destroys it. When AI consistently offers useful, contextual suggestions, users learn to rely on it.

---

### Principle 3: Visible Action

Users need to see AI working.

**Invisible action (bad):**
> User: "Update the settings"
> AI: [something happens]
> AI: "Done."
> User: "What changed? Did it work?"

**Visible action (good):**
> User: "Update the settings"
> AI: [navigates to settings—user sees this]
> AI: [toggles option—user sees this]
> AI: [clicks save—user sees this]
> AI: "Done. Changed notification preference to 'daily digest'."

**Why it matters:** Visibility enables three critical things:
1. **Trust**: User knows what happened
2. **Learning**: User learns the interface by watching
3. **Intervention**: User can stop or adjust mid-action

Black boxes erode trust. Visible actions build it.

---

### Principle 4: Progressive Agency

Start conservative. Build trust. Increase agency over time.

**Level 1 - Suggest (Low Agency):**
> "I can export that report for you. Want me to?"

User must explicitly approve before anything happens.

**Level 2 - Prepare (Medium Agency):**
> "I've filled in the form with the data you mentioned. Just confirm to submit."

AI sets things up, user confirms the final action.

**Level 3 - Execute (High Agency):**
> "Done. Exported the report as PDF. Here it is."

AI acts immediately, user monitors the result.

**Why it matters:** Different users, contexts, and stakes need different levels.
- New users need reassurance → Start at Level 1
- Power users want speed → Offer Level 3
- High-stakes actions → Stay at Level 1-2 regardless of user experience

---

### Principle 5: Safety Boundaries

Not everything should be automated.

**Hard rules:**
- Dangerous actions always require confirmation
- Irreversible actions get extra friction (intentionally)
- Everything logged (what, when, who, what changed)
- User can always stop, undo, override

**Examples:**

| Action Type | Agency Level | Confirmation Required |
|-------------|--------------|----------------------|
| View data | High | No |
| Edit draft | High | No |
| Send message | Medium | Brief confirmation |
| Delete record | Low | Explicit confirmation |
| Financial transaction | Low | Multi-step confirmation |

**Why it matters:** Your enterprise customers will ask about this. Your users' trust depends on it. Building safety in from the start is easier than retrofitting it later.

---

## Choosing the Right Agency Level

Agency isn't binary. It's a dial you turn based on context.

| Context | Suggested Agency | Reasoning |
|---------|------------------|-----------|
| High stakes (financial, legal) | Low—suggest only | Mistakes are costly |
| Irreversible actions | Low—require confirmation | Can't undo |
| New users | Low—build trust first | They don't know you yet |
| Repetitive tasks | High—save time | Same action, known outcome |
| Power users | High—they want speed | Trust established |
| Low stakes (preferences, drafts) | High—minimal risk | Easy to change |

**The key insight:** Match agency to risk and trust. Turn it up where appropriate, down where necessary. Let users control their own agency level when possible.

---

## Getting Started: A Pragmatic Path

Don't try to make everything agentic at once. That's how projects fail.

### Step 1: Pick One Workflow

Choose something that is:
- **High friction**: Users complain about it, or you see abandonment in analytics
- **Low stakes**: Mistakes aren't catastrophic, easy to fix
- **High frequency**: Happens often enough to matter

**Good first candidates:**

| Workflow | Why It's Good |
|----------|---------------|
| Onboarding | High friction, high impact, recoverable |
| Settings/Configuration | Users struggle to find things |
| Repetitive exports | Same action, over and over |
| Form filling | Tedious, error-prone |
| Search → Select → Act | Multi-step but predictable |

**Bad first candidates:**

| Workflow | Why to Avoid Initially |
|----------|------------------------|
| Financial transactions | High stakes |
| Compliance workflows | Audit requirements |
| Anything irreversible | Risk too high for learning |
| Workflows with external dependencies | Too many variables |

### Step 2: Measure Before

Before changing anything, establish baselines:

| Metric | How to Measure |
|--------|----------------|
| Task completion rate | Analytics, funnel tracking |
| Time to completion | Session recordings, timestamps |
| Error rate | Support tickets, error logs |
| User satisfaction | Survey, NPS for the workflow |
| Support tickets | Count tickets about this workflow |

These are your "before" numbers. You need them to prove value.

### Step 3: Add Agentic Assistance

For this one workflow:

1. **Register the relevant actions** in a tool registry
2. **Provide context awareness** so AI knows where user is
3. **Make execution visible** so user sees what's happening
4. **Start at low agency** (suggest first, don't just do)

**The implementation pattern:**

```
User enters workflow
  → AI offers: "I can help you complete this. Want me to?"
  → User accepts
  → AI executes steps visibly
  → User confirms result
```

### Step 4: Measure After

Same metrics as Step 2. Compare.

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Completion rate | 65% | 89% | +24% |
| Time to complete | 4.2 min | 1.1 min | -74% |
| Error rate | 12% | 3% | -75% |
| Support tickets | 47/week | 12/week | -74% |

Now you have a story to tell and a case for expanding.

### Step 5: Iterate and Expand

Based on results:

1. **Tune agency level** based on user feedback and metrics
2. **Roll out to more workflows** starting with similar patterns
3. **Build on what works** rather than starting fresh each time

---

## What to Avoid

**Don't:**
- Try to make everything agentic at launch (scope creep kills projects)
- Start with high-stakes workflows (mistakes will erode trust)
- Skip the visibility (black boxes feel unsafe)
- Forget fallbacks (what happens when AI fails?)
- Ignore security (prompt injection is real)

**Do:**
- Start small, prove value, expand
- Build trust progressively
- Keep humans in the loop (especially early)
- Log everything AI does
- Test AI paths specifically (they need different test strategies)

---

## The Security Conversation

Your security team will ask. Have answers ready.

**Prompt Injection:**
- Input validation on all user queries
- Sandboxed execution (AI can only call registered actions)
- Rate limiting on sensitive operations

**Principle of Least Privilege:**
- AI gets minimum necessary access
- Actions scoped to user's actual permissions
- No privilege escalation through AI

**Audit Logging:**
- Every AI action logged: what, when, who, result
- Searchable, exportable, retainable
- Meets compliance requirements (SOC2, GDPR, etc.)

**User Control:**
- Users can disable AI assistance
- Users can adjust agency levels
- Users can review and undo AI actions

---

## The Choice Ahead

You have two paths:

### Path A: Status Quo

- Keep adding chat features
- Watch usage plateau
- Wonder why AI isn't moving metrics
- Compete on features (commodity, easily copied)

**Outcome:** AI remains a cost center. Users remain frustrated. Differentiation erodes.

### Path B: Agency

- Build AI that does, not tells
- Reduce unrewarding effort in key workflows
- Watch adoption, retention, and satisfaction improve
- Compete on experience (hard to copy)

**Outcome:** AI becomes a value driver. Users succeed. Differentiation strengthens.

The technology is ready. The question is: will your AI tell users what to do, or do it for them?

---

## Series Conclusion

Three perspectives. One solution.

**You as a person:** Want the outcome, not the process. With Agentic UX, you get it.

**You for your client:** Want them to succeed. With Agentic UX, they do.

**You for your business:** Need the AI investment to pay off. With Agentic UX, it does.

Current AI chat translates effort into instructions.
Agentic UX eliminates effort entirely.

The best AI interface is one users don't notice. They just notice they're getting more done.

---

## Key Takeaways

1. **Agentic UX** = AI that acts in your UI, visibly, in real-time, with full context
2. **Five principles**: Tool Registry, Context Awareness, Visible Action, Progressive Agency, Safety Boundaries
3. **Start small**: One high-friction, low-stakes workflow
4. **Measure everything**: Before and after, same metrics
5. **Build trust progressively**: Low agency first, increase over time
6. **Safety first**: Log everything, scope permissions, keep humans in the loop

---

## The Question

The question isn't "should we add AI?"

**It's "should our AI tell, or do?"**

---

*This is Part 3 of the Agentic UX series.*

*[Read Part 1: Your Users Want It to Work →](./agentic-ux-part-1-the-problem)*
*[Read Part 2: AI That Does, Not Tells →](./agentic-ux-part-2-the-solution)*

---

*Ready to build AI that does? Supernal Interface provides the architecture—Tool Registry, Context Awareness, Visible Actions—out of the box. [Learn more →](/docs/getting-started)*



## From Supernal Code to Supernal Company

Supernal Interface began as a technical solution—a way to build AI-controllable applications. But as we developed these patterns, a deeper truth emerged: **the same principles that make code AI-native can make entire businesses AI-native.**

This is the evolution from **Supernal Code** to **Supernal Company**—from AI-woven applications to AI-woven businesses.

## What Does "AI-Woven" Really Mean?

Most companies use AI as a tool. They bolt it onto existing processes:
- Add a chatbot to customer service
- Use AI for data analysis
- Automate some routine tasks

**AI-woven is fundamentally different.**

In an AI-woven business, AI isn't a tool you use—it's **threaded throughout every feedback loop in your organization**. AI doesn't just assist; it **accelerates, optimizes, and closes feedback cycles** at scales impossible for humans alone.

Think of traditional fabric: threads run in one direction, then another is added on top. That's bolted-on AI.

AI-woven is like modern composite materials: the AI is integrated into the molecular structure itself. You can't separate it—it **is** the structure.

## The Core Insight: Development Cycles Are Everything

Every business operates on feedback loops:
1. **Build** something
2. **Test** if it works
3. **Deploy** to users
4. **Measure** results
5. **Learn** from feedback
6. **Iterate** and improve

**The faster you complete this cycle, the faster you create value.**

Traditional businesses measure these cycles in:
- **Code level**: Days to weeks (write → test → deploy)
- **Product level**: Weeks to months (feature → user feedback → iteration)
- **Market level**: Months to quarters (launch → market data → pivot)

**AI-woven businesses measure these cycles in hours to days across all levels.**

## The AI-Woven Stack: Feedback Loops at Every Scale

### Layer 1: Code Feedback (Minutes to Hours)

This is where Supernal Interface operates. AI is woven into the development process:

```typescript
// Developer writes function with AI-native decorator
@Tool({
  elementId: CheckoutFlow.submitButton,
  callbacks: { storage: true }
})
async completeCheckout(paymentDetails: Payment): Promise<Result> {
  // Implementation
}

// AI immediately:
// ✅ Generates tests automatically
// ✅ Validates implementation against patterns
// ✅ Suggests optimizations
// ✅ Identifies edge cases
// ✅ Creates documentation
```

**Traditional cycle**: Write code → Write tests → Run tests → Fix bugs → Deploy (days to weeks)

**AI-woven cycle**: Write code → AI generates tests + docs + validates + optimizes → Deploy (hours)

**Impact**: 10-50x faster iteration at the code level.

### Layer 2: Application Feedback (Hours to Days)

AI doesn't just help build the application—it **uses the application** to test it:

```typescript
// AI agents interact with your app before users do
const aiTestResults = await AIAgent.testUserFlow({
  scenario: "New user checkout flow",
  iterations: 1000, // AI tests 1000 variations
  optimize: true    // AI finds optimal paths
});

// AI discovers:
// - Where users might get confused
// - Which flows are slow
// - What breaks under load
// - How to improve conversion
```

**Traditional cycle**: Deploy → Wait for users → Collect analytics → Analyze → Fix (weeks)

**AI-woven cycle**: AI tests at scale → Optimize → Deploy → Monitor (days)

**Impact**: Find and fix issues before users encounter them.

### Layer 3: User Feedback (Days)

Once deployed, AI continuously monitors real user behavior:

```typescript
// Every user interaction is tracked and analyzed in real-time
@Tool({
  elementId: ProductPage.addToCart,
  callbacks: {
    storage: true,      // Remember context
    analytics: true     // Track usage patterns
  }
})
async addToCart(productId: string): Promise<void> {
  // AI learns:
  // - Why users abandon carts here
  // - What product combinations work
  // - How to personalize the experience
  // - When to offer assistance
}
```

**Traditional cycle**: User acts → Event logged → Daily batch → Analysis → Meeting → Decision → Implement (weeks)

**AI-woven cycle**: User acts → AI analyzes pattern → AI adjusts experience → Learn (hours)

**Impact**: Continuous micro-optimization based on real behavior.

### Layer 4: Market Feedback (Days to Weeks)

AI analyzes aggregate patterns across your entire user base and market:

```typescript
// AI synthesizes insights across all layers
const marketIntelligence = await AI.analyzeMarket({
  userBehavior: componentMemory.getPatterns(),
  competitors: marketData.getCompetitorActions(),
  trends: externalData.getMarketTrends(),
  financials: purchaseData.getConversionMetrics()
});

// AI identifies:
// - Emerging customer needs before they're obvious
// - Feature gaps vs. competitors
// - Pricing optimization opportunities
// - Market segment shifts
// - Product-market fit issues
```

**Traditional cycle**: Quarterly reviews → Strategy meetings → Planning → Execution (months)

**AI-woven cycle**: Continuous market analysis → Rapid strategic adjustments → Immediate testing (weeks)

**Impact**: Respond to market changes before competitors notice them.

## The Compound Effect: Velocity Multiplication

Here's where AI-woven businesses create exponential advantages:

**Traditional Business:**
- Code cycle: 2 weeks
- User feedback: 4 weeks
- Market adjustment: 12 weeks
- **Total iteration**: ~18 weeks per major change

**AI-Woven Business:**
- Code cycle: 1 day (AI-assisted development)
- User feedback: 3 days (AI testing + real user monitoring)
- Market adjustment: 1 week (AI-driven insights)
- **Total iteration**: ~2 weeks per major change

**That's 9x faster iteration.** But the real power is **compounding**:

| Quarter | Traditional | AI-Woven |
|---------|-------------|----------|
| Q1 | 1 major iteration | 6 major iterations |
| Q2 | 2 iterations | 12 iterations |
| Q3 | 3 iterations | 18 iterations |
| Q4 | 4 iterations | 24 iterations |

**After one year:**
- Traditional business: 4 product iterations
- AI-woven business: 24 product iterations

The AI-woven business has learned **6x more** about their market, users, and product. That knowledge gap is nearly impossible to close.

## Real-World Example: The AI-Woven E-Commerce Company

Let's trace a specific scenario:

### Week 1: Code Development
**Monday morning**: Developer implements new checkout flow
- Supernal Interface decorators generate tests automatically
- AI validates implementation, suggests optimizations
- AI generates documentation
- **Deployed by Monday afternoon**

**Tuesday**: AI agents test 10,000 checkout variations
- Find 3 edge cases humans missed
- Optimize button placement for conversion
- Identify slow payment API calls
- **Fixes deployed by Tuesday evening**

### Week 1: Initial User Feedback
**Wednesday-Friday**: Real users start using new checkout
- AI tracks every interaction via Component Memory
- 5% of users abandon at payment screen
- AI identifies pattern: mobile users on slow connections timing out
- **AI suggests and A/B tests solution by Friday**

### Week 2: Optimization
**Monday**: AI analysis shows mobile timeout fix improved conversion by 12%
- AI notices users in Europe converting better than US users
- Deep analysis reveals European users prefer different payment methods
- **AI recommends regional checkout variations**

**Tuesday-Wednesday**: Implement AI-recommended regional variations
- Supernal Interface makes this easy (same decorators, different configs)
- AI generates tests for each region automatically
- **Deployed and testing by Wednesday**

### Week 2: Market Intelligence
**Thursday**: AI analyzes aggregate data across all changes
- Overall conversion up 18% from baseline
- Customer acquisition cost down 15%
- AI identifies correlation: users from social media ads prefer mobile checkout
- **AI recommends adjusting ad spend toward mobile-optimized campaigns**

**Friday**: Marketing team reviews AI recommendations
- Increase mobile ad budget
- AI monitors results in real-time
- **By end of day, ROI projections updated with live data**

### Week 3: Strategic Insight
**Monday**: AI identifies broader pattern
- Mobile checkout improvements attracted younger demographic
- This demographic has 2x lifetime value but different product preferences
- **AI suggests new product line for this segment**

**Week 3-4**: Rapid product testing
- Use AI insights to design products for new segment
- AI-woven architecture allows rapid testing
- **Launch MVP in 2 weeks instead of 2 months**

## The Result: Continuous Value Creation

In **4 weeks**, this AI-woven company:
1. ✅ Built and deployed new checkout flow
2. ✅ Identified and fixed 3 edge cases
3. ✅ Optimized for mobile users (+12% conversion)
4. ✅ Implemented regional variations (+18% overall conversion)
5. ✅ Reduced customer acquisition cost (-15%)
6. ✅ Optimized marketing spend
7. ✅ Discovered new high-value customer segment
8. ✅ Launched product line for that segment

**A traditional company might accomplish steps 1-3 in the same timeframe.**

## The Supernal Company: Business Architecture for the AI Age

A Supernal Company isn't just a company that uses AI. It's a company **architected for AI-native operations**:

### 1. **AI-Native Code** (Supernal Interface)
- All components expose AI-controllable interfaces
- Tests generate automatically
- Documentation stays synchronized
- AI can operate the system like a human would

### 2. **AI-Native Data**
- Component Memory tracks every interaction
- Data structured for AI analysis
- Real-time streaming to AI systems
- Privacy-preserving and ethical by design

### 3. **AI-Native Processes**
- AI integrated into build/test/deploy pipelines
- AI monitors production systems continuously
- AI provides insights at every decision point
- Humans focus on strategy, AI handles execution velocity

### 4. **AI-Native Culture**
- Teams trained to work with AI insights
- Decisions data-driven but AI-accelerated
- Experimentation encouraged and AI-tested
- Learning loops built into every process

## The Feedback Loop Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    SUPERNAL COMPANY                     │
│                   (AI-Woven Business)                   │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐   ┌───────────────┐   ┌───────────────┐
│  CODE CYCLE   │   │  USER CYCLE   │   │ MARKET CYCLE  │
│   (Hours)     │   │    (Days)     │   │   (Weeks)     │
└───────┬───────┘   └───────┬───────┘   └───────┬───────┘
        │                   │                   │
        │  ┌────────────────┴────────────────┐  │
        │  │         AI INTELLIGENCE         │  │
        │  │    (Cross-Layer Optimization)   │  │
        │  └────────────────┬────────────────┘  │
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │ VALUE CREATED │
                    │  (Continuous) │
                    └───────────────┘
```

Each cycle feeds insights into the others:
- **Code insights** inform user experience optimization
- **User patterns** guide market strategy
- **Market intelligence** directs development priorities
- **AI synthesizes** across all layers continuously

## Why This Matters: The Competitive Moat

Companies operating at 9x iteration velocity don't just move faster—they build **knowledge moats**:

### Year 1:
- **Traditional company**: Understands product basics, has some user data
- **AI-woven company**: Deep understanding of user psychology, market dynamics, optimal product-market fit

### Year 2:
- **Traditional company**: Starting to optimize based on accumulated data
- **AI-woven company**: Has tested hundreds of variations, knows exactly what works, why it works, and for whom

### Year 3:
- **Traditional company**: Attempting to catch up, maybe adding AI tools
- **AI-woven company**: Knowledge gap is insurmountable—they've learned in 3 years what would take traditional company 27 years

**This isn't about being slightly better. It's about operating in a different regime of business velocity.**

## The Path Forward: Building Supernal Companies

You don't become an AI-woven business overnight. It's an architectural evolution:

### Phase 1: AI-Native Code (Supernal Interface)
Start with development velocity. Build AI controllability into your applications from the ground up.

**Outcome**: 10x faster code iteration, automated testing, AI-assisted development

### Phase 2: AI-Native Operations
Extend AI integration to deployment, monitoring, and optimization.

**Outcome**: Real-time system intelligence, predictive issue detection, automated optimization

### Phase 3: AI-Native Business Intelligence
Connect user behavior, component memory, and market data into unified AI analysis.

**Outcome**: Deep understanding of user needs, market trends, competitive positioning

### Phase 4: AI-Native Strategy
Use AI insights to drive strategic decisions, product direction, and market positioning.

**Outcome**: Data-driven strategy at execution velocity, continuous market adaptation

### Phase 5: Fully AI-Woven
AI integrated into every feedback loop, every decision point, every process.

**Outcome**: Exponential competitive advantage through knowledge accumulation and velocity multiplication

## The Future Belongs to AI-Woven Businesses

We're at an inflection point. The companies that embrace AI-woven architecture today will be the category leaders tomorrow—not because they have better AI, but because they've **built their entire business to operate at AI velocity**.

Traditional businesses will find themselves competing not just against better products, but against organizations that:
- Learn 9x faster
- Iterate 24x more per year
- Accumulate knowledge exponentially
- Respond to market changes in days instead of months

**This is why Supernal Code evolved into Supernal Company.**

The technical patterns that make code AI-native (Supernal Interface, Component Memory, automated testing) are the foundation. But the real transformation is organizational: **building businesses that operate at AI speed across every feedback loop**.

## Call to Action

If you're building a business in 2024 and beyond, ask yourself:

1. How long does it take your code to get from idea to production?
2. How quickly can you test and validate new features?
3. How fast can you respond to user feedback?
4. How quickly do you detect and adapt to market changes?
5. How many product iterations can you complete in a year?

If those answers are measured in weeks and months instead of days and weeks, **you're building a traditional business in an AI-woven world**.

The good news: you can start the transformation today.

Begin with **Supernal Interface**—make your code AI-native. Build feedback loops at the component level. Generate tests automatically. Let AI help accelerate development.

Then expand those principles outward: AI-native operations, AI-native intelligence, AI-native strategy.

**Layer by layer, feedback loop by feedback loop, build the AI-woven business that can compete at AI velocity.**

---

## The Bottom Line

**AI-woven businesses don't just use AI. They're built for AI from the ground up—with feedback loops at every scale that compound into exponential advantages.**

From code that writes its own tests, to applications that optimize themselves, to businesses that learn and adapt faster than humanly possible—this is the future of competitive advantage.

**Welcome to the age of Supernal Companies: businesses architected for AI velocity.**

The question isn't whether your competitors will become AI-woven.

The question is: **Will you get there first?**

---

*This is part of the Supernal Coding movement—building the patterns, tools, and architectures that make AI-native businesses possible. From Supernal Interface to Supernal Company, we're creating the future of business velocity.*




## The Testing Problem That Started It All

It began with a simple, frustrating problem: generating tests for a growing application. Like many developers, I was writing test after test, each one slightly different from the last, duplicating selectors, repeating logic, and creating a maintenance nightmare. The tests were brittle. Every UI change meant updating dozens of test files. Every new feature meant copying and pasting similar test patterns.

I kept asking myself: *Why am I doing this manually? Why isn't there a better way?*

## The First Insight: Names as the Foundation

The breakthrough came when I realized the core issue wasn't the tests themselves—it was **duplication**. We were violating DRY (Don't Repeat Yourself) at a fundamental level. Every time we wrote a test selector like `'button.submit'` or `'[data-testid="login-form"]'`, we were creating a magic string that existed nowhere else in our codebase.

The solution seemed obvious in retrospect: **centralize component names**.

```typescript
// Instead of magic strings everywhere...
await page.locator('[data-testid="chat-send-button"]').click();

// Use stable, centralized identifiers
await page.locator(`[data-testid="${ChatInput.sendButton}"]`).click();
```

This simple change had profound implications. Now we had:
- **Single source of truth** for component identifiers
- **Type safety** across tests and components
- **Refactor confidence** - rename once, update everywhere
- **Discovery** - developers could explore available components through autocomplete

But this was just the beginning.

## The Second Realization: Names Enable Connectivity

Once we had centralized names, something interesting happened. We could now **trace connections** between:
- React components using `data-testid={ComponentNames.input}`
- Playwright tests selecting those same components
- Documentation referencing specific UI elements
- Analytics tracking user interactions

The names became **stable identifiers** that connected different layers of the application. This wasn't just about DRY anymore—it was about creating a **unified namespace** for the entire system.

## The Third Leap: AI Controllability

Then came the moment that changed everything.

If human developers could use these names to interact with the UI through tests, **why couldn't AI do the same?**

I realized we could create a system where:
1. **Developers decorate functions** with metadata pointing to UI elements
2. **AI agents discover** these decorated functions automatically
3. **AI can control** the application using the same interfaces humans use
4. **Tests generate automatically** from the decorated functions

```typescript
@Tool({
  elementId: ChatInput.sendButton,
  containerId: ChatContainer.root
})
async sendMessage(text: string): Promise<void> {
  // Implementation
}
```

This single decorator pattern solved multiple problems at once:
- ✅ AI knows what UI elements exist
- ✅ AI knows how to interact with them
- ✅ Tests generate from the same source of truth
- ✅ No duplicate test writing needed

**AI could now control applications faster and more reliably than humans clicking through UIs manually.**

## The Fourth Evolution: State, Data, and Component Memory

But AI control wasn't enough. AI agents need **context**. They need to know:
- What happened in previous interactions?
- What data is currently displayed?
- What state is the component in?

This led to the development of **Component Memory** and **data integration patterns**:

```typescript
@Tool({
  elementId: ChatInput.sendButton,
  callbacks: {
    storage: true,  // Enable memory
    navigation: true  // Track navigation
  }
})
async sendMessage(
  text: string,
  options?: {
    storage?: ComponentStorage  // AI can read/write context
  }
): Promise<void> {
  // AI remembers what happened here
}
```

Now AI could:
- **Remember** previous interactions with components
- **Load state** across sessions
- **Make intelligent decisions** based on history
- **Avoid repeating failed actions**

We were no longer just enabling AI control—we were giving AI **learning capability** at the component level.

## The Fifth Insight: Usage Analytics and AI-Driven Optimization

With AI interacting with components and storing data about those interactions, we suddenly had a **goldless dataset**:
- Which components are AI using most frequently?
- Which interactions succeed vs. fail?
- What patterns lead to better outcomes?
- How can we optimize the UI for AI efficiency?

This evolved into **AI Site Optimization**:
- Track AI interaction patterns
- Identify bottlenecks in AI workflows
- Optimize component placement and behavior
- A/B test AI interaction strategies
- **Make applications that adapt to how AI uses them**

The application becomes **self-optimizing for AI interaction**.

## The Bigger Picture: Supernal Coding

As these patterns emerged, I realized this wasn't just about one application or one problem. This was a **fundamental shift in how we build software**:

### Traditional Development:
1. Write components
2. Write tests manually
3. Write documentation separately
4. Build AI integrations as an afterthought
5. Optimize based on human usage

### Supernal Coding:
1. Write components with AI-native decorators
2. Tests generate automatically
3. Documentation generates from decorators
4. AI integration is built-in by design
5. Optimize for both human and AI usage
6. Application evolves based on AI interaction patterns

## Supernal Interface: The Meta-Repository

Supernal Interface became the **core enabling technology** for this new paradigm. It's designed as an **evolving meta-repository**—a set of patterns, decorators, and tools that make applications:

- **AI-Compliant**: Built for AI interaction from the ground up
- **AI-Woven**: AI capabilities are threaded throughout, not bolted on
- **Self-Documenting**: The code itself describes how to interact with it
- **Self-Testing**: Tests generate from the same decorators that enable AI control
- **Self-Optimizing**: Applications learn and adapt based on AI usage patterns

## The Journey Continues

What started as frustration with writing tests evolved into a complete reimagining of how we build software in the age of AI. Supernal Interface and Supernal Coding represent a new way of thinking about development:

**Applications are no longer static artifacts humans build for other humans. They are dynamic, AI-native systems that humans and AI build together, for both to use.**

The testing problem that started this journey? It solved itself. When you build for AI-native interaction from the start, tests become a natural byproduct of your architecture, not a burden.

---

## Key Takeaways

1. **DRY extends beyond code** - eliminating duplication in identifiers creates system-wide benefits
2. **Names are infrastructure** - stable identifiers enable connectivity across layers
3. **AI controllability should be built-in** - not added as an afterthought
4. **Component-level memory** - giving AI context at the interaction layer
5. **AI-driven optimization** - applications can evolve based on how AI uses them
6. **Meta-repositories** - frameworks that enable new development paradigms

## What's Next?

Supernal Interface is just the beginning. As more developers adopt AI-native patterns, we'll see:
- **Industry standards** for AI-controllable interfaces
- **AI-first frameworks** that make these patterns default
- **Hybrid applications** optimized for both human and AI users
- **Self-evolving systems** that improve through AI interaction

The future of software development isn't just human-written or AI-generated. It's **human-guided, AI-woven, and collaboratively evolved**.

---

*This is the story of Supernal Interface—born from a testing problem, evolved into an AI-native architecture, and part of the larger Supernal Coding movement to make software development more intelligent, more collaborative, and more adaptive.*

**Welcome to the age of AI-native development.**




## The Problem: Too Much Ceremony

When we first launched `@supernal-interface`, developers loved the power but complained about the verbosity. Creating a simple tool required **40 lines of configuration**:

```typescript
@Tool({
  name: 'Send Message',
  description: 'Sends a chat message',
  toolId: Components.ChatSendButton,
  elementId: Components.ChatSendButton,
  aiEnabled: true,
  dangerLevel: 'safe',
  category: ToolCategory.UI,
  executionContext: 'ui',
  examples: ['send message', 'send chat'],
  // ... 15 more lines of config
})
async sendMessage(text: string) {
  // Your logic here
}
```

For a simple button click, this was **overkill**.

## The Solution: Smart Defaults + Inference

We redesigned the `@Tool` decorator with three key principles:

### 1. Minimal Required Fields

Only specify **what the AI needs to know**:

```typescript
@Tool(Components.ChatSendButton, {
  examples: ['send message', 'send chat']
})
async sendMessage(text: string) {
  // That's it!
}
```

### 2. Container Inheritance

Use `@ToolProvider` to set defaults for an entire class:

```typescript
@ToolProvider(DemoContainers.Chat.id)
class ChatTools {
  @Tool(Components.SendButton, {
    examples: ['send message']
  })
  async send() { /* containerId inherited! */ }
}
```

### 3. Intelligent Inference

The decorator **infers** from your method name:

```typescript
// Method name → inferred properties
async sendMessage()      // → aiEnabled: true, dangerLevel: 'safe'
async deleteAccount()    // → aiEnabled: false, dangerLevel: 'destructive'
async updateSettings()   // → category: 'settings'
```

## Before & After Comparison

### Before (40 lines)
```typescript
@Tool({
  name: 'Increment Counter',
  description: 'Increments the counter by 1',
  toolId: 'counter-increment',
  elementId: 'counter-increment-button',
  aiEnabled: true,
  dangerLevel: 'safe',
  category: ToolCategory.UTILITY,
  executionContext: 'ui',
  examples: ['increment', 'add one', 'count up'],
  permissions: {
    level: 'user',
    sensitiveDataAccess: false,
    networkAccess: false,
  },
  callbacks: {
    storage: true,
    validation: false,
  },
  containerId: 'demo-container',
  tags: ['counter', 'increment'],
  keywords: ['add', 'increment', 'plus'],
})
async incrementCounter() {
  this.count++;
}
```

### After (3 lines!)
```typescript
@Tool('counter-increment-button', {
  examples: ['increment', 'add one', 'count up']
})
async incrementCounter() {
  this.count++;
}
```

## What Gets Inferred?

| Property | Inference Logic |
|---|---|
| `name` | Method name → "Increment Counter" |
| `aiEnabled` | Safe method names → `true` |
| `dangerLevel` | Method name patterns → 'safe', 'moderate', 'dangerous' |
| `category` | Method context → ToolCategory |
| `containerId` | From `@ToolProvider` parent |
| `description` | Generated from name |

## Hierarchical Naming Prevents Collisions

The image you shared showed a key insight: **hierarchical naming prevents ID collisions**.

```typescript
// Main navigation menu
const MainMenuNames = {
  open: 'demo-simple-mainmenu-open',
  close: 'demo-simple-mainmenu-close',
  home: 'demo-simple-mainmenu-home',
} as const;

// User profile menu (different feature)
const UserMenuNames = {
  open: 'demo-simple-usermenu-open',    // ✅ No collision!
  profile: 'demo-simple-usermenu-profile',
  settings: 'demo-simple-usermenu-settings',
} as const;
```

Pattern: `{container}-{feature}-{element}`

## Benefits

### For Developers
- **80% less code** to write and maintain
- **Faster onboarding** - just elementId + examples
- **Type-safe** - compile-time validation still works
- **Flexible** - can still use full config when needed

### For Teams
- **Consistent patterns** across the codebase
- **Less room for errors** - fewer fields to misconfigure
- **Better DX** - developers focus on logic, not config

## Migration Path

Existing code? **No changes required**. The old syntax still works:

```typescript
// Old syntax - still supported
@Tool({
  toolId: 'my-tool',
  elementId: 'my-element',
  aiEnabled: true,
  // ... full config
})
async myMethod() { }

// New syntax - use when ready
@Tool('my-element', {
  examples: ['do thing']
})
async myMethod() { }
```

## Try It Yourself

```bash
npm install @supernal-interface/core@latest
```

Then explore the [Examples](/examples) page to see the shorthand in action with interactive demos.

## What's Next?

We're exploring:
- **CLI tool** to help migrate existing code
- **ESLint plugin** to suggest simplifications
- **VS Code extension** with snippets for common patterns

Join the conversation on [GitHub](https://github.com/supernalintelligence/interface).




# Making Any Application AI-Controllable: Introducing @supernal-interface/core

*How a single decorator transforms your code into an AI-operable, auto-testable interface*

---

## The Problem

Building AI-controllable applications is hard. You need to:
- Define tools for the AI to call
- Write comprehensive tests
- Document your API
- Implement safety controls
- Keep everything in sync

Traditional approaches require maintaining separate systems for each concern, leading to duplication, drift, and maintenance nightmares.

## The Solution

What if you could do all of this with a single decorator?

```typescript
@Tool({ 
  description: 'Send a chat message',
  aiEnabled: true,
  examples: ['send message "hello"', 'type and send "test"']
})
async sendMessage(text: string): Promise<ToolResult> {
  // Your business logic here
  await this.typeIntoInput(text);
  await this.clickSendButton();
  return { success: true, message: `Sent: "${text}"` };
}
```

From this one decorator:
- ✅ **AI can call it** via natural language ("send message hello")
- ✅ **Tests auto-generate** (unit, integration, E2E)
- ✅ **Documentation auto-generates**
- ✅ **Safety controls apply** automatically
- ✅ **Full type safety** through TypeScript

Meet **@supernal-interface/core**: A universal system for making any application AI-controllable and auto-testable.

---

## How It Works

### 1. Decorate Your Methods

Add `@Tool` to any async method:

```typescript
import { Tool, ToolProvider, ToolResult } from '@supernal-interface/core';

@ToolProvider({ category: 'chat' })
export class ChatTools {
  
  @Tool({
    description: 'Click the send button',
    aiEnabled: true,
    dangerLevel: 'safe'
  })
  async clickSendButton(): Promise<ToolResult> {
    const button = document.querySelector('[data-testid="send-button"]');
    if (!button) {
      return { success: false, error: 'Button not found' };
    }
    button.click();
    return { success: true };
  }
}
```

That's it. **No schemas to maintain. No separate test files. No documentation to write.**

### 2. Auto-Generate Everything

```bash
# Generate comprehensive test suites
npm run generate:tests

# Generate API documentation
npm run generate:docs

# Extract tool metadata
npm run generate:metadata
```

The system scans your `@Tool` decorators and generates:

**Unit Tests:**
```typescript
test('clickSendButton - should click send button', async () => {
  const result = await tools.clickSendButton();
  expect(result.success).toBe(true);
});

test('clickSendButton - should have correct metadata', () => {
  const meta = ToolRegistry.getTool('ChatTools.clickSendButton');
  expect(meta.aiEnabled).toBe(true);
  expect(meta.dangerLevel).toBe('safe');
});
```

**Integration Tests:**
```typescript
test('clickSendButton - AI can execute safely', async () => {
  const result = await ToolRegistry.executeForAI('ChatTools.clickSendButton', {});
  expect(result.success).toBe(true);
});
```

**E2E Tests:**
```typescript
test('clickSendButton - UI interaction works', async ({ page }) => {
  await page.goto('/chat');
  const button = page.locator('[data-testid="send-button"]');
  await expect(button).toBeVisible();
  await button.click();
});
```

### 3. Let AI Control Your App

The AI sees your decorated methods as callable tools:

```typescript
// User says: "send message hello"
// AI calls:
await chatTools.sendMessage('hello');

// User says: "search for users named John"
// AI calls:
await userTools.searchUsers('John');
```

---

## Works For Everything

### DOM Interactions

```typescript
@Tool({ elementId: 'chat-input-send-button', aiEnabled: true })
async clickSendButton(): Promise<ToolResult> {
  const element = document.querySelector('[data-testid="send-button"]');
  element.click();
  return { success: true };
}
```

### Pure Functions

```typescript
@Tool({ description: 'Validate email format', aiEnabled: true })
async validateEmail(email: string): Promise<ToolResult> {
  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
  return { 
    success: isValid, 
    data: { valid: isValid },
    error: isValid ? undefined : 'Invalid email format'
  };
}
```

### API Calls

```typescript
@Tool({ description: 'Fetch user profile from backend', aiEnabled: true })
async fetchUserProfile(userId: string): Promise<ToolResult> {
  try {
    const response = await fetch(`/api/users/${userId}`);
    const data = await response.json();
    return { success: true, data };
  } catch (error) {
    return { success: false, error: error.message };
  }
}
```

### Complex Workflows

```typescript
@Tool({
  description: 'Send message with validation and retry',
  aiEnabled: true,
  examples: ['send message "hello"', 'type and send "test"']
})
async sendMessage(text: string): Promise<ToolResult> {
  // 1. Validate
  const validation = await this.validateMessage(text);
  if (!validation.success) return validation;
  
  // 2. Type into input
  await this.typeIntoInput(text);
  
  // 3. Click send with retry
  for (let i = 0; i < 3; i++) {
    const result = await this.clickSendButton();
    if (result.success) return result;
    await this.wait(1000);
  }
  
  return { success: false, error: 'Failed after 3 retries' };
}
```

---

## Safety First

### Default: Test-Only

All tools are **test-only by default** - AI cannot execute them:

```typescript
@Tool()  // Default: aiEnabled = false
async deleteAllUsers() {
  // Only tests can call this
}
```

### Explicit AI Enablement

You must explicitly enable AI execution:

```typescript
@Tool({ aiEnabled: true })  // Now AI can call it
async searchUsers(query: string) { }
```

### Danger Levels (Auto-Inferred)

The system automatically infers danger levels from method names:

```typescript
// Auto-inferred: 'safe'
@Tool({ aiEnabled: true })
async searchUsers(query: string) { }

// Auto-inferred: 'moderate'
@Tool({ aiEnabled: true })
async createUser(email: string) { }

// Auto-inferred: 'dangerous'
@Tool({ aiEnabled: true })
async approveRegistration(userId: string) { }

// Auto-inferred: 'destructive'
@Tool({ aiEnabled: true })
async deleteUser(userId: string) { }
```

### Require Human Approval

For dangerous operations, require human approval:

```typescript
@Tool({ 
  aiEnabled: true, 
  dangerLevel: 'destructive',
  requiresApproval: true  // AI must ask permission first
})
async deleteAllUserData(userId: string) {
  // Requires human to click "Approve" before execution
}
```

---

## Optional: Name Contracts for Stability

For UI-heavy applications, you can define centralized name contracts:

```typescript
// src/names/Chat.names.ts
export const Chat = {
  Input: {
    sendButton: 'chat-input-send-button',
    textfield: 'chat-input-textfield',
  },
  MessageList: {
    container: 'chat-messages-container',
  }
} as const;
```

Then reference them in your tools:

```typescript
import { Chat } from '@/names';

@Tool({ 
  elementId: Chat.Input.sendButton,  // Stable reference
  aiEnabled: true 
})
async clickSendButton() {
  const element = document.querySelector(`[data-testid="${Chat.Input.sendButton}"]`);
  element.click();
}
```

And in your components:

```typescript
import { Chat } from '@/names';

export const ChatInput = () => (
  <button data-testid={Chat.Input.sendButton}>
    Send
  </button>
);
```

**Benefits:**
- Single source of truth for DOM IDs
- Type-safe references
- Easy refactoring
- Clear contracts between systems

**But it's optional** - for backend APIs or pure functions, you don't need name contracts at all.

---

## Real-World Example

Here's a complete, production-ready tool class:

```typescript
import { Tool, ToolProvider, ToolResult } from '@supernal-interface/core';
import { Chat } from '@/names';

@ToolProvider({ category: 'chat' })
export class ChatTools {
  
  // Simple DOM interaction
  @Tool({
    elementId: Chat.Input.sendButton,
    description: 'Click the send button',
    aiEnabled: true,
    dangerLevel: 'safe'
  })
  async clickSendButton(): Promise<ToolResult> {
    const element = document.querySelector(`[data-testid="${Chat.Input.sendButton}"]`);
    if (!element) return { success: false, error: 'Button not found' };
    element.click();
    return { success: true, message: 'Clicked send button' };
  }
  
  // Pure function
  @Tool({
    description: 'Validate chat message',
    aiEnabled: true,
    dangerLevel: 'safe'
  })
  async validateMessage(text: string): Promise<ToolResult> {
    if (!text || text.trim().length === 0) {
      return { success: false, error: 'Message is empty' };
    }
    if (text.length > 500) {
      return { success: false, error: 'Message too long (max 500 chars)' };
    }
    return { success: true, data: { valid: true, length: text.length } };
  }
  
  // API call
  @Tool({
    description: 'Fetch chat history',
    aiEnabled: true,
    dangerLevel: 'safe'
  })
  async fetchChatHistory(userId: string): Promise<ToolResult> {
    try {
      const response = await fetch(`/api/chat/history/${userId}`);
      if (!response.ok) throw new Error('API error');
      const data = await response.json();
      return { success: true, data };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }
  
  // Complex workflow
  @Tool({
    name: 'Send Message',
    description: 'Validate, type, and send a chat message',
    aiEnabled: true,
    dangerLevel: 'safe',
    examples: [
      'send message "hello"',
      'type and send "test"',
      'send "hi there"'
    ]
  })
  async sendMessage(text: string): Promise<ToolResult> {
    // 1. Validate
    const validation = await this.validateMessage(text);
    if (!validation.success) return validation;
    
    // 2. Type into input
    const typeResult = await this.typeIntoInput(text);
    if (!typeResult.success) return typeResult;
    
    // 3. Click send
    return await this.clickSendButton();
  }
  
  private async typeIntoInput(text: string): Promise<ToolResult> {
    const element = document.querySelector(`[data-testid="${Chat.Input.textfield}"]`);
    if (!element) return { success: false, error: 'Input not found' };
    (element as HTMLInputElement).value = text;
    element.dispatchEvent(new Event('input', { bubbles: true }));
    return { success: true };
  }
}
```

**What you get:**
- 4 AI-callable tools
- 12+ auto-generated tests (unit + integration + E2E)
- Complete API documentation
- Safety controls
- Natural language examples
- **All from decorated methods**

---

## Getting Started

### Installation

```bash
npm install @supernal-interface/core
```

### Basic Setup

1. **Create tool class:**
```typescript
// src/tools/MyTools.ts
import { Tool, ToolProvider, ToolResult } from '@supernal-interface/core';

@ToolProvider({ category: 'my-feature' })
export class MyTools {
  
  @Tool({
    description: 'Do something useful',
    aiEnabled: true
  })
  async doSomething(param: string): Promise<ToolResult> {
    // Your logic here
    return { success: true, data: { result: 'done' } };
  }
}
```

2. **Generate tests:**
```bash
npm run generate:tests
```

3. **Run tests:**
```bash
npm test
```

That's it! You now have:
- AI-controllable functionality
- Comprehensive test coverage
- Auto-generated documentation

### Advanced: Add Name Contracts (Optional)

For UI-heavy apps:

1. **Define names:**
```typescript
// src/names/MyFeature.names.ts
export const MyFeature = {
  Button: 'my-feature-button',
  Input: 'my-feature-input',
} as const;
```

2. **Reference in tools:**
```typescript
@Tool({ elementId: MyFeature.Button })
async clickButton() { }
```

3. **Use in components:**
```typescript
<button data-testid={MyFeature.Button}>Click Me</button>
```

---

## Why This Matters

### Traditional Approach

❌ **Separate systems for everything:**
- Write tool definitions (JSON/YAML schemas)
- Write implementation
- Write tests manually
- Write documentation manually
- Keep everything synchronized

**Result:** Duplication, drift, maintenance burden

### @supernal-interface/core Approach

✅ **Single source of truth:**
- Write decorated methods once
- Everything else generates automatically
- Always in sync
- Zero duplication

**Result:** Faster development, better quality, easier maintenance

---

## Comparison

| Feature | Traditional | @supernal-interface/core |
|---------|-------------|--------------------------|
| **Tool Definition** | Separate schema files | `@Tool` decorator |
| **Implementation** | Separate implementation | Same decorated method |
| **Tests** | Manual | Auto-generated |
| **Documentation** | Manual | Auto-generated |
| **Type Safety** | Loose/external | Full TypeScript |
| **AI Integration** | Complex setup | Built-in |
| **Maintenance** | High (sync multiple files) | Low (single source) |
| **Learning Curve** | Steep | Minimal |
| **Versatility** | Often domain-specific | Works for everything |

---

## Real Benefits

### For Developers

- **Write less code** - One decorator does everything
- **Better type safety** - Full TypeScript support
- **Faster iteration** - No manual test writing
- **Clear contracts** - Optional name contracts for clarity
- **Zero lock-in** - Just decorators, easy to migrate away

### For Teams

- **Consistency** - Standard pattern across codebase
- **Onboarding** - Simple concept to learn
- **Maintainability** - Single source of truth
- **Quality** - Auto-generated tests ensure coverage
- **Safety** - Built-in AI safety controls

### For Products

- **AI-ready** - Instant AI controllability
- **Testable** - Comprehensive test coverage
- **Documented** - Always up-to-date docs
- **Scalable** - Pattern works at any size
- **Flexible** - Works for any type of operation

---

## What's Next

**@supernal-interface/core is production-ready today.**

Try it on your next project:

```bash
npm install @supernal-interface/core
```

Read the [complete documentation](./ARCHITECTURE.md) for detailed guidance.

Join our community and share what you build!

---

## Key Takeaways

✅ **One decorator** transforms methods into AI-controllable, auto-testable tools  
✅ **Works for everything** - DOM, APIs, pure functions, complex workflows  
✅ **Auto-generates** tests and documentation  
✅ **Safety first** - Test-only by default, explicit AI enablement  
✅ **Optional name contracts** for UI stability (but not required)  
✅ **Zero lock-in** - Just decorators, standard TypeScript

**Making any application AI-controllable has never been simpler.**

---

*Ready to make your app AI-controllable? [Get started with @supernal-interface/core →](./ARCHITECTURE.md)*




# What's In a Name? Type-Safe UI Automation with Name Contracts

**TL;DR:** We reduced UI tool boilerplate by 80% using the same pattern Redux uses for action types - but applied to DOM IDs. The result: type-safe, refactor-safe, AI-friendly UI automation that scales to hundreds of components.

---

## The Problem: Magic Strings Everywhere

If you've ever written Playwright tests, you've written code like this:

```typescript
// component.tsx
<button data-testid="menu-open">Open Menu</button>

// test.spec.ts
await page.locator('[data-testid="menu-open"]').click();
```

**This works... until you refactor.**

One day, you decide "menu-open" should be "main-menu-open" for clarity. You update the component:

```typescript
<button data-testid="main-menu-open">Open Menu</button>
```

**Your tests break at runtime.** No compile error, no warning. Just a failing test.

### The Core Problem: No Single Source of Truth

In a typical UI automation setup, the same ID appears in **three places**:

1. **Component** (`data-testid` attribute)
2. **Tool/Action** (automation script that clicks it)
3. **Test** (Playwright selector)

**Three copies = three places to update = guaranteed drift.**

---

## The Pattern: Name Contracts

If you've used Redux, you've seen this pattern:

```typescript
// Redux action types
const TOGGLE_TODO = 'todos/toggle';
const ADD_TODO = 'todos/add';

// Used in actions
dispatch({ type: TOGGLE_TODO, id: 5 });

// Used in reducers
switch (action.type) {
  case TOGGLE_TODO:
    // ...
}
```

**Why does Redux do this?**
- ✅ Single source of truth
- ✅ Type-safe (typos caught at compile-time)
- ✅ Refactor-safe (rename once, updates everywhere)
- ✅ IDE autocomplete

**What if we applied the same pattern to DOM IDs?**

---

## The Solution: Name Contracts for UI

### Step 1: Define Names Once

```typescript
// menu.names.ts
export const MenuNames = {
  container: 'demo-menu-container',
  openButton: 'demo-menu-open',
  closeButton: 'demo-menu-close',
  item1: 'demo-menu-item-1',
  item2: 'demo-menu-item-2',
} as const;

export type MenuNameId = typeof MenuNames[keyof typeof MenuNames];
```

**Just like Redux action types, but for DOM elements.**

### Step 2: Use Names Everywhere

**In Components:**
```typescript
// MenuWidget.tsx
import { MenuNames } from './menu.names';

export function MenuWidget() {
  return (
    <div data-testid={MenuNames.container}>
      <button data-testid={MenuNames.openButton}>
        Open Menu
      </button>
    </div>
  );
}
```

**In Automation Tools:**
```typescript
// MenuTools.ts
import { Tool, ToolProvider } from '@supernal-interface/core';
import { MenuNames } from './menu.names';

@ToolProvider('demo-app')
export class MenuTools {
  @Tool(MenuNames.openButton, { examples: ['open menu'] })
  async openMenu() {
    return this.state.merge({ menuOpen: true });
  }
}
```

**In Tests:**
```typescript
// menu.spec.ts
import { test, expect } from '@playwright/test';
import { MenuNames } from '@/features/menu/menu.names';

test('menu interaction', async ({ page }) => {
  await page.goto('/demo');
  
  // Use the same constant
  await page.locator(`[data-testid="${MenuNames.openButton}"]`).click();
  
  await expect(page.locator(`[data-testid="${MenuNames.container}"]`))
    .toBeVisible();
});
```

### Step 3: Refactor with Confidence

**Change the ID once:**
```typescript
export const MenuNames = {
  openButton: 'demo-main-menu-open',  // ← Changed
  // ...
} as const;
```

**All three uses update automatically:**
- ✅ Component: `<button data-testid={MenuNames.openButton}>`
- ✅ Tool: `@Tool(MenuNames.openButton, ...)`
- ✅ Test: `page.locator(\`[data-testid="${MenuNames.openButton}"]\`)`

**Typo?** TypeScript catches it at compile-time:
```typescript
<button data-testid={MenuNames.opnButton}>
//                              ^^^^^^^^^ 
// Error: Property 'opnButton' does not exist on type 'typeof MenuNames'
```

---

## The Innovation: Three-Way Contracts

Most patterns connect **two** things:
- Redux: actions ↔ reducers
- React Query: queries ↔ cache

**Name contracts connect THREE:**
- Component (`data-testid`) ↔ Tool (`@Tool` decorator) ↔ Test (Playwright)

**This is the key insight:** UI automation needs a **stronger contract** than state management because it spans three domains:
1. **Rendering** (React components)
2. **Behavior** (automation tools)
3. **Verification** (tests)

**Name contracts unify all three.**

---

## Real-World Impact: 80% Boilerplate Reduction

### Before (40 lines):
```typescript
@ToolProvider({
  category: 'demo-app',
  containerId: 'demo-stateful',
})
export class DemoTools {
  @Tool({
    elementId: StatefulDemoNames.openMenu,
    containerId: 'demo-stateful',
    callbacks: { storage: true },
    name: 'Open Menu',
    description: 'Open the main menu',
    aiEnabled: true,
    dangerLevel: 'safe',
    requiresApproval: false,
    examples: ['open menu', 'open', 'show menu'],
  })
  async openMenu() {
    await this.ensureInitialized();
    if (!this.stateManager) return { success: false };
    await this.stateManager.merge('demo-widgets', { menuOpen: true });
    return { success: true };
  }
}
```

### After (8 lines):
```typescript
@ToolProvider('demo-stateful')
export class DemoTools {
  @Tool(MenuNames.openButton, {
    examples: ['open menu', 'open', 'show menu']
  })
  async openMenu() {
    return this.state.merge({ menuOpen: true });
  }
}
```

**What happened to the other 32 lines?**
- **Inferred from method name:** `name`, `description`, `category`
- **Inferred from prefix:** `dangerLevel` (`open*` → `'safe'`)
- **Inferred from toolType:** `aiEnabled`
- **Inherited from `@ToolProvider`:** `containerId`, `category`
- **Auto-injected:** `this.state` (StateManager)

**Only explicit requirements:**
- ✅ `elementId` (must match actual DOM element)
- ✅ `examples` (for AI natural language matching)

**Everything else? Automatic.**

---

## Scaling: Hierarchical Naming Prevents Collisions

**Problem:** What if you have multiple menus in the same container?

**Solution:** Hierarchical naming: `{container}-{feature}-{element}`

```typescript
// Main navigation menu
const MainMenuNames = {
  open: 'demo-simple-mainmenu-open',
  close: 'demo-simple-mainmenu-close',
  home: 'demo-simple-mainmenu-home',
};

// User profile menu (different feature)
const UserMenuNames = {
  open: 'demo-simple-usermenu-open',     // ✅ No collision!
  profile: 'demo-simple-usermenu-profile',
  settings: 'demo-simple-usermenu-settings',
};

// App settings menu (another feature)
const SettingsMenuNames = {
  open: 'demo-simple-settings-open',     // ✅ No collision!
  theme: 'demo-simple-settings-theme',
  language: 'demo-simple-settings-language',
};
```

**Benefits:**
- ✅ Clear ownership (which container + feature)
- ✅ No collisions (multiple menus, same container)
- ✅ Searchable (`grep "demo-simple-mainmenu-*"`)
- ✅ Scales to hundreds of components

**This is the same pattern React Router uses for route hierarchies.**

---

## Type Safety: Compile-Time Validation

### Level 1: TypeScript Structure Validation

```typescript
// Enforce naming pattern with template literal types
type ValidNameId = `${string}-${string}-${string}`;

const MenuNames: Record<string, ValidNameId> = {
  openButton: 'demo-menu-open',        // ✅ Valid
  badName: 'invalid',                  // ❌ TypeScript error!
};
```

### Level 2: ESLint Convention Enforcement

```javascript
// .eslintrc.js
rules: {
  'supernal-interface/name-format': ['error', {
    pattern: '{container}-{feature}-{element}',
    detectContainerFrom: 'file-path'
  }],
  'supernal-interface/no-duplicate-names': 'error'
}
```

**IDE experience:**
```typescript
const Names = {
  openButton: 'menu-open'  
  //          ^^^^^^^^^^
  //          ESLint: Name must start with 'demo-simple-'
  //          Quick fix: Change to 'demo-simple-menu-open'
};
```

### Level 3: CI/CD Uniqueness Validation

```bash
# Build fails if duplicate names found
npm run validate:names

# Output:
❌ DUPLICATE NAME: 'demo-menu-open'
   First: src/features/menu/menu.names.ts:5
   Duplicate: src/features/nav/nav.names.ts:12
   
   Fix: Use different feature name
   - demo-mainmenu-open
   - demo-navmenu-open
```

**Three layers of validation, zero runtime cost.**

---

## AI-Friendly: Natural Language Examples

**The pattern extends to AI automation:**

```typescript
@Tool(MenuNames.openButton, {
  examples: [
    'open menu',
    'show menu',
    'open',
    'menu open',
    'display menu'
  ]
})
async openMenu() {
  return this.state.merge({ menuOpen: true });
}
```

**User types:** "open menu"  
**AI matches:** `MenuNames.openButton` tool  
**Result:** Menu opens

**The name contract bridges human language and code.**

---

## Comparison to Alternatives

### vs. Magic Strings
| Aspect | Magic Strings | Name Contracts |
|--------|---------------|----------------|
| Type-safe | ❌ No | ✅ Yes |
| Refactor-safe | ❌ No | ✅ Yes |
| IDE autocomplete | ❌ No | ✅ Yes |
| Duplicate detection | ❌ Manual | ✅ Automatic |
| Runtime cost | ✅ Zero | ✅ Zero |

### vs. Pre-Generated IDs
| Aspect | Pre-Generation | Name Contracts |
|--------|---------------|----------------|
| Build complexity | ❌ High | ✅ Low |
| Dev experience | ❌ Delayed feedback | ✅ Immediate |
| Flexibility | ❌ Rigid | ✅ Flexible |
| Maintenance | ❌ Manual regen | ✅ Automatic |

### vs. Custom DSL (like Hyperlambda)
| Aspect | Custom DSL | Name Contracts |
|--------|-----------|----------------|
| Learning curve | ❌ High | ✅ Low (if you know Redux) |
| IDE support | ❌ Limited | ✅ Full |
| Syntax | ❌ Custom | ✅ Standard TypeScript |
| Tooling | ❌ Custom parser | ✅ ESLint + TypeScript |

**Name contracts win on simplicity: no new language, just constants.**

---

## Minification Safety: Why This Works

**Critical concern:** Do function names survive minification?

**Answer:** We don't rely on function names!

### Class Methods (Metadata Captured)
```typescript
@Tool(MenuNames.openButton, { examples: ['open'] })
async openMenu() {}  // ← Name captured at decorator-time (before minification)

// After minification:
async a() {}  // ← Function name changes, but metadata already stored!
```

### Standalone Functions (Explicit IDs)
```typescript
Tool({
  toolId: MenuNames.openButton,  // ← String literal 'demo-menu-open'
  examples: ['open']
})(function openMenu() {})

// After minification:
Tool({
  toolId: 'demo-menu-open',  // ← Preserved!
  examples: ['open']
})(function a() {})  // ← Function name changes, but we never use it!
```

**Both patterns are minification-safe because we use explicit string IDs, not function names.**

---

## Implementation: Backwards Compatible

**Old syntax still works (zero breaking changes):**

```typescript
// Old (verbose, still valid)
@Tool({
  elementId: MenuNames.openButton,
  name: 'Open Menu',
  aiEnabled: true,
  dangerLevel: 'safe',
  examples: ['open menu'],
})
async openMenu() { ... }

// New (concise, recommended)
@Tool(MenuNames.openButton, { examples: ['open menu'] })
async openMenu() { ... }
```

**Migration is optional, incremental, and non-breaking.**

---

## The Pattern in Action: Complete Feature

### File Structure
```
src/features/menu/
├── menu.names.ts       # Name contracts (single source of truth)
├── MenuWidget.tsx      # UI component
├── MenuTools.ts        # Automation tools
└── menu.spec.ts        # Tests
```

### 1. Names (Contract)
```typescript
// menu.names.ts
export const MenuNames = {
  container: 'demo-menu-container',
  openButton: 'demo-menu-open',
  closeButton: 'demo-menu-close',
} as const;
```

### 2. Component (UI)
```typescript
// MenuWidget.tsx
import { MenuNames } from './menu.names';

export function MenuWidget() {
  return (
    <div data-testid={MenuNames.container}>
      <button data-testid={MenuNames.openButton}>Open</button>
      <button data-testid={MenuNames.closeButton}>Close</button>
    </div>
  );
}
```

### 3. Tools (Behavior)
```typescript
// MenuTools.ts
import { Tool, ToolProvider } from '@supernal-interface/core';
import { MenuNames } from './menu.names';

@ToolProvider('demo-app')
export class MenuTools {
  @Tool(MenuNames.openButton, { examples: ['open menu'] })
  async open() {
    return this.state.merge({ menuOpen: true });
  }
  
  @Tool(MenuNames.closeButton, { examples: ['close menu'] })
  async close() {
    return this.state.merge({ menuOpen: false });
  }
}
```

### 4. Tests (Verification)
```typescript
// menu.spec.ts
import { test, expect } from '@playwright/test';
import { MenuNames } from './menu.names';

test('menu interaction', async ({ page }) => {
  await page.goto('/demo');
  
  // Open menu
  await page.locator(`[data-testid="${MenuNames.openButton}"]`).click();
  await expect(page.locator(`[data-testid="${MenuNames.container}"]`))
    .toBeVisible();
  
  // Close menu
  await page.locator(`[data-testid="${MenuNames.closeButton}"]`).click();
  await expect(page.locator(`[data-testid="${MenuNames.container}"]`))
    .not.toBeVisible();
});
```

**Total: 4 files, ~70 lines, complete feature with UI + behavior + tests.**

**Change a name? Update `menu.names.ts` once. Everything else stays in sync.**

---

## Why This Matters

### For React Developers
- ✅ Same pattern as Redux action types
- ✅ Reduces test brittleness
- ✅ IDE autocomplete for test IDs
- ✅ Refactor UI without breaking tests

### For QA Engineers
- ✅ Type-safe selectors
- ✅ No runtime surprises
- ✅ Easy to find what's testable
- ✅ Less maintenance burden

### For Framework Authors
- ✅ Proven pattern (Redux validates it)
- ✅ Zero runtime cost
- ✅ Works with existing tools (TypeScript, ESLint)
- ✅ Scales to large codebases

**This pattern solves a universal problem: keeping UI, behavior, and tests in sync.**

---

## Lessons Learned

### 1. **Don't Invent a New Language**
Use existing language features (constants, decorators, TypeScript).  
**Redux didn't invent new syntax - neither should you.**

### 2. **Patterns Should Feel Natural**
If developers say "this feels weird," the pattern is wrong.  
**Name contracts feel natural because they mirror mental models.**

### 3. **Validation Should Be Automatic**
Don't rely on discipline - use tools (TypeScript, ESLint, CI/CD).  
**Make the right thing easy, make the wrong thing hard.**

### 4. **Start with Constraints, Then Simplify**
We started verbose, then found what could be inferred.  
**80% reduction came from understanding what's truly required.**

### 5. **Backwards Compatibility Matters**
Old code should keep working while new patterns emerge.  
**Progressive enhancement, not breaking changes.**

---

## Conclusion: What's In a Name?

**A lot, it turns out.**

Names are the **contracts** that bind your UI, behavior, and tests together.

**Magic strings break those contracts.**  
**Name constants enforce them.**

This isn't a new language or a complex DSL. It's just:
- ✅ Constants (like Redux action types)
- ✅ TypeScript (for compile-time safety)
- ✅ ESLint (for convention enforcement)
- ✅ Applied to DOM IDs (instead of action types)

**The result:**
- 80% less boilerplate
- Type-safe refactoring
- Scales to hundreds of components
- Works with existing tools
- Zero runtime cost

**What's in a name?** Everything.

---

## Try It Yourself

```bash
npm install @supernal-interface/core
```

**Resources:**
- [GitHub](https://github.com/supernalintelligence/interface)
- [Documentation](https://interface.supernal.ai/docs)
- [Examples](https://interface.supernal.ai/examples)

**Questions? Comments?** Find me on [Twitter](https://twitter.com/your-handle) or [GitHub](https://github.com/your-username).

---

**Special thanks to the Redux, React Query, and Playwright teams for inspiring this pattern.**




## The Magic String Problem

Traditional UI testing relies on fragile string identifiers:

```typescript
// ❌ Brittle - typos break at runtime
await page.locator('[data-testid="chat-send-buton"]').click(); // Oops!

// ❌ No refactoring support
// If you rename the button, all tests break silently
```

One typo. Runtime failure. Hours of debugging.

## Name Contracts: The Solution

Name contracts are **typed string constants** that act as a single source of truth:

```typescript
// Define once
export const ChatNames = {
  sendButton: 'chat-send-button',
  input: 'chat-input',
  clearButton: 'chat-clear-button'
} as const;

// Use everywhere with autocomplete
<button data-testid={ChatNames.sendButton}>Send</button>

// Playwright tests get type safety
await page.locator(`[data-testid="${ChatNames.sendButton}"]`).click();

// AI tools reference the same constants
@Tool(ChatNames.sendButton, {
  examples: ['send message']
})
```

## Benefits

### 1. Compile-Time Validation
```typescript
// ✅ TypeScript catches typos instantly
<button data-testid={ChatNames.sendButon}> // Error: Property doesn't exist
```

### 2. Refactoring Safety
```typescript
// Change the name in ONE place
export const ChatNames = {
  sendButton: 'chat-message-send-button', // Updated
} as const;

// ALL references update automatically
// Tests, components, and AI tools stay in sync
```

### 3. IDE Autocomplete
Just type `ChatNames.` and get instant suggestions for all available elements.

### 4. No Runtime Errors
If it compiles, your IDs are correct.

## Hierarchical Naming

Prevent collisions with structured naming:

```typescript
// Pattern: {container}-{feature}-{element}

export const MainMenu = {
  open: 'demo-simple-mainmenu-open',
  close: 'demo-simple-mainmenu-close',
} as const;

export const UserMenu = {
  open: 'demo-simple-usermenu-open', // Different feature, no collision!
} as const;
```

## Real-World Example

### Before (Magic Strings)
```typescript
// Component
<button data-testid="submit-btn">Submit</button>

// Test
await page.locator('[data-testid="submit-btn"]').click();

// AI Tool
@Tool({
  elementId: 'submit-btn', // Might be different!
  examples: ['submit form']
})
```

**Problem:** Three different places. Easy to get out of sync.

### After (Name Contracts)
```typescript
// Names file (single source of truth)
export const FormNames = {
  submitButton: 'form-submit-button'
} as const;

// Component
<button data-testid={FormNames.submitButton}>Submit</button>

// Test  
await page.locator(`[data-testid="${FormNames.submitButton}"]`).click();

// AI Tool
@Tool(FormNames.submitButton, {
  examples: ['submit form']
})
```

**Solution:** One definition. Always in sync. Type-safe.

## Organization Patterns

### Centralized (Small Projects)
```typescript
// src/names/index.ts
export const ChatNames = { /* ... */ };
export const UserNames = { /* ... */ };
```

### Co-located (Large Projects)
```typescript
// src/features/chat/Chat.names.ts
export const ChatNames = { /* ... */ };

// src/features/user/User.names.ts  
export const UserNames = { /* ... */ };
```

Both work! Pick what fits your project size.

## Validation

Add a validation script to catch duplicates:

```typescript
// scripts/validate-names.ts
const allNames = Object.values({
  ...ChatNames,
  ...UserNames,
  // ... more
});

const duplicates = allNames.filter((name, i) => 
  allNames.indexOf(name) !== i
);

if (duplicates.length > 0) {
  throw new Error(`Duplicate IDs found: ${duplicates}`);
}
```

Run it in CI to prevent collisions.

## Migration Path

Incrementally adopt name contracts:

1. **Create names file** for one feature
2. **Update component** to use names
3. **Update tests** to use names
4. **Add AI tools** using names
5. **Repeat** for next feature

No big-bang rewrites required.

## Best Practices

✅ **DO:**
- Use kebab-case for IDs (`'chat-send-button'`)
- Use PascalCase for containers (`'ChatContainer'`)
- Export as `const` with `as const`
- Add JSDoc comments explaining usage

❌ **DON'T:**
- Use magic strings directly in components
- Create names inline
- Duplicate IDs across files
- Forget the `as const` (loses type safety!)

## Learn More

- See [Examples](/examples) for live demos
- Read [80% Less Boilerplate](/blog/80-percent-less-boilerplate) for decorator usage
- Check [GitHub](https://github.com/supernal-nova/supernal-interface) for full docs



Supernal Interface

Supernal Interface Blog

Latest Articles

Stop Duplicating Test Setup: The Background Pattern

Your Users Want It to Work. Your AI Is Getting in the Way.

Agentic UX: AI That Does, Not Tells

Building AI That Does: Architecture and Path Forward

AI-Woven Businesses: Accelerating the Value Cycle at Every Scale

The Birth of Supernal Interface: A Developer's Journey from Testing Problem to AI-Native Architecture

80% Less Boilerplate: The New @Tool Decorator

Making Any Application AI-Controllable: Introducing @supernal-interface/core

What's In a Name? Type-Safe UI Automation with Name Contracts

Type-Safe UI Testing Without the Pain

Supernal Interface