nexus/.planning/phases/22-agent-streaming/22-UI-SPEC.md

phase	slug	status	shadcn_initialized	preset	created
22	agent-streaming	draft	true	new-york / neutral / css-variables	2026-04-01

Phase 22 — UI Design Contract

Visual and interaction contract for Phase 22: Agent Streaming. Generated by gsd-ui-researcher. Verified by gsd-ui-checker.

---

Design System

Property	Value	Source
Tool	shadcn/ui	ui/components.json — unchanged from Phase 21
Style	new-york	ui/components.json
Base color	neutral	ui/components.json
CSS variables	true	ui/components.json
Component library	Radix UI (via shadcn new-york)	ui/components.json
Icon library	lucide-react ^0.574.0	ui/components.json
Font	System UI (font-sans, inherited)	ui/src/index.css

Existing shadcn components available (no install needed): avatar, badge, button, card, checkbox, collapsible, command, dialog, dropdown-menu, input, label, popover, scroll-area, select, separator, sheet, skeleton, tabs, textarea, tooltip

Existing custom components to reuse/extend:

• ChatPanel.tsx — extend with agent selector header area and streaming state; do not restructure the two-column layout
• ChatMessage.tsx — extend props to accept agentId, agentName, agentIcon for identity rendering
• ChatMessageList.tsx — replace with virtualized list (@tanstack/react-virtual) for PERF-03
• ChatInput.tsx — extend with slash command popover and @mention popover (reuse MentionOption pattern from MarkdownEditor.tsx)
• AgentIcon (from AgentIconPicker.tsx) — reuse directly for agent avatar rendering in messages
• agentStatusDot (from status-colors.ts) — reuse running: "bg-cyan-400 animate-pulse" for streaming indicator

New package required:

• @tanstack/react-virtual — not currently installed; add to ui/package.json for PERF-03 (1,000+ message virtualization)

---

Layout Contract

Layout Unchanged

The overall layout established in Phase 21 is unchanged:

[ CompanyRail ] [ Sidebar ] [ <main> ] [ ChatPanel ] [ PropertiesPanel ]

Phase 22 adds new UI surfaces inside ChatPanel only. No layout-level changes.

ChatPanel Header — Agent Selector

The ChatPanel header row gains an agent selector to the left of the close button:

[ "Chat" label ]  [ AgentSelector dropdown ]  [ ─── spacer ─── ]  [ X close ]

• The AgentSelector is a <Select> or <Popover> trigger showing the active agent's icon + name
• Width: fit-content, max 120px, truncated with ellipsis
• Placement: flex items-center gap-2 row, same px-4 py-2 padding as Phase 21 header
• When no agent is selected, label reads "Select agent" in text-muted-foreground

Message Bubble — Agent Identity Bar

Every assistant message gains an identity bar above the message content:

[ AgentIcon 16px ]  [ agentName 13px semibold ]  [ timestamp 11px muted ]

• Identity bar: flex items-center gap-2 mb-1
• Icon: 16×16px, rendered via <AgentIcon icon={agentIcon} className="h-4 w-4" />
• Name: text-[13px] font-semibold text-foreground
• Timestamp: text-[11px] text-muted-foreground
• No background, no border — identity floats above message content

Streaming Cursor

A blinking block cursor appended to the last streamed token while generation is active:

• Element: <span className="inline-block w-2 h-[1em] bg-foreground/70 animate-cursor-blink ml-0.5 align-text-bottom" />
• Animation: animate-cursor-blink — declare in index.css (see Animation section)
• Rendered only when isStreaming: true on the message; removed when stream ends

Stop Button

While a response is streaming, a Stop button appears below the message thread, centered above ChatInput:

[ (─────────────) ]   ← centered row
[  ■ Stop generating ]  ← Button variant="outline" size="sm"
[ (─────────────) ]
[ ChatInput ]

• Container: flex justify-center py-2 border-t border-border
• Button: variant="outline" size="sm", icon Square (filled stop), label "Stop generating"
• Disappears immediately on click (optimistic) before server confirms cancellation

Edit / Retry Controls

User messages gain an edit pencil on hover. Assistant messages gain a retry button on hover.

User message edit:

• Pencil icon button, 14×14px, variant="ghost" size="icon", positioned at top-right of message bubble
• Visible only on group-hover; always visible on touch devices
• Click → switches message bubble to inline edit mode (see Interaction Contract)

Assistant message retry:

• RefreshCw icon button, 14×14px, variant="ghost" size="icon", positioned below message content, right-aligned
• Visible only on group-hover; always visible on touch devices
• Only present on messages where isStreaming: false and role === "assistant"

