---
phase: 22
slug: agent-streaming
status: draft
shadcn_initialized: true
preset: new-york / neutral / cssVariables
created: 2026-04-01
revised: 2026-04-01
---

# Phase 22 — UI Design Contract

> Visual and interaction contract for frontend phases. Generated by gsd-ui-researcher, verified by gsd-ui-checker.

---

## Design System

| Property | Value |
|----------|-------|
| Tool | shadcn (new-york style) — carried forward from Phase 21 |
| Preset | new-york, baseColor: neutral, cssVariables: true |
| Component library | Radix UI (via shadcn) |
| Icon library | lucide-react (^0.574.0) |
| Font | System UI stack (inherited from existing CSS — no custom font declared) |

Source: `ui/components.json`, `ui/src/index.css` (unchanged from Phase 21)

**shadcn components already installed (usable without install):**
`Avatar`, `Badge`, `Button`, `Card`, `Checkbox`, `Command`, `Dialog`, `DropdownMenu`, `Input`, `Popover`, `ScrollArea`, `Select`, `Separator`, `Sheet`, `Skeleton`, `Tabs`, `Textarea`, `Tooltip`

**New shadcn components for this phase (install before use):**
None required — `Select` and `DropdownMenu` cover the AgentSelector. `Avatar` covers the agent badge avatar slot.

**New npm packages for this phase (not shadcn registry):**
- `virtua` ^0.49.0 — virtualized list for ChatMessageList (PERF-03). Install: `pnpm --filter @paperclipai/ui add virtua`
- Server: `openai` or `ai` SDK — LLM streaming. See RESEARCH.md for provider resolution. Not a UI registry concern.

---

## Focal Point

The primary focal point of Phase 22 is the **streaming message in progress** — specifically the assistant message bubble that receives incoming tokens. While tokens arrive, the bubble is the only animated element on screen. The Stop button (rendered inside `ChatInput` in place of Send) is the secondary focal point during streaming.

---

## Spacing Scale

Carried forward from Phase 21 without change. Source: 21-UI-SPEC.md.

| Token | Value | Usage |
|-------|-------|-------|
| xs | 4px | Icon gaps (`gap-1`), inline icon + label spacing |
| sm | 8px | Compact padding inside list items, badge padding, button icon padding |
| sm+ | 12px | Conversation list item vertical padding (`py-3`) — named exception, follows `EntityRow` pattern |
| md | 16px | Default element padding (`p-4`), chat panel header padding |
| lg | 24px | Section padding on desktop (`p-6`) |
| xl | 32px | Gap between major UI zones |
| 2xl | 48px | Empty-state vertical padding (`py-12`) |
| 3xl | 64px | Page-level section breaks (not applicable in panel context) |

**Phase 22 additions:**

| Token | Value | Usage |
|-------|-------|-------|
| agent-badge-gap | 8px (sm) | Gap between agent avatar and agent name in `ChatAgentBadge` |
| agent-avatar | 20px | Width and height of the agent avatar circle in `ChatAgentBadge` |
| streaming-dot | 8px (sm) | Width and height of the pulsing streaming cursor dot |

Exceptions (unchanged from Phase 21):
- `sm+` (12px): conversation list item vertical padding only.
- Touch targets: `min-height: 44px` on coarse-pointer devices (global `index.css` rule).
- Chat input bottom padding: `pb-[calc(env(safe-area-inset-bottom)+16px)]` on mobile.

---

## Typography

Carried forward from Phase 21 without change. Source: 21-UI-SPEC.md.

Two weights only: regular (400) and semibold (600).

| Role | Size | Weight | Line Height | Tailwind Class |
|------|------|--------|-------------|----------------|
| Body | 14px | 400 (regular) | 1.5 | `text-sm` |
| Label | 13px | 400 (regular) | 1.4 | `text-[13px]` |
| Heading | 16px | 600 (semibold) | 1.25 | `text-base font-semibold` |
| Meta / Timestamp | 12px | 400 (regular) | 1.4 | `text-xs text-muted-foreground` |

**Phase 22 typography additions:**
- Agent name in `ChatAgentBadge`: Label (13px / regular / `text-muted-foreground`). Not semibold — the name is contextual metadata, not a heading.
- Slash command suggestion label in the command popover: Body (14px / regular).
- Agent selector trigger label: Label (13px / regular), truncated with `truncate`.
- Stop button label (text inside ChatInput during streaming): Body (14px / regular), no special weight. The Square icon carries the visual signal.

