# Agent UI — Complete Documentation

> **@agent-ui/react** — 24 shadcn-style React components for building ChatGPT-class chat interfaces. WCAG AA, TypeScript, zero vendor lock-in.

**Version:** 0.1.0
**License:** MIT
**Repository:** https://github.com/agent-ui/agent-ui
**npm:** https://npmjs.com/@agent-ui/react
**Install:** `pnpm add @agent-ui/react`

---

## Table of Contents

1. [Installation](#installation)
2. [Core Chat Components](#core-chat-components)
   - [MessageBubble](#messagebubble)
   - [Composer](#composer)
   - [MessageList](#messagelist)
   - [ChatShell](#chatshell)
   - [useChat](#usechat)
3. [Display Components](#display-components)
   - [MarkdownContent](#markdowncontent)
   - [CodeBlock](#codeblock)
   - [Skeleton](#skeleton)
4. [Streaming Components](#streaming-components)
   - [StreamingText](#streamingtext)
   - [TypingIndicator](#typingindicator)
   - [StopButton](#stopbutton)
   - [CancelledBadge](#cancelledbadge)
5. [Agent / Tool Components](#agent--tool-components)
   - [ToolCallCard](#toolcallcard)
   - [ToolResult](#toolresult)
   - [ThinkingBlock](#thinkingblock)
   - [SourceCard](#sourcecard)
6. [Model / Provider Components](#model--provider-components)
   - [ModelPicker](#modelpicker)
   - [ProviderSelector](#providerselector)
7. [Input Components](#input-components)
   - [Button](#button)
   - [SuggestionChips](#suggestionchips)
8. [Chrome Components](#chrome-components)
   - [ConversationSidebar](#conversationsidebar)
   - [FeedbackButtons](#feedbackbuttons)
   - [BranchPicker](#branchpicker)
9. [Protocol](#protocol)
   - [dcmp](#dcmp)
10. [Demo Apps](#demo-apps)
11. [Architecture](#architecture)
12. [Accessibility](#accessibility)

---

## Installation

```bash
pnpm add @agent-ui/react
```

Each component is importable from its own subpath:

```tsx
import { MessageBubble } from "@agent-ui/react/message-bubble";
import { Composer } from "@agent-ui/react/composer";
import { useChat } from "@agent-ui/react/use-chat";
```

Or import everything from the barrel:

```tsx
import { Button, MessageBubble, ChatShell } from "@agent-ui/react";
```

---

## Core Chat Components

### MessageBubble

A chat message bubble with role-based styling. Supports user, assistant, and system roles.

**Import:** `@agent-ui/react/message-bubble`

```tsx
import { MessageBubble } from "@agent-ui/react/message-bubble";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `role` | `"user" \| "assistant" \| "system"` | required | Message role determines alignment and styling |
| `children` | `ReactNode` | required | Message content |
| `avatar?` | `string` | — | Avatar image URL |
| `name?` | `string` | — | Display name |
| `timestamp?` | `Date` | — | Message timestamp |
| `status?` | `"sending" \| "sent" \| "error"` | — | Delivery status indicator |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<MessageBubble
  role="assistant"
  name="Assistant"
  timestamp={new Date()}
  avatar="/bot-icon.png"
>
  Hello! How can I help you today?
</MessageBubble>
```

#### Accessibility

- Uses `<article>` with `role="article"`
- `aria-label` set to "User message" / "Assistant message" / "System message"
- Status text rendered visually for delivery state

---

### Composer

A compound component for chat input with multiple slots. Uses React Context for state sharing between sub-components.

**Import:** `@agent-ui/react/composer`

```tsx
import { Composer } from "@agent-ui/react/composer";
```

#### Composer Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onSend?` | `(text: string, attachments: File[]) => void` | — | Send handler |
| `disabled?` | `boolean` | — | Disables input and send |
| `className?` | `string` | — | Additional CSS classes |
| `children` | `ReactNode` | required | Slot components |

#### Slots

| Slot | Description |
|------|-------------|
| `Composer.Input` | Auto-resizing `textarea` with `@` mention detection, Enter to send, Shift+Enter for newline |
| `Composer.SendButton` | Send button, disabled when text is empty |
| `Composer.ProviderModelSlot` | Container for provider/model selector |
| `Composer.SkillSlot` | Container for skill selector |
| `Composer.AttachmentSlot` | Container for attachment preview |
| `Composer.SearchToggle` | Toggle button for web search (`aria-pressed`) |
| `Composer.ThinkingToggle` | Cycling toggle: off → low → medium → high → off |
| `Composer.MentionMenu` | Conditional `@` mention suggestions `listbox` |

#### Composer.Input Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `placeholder?` | `string` | `"Type a message..."` | Input placeholder |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<Composer onSend={(text) => console.log(text)}>
  <Composer.ProviderModelSlot>
    <ModelPicker models={models} />
  </Composer.ProviderModelSlot>
  <Composer.Input placeholder="Ask anything..." />
  <Composer.AttachmentSlot>
    <FilePreview />
  </Composer.AttachmentSlot>
  <Composer.SearchToggle />
  <Composer.ThinkingToggle efforts={["low", "high"]} />
  <Composer.SendButton />
</Composer>
```

#### SimpleComposer

A pre-composed variant with just Input + SendButton:

```tsx
<SimpleComposer onSend={(text) => console.log(text)} />
```

#### Accessibility

- Textarea has `role="textbox"` and `aria-label="Message composer"`
- Send button has `aria-label="Send message"`
- Toggle buttons use `aria-pressed` for state
- MentionMenu uses `role="listbox"` and `aria-label="Mention suggestions"`

---

### MessageList

ARIA live region container for chat messages with auto-scroll and empty state.

**Import:** `@agent-ui/react/message-list`

```tsx
import { MessageList } from "@agent-ui/react/message-list";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children?` | `ReactNode` | — | Message elements |
| `emptyMessage?` | `ReactNode` | `"Start a conversation"` | Empty state content |
| `isLoading?` | `boolean` | — | Shows loading state |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<MessageList>
  {messages.map(msg => (
    <MessageBubble key={msg.id} role={msg.role}>
      {msg.content}
    </MessageBubble>
  ))}
</MessageList>
```

#### Accessibility

- `role="log"` with `aria-live="polite"` for dynamic content announcements
- `aria-relevant="additions text"` for screen reader updates
- Focusable via `tabIndex={0}` for keyboard scrolling

---

### ChatShell

A pre-composed chat interface combining MessageList, MessageBubble, Composer, TypingIndicator, StopButton, and CancelledBadge.

**Import:** `@agent-ui/react/chat-shell`

```tsx
import { ChatShell } from "@agent-ui/react/chat-shell";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `messages` | `ChatMessage[]` | required | Array of chat messages |
| `isStreaming?` | `boolean` | — | Shows typing indicator + stop button |
| `error?` | `string \| null` | — | Shows error badge |
| `onSend?` | `(text: string) => void` | — | Send handler |
| `onStop?` | `() => void` | — | Stop generation handler |
| `placeholder?` | `string` | — | Composer placeholder |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
function App() {
  const { messages, isStreaming, error, send, stop } = useChat({
    onSend: async (text) => { /* API call */ return response; },
  });

  return (
    <ChatShell
      messages={messages}
      isStreaming={isStreaming}
      error={error}
      onSend={send}
      onStop={stop}
    />
  );
}
```

---

### useChat

React hook for chat state management.

**Import:** `@agent-ui/react/use-chat`

```tsx
import { useChat } from "@agent-ui/react/use-chat";
```

#### Types

```tsx
interface ChatMessage {
  id: string;
  role: "user" | "assistant" | "system";
  content: string;
  timestamp: Date;
  status?: "sending" | "sent" | "error";
  name?: string;
}

interface UseChatOptions {
  initialMessages?: ChatMessage[];
  onSend?: (message: string) => Promise<string>;
}
```

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| `messages` | `ChatMessage[]` | Current messages |
| `isStreaming` | `boolean` | True during response generation |
| `error` | `string \| null` | Error message if send failed |
| `send` | `(text: string) => Promise<void>` | Send a message, await response |
| `stop` | `() => void` | Stop current generation |
| `clear` | `() => void` | Clear all messages |

#### Example

```tsx
const { messages, isStreaming, send, stop, clear } = useChat({
  initialMessages: [{ id: "1", role: "assistant", content: "Hi!", timestamp: new Date() }],
  onSend: async (text) => {
    const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ text }) });
    return res.text();
  },
});
```

---

## Display Components

### MarkdownContent

Renders GFM markdown with XSS protection. Supports headings, bold, inline code, fenced code blocks, links (with target="_blank"), ordered/unordered lists, and blockquotes.

**Import:** `@agent-ui/react/markdown-content`

```tsx
import { MarkdownContent } from "@agent-ui/react/markdown-content";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `content` | `string` | required | Markdown string |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<MarkdownContent content="# Hello\n\nThis is **bold** and `inline code`.\n\n- List item 1\n- List item 2" />
```

#### Security

- Strips `<script>` and `<style>` tags (with content)
- Escapes HTML entities before rendering
- Links open in `target="_blank"` with `rel="noopener noreferrer"`
- Uses `dangerouslySetInnerHTML` with sanitized content

#### Accessibility

- Heading hierarchy preserved (h1–h6)
- Uses `prose prose-sm dark:prose-invert` typography classes

---

### CodeBlock

Syntax-highlighted code display with copy button, language badge, and optional line numbers.

**Import:** `@agent-ui/react/code-block`

```tsx
import { CodeBlock } from "@agent-ui/react/code-block";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `code` | `string` | required | Source code |
| `language` | `string` | required | Language label |
| `showLineNumbers?` | `boolean` | — | Show line numbers |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<CodeBlock
  code={`function hello() {\n  console.log("world");\n}`}
  language="typescript"
  showLineNumbers
/>
```

#### Accessibility

- `role="region"` with `aria-label="Code block: {language}"`
- Copy button uses `aria-label="Copy code"` / `"Copied"`
- Uses `navigator.clipboard.writeText()`
- 2-second "Copied!" feedback

---

### Skeleton

Loading placeholder with configurable number of lines.

**Import:** `@agent-ui/react/skeleton`

```tsx
import { Skeleton } from "@agent-ui/react/skeleton";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `lines?` | `number` | `3` | Number of skeleton lines |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<Skeleton lines={4} />
```

#### Accessibility

- `role="status"` with `aria-busy="true"`
- Screen reader text: "Loading"

---

## Streaming Components

### StreamingText

Animated token reveal with a blinking cursor for real-time streaming text display.

**Import:** `@agent-ui/react/streaming-text`

```tsx
import { StreamingText } from "@agent-ui/react/streaming-text";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `content` | `string` | required | Text to display |
| `cursor?` | `boolean` | `true` | Show blinking cursor |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<StreamingText content={partialResponse} />
```

#### Accessibility

- `role="status"` with `aria-live="polite"`
- Cursor element has `aria-hidden="true"`
- `prefers-reduced-motion` respected via Tailwind

---

### TypingIndicator

Bouncing dots indicating the AI assistant is generating a response.

**Import:** `@agent-ui/react/typing-indicator`

```tsx
import { TypingIndicator } from "@agent-ui/react/typing-indicator";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<TypingIndicator />
```

#### Accessibility

- `role="status"` with `aria-label="Assistant is typing"`
- Screen reader text via `.sr-only`

---

### StopButton

Button to abort ongoing generation.

**Import:** `@agent-ui/react/stop-button`

```tsx
import { StopButton } from "@agent-ui/react/stop-button";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onStop?` | `() => void` | — | Click handler |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<StopButton onStop={() => abortController.abort()} />
```

#### Accessibility

- `aria-label="Stop generating"` for screen readers

---

### CancelledBadge

Alert badge for cancelled or failed responses.

**Import:** `@agent-ui/react/cancelled-badge`

```tsx
import { CancelledBadge } from "@agent-ui/react/cancelled-badge";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `message?` | `string` | `"Response cancelled"` | Badge text |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<CancelledBadge message="Response stopped by user" />
```

#### Accessibility

- `role="alert"` for immediate screen reader announcement

---

## Agent / Tool Components

### ToolCallCard

Displays a tool invocation with status transitions (pending → running → success/error).

**Import:** `@agent-ui/react/tool-call-card`

```tsx
import { ToolCallCard } from "@agent-ui/react/tool-call-card";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | required | Tool name |
| `status` | `"pending" \| "running" \| "success" \| "error"` | required | Current status |
| `args` | `Record<string, unknown>` | required | Tool arguments |
| `result?` | `string` | — | Tool result (displayed in collapsible details) |
| `error?` | `string` | — | Error message |
| `duration?` | `number` | — | Execution time in ms |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<ToolCallCard
  name="search_web"
  status="success"
  args={{ query: "latest news" }}
  result='[{ "title": "News item" }]'
  duration={1234}
/>
```

#### Accessibility

- `role="region"` with `aria-label="Tool: {name}"`
- Status has `role="status"` and `aria-live="polite"`
- Collapsible args/result use `<details>/<summary>`

---

### ToolResult

Rendered tool output with a copy button.

**Import:** `@agent-ui/react/tool-result`

```tsx
import { ToolResult } from "@agent-ui/react/tool-result";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `result` | `string` | required | Tool result content |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<ToolResult result={JSON.stringify(data, null, 2)} />
```

#### Accessibility

- `role="region"` with `aria-label="Tool result"`
- Copy button with `aria-label="Copy result"` / `"Copied!"`

---

### ThinkingBlock

Expandable reasoning block using the native `<details>/<summary>` pattern.

**Import:** `@agent-ui/react/thinking-block`

```tsx
import { ThinkingBlock } from "@agent-ui/react/thinking-block";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | required | Reasoning content |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<ThinkingBlock>
  The user wants to know about React hooks. Let me explain the key ones...
</ThinkingBlock>
```

#### Accessibility

- `role="group"` with `aria-label="Agent reasoning"`
- Uses native `<details>/<summary>` (keyboard expandable)
- Dashed border visually distinguishes from regular content

---

### SourceCard

Citation card with title, URL, and optional snippet.

**Import:** `@agent-ui/react/source-card`

```tsx
import { SourceCard } from "@agent-ui/react/source-card";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | required | Source title |
| `url` | `string` | required | Source URL |
| `snippet?` | `string` | — | Brief excerpt |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<SourceCard
  title="React Documentation"
  url="https://react.dev"
  snippet="React is a JavaScript library for building user interfaces."
/>
```

#### Accessibility

- Rendered as an `<a>` with `target="_blank"` and `rel="noopener noreferrer"`
- Title truncation, URL truncation, 2-line clip for snippet

---

## Model / Provider Components

### ModelPicker

Searchable dropdown for AI model selection with keyboard navigation.

**Import:** `@agent-ui/react/model-picker`

```tsx
import { ModelPicker } from "@agent-ui/react/model-picker";
```

#### Types

```tsx
interface ModelOption {
  id: string;
  name: string;
  provider: string;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `models` | `ModelOption[]` | required | Available models |
| `selectedId?` | `string` | — | Currently selected model ID |
| `onChange?` | `(model: ModelOption) => void` | — | Selection handler |
| `placeholder?` | `string` | `"Select model"` | Placeholder text |
| `className?` | `string` | — | Additional CSS classes |
| `disabled?` | `boolean` | — | Disable interaction |

#### Example

```tsx
<ModelPicker
  models={[
    { id: "gpt-4", name: "GPT-4", provider: "OpenAI" },
    { id: "claude-3", name: "Claude 3", provider: "Anthropic" },
  ]}
  selectedId="gpt-4"
  onChange={(m) => console.log(m)}
/>
```

#### Accessibility

- `aria-haspopup="listbox"` and `aria-expanded` on trigger button
- `role="listbox"` on dropdown list
- `role="option"` with `aria-selected` on options
- Keyboard navigation: Arrow Up/Down, Enter, Escape
- Click-outside-to-close
- Search input with `"Search models..."` placeholder

---

### ProviderSelector

Pill-button group for selecting an AI provider.

**Import:** `@agent-ui/react/provider-selector`

```tsx
import { ProviderSelector } from "@agent-ui/react/provider-selector";
```

#### Types

```tsx
interface ProviderOption {
  id: string;
  name: string;
  logo?: string;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `providers` | `ProviderOption[]` | required | Available providers |
| `selectedId?` | `string` | — | Currently selected provider ID |
| `onChange?` | `(provider: ProviderOption) => void` | — | Selection handler |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<ProviderSelector
  providers={[
    { id: "openai", name: "OpenAI" },
    { id: "anthropic", name: "Anthropic" },
  ]}
  selectedId="openai"
  onChange={(p) => console.log(p)}
/>
```

#### Accessibility

- Each button uses `aria-pressed` for toggle state
- Active state: `border-primary bg-primary/10 text-primary`

---

## Input Components

### Button

Polymorphic button component using class-variance-authority for variants and sizes. Supports `asChild` to render as a different element via Radix Slot.

**Import:** `@agent-ui/react/button`

```tsx
import { Button } from "@agent-ui/react/button";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant?` | `"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"` | `"default"` | Visual style |
| `size?` | `"default" \| "sm" \| "lg" \| "icon"` | `"default"` | Button size |
| `asChild?` | `boolean` | `false` | Use Radix Slot to render as child element |
| `className?` | `string` | — | Additional CSS classes |
| *(all button HTML attributes)* | — | — | Native button props forwarded |

#### Example

```tsx
<Button variant="destructive" size="sm">Delete</Button>
<Button variant="outline" asChild>
  <a href="/cancel">Cancel</a>
</Button>
```

#### Variants

| Variant | Description |
|---------|-------------|
| `default` | Solid primary background |
| `destructive` | Red/destructive action |
| `outline` | Bordered, transparent background |
| `secondary` | Muted secondary background |
| `ghost` | No background, appears on hover |
| `link` | Text-only with underline on hover |

#### Sizes

| Size | Height | Padding |
|------|--------|---------|
| `default` | h-10 | px-4 py-2 |
| `sm` | h-9 | px-3 |
| `lg` | h-11 | px-8 |
| `icon` | h-10 w-10 | — |

---

### SuggestionChips

Clickable quick-reply suggestion pills shown to the user.

**Import:** `@agent-ui/react/suggestion-chips`

```tsx
import { SuggestionChips } from "@agent-ui/react/suggestion-chips";
```

#### Types

```tsx
interface SuggestionChip {
  label: string;
  value: string;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chips` | `SuggestionChip[]` | required | Suggestion items |
| `onSelect?` | `(chip: SuggestionChip) => void` | — | Selection handler |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<SuggestionChips
  chips={[
    { label: "Explain React hooks", value: "Explain React hooks" },
    { label: "Write a poem", value: "Write a poem about AI" },
  ]}
  onSelect={(chip) => send(chip.value)}
/>
```

#### Accessibility

- `role="group"` with `aria-label="Suggested prompts"`
- Buttons styled as rounded pills

---

## Chrome Components

### ConversationSidebar

Navigation sidebar showing conversation history with a new chat button.

**Import:** `@agent-ui/react/conversation-sidebar`

```tsx
import { ConversationSidebar } from "@agent-ui/react/conversation-sidebar";
```

#### Types

```tsx
interface Conversation {
  id: string;
  title: string;
  updatedAt: Date;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `conversations` | `Conversation[]` | required | Conversation list |
| `activeId?` | `string` | — | Active conversation ID |
| `onSelect?` | `(conv: Conversation) => void` | — | Selection handler |
| `onNew?` | `() => void` | — | New chat handler |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<ConversationSidebar
  conversations={conversations}
  activeId={activeId}
  onSelect={(c) => setActiveId(c.id)}
  onNew={() => startNewChat()}
/>
```

#### Accessibility

- `<nav>` with `aria-label="Conversation history"`
- `role="list"` for items
- Empty state: "No conversations yet"

---

### FeedbackButtons

Thumbs up/down buttons for message feedback, visible on hover.

**Import:** `@agent-ui/react/feedback-buttons`

```tsx
import { FeedbackButtons } from "@agent-ui/react/feedback-buttons";
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onThumbsUp?` | `() => void` | — | Thumbs up handler |
| `onThumbsDown?` | `() => void` | — | Thumbs down handler |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<FeedbackButtons onThumbsUp={() => rate("good")} onThumbsDown={() => rate("bad")} />
```

#### Accessibility

- `role="radiogroup"` with `aria-label="Message feedback"`
- Each button has `aria-label="Thumbs up"` / `"Thumbs down"`

---

### BranchPicker

Tab switcher for navigating conversation branches.

**Import:** `@agent-ui/react/branch-picker`

```tsx
import { BranchPicker } from "@agent-ui/react/branch-picker";
```

#### Types

```tsx
interface Branch {
  id: string;
  label: string;
}
```

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `branches` | `Branch[]` | required | Branch tabs |
| `activeId?` | `string` | — | Active branch ID |
| `onSelect?` | `(branch: Branch) => void` | — | Selection handler |
| `className?` | `string` | — | Additional CSS classes |

#### Example

```tsx
<BranchPicker
  branches={[
    { id: "main", label: "Main" },
    { id: "v2", label: "Variant 2" },
  ]}
  activeId="main"
  onSelect={(b) => switchBranch(b.id)}
/>
```

#### Accessibility

- `role="tablist"` with `aria-label="Conversation branches"`
- Each button has `role="tab"` and `aria-selected`

---

## Protocol

### dcmp

Deterministic Component Message Protocol — Zod schemas for typed, component-based chat messages. Enables structured content rendering without LLM-generated HTML.

**Import:** `@agent-ui/react/dcmp`

```tsx
import * as dcmp from "@agent-ui/react/dcmp";
```

#### Schemas

| Schema | Type | Description |
|--------|------|-------------|
| `textPartSchema` | `{ type: "text", text: string }` | Plain text part |
| `componentPartSchema` | `{ type: "component", name: string, props: Record<string, unknown>, catalogVersion?: string }` | Component reference |
| `toolCallPartSchema` | `{ type: "tool_call", toolCallId: string, toolName: string, args: Record<string, unknown> }` | Tool invocation |
| `toolResultPartSchema` | `{ type: "tool_result", toolCallId: string, result: unknown }` | Tool result |
| `mediaPartSchema` | `{ type: "media", mimeType: string, url: string, alt?: string }` | Media (image, video, etc.) |
| `messagePartSchema` | Discriminated union of the above | Any message part |
| `chatMessageSchema` | `{ id, role, content: messagePartSchema[], catalogVersion, createdAt }` | Full chat message |

#### Utilities

| Function | Description |
|----------|-------------|
| `validateComponentRefs(name, catalogVersion, componentCatalog)` | Validates component exists in catalog |
| `compareVersions(a, b)` | Semver comparison |
| `makeMessageId(prefix?)` | Generate unique message ID |
| `makeToolCallId()` | Generate unique tool call ID |
| `makeCatalogVersion()` | Generate catalog version string |
| `prepareComponent(name, props, catalogVersion)` | Prepare component for rendering |

---

## Demo Apps

### ChatGPT Clone

Full-featured chat application demonstrating all components in a real chat interface.

**URL:** https://agent-ui.frontendx.dev/chat

Features:
- Message list with streaming responses
- Tool calls with status transitions
- Thinking/reasoning blocks
- Code blocks with copy
- Source citations
- Model/Provider selection
- Suggestion chips
- Conversation sidebar

### Popup Widget

Floating chat widget (bottom-right) that expands to a full chat panel.

**URL:** https://agent-ui.frontendx.dev/popup

Features:
- Minimal UI: chat bubble → expand → full panel
- Same component library, different shell
- Ready for embedding on any website

---

## Architecture

### Package Structure

```
@agent-ui/react/
├── button.tsx                    ← Polymorphic button
├── card.tsx                      ← Card (internal demo use)
├── code.tsx                      ← Inline code (internal demo use)
├── message-bubble.tsx            ← Chat message bubble
├── composer.tsx                  ← Compound composer + SimpleComposer
├── message-list.tsx              ← ARIA live region
├── chat-shell.tsx                ← Composed chat shell
├── markdown-content.tsx          ← GFM markdown renderer
├── code-block.tsx                ← Syntax-highlighted code
├── streaming-text.tsx            ← Animated streaming text
├── typing-indicator.tsx          ← Bouncing dots
├── skeleton.tsx                  ← Loading placeholder
├── stop-button.tsx               ← Abort button
├── cancelled-badge.tsx           ← Cancellation alert
├── tool-call-card.tsx            ← Tool invocation card
├── tool-result.tsx               ← Tool output
├── thinking-block.tsx            ← Expandable reasoning
├── source-card.tsx               ← Citation card
├── model-picker.tsx              ← Searchable model dropdown
├── provider-selector.tsx         ← Provider pill selector
├── suggestion-chips.tsx          ← Quick-reply pills
├── feedback-buttons.tsx          ← Thumbs up/down
├── conversation-sidebar.tsx      ← History sidebar
├── branch-picker.tsx             ← Tab switcher
├── use-chat.ts                   ← Chat state hook
├── index.ts                      ← Barrel exports
├── lib/utils.ts                  ← cn() utility
└── dcmp/                         ← DCMP protocol
    ├── index.ts
    ├── types.ts
    ├── schemas.ts
    ├── validate.ts
    └── prepare.ts
```

### Data Flow

```
apps/web (TanStack Start SSG showcase)
    │ import from
    ▼
@agent-ui/react (packages/ui)
    │
    ├── Components accept props only (no provider coupling)
    ├── Compound components use React Context
    └── lib/utils.ts → cn() (clsx + tailwind-merge)
```

### Dependencies

- **Runtime:** React 19, class-variance-authority, tailwind-merge, clsx, @radix-ui/react-slot, zod
- **Dev:** TypeScript, Vitest, Testing Library, jest-axe, Tailwind CSS

---

## Accessibility

All components meet WCAG 2.2 Level AA standards. Key patterns:

| Pattern | Components | Implementation |
|---------|-----------|----------------|
| Live regions | MessageList, StreamingText, TypingIndicator, ToolCallCard | `aria-live="polite"`, `role="log"`, `role="status"` |
| Alerts | CancelledBadge | `role="alert"` |
| Keyboard navigation | ModelPicker, Composer | Arrow keys, Enter, Escape, Tab |
| Focus management | MessageList, Composer | `tabIndex`, auto-focus |
| ARIA labels | All interactive | `aria-label`, `aria-pressed`, `aria-expanded`, `aria-selected` |
| Roles | List, Tab, Option, Group | `role="listbox"`, `role="tablist"`, `role="tab"`, `role="option"` |
| Reduced motion | StreamingText, Skeleton | Tailwind `animate-*` respects `prefers-reduced-motion` |
| Color contrast | All text | 4.5:1 minimum via CSS variable theme |
| Focus indicators | All interactive | `focus-visible:ring-2` |
| Screen reader text | TypingIndicator, Skeleton | `.sr-only` utility |

### ARIA Patterns by Component

| Component | ARIA Pattern |
|-----------|-------------|
| MessageList | `role="log" aria-live="polite" aria-relevant="additions text"` |
| MessageBubble | `role="article" aria-label` |
| Composer.Input | `role="textbox" aria-label="Message composer"` |
| Composer.MentionMenu | `role="listbox" aria-label="Mention suggestions"` |
| ModelPicker trigger | `aria-haspopup="listbox" aria-expanded` |
| ModelPicker list | `role="listbox"`, options: `role="option" aria-selected` |
| ToolCallCard | `role="region" aria-label`, status: `role="status"` |
| ThinkingBlock | `role="group" aria-label="Agent reasoning"` |
| Skeleton | `role="status" aria-busy="true"` |
| FeedbackButtons | `role="radiogroup" aria-label="Message feedback"` |
| BranchPicker | `role="tablist"`, tabs: `role="tab" aria-selected` |
| ConversationSidebar | `<nav aria-label="Conversation history">`, `role="list"` |
| CancelledBadge | `role="alert"` |
| StreamingText | `role="status" aria-live="polite"` |

---

## Quick Start

```tsx
import { ChatShell } from "@agent-ui/react/chat-shell";
import { useChat } from "@agent-ui/react/use-chat";

function App() {
  const { messages, isStreaming, error, send, stop } = useChat({
    onSend: async (text) => {
      const res = await fetch("/api/chat", {
        method: "POST",
        body: JSON.stringify({ message: text }),
      });
      return res.text();
    },
  });

  return (
    <div className="h-screen">
      <ChatShell
        messages={messages}
        isStreaming={isStreaming}
        error={error}
        onSend={send}
        onStop={stop}
      />
    </div>
  );
}
```