Slash Command Popover

When the user types / as the first character in ChatInput:

[ /brainstorm  — Route to Brainstormer    ]  ← highlighted item
[ /ask-pm      — Route to PM              ]
[ /ask-engineer — Route to Engineer       ]
[ /task        — Create a task            ]
[ /search      — Search conversations     ]

• Container: shadcn <Popover> anchored to the top-left of the textarea, opens upward
• List: <Command> component inside popover (reuses existing cmdk install)
• Width: 260px, max 5 items visible before scroll
• Dismiss: Escape, clicking outside, or completing the command

@Mention Popover

When the user types @ in ChatInput, an agent autocomplete popover appears. Reuses the MentionOption pattern from MarkdownEditor.tsx:

• Container: <Popover> anchored to the @ character position, opens upward
• List: agent names filtered by query string after @
• Each row: <AgentIcon> 14×14px + agentName text + role label in muted text
• Width: 200px, max 5 agents before scroll
• Selection: click or Enter inserts @agentName token into textarea and routes message to that agent

---

Spacing Scale

Inherited from Phase 21. No new tokens for Phase 22.

Token	Value	Phase 22 Usage
xs	4px	Icon gaps in identity bar (gap-1)
sm	8px	Stop button padding, retry button margin
md	16px	Panel padding (unchanged)
lg	24px	(no new usage)
xl	32px	(no new usage)

New spacing values (Phase 22 only):

• Identity bar gap: gap-2 (8px) — between icon and agent name; matches existing gap-2 pattern in ChatPanel header
• Edit/retry icon button size: 14×14px (h-3.5 w-3.5) — matches MoreHorizontal in ChatConversationItem
• Streaming cursor width: w-2 (8px), height: h-[1em]

---

Typography

All inherited from Phase 21. One addition for agent identity:

Role	Size	Weight	Line Height	Usage
Body / message text	15px (0.9375rem)	400	1.6	Chat message prose (unchanged)
Label / UI chrome	13px (0.8125rem)	400	1.4	Conversation list, timestamps, slash command descriptions (unchanged)
Agent name (identity bar)	13px (0.8125rem)	600	1.4	Agent name above assistant messages
Message timestamp	11px (0.6875rem)	400	1.4	Timestamp in identity bar

Weights used: 400 (regular) and 600 (semibold). No additional weights. Same constraint as Phase 21.

Slash command descriptions: Rendered at 13px / 400 with text-muted-foreground — color/opacity distinction from the 13px / 400 command label is sufficient; no separate size needed. This keeps the total distinct sizes at 4 (11px, 13px, 15px, and 20px from Phase 21 markdown headings).

11px timestamp note: This is a 2px reduction below the Phase 21 minimum of 13px, used only within the compact identity bar where spatial context is sufficient. It is never used for interactive or error text.

---

Color

All values inherited from Phase 21 CSS variable system. No new color variables introduced.

Role	Catppuccin Mocha	Tokyo Night	Catppuccin Latte	Phase 22 Usage
Dominant (60%)	--background #1e1e2e	--background #1a1b26	--background #eff1f5	Unchanged
Secondary (30%)	--card #181825	--card #16161e	--card #e6e9ef	Unchanged
Accent (10%)	--accent #45475a	--accent #3b4261	--accent #bcc0cc	Hovered rows (unchanged)
Primary	--primary	--primary	--primary	Agent selector focus ring, send button
Destructive	--destructive	--destructive	--destructive	Not used in Phase 22
Muted text	--muted-foreground	--muted-foreground	--muted-foreground	Timestamps, role labels, empty states

Accent reserved for (Phase 22 additions):

• Same as Phase 21 (conversation rows, code block toolbar)
• Slash command popover highlighted item: bg-accent (via <Command> item selection)

Streaming indicator color: bg-cyan-400 animate-pulse — reused directly from agentStatusDot.running in status-colors.ts. Applied as a 6×6px dot beside the agent name in the identity bar while streaming. Note: bg-cyan-400 bypasses the CSS variable system. If theming requirements evolve (e.g. a theme requires a different streaming color), promote this to a semantic token such as --streaming-indicator in the CSS variable layer.

Agent Role Colors (THEME-03)

Agent avatars are distinguishable across all three themes using semantic role color tokens. These use Tailwind semantic colors with dark: variants — no new CSS variables needed.