Rules (unchanged):
- Agent message content inside `ChatMarkdownMessage` uses `prose prose-sm` — do not override.
- The chat input `Textarea` uses Body (14px / regular).
- Timestamps use Meta (12px / regular / muted-foreground), visible on hover only.

---

## Color

All colors reference CSS custom properties already declared for all three themes in `ui/src/index.css`. Never hard-code hex values. Source: 21-UI-SPEC.md + RESEARCH.md Pattern 6.

| Role | CSS Variable | 60/30/10 | Usage |
|------|-------------|----------|-------|
| Dominant surface | `--background` | 60% | Chat panel background, message list background |
| Secondary surface | `--card` / `--sidebar` | 30% | Conversation list sidebar, code block container |
| Accent | `--primary` | 10% | Send button, active conversation border-left, filled pin icon |
| Muted | `--muted` | — | Input background, empty state icon container, streaming cursor background |
| Muted foreground | `--muted-foreground` | — | Placeholder text, timestamps, agent name in badge, secondary labels |
| Destructive | `--destructive` | — | Delete conversation action only (carried from Phase 21) |
| Border | `--border` | — | Dividers, chat panel border, input border |

Accent (`--primary`) reserved for exactly these elements (Phase 22 carries Phase 21 list, no additions):
1. The "Send message" primary action button background
2. The active conversation in the sidebar (left-border indicator)
3. Filled pin icon on pinned conversations

**Phase 22 agent colors — CSS custom properties (THEME-03):**

Agent role colors use `--chart-1` through `--chart-5` CSS custom properties already declared for all three themes in `ui/src/index.css`. These are the ONLY variables permitted for agent identity coloring. Implementation via `bg-[hsl(var(--chart-N))]` Tailwind utility.

| Agent Role | CSS Variable | Tailwind Class |
|------------|-------------|----------------|
| `ceo` | `--chart-1` | `bg-[hsl(var(--chart-1))]` |
| `pm` | `--chart-2` | `bg-[hsl(var(--chart-2))]` |
| `engineer` | `--chart-3` | `bg-[hsl(var(--chart-3))]` |
| `general` / `generalist` | `--chart-4` | `bg-[hsl(var(--chart-4))]` |
| `brainstormer` | `--chart-5` | `bg-[hsl(var(--chart-5))]` |
| Unknown / fallback | `--muted` | `bg-muted` |

Text on all agent color backgrounds: `text-white` (sufficient contrast on all three themes per chart variable definitions). Do not use `text-foreground` — the chart variables are saturated colors and require white text.

**Stop button color:** The Stop button uses `variant="destructive"` from shadcn Button — it uses `--destructive` background with destructive-foreground text. This signals urgency (cancel an ongoing action) without being confused with a data-destructive action.

---

## Component Inventory

### Modified from Phase 21

#### ChatInput (modified)
- Existing behavior fully preserved (auto-resize, Enter/Shift+Enter, Escape)
- **Addition: Stop button during streaming**
  - When `streaming === true`: Send button is replaced by a Stop button
  - Stop button: `variant="destructive"`, icon-only (`Square` from lucide, 16px), `aria-label="Stop generation"`
  - Stop button is NEVER disabled — it must always be clickable during streaming
  - Layout: same position as Send button (flex row right of Textarea). Dimensions identical to Send button so the layout does not shift when toggling.
- **Addition: Slash command popover**
  - Trigger: when input value starts with `/` and matches a known prefix
  - Popover appears above the input (`<Popover>` with `side="top" align="start"`)
  - Contents: list of matching commands using `<Command>` component (already installed)
  - Command item format: `/{command}` label (14px / regular) + destination agent name (13px / muted-foreground)
  - Dismiss: Escape, backspace past `/`, or clicking away
  - Max 5 items displayed; no scrolling inside the popover
  - Commands list (hardcoded):

| Command | Label | Agent Destination |
|---------|-------|-------------------|
| `/brainstorm` | Brainstorm an idea | Brainstormer |
| `/ask-pm` | Ask the PM | PM |
| `/ask-engineer` | Ask the Engineer | Engineer |
| `/task` | Create a task | Engineer |
| `/search` | Search conversations | Generalist |