Role	Icon color (light theme)	Icon color (dark theme)	Rationale
pm	text-blue-600	text-blue-400	Matches todo status color (existing pattern)
engineer	text-violet-600	text-violet-400	Matches in_review status color (existing pattern)
ceo / general	text-yellow-600	text-yellow-400	Matches idle agent status (existing pattern)
designer	text-pink-600	text-pink-400	New — no conflict with existing semantic
qa	text-orange-600	text-orange-400	Matches paused agent status (existing pattern)
researcher	text-teal-600	text-teal-400	New — no conflict with existing semantic
devops / cto	text-green-600	text-green-400	Matches done / active status (existing pattern)
cmo / cfo	text-neutral-600	text-neutral-400	Secondary/finance roles — muted
fallback	text-muted-foreground	text-muted-foreground	Unknown or null role

These colors apply to the <AgentIcon> in the message identity bar only. The existing status-colors.ts patterns are NOT modified — Phase 22 adds a new agent-role-colors.ts utility.

---

Component Inventory

New components to build in Phase 22:

Component	shadcn base	Notes
ChatAgentSelector.tsx	select or popover + command	Dropdown in ChatPanel header; shows active agent icon + name; lists all workspace agents
ChatMessageIdentityBar.tsx	none	Icon + name + timestamp row above assistant messages; uses AgentIcon
ChatStreamingCursor.tsx	none	Inline blinking cursor element; rendered conditionally during streaming
ChatStopButton.tsx	button	"Stop generating" button shown above input during active stream
ChatMessageActions.tsx	button, tooltip	Edit (on user messages) and Retry (on assistant messages) hover actions
ChatSlashCommandPopover.tsx	popover, command	Slash command menu anchored to textarea; 5 commands
ChatMentionPopover.tsx	popover	Agent @mention autocomplete anchored to @ position
useStreamingChat.ts	none	Hook managing SSE connection, token accumulation, streaming state
agent-role-colors.ts	none	Map of AgentRole → Tailwind class string for icon coloring

Existing components to modify:

Component	Change
ChatPanel.tsx	Add ChatAgentSelector to header; add ChatStopButton above input when streaming
ChatMessage.tsx	Accept agentId, agentName, agentIcon, agentRole, isStreaming props; render ChatMessageIdentityBar and ChatStreamingCursor; wrap in group for hover actions
ChatMessageList.tsx	Replace div iteration with @tanstack/react-virtual virtualizer; pass agent identity props down to ChatMessage
ChatInput.tsx	Wire ChatSlashCommandPopover (on / keystroke) and ChatMentionPopover (on @ keystroke); accept disabled prop during streaming

Icons (lucide-react) — Phase 22 additions:

• Square — Stop generating button icon (filled stop)
• Pencil — Edit user message
• RefreshCw — Retry assistant message
• ChevronDown — Agent selector dropdown indicator
• Bot — Default agent icon fallback (already in AGENT_ICON_NAMES)

All icons from Phase 21 remain unchanged.

---

Interaction Contract

Streaming Response

Interaction	Behavior
User sends message	ChatInput disabled; isSubmitting spinner on send button; SSE connection opens
First token arrives	New assistant message appended to list; identity bar renders; ChatStreamingCursor shown; ChatStopButton appears above input
Tokens continue	Text accumulates character-by-character in the message; cursor stays at end; list auto-scrolls to bottom if user has not scrolled up
User scrolls up during stream	Auto-scroll pauses; "Jump to bottom" button appears (↓ icon, variant="outline" size="icon-sm", fixed at bottom-right of message list)
Stream ends	ChatStreamingCursor removed; ChatStopButton removed; ChatInput re-enabled; message gets final updatedAt timestamp
Stream error	Streaming cursor replaced with error inline text: "Response interrupted. [Retry ↺]" — text-destructive with inline Retry link

Stop Generation

Interaction	Behavior
Click "Stop generating"	Button removed immediately (optimistic); SSE connection closed client-side; partial message preserved as-is with a [stopped] suffix in muted text
Server confirms stop	No additional UI change needed — state already settled on client

Message Edit (User Messages)

Interaction	Behavior
Hover user message	Pencil icon button appears at top-right of bubble
Click Pencil	Message bubble becomes an inline textarea pre-filled with existing content; "Save edit" and "Discard edit" buttons appear below; send button hidden
Edit textarea + click "Save edit"	POST updated message to server; assistant messages after this message are removed from thread (regeneration); new streaming response begins
Click "Discard edit"	Textarea reverts to read-only bubble; no changes
Save with empty content	"Save edit" button disabled when textarea is empty

Retry (Assistant Messages)

Interaction	Behavior
Hover assistant message	RefreshCw icon button appears below message, right-aligned
Click RefreshCw	Current assistant message replaced with a streaming placeholder; SSE connection opens; regenerated response streams in
Retry during active stream	Not available — RefreshCw button hidden while any stream is active