- **Addition: @mention popover**
  - Trigger: when input value starts with `@` and has at least 1 character following
  - Same `<Popover>` + `<Command>` pattern as slash commands
  - Contents: filtered list of agent names from `useAgents()` cache
  - Item format: `AgentBadge` (20px avatar) + agent name (14px / regular)
  - Dismiss: same as slash command popover
- **No change to aria-label, placeholder, or keyboard shortcuts**

#### ChatMessageList (modified)
- **Replace flat div with `<VList>` from `virtua` (PERF-03)**
  - Drop `<ScrollArea>` wrapper — `virtua` manages scroll internally
  - `<VList style={{ flex: 1 }} ref={listRef}>` wraps all message items
  - Auto-scroll to bottom logic: `isAtBottom` state derived from VList `onScroll` callback — only auto-scroll when `isAtBottom === true`
  - Threshold: `isAtBottom = scrollOffset + clientHeight >= scrollSize - 80` (80px tolerance)
- **Addition: streaming optimistic message**
  - When `streaming === true`: append a synthetic `ChatMessageItem` at bottom with:
    - `role: "assistant"`
    - `content: partialContent` (from `useStreamMessage` hook)
    - `isStreaming: true` prop
  - Streaming indicator: a pulsing dot (`w-2 h-2 rounded-full bg-muted animate-pulse`) appended after the last rendered markdown token
  - The streaming item has no timestamp (omit timestamp row entirely while `isStreaming`)
  - The streaming item has no action buttons (edit/retry are not shown on in-progress messages)
- **Addition: message action buttons (edit/retry) on existing assistant messages**
  - Visible on hover only (`opacity-0 group-hover:opacity-100 transition-opacity duration-150`)
  - Position: below the message bubble, right-aligned (`flex justify-end gap-1 mt-1`)
  - Retry button: `variant="ghost" size="icon-sm"`, icon `RotateCcw` (14px), `aria-label="Retry response"`
  - Edit button: on user messages only — `variant="ghost" size="icon-sm"`, icon `Pencil` (14px), `aria-label="Edit message"`
  - While streaming is in progress (`streaming === true`): hide all action buttons on all messages (prevent conflicting actions)
- **Addition: `ChatAgentBadge` above each assistant message bubble**
  - See new component spec below

#### ChatPanel (modified)
- **Addition: `AgentSelector` in the panel header**
  - Position: right side of the header bar (flex row, `ml-auto` before close button)
  - See new component spec below
- Header height remains 48px — AgentSelector must fit within this height
- No other structural changes

### New Components for Phase 22

#### ChatAgentBadge
- Rendered above each assistant message bubble in `ChatMessageList`
- Layout: `flex items-center gap-2 mb-1` (8px gap — `sm` token; 4px margin-bottom)
- Avatar: 20px circle (`w-5 h-5 rounded-full flex items-center justify-center`), background color from `agentRoleColorClass(agent.role)` (see Color section)
  - If agent has an `icon` value: render `AgentIcon` at 12px size inside the circle
  - If no icon: render the first letter of `agent.name` at `text-[10px] font-semibold text-white`
- Agent name: Label (13px / regular / `text-muted-foreground`), truncated at 120px max-width
- Source: `agent.name` and `agent.role` resolved client-side from `useAgents(companyId)` cache keyed by `agentId` on the message
- Fallback when agent not found in cache: show `Bot` icon (lucide, 12px) + "Agent" as name, `bg-muted` background — never throw or show nothing

#### AgentSelector
- Location: ChatPanel header, right side before the close button
- Component: `<Select>` (shadcn) with a custom trigger styled to match the 48px header height
- Trigger: compact, `h-8 px-2 py-1`, shows current agent avatar (16px, same color circle pattern as ChatAgentBadge) + agent name Label (13px / regular)
- Dropdown items: each agent as a `<SelectItem>`, showing `ChatAgentBadge`-style avatar (16px) + agent name (14px / regular) in a flex row
- Current agent persisted to `conversation.agentId` via `PATCH /api/conversations/:id` — this is the per-conversation default agent
- Empty state: if no agents available, show a single disabled item "No agents configured"
- Loading state: `<Skeleton className="h-8 w-28" />` while agents are fetching
- Tooltip on the selector trigger: "Active agent for this conversation" (shown on hover via `<Tooltip>`)