Agent Selector

Interaction	Behavior
Click agent selector	Popover/dropdown opens listing all workspace agents (icon + name + role label)
Select agent	Active agent updated for current conversation; PATCH /conversations/:id with agentId; selector shows new agent immediately (optimistic)
No agents available	Selector shows "No agents" in muted text; disabled state
Active agent deleted externally	Selector shows "Unknown agent" in muted text; conversation continues with null agentId until user selects another

Slash Commands (INPUT-05)

Interaction	Behavior
Type / as first char	ChatSlashCommandPopover opens above input listing all 5 commands
Type /bra (partial)	Popover filters to matching commands
Arrow keys / Tab	Navigate popover items
Enter or click item	Command token inserted into textarea (e.g. /brainstorm ); popover closes; routing applied on send
Escape	Popover closes; typed text remains
Send with /brainstorm prefix	Routes message to Brainstormer agent regardless of active agent selector

Slash command routing table:

Command	Routes to
/brainstorm	Brainstormer (general role with brainstormer prompt)
/ask-pm	PM role agent
/ask-engineer	Engineer role agent
/task	PM role agent (task creation intent)
/search	No-op in Phase 22 (stubbed; Phase 24 implements)

@Mention Routing (INPUT-06)

Interaction	Behavior
Type @	ChatMentionPopover opens listing workspace agents (icon + name + role)
Type @eng (partial)	List filters to agents whose name contains "eng" (case-insensitive)
Select agent	@AgentName token inserted; popover closes
Send message with @AgentName	Message routed to named agent for this turn only (overrides active agent selector)
Unknown mention	Sent as plain text; no routing override

Virtualized Message List (PERF-03)

• Uses @tanstack/react-virtual with useVirtualizer
• overscan: 5 — renders 5 items above/below visible window
• Item height: estimated 80px default; dynamic measurement via measureElement for variable-height markdown messages
• scrollMarginBottom: 120px to keep new messages visible above the input area
• "Jump to bottom" appears when scrollOffset > 200px from bottom; clicking calls scrollToIndex(messages.length - 1, { align: 'end' })

---

Copywriting Contract

All Phase 21 copy is preserved unchanged. Phase 22 additions:

Element	Copy	Notes
Agent selector placeholder	"Select agent"	text-muted-foreground; shown when no agent assigned
Agent selector no-options	"No agents configured"	Disabled state
Stop button label	"Stop generating"	variant="outline" size="sm"; icon Square precedes label
Edit message button aria-label	"Edit message"	Icon-only; Pencil icon
Retry message button aria-label	"Retry response"	Icon-only; RefreshCw icon
Inline edit save button	"Save edit"	variant="default" size="sm"
Inline edit cancel button	"Discard edit"	variant="ghost" size="sm"
Streaming interrupted error	"Response interrupted."	Inline text-destructive; followed by Retry link
Retry inline link	"Retry"	text-primary underline cursor-pointer — not a <Button>
Stopped message suffix	"[stopped]"	text-muted-foreground text-[11px] ml-1; appended to partial message
Slash command: /brainstorm description	"Route to Brainstormer"	Second line in slash popover item; text-muted-foreground
Slash command: /ask-pm description	"Route to PM"	Second line; text-muted-foreground
Slash command: /ask-engineer description	"Route to Engineer"	Second line; text-muted-foreground
Slash command: /task description	"Create a task"	Second line; text-muted-foreground
Slash command: /search description	"Search conversations"	Second line; text-muted-foreground; "Coming soon" suffix in muted text; greyed out
Jump to bottom button aria-label	"Scroll to latest message"	Icon-only; ArrowDown icon
Input placeholder (streaming)	"Waiting for response..."	Replaces "Message your agent..." while isStreaming: true; textarea is disabled

Tone: Direct, functional, no corporate language. Consistent with Phase 21.

---

States and Loading

Component	Loading state	Empty state	Error state	Streaming state
ChatAgentSelector	Skeleton pill 80px wide	"No agents configured"	"Could not load agents. Refresh to try again." — popover body	n/a
ChatMessage (assistant)	n/a	n/a	Inline "Response interrupted. Retry"	Cursor blink + streaming text accumulation
ChatMessageList	3x Skeleton rows (h-16 variable)	Inherited from Phase 21	Inherited from Phase 21	Auto-scroll; Stop button visible
ChatInput	n/a	n/a	Inherited from Phase 21	disabled; placeholder "Waiting for response..."
ChatSlashCommandPopover	n/a	n/a	n/a	Hidden while streaming
ChatMentionPopover	Skeleton 3 rows	"No agents found"	n/a	Hidden while streaming