---

## Interaction Contract

### Streaming lifecycle (CHAT-01, CHAT-12)

| State | ChatInput | ChatMessageList |
|-------|-----------|-----------------|
| Idle | Send button enabled; textarea enabled | No streaming indicator |
| Sending user message | Send button disabled, `Loader2` spin icon, textarea disabled | User message appears immediately (optimistic insert) |
| Streaming in progress | **Stop button** (`variant="destructive"`, Square icon); textarea disabled | Streaming assistant message at bottom with pulsing dot; action buttons hidden on all messages |
| Stop clicked | Stop button transitions briefly to `Loader2` for 200ms, then reverts to Send | Streaming message remains in list with last received content (partial); pulsing dot removed; action buttons re-appear |
| Stream complete | Reverts to Send button; textarea re-enabled and focused | Streaming indicator removed; persisted message replaces optimistic; `RotateCcw` + other action buttons appear on hover |
| Stream error | Reverts to Send button; textarea re-enabled; error toast fires | Streaming message removed from list |

### Message editing inline (CHAT-10)

- Trigger: click `Pencil` icon on hover over any user message
- The user message bubble text is replaced with a `<Textarea>` pre-filled with the original content
- Min height: 40px; max height: 120px; `variant: none` (no extra border — let the bubble container provide the boundary)
- Confirm: Enter (without Shift), or a "Regenerate" button (`variant="default"`, 14px label "Regenerate") that appears below the edit area
- Cancel: Escape — restores original content, hides textarea
- On submit: POST the edited content to `PUT /api/messages/:id`; this re-triggers the stream from that point; messages after the edited message are NOT removed from the UI in Phase 22 (branching is Phase 24 scope)
- While editing: all other action buttons in the list are hidden

### Response regeneration (CHAT-11)

- Trigger: click `RotateCcw` on hover over any existing assistant message
- Confirmation: none — immediate action
- Behavior: re-invokes the stream route for that message position; a new streaming message appears below the existing one; the existing assistant message is retained in the list until the new stream completes, at which point the existing message is replaced with the new one in-place
- While regenerating: Stop button active in ChatInput; all other action buttons hidden

### Agent selector interaction (CHAT-08)

- Trigger: open `AgentSelector` dropdown in ChatPanel header
- Selection: clicking an agent item immediately calls `PATCH /api/conversations/:id` with `{ agentId }` and updates local state optimistically
- Error: if PATCH fails, revert to previous agent selection and show a toast: "Couldn't update agent. Try again."
- The selected agent takes effect on the next message sent — it does NOT retroactively re-label past messages

### Slash command and @mention routing (INPUT-05, INPUT-06)

- Slash command: when ChatInput contains `/ask-engineer Hello`, the command prefix is parsed before send; the message body "Hello" is sent with `targetRole: "engineer"` as a per-message agent override; the conversation's `agentId` is NOT changed
- @mention: same per-message override behavior; `@engineer Hello` extracts `targetName: "engineer"` and resolves to the matching agent by name (case-insensitive)
- If a command is recognized but the target agent does not exist in `useAgents()` cache: show inline toast "No engineer agent found. Message sent to active agent." and fall back to `conversation.agentId`
- If the `/` prefix does not match any known command: send as plain text (no routing, no error)
- Popover keyboard navigation: arrow keys move selection, Enter selects, Tab accepts, Escape dismisses

### Auto-scroll behavior during streaming (PERF-03)

- When `isAtBottom === true` at the time a new token arrives: call `listRef.current?.scrollToIndex(allMessages.length - 1, { smooth: false })` to keep bottom in view
- When user has scrolled up (isAtBottom === false): do NOT scroll; show a "Jump to bottom" button: `<Button variant="outline" size="sm">` with a `ChevronDown` icon (16px), positioned `absolute bottom-20 right-4 z-10` relative to the message list container. Clicking it scrolls to bottom and sets `isAtBottom = true`
- "Jump to bottom" button disappears immediately when `isAtBottom === true`

---

## Copywriting Contract

Source: Claude's discretion (discuss phase skipped). Follows Phase 21 tone: direct, lowercase preference, no corporate language.