Optimistic updates:

• Agent selector: updates conversation's agentId optimistically; reverts on API error with toast "Could not update agent. Try again."
• Stop: button removed immediately; error shown inline if SSE close fails silently
• Edit/Retry: new streaming message renders immediately; old messages removed optimistically

---

Theme Integration Contract

Phase 22 extends Phase 21's zero-new-plumbing approach:

• Agent role colors use text-{color}-600 dark:text-{color}-400 Tailwind classes — resolve correctly in all three themes via the existing .dark class on <html>
• Tokyo Night: .dark class is present (as established in Phase 21 ThemeContext) — dark variants apply correctly
• Streaming cursor: bg-foreground/70 uses CSS variable — resolves to near-white in dark themes, near-black in Catppuccin Latte
• Slash command popover and mention popover: use shadcn <Popover> + <Command> which inherit --popover, --popover-foreground CSS variables — no manual theme wiring needed

THEME-03 checklist:

• Agent icon colors declared per-role with dark: variants — all three themes tested
• Streaming indicator uses bg-cyan-400 (same across themes — sufficient contrast on all three backgrounds)
• No hardcoded hex colors introduced in Phase 22

---

Accessibility

Inherits all Phase 21 accessibility contracts. Phase 22 additions:

Concern	Requirement
Agent selector	aria-label="Active agent" on trigger; dropdown items have role="option"
Streaming message	aria-live="polite" on ChatMessageList (established in Phase 21) handles streamed token announcements without modification
Stop button	aria-label="Stop generating response"
Streaming cursor	aria-hidden="true" — decorative only
Edit textarea	aria-label="Edit your message" on inline textarea
Retry button	aria-label="Retry response"
Slash popover	role="listbox" on items; announce open state with aria-expanded
Mention popover	role="listbox" on items; announce open state with aria-expanded
Jump to bottom	aria-label="Scroll to latest message"
Edit save/cancel	Standard button labels — "Save edit" and "Discard edit" (no icon-only ambiguity)
Focus after stop	Focus returns to ChatInput textarea after stop action
Focus after retry	No focus change — user may be reading the regenerated message

---

Animation and Motion

Inherits Phase 21 animation contract. Phase 22 additions:

Element	Animation	Duration	Easing	CSS
Streaming cursor	animate-cursor-blink keyframe	800ms	step-start	See below
Stop button appear	animate-in fade-in slide-in-from-bottom-1	150ms	ease-out — shadcn default
Stop button disappear	animate-out fade-out slide-out-to-bottom-1	100ms	ease-in
Slash popover open	animate-in fade-in zoom-in-95	100ms	ease-out — shadcn Popover default
Mention popover open	Same as slash popover	100ms	ease-out
Jump to bottom button	animate-in fade-in slide-in-from-bottom-2	150ms	ease-out
Streaming indicator dot	animate-pulse (Tailwind)	continuous	—
Edit mode transition	No animation — immediate swap; avoids layout shift	—	—

animate-cursor-blink keyframe (add to index.css):

@keyframes cursor-blink {
  0%, 100% { opacity: 1; }
  50% { opacity: 0; }
}

.animate-cursor-blink {
  animation: cursor-blink 800ms step-start infinite;
}

@media (prefers-reduced-motion: reduce) {
  .animate-cursor-blink {
    animation: none;
    opacity: 1;
  }
}

Reduced motion: All Phase 22 entrance/exit animations must respect prefers-reduced-motion. Use motion-safe: Tailwind prefix or @media guards matching the Phase 21 pattern in index.css.

---

Performance Contract

Requirement	Target	Implementation
PERF-02	First token ≤ 100ms server-to-UI	SSE connection opened before server begins generation; client-side: no React re-render batching delay — use startTransition for text accumulation to keep input responsive
PERF-03	1,000+ messages no jank	@tanstack/react-virtual with dynamic measurement; overscan: 5; avoid re-rendering all messages on token append — only the active streaming message re-renders

Token accumulation pattern:

• Maintain a streamingContent string in useStreamingChat local state
• Append tokens via setState(prev => prev + token) — single string concat, not array push
• When stream ends, commit full message to React Query cache via queryClient.setQueryData; clear local streamingContent

---

Registry Safety

Registry	Blocks Used	Safety Gate
shadcn official	All existing Phase 21 components (already installed)	not required
npm (non-registry)	@tanstack/react-virtual — standard npm package install via pnpm add	not applicable (not a shadcn registry block)
Third-party	none	not applicable

No third-party shadcn registries used in Phase 22.

---

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