| Element | Copy |
|---------|------|
| Stop button tooltip | "Stop generation" |
| Retry button tooltip | "Retry response" |
| Edit button tooltip (on user message) | "Edit message" |
| Edit confirm button | "Regenerate" |
| Edit cancel instruction | Press Escape to cancel |
| Streaming indicator aria-label | "Response streaming" |
| Agent selector tooltip | "Active agent for this conversation" |
| Agent selector empty | "No agents configured" |
| Jump to bottom button aria-label | "Jump to bottom" |
| Slash command popover heading | (none — no heading; list items self-describe) |
| @mention popover heading | (none — no heading; agent names self-describe) |
| Error: stream failed | "Response failed. Try again." |
| Error: edit failed | "Couldn't update message. Try again." |
| Error: agent update failed | "Couldn't update agent. Try again." |
| Error: target agent not found | "No {role} agent found. Message sent to active agent." |
| Error: retry failed | "Retry failed. Try again." |
| Toast on stop (if partial message not saved) | (no toast — stopping is expected; silent is correct) |

No new destructive actions in Phase 22. The Stop generation action is a cancellation, not a destructive action — no confirmation required.

---

## Accessibility Contract

Carried forward from Phase 21. Phase 22 additions:

- `ChatAgentBadge` avatar: `aria-hidden="true"` (decorative — the agent name provides the text label)
- Agent name in `ChatAgentBadge`: `aria-label="Agent: {agent.name}"` on the containing span
- `AgentSelector` trigger: `aria-label="Active agent: {currentAgent.name}"` (dynamically updated)
- Stop button: `aria-label="Stop generation"`, never `aria-disabled` — always interactive during streaming
- Streaming message container: `aria-live="off"` — do NOT use `aria-live="polite"` on the partial content container; the completed persisted message in the `role="log"` container is sufficient for screen reader announcement. Streaming token-by-token announcement would be noisy.
- Edit textarea: `aria-label="Edit message"`, `aria-multiline="true"`
- "Jump to bottom" button: `aria-label="Jump to bottom"`, `aria-hidden="true"` when not visible
- Slash command popover: `role="listbox"`, each item `role="option"`, `aria-selected` on highlighted item
- @mention popover: same `role="listbox"` pattern

---

## Animation Contract

All animations use Tailwind utilities or existing CSS transitions. No new animation libraries.

Carried from Phase 21:

| Element | Animation | Duration | Easing |
|---------|-----------|----------|--------|
| Chat panel open/close | `transition-[width]` | 100ms | `ease-out` |
| Conversation list item hover | `transition-colors` | 150ms | Tailwind default |

Phase 22 additions:

| Element | Animation | Duration | Easing |
|---------|-----------|----------|--------|
| Streaming cursor dot | `animate-pulse` (Tailwind) | continuous | built-in |
| Message action buttons (edit/retry/stop) | `transition-opacity` | 150ms | `ease-out` |
| Send → Stop button swap | `transition-opacity` | 100ms | `ease-out` (cross-fade; layout does NOT shift) |
| "Jump to bottom" button appear/disappear | `transition-opacity` | 150ms | `ease-out` |
| AgentSelector dropdown open | Radix `<Select>` built-in animation | 150ms | Radix default |
| Slash/mention popover open | `transition-opacity duration-100` | 100ms | `ease-out` |

No enter/exit animations for new streaming tokens — tokens append directly with no animation. This keeps PERF-02 (100ms latency) achievable without layout thrashing.

---

## Registry Safety

| Registry | Blocks Used | Safety Gate |
|----------|-------------|-------------|
| shadcn official | All components from Phase 21 + `Command`, `Popover`, `Select` (already installed) | not required |
| Third-party registries | none | not applicable |

`virtua` is installed via npm (not shadcn registry). npm packages are not subject to the shadcn registry safety gate.

No third-party shadcn registry blocks are declared for this phase.

---

## Checker Sign-Off

- [ ] Dimension 1 Copywriting: PASS
- [ ] Dimension 2 Visuals: PASS
- [ ] Dimension 3 Color: PASS
- [ ] Dimension 4 Typography: PASS
- [ ] Dimension 5 Spacing: PASS
- [ ] Dimension 6 Registry Safety: PASS

**Approval:** pending