@wallarm-org/claude-design 0.0.0-stage → 4.8.0

package/dist/project/components/WallyAssistant/README.md

@@ -0,0 +1,1380 @@
+The closed Wally panel: pass a `ChatSnapshot` (messages, status, suggestions, permissions, context) and callbacks, and it renders the whole Figma chat — header, stick-to-bottom log, greeting, chain of thought, docked approval and input. It holds no agent state: the app folds its stream into a new snapshot on every delta. Send is blocked while the last message has a pending approval (typing still works), and a resolved card stays docked until the next message. Every rule lives in exported pieces — `ChatViewProvider`, `deriveChatState`, `ChatMessageView`, `ChatPartView` — so a custom layout reuses them (Custom Layout). Seams like `renderPart`, `renderStepContent` and `renderMessageActions` hand back the default rendering. Stories are driven by `useMockWally()` from `WallyAssistant/mocks` and keep feedback and permissions in app state. Messages render with the default `AssistantMessageMarkdown`, and fenced code highlights with the lazy Prism adapter WallyAssistant mounts unless the app provides a `CodeSnippetAdapterProvider`.
+
+## Props as canvas attributes
+
+Use kebab-case attribute names. Pass non-string values through renderVals holes, including booleans. The full emitted API is in `components/index.d.ts`.
+
+| Attribute | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `default-checked` | `boolean \| undefined` | no | — |  |
+| `auto-focus` | `boolean \| undefined` | no | — |  |
+| `id` | `string \| undefined` | no | — |  |
+| `tab-index` | `number \| undefined` | no | — |  |
+| `rel` | `string \| undefined` | no | — |  |
+| `on-change` | `ChangeEventHandler<T, Element> \| undefined` | no | — |  |
+| `data-testid` | `string \| undefined` | no | — |  |
+| `background` | `"strong" \| "none" \| "subtle"` | no | — | Decorative mesh behind the panel (Figma chat-bg 67:1254). `'strong'` is Main (12%, for an empty chat), `'subtle'` is Chat (5%, for a running conversation), `'none'` renders nothing. |
+| `messages` | `complex` | yes | — |  |
+| `status` | `"error" \| "ready" \| "submitted" \| "streaming"` | no | `ready` | Default 'ready'. |
+| `suggestions` | `complex` | no | — |  |
+| `permissions` | `complex` | no | — |  |
+| `context` | `complex` | no | — |  |
+| `value` | `string \| undefined` | no | — |  |
+| `on-value-change` | `((value: string) => void) \| undefined` | no | — |  |
+| `disabled` | `boolean \| undefined` | no | — | Disables the textarea, Send and the suggestion pills (e.g. `!agent.isReady`). |
+| `textarea-ref` | `Ref<HTMLTextAreaElement> \| undefined` | no | — | Focus management, e.g. focus the input after a thread switch. |
+| `on-submit` | `(text: string) => void` | yes | — | Trimmed text. Not called when empty, while running, while an approval is pending, or when disabled. |
+| `on-stop` | `(() => void) \| undefined` | no | — | Stop button, and Esc in the textarea while running (also inside a Drawer/Dialog: ChatInput claims that Esc from the layer, so no host recipe is needed). |
+| `on-suggestion-select` | `complex` | no | — | Default: onSubmit(suggestion.prompt ?? suggestion.label). |
+| `on-permission-change` | `complex` | no | — | Absent, or no permissions → no permissions button in the input. |
+| `on-context-remove` | `complex` | no | — | Absent → context chips aren't removable. |
+| `header` | `ReactNode` | no | — |  |
+| `header-title` | `ReactNode` | no | — | ChatHeaderTitle children, e.g. a thread Select (Figma Variant2). |
+| `header-actions` | `ReactNode` | no | — | New chat, history, close: your Buttons, so analytics land on them. |
+| `empty-state` | `ReactNode` | no | — | Replaces the greeting and its pills (e.g. a history-loading state). |
+| `footer-start` | `ReactNode` | no | — | Top of ChatFooter, above the suggestions (banners). |
+| `input-tools` | `ReactNode` | no | — | Extra toolbar items in the input, between permissions and Send. |
+| `input` | `ReactNode` | no | — | Replaces the whole ChatInput composition (you wire value and submit yourself). |
+| `on-copy` | `complex` | no | — | Fired after Copy copied; Copy itself shows whenever the message has text. |
+| `labels` | `complex` | no | — |  |
+| `icons` | `Readonly<Record<string, ReactNode>> \| undefined` | no | — | Icon key → element from src/icons; wins over the built-in Figma 483:1899 table. |
+| `markdown` | `complex` | no | — | The markdown renderer, at module scope (never inline). Default: the DS `AssistantMessageMarkdown` (GFM, streaming-safe, no raw HTML, http/https/mailto/relative links only, no images). A replacement owns its own sanitizing. To change one element, wrap it at module scope: `const WallyMarkdown: FC<ChatMarkdownProps> = p => <AssistantMessageMarkdown {...p} components={MAP} />`. |
+| `format-timestamp` | `((createdAt: string) => string) \| undefined` | no | — | ISO → label. Default: DS formatRelativeTime (honours DateFormatProvider). Give it a new identity on your clock tick to refresh "2 min ago" — the DS runs no clock. |
+| `approval-placement` | `"inline" \| "docked" \| undefined` | no | `docked` | 'docked': the last message's approvals render in the footer. Default 'inline' here; WallyAssistant defaults to 'docked' (Figma). A custom layout passes the same value to `deriveChatState`, or the approval renders twice (provider 'inline') or never (provider 'docked'). |
+| `render-part` | `complex` | no | — | Called for every part, custom and unknown types included. undefined = the default; null = nothing. A render function: no hooks inside — put them in the components you return. While it is set, every part counts as rendered for the loader and the actions row (its output is unknown up front), so a running reply made only of parts it maps to nothing shows no loader. |
+| `render-step-content` | `complex` | no | — | A step's collapsible body: rich tool output, or a card for one tool via `step.name`. undefined = the default; null = no body (the row isn't collapsible). No hooks inside. |
+| `render-message-actions` | `complex` | no | — | The actions row's children (Figma Wally order: Copy, ThumbsUp, ThumbsDown, Ellipsis, Timestamp). undefined = the default order; null = no row. No hooks inside. |
+| `on-approval-respond` | `complex` | no | — | Absent → approval buttons are disabled. |
+| `on-feedback` | `complex` | no | — | Absent → no thumbs. Clicking the pressed thumb sends null. |
+| `on-retry` | `complex` | no | — | Absent → no Retry on error parts. |
+
+## Sub-components
+
+- `WallarmDS.ApprovalCardView` — `ApprovalCardViewProps` in the declaration bundle.
+- `WallarmDS.ChainOfThoughtView` — `ChainOfThoughtViewProps` in the declaration bundle.
+- `WallarmDS.ChatMessageView` — `ChatMessageViewProps` in the declaration bundle.
+- `WallarmDS.ChatPartView` — `ChatPartViewProps` in the declaration bundle.
+- `WallarmDS.ChatViewProvider` — `ChatViewProviderProps` in the declaration bundle.
+
+## Stories
+
+### Empty
+
+No messages: the greeting with Large suggestion pills on the strong background. A pill starts a run.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#Empty
+
+### Conversation
+
+Two finished turns: folded chain of thought, answers with Copy, thumbs and timestamps, follow-up pills and the permissions button.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#Conversation
+
+### StreamingSimulation
+
+The whole Wally script from `useMockWally()`: send a message or click a pill to watch the loader,
+a live reasoning step, three tool steps with the Working row between them, the streamed answer,
+then the fold under "Worked for 12s". Stop cancels the run. `speed` scales every delay (0 = instant).
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#StreamingSimulation
+
+### Approval
+
+A pending approval docked above the input: Send is blocked (typing still works). Allow or Reject goes through `onApprovalRespond`, and the next snapshot resolves the card in place.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#Approval
+
+### ErrorState
+
+A run that failed before any output: `AssistantMessageError` with Retry, wired to `onRetry`.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#ErrorState
+
+### Overrides
+
+Every seam at once: `renderPart` draws a `custom` attack summary, `renderStepContent` puts a table
+under `search_attacks`, `renderMessageActions` adds a tagged Copy and an Ellipsis menu, a thread
+`Select` in `headerTitle`, an attach button in `inputTools`, and German `labels`.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#Overrides
+
+### CustomLayout
+
+A full-page chat with a centered 768px column, built from `ChatViewProvider`, `deriveChatState`, `Chat`, `Conversation*`, `ChatMessageView`, docked `ChatPartView` and its own `ChatInput` — proof the open parts reuse every rule.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#CustomLayout
+
+### InDrawer
+
+Hosted in a 480px Drawer opened by `ChatTrigger`. Esc in the textarea while a reply streams stops it without closing the drawer — ChatInput handles that itself, no host recipe needed.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#InDrawer
+
+### Analytics
+
+Analytics attributes land on real nodes: the root `<section>`, header-action Buttons and a tagged Copy from `renderMessageActions` (like, dislike and timestamp stay default). Closed targets (pills, Send, approval options) report through their callbacks — see ANALYTICS_GAPS.md.
+
+Source: WallyAssistant/WallyAssistant.stories.tsx#Analytics
+
+## Story sources
+
+### WallyAssistant/WallyAssistant.stories.tsx
+
+```tsx
+import { useState } from 'react';
+import type { Meta, StoryFn } from 'storybook-react-rsbuild';
+import { Ellipsis, History, Paperclip, Plus, X } from '../../icons';
+import { Button } from '../Button';
+import { Chat, ChatFooter, ChatHeader, ChatHeaderTitle, ChatTrigger } from '../Chat';
+import { ChatInput, ChatInputSubmit, ChatInputTextarea } from '../ChatInput';
+import {
+  ConversationContent,
+  Conversation as ConversationRoot,
+  ConversationScrollButton,
+} from '../Conversation';
+import { Copyable, CopyableIcon } from '../Copyable';
+import { Drawer, DrawerClose, DrawerContent, DrawerTitle, DrawerTrigger } from '../Drawer';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '../DropdownMenu';
+import { MessageAction } from '../MessageActions';
+import {
+  createListCollection,
+  Select,
+  SelectButton,
+  SelectContent,
+  SelectOption,
+  SelectOptionIndicator,
+  SelectOptionText,
+  SelectPositioner,
+} from '../Select';
+import { Separator } from '../Separator';
+import {
+  type ChatAssistantMessage,
+  type ChatFeedback,
+  ChatMessageView,
+  ChatPartView,
+  type ChatSnapshot,
+  type ChatToolPermission,
+  type ChatViewConfig,
+  ChatViewProvider,
+  copyTextOf,
+  deriveChatState,
+  WallyAssistant,
+} from '.';
+import { APPROVAL_PENDING, CONVERSATION, EMPTY, ERROR_TURN, useMockWally } from './mocks';
+
+const DESCRIPTION = [
+  'The closed Wally panel: pass a `ChatSnapshot` (messages, status, suggestions, permissions, context) and callbacks, and it renders the whole Figma chat — header, stick-to-bottom log, greeting, chain of thought, docked approval and input.',
+  'It holds no agent state: the app folds its stream into a new snapshot on every delta. Send is blocked while the last message has a pending approval (typing still works), and a resolved card stays docked until the next message.',
+  'Every rule lives in exported pieces — `ChatViewProvider`, `deriveChatState`, `ChatMessageView`, `ChatPartView` — so a custom layout reuses them (Custom Layout). Seams like `renderPart`, `renderStepContent` and `renderMessageActions` hand back the default rendering.',
+  'Stories are driven by `useMockWally()` from `WallyAssistant/mocks` and keep feedback and permissions in app state. Messages render with the default `AssistantMessageMarkdown`, and fenced code highlights with the lazy Prism adapter WallyAssistant mounts unless the app provides a `CodeSnippetAdapterProvider`.',
+].join(' ');
+
+const meta = {
+  title: 'AI/WallyAssistant',
+  component: WallyAssistant,
+  parameters: {
+    layout: 'centered',
+    docs: { description: { component: DESCRIPTION } },
+  },
+} satisfies Meta<typeof WallyAssistant>;
+
+export default meta;
+
+// --- story data and config -----------------------------------------------------------------------------
+
+/** Fixed (UTC) clock text, so screenshots don't drift. */
+const fixedTime = (iso: string) => new Date(iso).toISOString().slice(11, 16);
+
+/**
+ * Merges app-held feedback into an assistant message, caching one object per (message, feedback)
+ * pair so a streaming delta doesn't hand untouched rows a new identity (§7.2).
+ */
+const merged = new WeakMap<
+  ChatAssistantMessage,
+  { feedback: ChatFeedback | null; message: ChatAssistantMessage }
+>();
+const withFeedback = (
+  m: ChatAssistantMessage,
+  feedback: ChatFeedback | null,
+): ChatAssistantMessage => {
+  const hit = merged.get(m);
+  if (hit && hit.feedback === feedback) return hit.message;
+  const message = { ...m, feedback };
+  merged.set(m, { feedback, message });
+  return message;
+};
+
+interface AttackSummary {
+  total: number;
+  blocked: number;
+}
+
+const OVERRIDES: ChatSnapshot = {
+  ...CONVERSATION,
+  messages: [
+    ...CONVERSATION.messages,
+    {
+      role: 'user',
+      id: 'u3',
+      createdAt: '2026-10-21T09:02:00.000Z',
+      parts: [{ type: 'text', id: 'u3:text', text: 'Summarize the attacks' }],
+    },
+    {
+      role: 'assistant',
+      id: 'u3:reply',
+      createdAt: '2026-10-21T09:02:04.000Z',
+      parts: [
+        {
+          type: 'chain-of-thought',
+          id: 'u3:reply:cot:0',
+          steps: [
+            {
+              id: 'search',
+              kind: 'tool',
+              name: 'search_attacks',
+              icon: 'query',
+              status: 'done',
+              label: 'Searched attacks',
+              metric: '3 sources',
+            },
+          ],
+        },
+        {
+          type: 'custom',
+          id: 'u3:reply:summary',
+          kind: 'wallarm.attack-summary',
+          data: { total: 1204, blocked: 1019 } satisfies AttackSummary,
+        },
+        {
+          type: 'text',
+          id: 'u3:reply:text',
+          text: 'Most of it is SQL injection from `203.0.113.7`.',
+        },
+      ],
+    },
+  ],
+};
+
+const SOURCES = [
+  { ip: '203.0.113.7', attacks: 185 },
+  { ip: '198.51.100.4', attacks: 610 },
+  { ip: '192.0.2.10', attacks: 409 },
+];
+
+const threads = createListCollection({
+  items: [
+    { value: 'attacks', label: 'Top attacks today' },
+    { value: 'rules', label: 'Rule tuning for API v2' },
+  ],
+});
+
+// Render seams stay at module scope so their identity is stable (ChatViewProvider memoizes on it).
+const renderPart: ChatViewConfig['renderPart'] = part => {
+  if (part.type !== 'custom' || part.kind !== 'wallarm.attack-summary') return undefined;
+  const { total, blocked } = part.data as AttackSummary;
+  return (
+    <div
+      data-testid='attack-summary'
+      className='rounded-8 border border-border-primary-light p-12 text-sm text-text-primary'
+    >
+      {blocked} of {total} attacks blocked
+    </div>
+  );
+};
+
+const renderStepContent: ChatViewConfig['renderStepContent'] = step =>
+  step.name === 'search_attacks' ? (
+    <table data-testid='search-table' className='text-xs text-text-secondary'>
+      <tbody>
+        {SOURCES.map(s => (
+          <tr key={s.ip}>
+            <td className='pr-12 font-mono'>{s.ip}</td>
+            <td>{s.attacks}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  ) : undefined;
+
+// Overrides: tagged Copy with a German label, an Ellipsis menu, then the default like/dislike/timestamp.
+const renderMessageActions: ChatViewConfig['renderMessageActions'] = (m, a) =>
+  m.role === 'user' ? undefined : (
+    <>
+      <Copyable text={copyTextOf(m)}>
+        <MessageAction aria-label='Kopieren' data-analytics-id='wally.copy'>
+          <CopyableIcon />
+        </MessageAction>
+      </Copyable>
+      {a.like}
+      {a.dislike}
+      <DropdownMenu positioning={{ placement: 'bottom-end' }}>
+        <DropdownMenuTrigger asChild>
+          <MessageAction aria-label='More actions' data-analytics-id='wally.more'>
+            <Ellipsis />
+          </MessageAction>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent>
+          <DropdownMenuItem data-analytics-id='wally.report'>Report {m.id}</DropdownMenuItem>
+          <DropdownMenuItem>Share</DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      {a.timestamp}
+    </>
+  );
+
+// Analytics: the default actions, with Copy swapped for one carrying `data-analytics-id`.
+const renderAnalyticsActions: ChatViewConfig['renderMessageActions'] = (m, a) =>
+  m.role === 'user' ? undefined : (
+    <>
+      <Copyable text={copyTextOf(m)}>
+        <MessageAction aria-label='Copy' data-analytics-id='wally.copy'>
+          <CopyableIcon />
+        </MessageAction>
+      </Copyable>
+      {a.like}
+      {a.dislike}
+      {a.timestamp}
+    </>
+  );
+
+// --- stories ------------------------------------------------------------------------------------
+
+/** No messages: the greeting with Large suggestion pills on the strong background. A pill starts a run. */
+export const Empty: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: EMPTY });
+  const [feedback, setFeedback] = useState<Record<string, ChatFeedback | null>>({});
+  const [permissions, setPermissions] = useState(EMPTY.permissions);
+  const messages = wally.snapshot.messages.map(m =>
+    m.role === 'assistant' && m.id in feedback ? withFeedback(m, feedback[m.id] ?? null) : m,
+  );
+
+  const handleFeedback = (message: ChatAssistantMessage, value: ChatFeedback | null) => {
+    setFeedback(f => ({ ...f, [message.id]: value }));
+  };
+
+  const handlePermissionChange = (permission: ChatToolPermission, allowed: boolean) => {
+    setPermissions(list => list?.map(x => (x.id === permission.id ? { ...x, allowed } : x)));
+  };
+
+  return (
+    <div className='h-640 w-480'>
+      <WallyAssistant
+        data-testid='wally'
+        {...wally.snapshot}
+        messages={messages}
+        permissions={permissions}
+        formatTimestamp={fixedTime}
+        onSubmit={wally.send}
+        onStop={wally.stop}
+        onApprovalRespond={wally.respond}
+        onFeedback={handleFeedback}
+        onPermissionChange={handlePermissionChange}
+      />
+    </div>
+  );
+};
+
+/** Two finished turns: folded chain of thought, answers with Copy, thumbs and timestamps, follow-up pills and the permissions button. */
+export const Conversation: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: CONVERSATION });
+  const [feedback, setFeedback] = useState<Record<string, ChatFeedback | null>>({});
+  const [permissions, setPermissions] = useState(CONVERSATION.permissions);
+  const messages = wally.snapshot.messages.map(m =>
+    m.role === 'assistant' && m.id in feedback ? withFeedback(m, feedback[m.id] ?? null) : m,
+  );
+
+  const handleFeedback = (message: ChatAssistantMessage, value: ChatFeedback | null) => {
+    setFeedback(f => ({ ...f, [message.id]: value }));
+  };
+
+  const handlePermissionChange = (permission: ChatToolPermission, allowed: boolean) => {
+    setPermissions(list => list?.map(x => (x.id === permission.id ? { ...x, allowed } : x)));
+  };
+
+  return (
+    <div className='h-640 w-480'>
+      <WallyAssistant
+        data-testid='wally'
+        {...wally.snapshot}
+        messages={messages}
+        permissions={permissions}
+        formatTimestamp={fixedTime}
+        onSubmit={wally.send}
+        onStop={wally.stop}
+        onApprovalRespond={wally.respond}
+        onFeedback={handleFeedback}
+        onPermissionChange={handlePermissionChange}
+      />
+    </div>
+  );
+};
+
+/**
+ * The whole Wally script from `useMockWally()`: send a message or click a pill to watch the loader,
+ * a live reasoning step, three tool steps with the Working row between them, the streamed answer,
+ * then the fold under "Worked for 12s". Stop cancels the run. `speed` scales every delay (0 = instant).
+ */
+export const StreamingSimulation: StoryFn<{ speed: number }> = ({ speed }) => {
+  const wally = useMockWally({ initial: CONVERSATION, speed });
+  const [feedback, setFeedback] = useState<Record<string, ChatFeedback | null>>({});
+  const [permissions, setPermissions] = useState(CONVERSATION.permissions);
+  const messages = wally.snapshot.messages.map(m =>
+    m.role === 'assistant' && m.id in feedback ? withFeedback(m, feedback[m.id] ?? null) : m,
+  );
+
+  const handleFeedback = (message: ChatAssistantMessage, value: ChatFeedback | null) => {
+    setFeedback(f => ({ ...f, [message.id]: value }));
+  };
+
+  const handlePermissionChange = (permission: ChatToolPermission, allowed: boolean) => {
+    setPermissions(list => list?.map(x => (x.id === permission.id ? { ...x, allowed } : x)));
+  };
+
+  return (
+    <div className='h-640 w-480'>
+      <WallyAssistant
+        data-testid='wally'
+        {...wally.snapshot}
+        messages={messages}
+        permissions={permissions}
+        formatTimestamp={fixedTime}
+        onSubmit={wally.send}
+        onStop={wally.stop}
+        onApprovalRespond={wally.respond}
+        onFeedback={handleFeedback}
+        onPermissionChange={handlePermissionChange}
+      />
+    </div>
+  );
+};
+StreamingSimulation.args = { speed: 1 };
+StreamingSimulation.argTypes = {
+  speed: { control: { type: 'range', min: 0, max: 3, step: 0.25 } },
+};
+
+/** A pending approval docked above the input: Send is blocked (typing still works). Allow or Reject goes through `onApprovalRespond`, and the next snapshot resolves the card in place. */
+export const Approval: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: APPROVAL_PENDING });
+  const [feedback, setFeedback] = useState<Record<string, ChatFeedback | null>>({});
+  const [permissions, setPermissions] = useState(APPROVAL_PENDING.permissions);
+  const messages = wally.snapshot.messages.map(m =>
+    m.role === 'assistant' && m.id in feedback ? withFeedback(m, feedback[m.id] ?? null) : m,
+  );
+
+  const handleFeedback = (message: ChatAssistantMessage, value: ChatFeedback | null) => {
+    setFeedback(f => ({ ...f, [message.id]: value }));
+  };
+
+  const handlePermissionChange = (permission: ChatToolPermission, allowed: boolean) => {
+    setPermissions(list => list?.map(x => (x.id === permission.id ? { ...x, allowed } : x)));
+  };
+
+  return (
+    <div className='h-640 w-480'>
+      <WallyAssistant
+        data-testid='wally'
+        {...wally.snapshot}
+        messages={messages}
+        permissions={permissions}
+        formatTimestamp={fixedTime}
+        onSubmit={wally.send}
+        onStop={wally.stop}
+        onApprovalRespond={wally.respond}
+        onFeedback={handleFeedback}
+        onPermissionChange={handlePermissionChange}
+      />
+    </div>
+  );
+};
+
+/** A run that failed before any output: `AssistantMessageError` with Retry, wired to `onRetry`. */
+export const ErrorState: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: ERROR_TURN });
+  const [feedback, setFeedback] = useState<Record<string, ChatFeedback | null>>({});
+  const [permissions, setPermissions] = useState(ERROR_TURN.permissions);
+  const [retries, setRetries] = useState(0);
+  const messages = wally.snapshot.messages.map(m =>
+    m.role === 'assistant' && m.id in feedback ? withFeedback(m, feedback[m.id] ?? null) : m,
+  );
+
+  const handleFeedback = (message: ChatAssistantMessage, value: ChatFeedback | null) => {
+    setFeedback(f => ({ ...f, [message.id]: value }));
+  };
+
+  const handlePermissionChange = (permission: ChatToolPermission, allowed: boolean) => {
+    setPermissions(list => list?.map(x => (x.id === permission.id ? { ...x, allowed } : x)));
+  };
+
+  const handleRetry = () => {
+    setRetries(n => n + 1);
+  };
+
+  return (
+    <div className='h-640 w-480'>
+      <WallyAssistant
+        data-testid='wally'
+        {...wally.snapshot}
+        messages={messages}
+        permissions={permissions}
+        formatTimestamp={fixedTime}
+        onSubmit={wally.send}
+        onStop={wally.stop}
+        onApprovalRespond={wally.respond}
+        onFeedback={handleFeedback}
+        onPermissionChange={handlePermissionChange}
+        onRetry={handleRetry}
+        footerStart={
+          retries ? <p className='text-xs text-text-secondary'>Retried {retries}×</p> : null
+        }
+      />
+    </div>
+  );
+};
+
+/**
+ * Every seam at once: `renderPart` draws a `custom` attack summary, `renderStepContent` puts a table
+ * under `search_attacks`, `renderMessageActions` adds a tagged Copy and an Ellipsis menu, a thread
+ * `Select` in `headerTitle`, an attach button in `inputTools`, and German `labels`.
+ */
+export const Overrides: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: OVERRIDES });
+  const [feedback, setFeedback] = useState<Record<string, ChatFeedback | null>>({});
+  const [permissions, setPermissions] = useState(OVERRIDES.permissions);
+  const messages = wally.snapshot.messages.map(m =>
+    m.role === 'assistant' && m.id in feedback ? withFeedback(m, feedback[m.id] ?? null) : m,
+  );
+
+  const handleFeedback = (message: ChatAssistantMessage, value: ChatFeedback | null) => {
+    setFeedback(f => ({ ...f, [message.id]: value }));
+  };
+
+  const handlePermissionChange = (permission: ChatToolPermission, allowed: boolean) => {
+    setPermissions(list => list?.map(x => (x.id === permission.id ? { ...x, allowed } : x)));
+  };
+
+  return (
+    <div className='h-640 w-480'>
+      <WallyAssistant
+        data-testid='wally'
+        {...wally.snapshot}
+        messages={messages}
+        permissions={permissions}
+        formatTimestamp={fixedTime}
+        onSubmit={wally.send}
+        onStop={wally.stop}
+        onApprovalRespond={wally.respond}
+        onFeedback={handleFeedback}
+        onPermissionChange={handlePermissionChange}
+        renderPart={renderPart}
+        renderStepContent={renderStepContent}
+        renderMessageActions={renderMessageActions}
+        headerTitle={
+          <Select collection={threads} defaultValue={['attacks']}>
+            <SelectButton variant='ghost' size='small' placeholder='New chat' />
+            <SelectPositioner>
+              <SelectContent>
+                {threads.items.map(item => (
+                  <SelectOption key={item.value} item={item}>
+                    <SelectOptionText>{item.label}</SelectOptionText>
+                    <SelectOptionIndicator />
+                  </SelectOption>
+                ))}
+              </SelectContent>
+            </SelectPositioner>
+          </Select>
+        }
+        inputTools={
+          <Button variant='ghost' color='neutral' size='small' aria-label='Datei anhängen'>
+            <Paperclip />
+          </Button>
+        }
+        labels={{
+          placeholder: 'Frag Wally...',
+          input: 'Nachricht an Wally',
+          send: 'Senden',
+          stop: 'Antwort stoppen',
+          disclaimer: 'Wally kann sich irren; bitte prüfen.',
+          suggestions: 'Vorschläge',
+          feedbackPositive: 'Gute Antwort',
+          feedbackNegative: 'Schlechte Antwort',
+        }}
+      />
+    </div>
+  );
+};
+
+/** A full-page chat with a centered 768px column, built from `ChatViewProvider`, `deriveChatState`, `Chat`, `Conversation*`, `ChatMessageView`, docked `ChatPartView` and its own `ChatInput` — proof the open parts reuse every rule. */
+export const CustomLayout: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: CONVERSATION });
+  const [draft, setDraft] = useState('');
+  const { messages, status } = wally.snapshot;
+  const state = deriveChatState(messages, status, 'docked');
+  const last = state.rows[state.rows.length - 1];
+
+  const handleSubmit = (text: string) => {
+    if (state.awaitingApproval) return;
+    wally.send(text);
+    setDraft('');
+  };
+
+  return (
+    <ChatViewProvider
+      status={status}
+      approvalPlacement='docked'
+      formatTimestamp={fixedTime}
+      onApprovalRespond={wally.respond}
+    >
+      <div className='h-screen'>
+        <Chat data-testid='wally' background={state.empty ? 'strong' : 'subtle'}>
+          <ChatHeader>
+            <ChatHeaderTitle label='Wally workspace' />
+          </ChatHeader>
+          <ConversationRoot autoScrollKey={state.lastUserMessageId}>
+            <ConversationContent aria-busy={state.busy} contentClassName='mx-auto w-full max-w-768'>
+              {state.rows.map((m, i) => (
+                <ChatMessageView
+                  key={m.id}
+                  message={m}
+                  index={i}
+                  isLast={i === state.rows.length - 1}
+                />
+              ))}
+            </ConversationContent>
+            <ConversationScrollButton />
+          </ConversationRoot>
+          <ChatFooter className='mx-auto w-full max-w-768'>
+            {last &&
+              state.dockedApprovals.map(a => (
+                <ChatPartView key={a.id} part={a} message={last} isLast placement='docked' />
+              ))}
+            <ChatInput
+              value={draft}
+              onValueChange={setDraft}
+              onSubmit={handleSubmit}
+              onStop={wally.stop}
+              isRunning={state.running}
+            >
+              <ChatInputTextarea />
+              <ChatInputSubmit disabled={state.awaitingApproval && !state.running} />
+            </ChatInput>
+          </ChatFooter>
+        </Chat>
+      </div>
+    </ChatViewProvider>
+  );
+};
+CustomLayout.parameters = { layout: 'fullscreen' };
+
+/** Hosted in a 480px Drawer opened by `ChatTrigger`. Esc in the textarea while a reply streams stops it without closing the drawer — ChatInput handles that itself, no host recipe needed. */
+export const InDrawer: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: CONVERSATION });
+
+  return (
+    <Drawer width={480}>
+      <DrawerTrigger asChild>
+        <ChatTrigger data-testid='chat-trigger' />
+      </DrawerTrigger>
+      <DrawerContent>
+        {/* Names the dialog "Wally" (Ark points aria-labelledby at the title); hidden because
+            the panel header already shows it. */}
+        <div className='sr-only'>
+          <DrawerTitle>Wally</DrawerTitle>
+        </div>
+        <WallyAssistant
+          data-testid='wally'
+          {...wally.snapshot}
+          formatTimestamp={fixedTime}
+          onSubmit={wally.send}
+          onStop={wally.stop}
+          onApprovalRespond={wally.respond}
+          headerActions={
+            <>
+              <Button variant='ghost' color='neutral' size='small' aria-label='New chat'>
+                <Plus />
+              </Button>
+              <Button variant='ghost' color='neutral' size='small' aria-label='Chat history'>
+                <History />
+              </Button>
+              <Separator orientation='vertical' />
+              <DrawerClose asChild>
+                <Button variant='ghost' color='neutral' size='small' aria-label='Close chat'>
+                  <X />
+                </Button>
+              </DrawerClose>
+            </>
+          }
+        />
+      </DrawerContent>
+    </Drawer>
+  );
+};
+
+/** Analytics attributes land on real nodes: the root `<section>`, header-action Buttons and a tagged Copy from `renderMessageActions` (like, dislike and timestamp stay default). Closed targets (pills, Send, approval options) report through their callbacks — see ANALYTICS_GAPS.md. */
+export const Analytics: StoryFn<typeof meta> = () => {
+  const wally = useMockWally({ initial: CONVERSATION });
+  const [feedback, setFeedback] = useState<Record<string, ChatFeedback | null>>({});
+  const [permissions, setPermissions] = useState(CONVERSATION.permissions);
+  const messages = wally.snapshot.messages.map(m =>
+    m.role === 'assistant' && m.id in feedback ? withFeedback(m, feedback[m.id] ?? null) : m,
+  );
+
+  const handleFeedback = (message: ChatAssistantMessage, value: ChatFeedback | null) => {
+    setFeedback(f => ({ ...f, [message.id]: value }));
+  };
+
+  const handlePermissionChange = (permission: ChatToolPermission, allowed: boolean) => {
+    setPermissions(list => list?.map(x => (x.id === permission.id ? { ...x, allowed } : x)));
+  };
+
+  return (
+    <div className='h-640 w-480'>
+      <WallyAssistant
+        data-testid='wally'
+        data-analytics-id='wally.panel'
+        data-analytics-props='{"surface":"story"}'
+        {...wally.snapshot}
+        messages={messages}
+        permissions={permissions}
+        formatTimestamp={fixedTime}
+        onSubmit={wally.send}
+        onStop={wally.stop}
+        onApprovalRespond={wally.respond}
+        onFeedback={handleFeedback}
+        onPermissionChange={handlePermissionChange}
+        headerActions={
+          <Button
+            variant='ghost'
+            color='neutral'
+            size='small'
+            aria-label='New chat'
+            data-analytics-id='wally.new-chat'
+          >
+            <Plus />
+          </Button>
+        }
+        renderMessageActions={renderAnalyticsActions}
+      />
+    </div>
+  );
+};
+```
+
+### WallyAssistant/mocks/index.ts
+
+````tsx
+/**
+ * Story and test fixtures for WallyAssistant, plus the custom SSE/REST mapper example from spec §10.2.
+ * Excluded from the build and the d.ts (`**\/mocks.{ts,tsx}`), like `Table/mocks.tsx`.
+ */
+import { useEffect, useReducer, useRef } from 'react';
+import { isRunningStatus } from '../model/deriveChatState';
+import type {
+  ChatApprovalPart,
+  ChatApprovalResponse,
+  ChatAssistantMessage,
+  ChatAssistantPart,
+  ChatChainOfThoughtPart,
+  ChatMessage,
+  ChatSnapshot,
+  ChatStatus,
+  ChatStep,
+  ChatStepStatus,
+} from '../model/model';
+
+export type WallyEvent =
+  | { t: 'user'; id: string; text: string; at?: string }
+  /** Insert, or replace by id anywhere in the reply. */
+  | { t: 'step'; step: ChatStep; parentId?: string }
+  /** Deltas aren't idempotent: real streams carry offsets or snapshots. */
+  | { t: 'text'; delta: string }
+  /** Insert, or replace by id (resolving it too). */
+  | { t: 'approval'; approval: ChatApprovalPart }
+  /** "Worked for 12s", stamped on the first block. */
+  | { t: 'summary'; text: string }
+  | { t: 'error'; text: string }
+  | { t: 'end'; stopped?: boolean };
+
+const LIVE = new Set<ChatStepStatus>(['pending', 'running', 'awaiting-approval']);
+
+const upsert = <T extends { id: string }>(list: readonly T[], item: T): readonly T[] => {
+  const i = list.findIndex(x => x.id === item.id);
+  return i < 0 ? [...list, item] : list.map((x, j) => (j === i ? item : x));
+};
+
+const isCot = (p: ChatAssistantPart): p is ChatChainOfThoughtPart => p.type === 'chain-of-thought';
+
+const hasStep = (steps: readonly ChatStep[], id: string): boolean =>
+  steps.some(s => s.id === id || hasStep(s.steps ?? [], id));
+
+/** Depth-first map; untouched branches keep their identity. */
+const mapSteps = (
+  steps: readonly ChatStep[],
+  f: (s: ChatStep) => ChatStep,
+): readonly ChatStep[] => {
+  const next = steps.map(s => {
+    const kids = s.steps && mapSteps(s.steps, f);
+    return f(kids === s.steps ? s : { ...s, steps: kids });
+  });
+  return next.every((s, i) => s === steps[i]) ? steps : next;
+};
+
+const mapBlocks = (
+  m: ChatAssistantMessage,
+  f: (steps: readonly ChatStep[]) => readonly ChatStep[],
+): ChatAssistantMessage => {
+  const parts = m.parts.map(p => {
+    if (!isCot(p)) return p;
+    const steps = f(p.steps);
+    return steps === p.steps ? p : { ...p, steps };
+  });
+  return parts.every((p, i) => p === m.parts[i]) ? m : { ...m, parts };
+};
+
+const addStep = (
+  m: ChatAssistantMessage,
+  step: ChatStep,
+  parentId?: string,
+): ChatAssistantMessage => {
+  const has = (id: string) => m.parts.some(p => isCot(p) && hasStep(p.steps, id));
+  if (has(step.id)) {
+    return mapBlocks(m, s =>
+      mapSteps(s, x => (x.id === step.id ? { ...step, steps: step.steps ?? x.steps } : x)),
+    );
+  }
+  if (parentId && has(parentId)) {
+    return mapBlocks(m, s =>
+      mapSteps(s, x => (x.id === parentId ? { ...x, steps: [...(x.steps ?? []), step] } : x)),
+    );
+  }
+  const tail = [...m.parts].reverse().find(p => p.type !== 'approval'); // approvals don't close a block
+  if (tail && isCot(tail)) {
+    return {
+      ...m,
+      parts: m.parts.map(p => (p === tail ? { ...tail, steps: [...tail.steps, step] } : p)),
+    };
+  }
+  // After text (or at the start): a new block.
+  return {
+    ...m,
+    parts: [
+      ...m.parts,
+      { type: 'chain-of-thought', id: `${m.id}:cot:${m.parts.length}`, steps: [step] },
+    ],
+  };
+};
+
+const settle = (m: ChatAssistantMessage, to: ChatStepStatus) =>
+  mapBlocks(m, s => mapSteps(s, x => (LIVE.has(x.status) ? { ...x, status: to } : x)));
+
+const cancelApprovals = (m: ChatAssistantMessage): ChatAssistantMessage => ({
+  ...m,
+  parts: m.parts.map(p =>
+    p.type === 'approval' && p.status === 'pending'
+      ? { ...p, status: 'rejected' as const, resolvedLabel: 'Cancelled' }
+      : p,
+  ),
+});
+
+const lastUserId = (s: ChatSnapshot) => {
+  for (let i = s.messages.length - 1; i >= 0; i--) {
+    if (s.messages[i]?.role === 'user') return s.messages[i]?.id;
+  }
+  return undefined;
+};
+
+/** The reply to the last user message, created on demand; its id is the one WallyAssistant's loading row uses. */
+const withReply = (
+  s: ChatSnapshot,
+  f: (m: ChatAssistantMessage) => ChatAssistantMessage,
+  status: ChatStatus = 'streaming',
+): ChatSnapshot => {
+  const id = `${lastUserId(s) ?? 'boot'}:reply`;
+  const prev = s.messages.find(m => m.id === id);
+  const reply: ChatAssistantMessage =
+    prev?.role === 'assistant' ? prev : { role: 'assistant', id, parts: [] };
+  return { ...s, status, messages: upsert(s.messages, f(reply)) }; // untouched messages keep their identity
+};
+
+/** Folds one backend event into the next immutable snapshot (spec §10.2). */
+export function reduceWally(s: ChatSnapshot, e: WallyEvent): ChatSnapshot {
+  switch (e.t) {
+    case 'user':
+      return {
+        ...s,
+        status: 'submitted',
+        messages: upsert(s.messages, {
+          role: 'user',
+          id: e.id,
+          createdAt: e.at,
+          parts: [{ type: 'text', id: `${e.id}:text`, text: e.text }],
+        }),
+      };
+    case 'step':
+      return withReply(s, m => addStep(m, e.step, e.parentId));
+    case 'text':
+      return withReply(s, m => {
+        const last = m.parts[m.parts.length - 1];
+        return last?.type === 'text'
+          ? { ...m, parts: [...m.parts.slice(0, -1), { ...last, text: last.text + e.delta }] }
+          : {
+              ...m,
+              parts: [
+                ...m.parts,
+                { type: 'text', id: `${m.id}:text:${m.parts.length}`, text: e.delta },
+              ],
+            };
+      });
+    case 'approval':
+      return withReply(s, m => {
+        const n = { ...m, parts: upsert(m.parts, e.approval) };
+        if (e.approval.status === 'pending') return n;
+        // ponytail: approvals don't name their step, so a resolution settles every HITL step in the reply
+        const to = e.approval.status === 'approved' ? 'done' : 'denied';
+        return mapBlocks(n, st =>
+          mapSteps(st, x => (x.status === 'awaiting-approval' ? { ...x, status: to } : x)),
+        );
+      });
+    case 'summary':
+      return withReply(s, m => {
+        const first = m.parts.find(isCot);
+        return first
+          ? { ...m, parts: m.parts.map(p => (p === first ? { ...first, summary: e.text } : p)) }
+          : m;
+      });
+    case 'error':
+      return withReply(
+        s,
+        m => {
+          const n = settle(m, 'error');
+          return {
+            ...n,
+            parts: upsert(n.parts, {
+              type: 'error',
+              id: `${m.id}:error`,
+              text: e.text,
+              retryable: true,
+            }),
+          };
+        },
+        'error',
+      );
+    case 'end':
+      return e.stopped
+        ? withReply(s, m => cancelApprovals(settle(m, 'cancelled')), 'ready')
+        : { ...s, status: 'ready' };
+    default:
+      return s; // unknown events are ignored: forward compatible
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Script
+// ---------------------------------------------------------------------------------------------------------------
+
+/** About 30ms per token at `speed: 1`. */
+const TOKEN_MS = 30;
+const tokens = (text: string) => text.match(/\S+\s*/g) ?? [];
+
+const REASONING =
+  'The user wants the noisiest attack sources. I will query the last 24 hours of attack events, ' +
+  'check which applications they hit, then read the policy to see what is already blocked.';
+const ANSWER =
+  'Over the last 24 hours `api.example.com` received 1,204 attacks, mostly SQL injection from 3 IPs.\n\n' +
+  'Two of those IPs are already on the denylist. I can propose a rule for the third one, `203.0.113.7`.';
+
+const reasoningStep = (status: ChatStepStatus, label: string, content?: string): ChatStep => ({
+  id: 'reasoning',
+  kind: 'reasoning',
+  status,
+  label,
+  content,
+});
+
+const tool = (id: string, icon: string, running: string, done: string, metric?: string) =>
+  [
+    [500, { t: 'step', step: { id, kind: 'tool', icon, status: 'running', label: running } }],
+    [900, { t: 'step', step: { id, kind: 'tool', icon, status: 'done', label: done, metric } }],
+  ] satisfies [number, WallyEvent][];
+
+/** `[delayMs, event]` pairs replayed by `useMockWally` after the user event (Streaming Simulation story). */
+export const WALLY_SCRIPT: readonly (readonly [number, WallyEvent])[] = [
+  [400, { t: 'step', step: reasoningStep('running', 'Thinking...') }],
+  ...tokens(REASONING).map(
+    (_, i, all) =>
+      [
+        TOKEN_MS,
+        { t: 'step', step: reasoningStep('running', 'Thinking...', all.slice(0, i + 1).join('')) },
+      ] as const,
+  ),
+  [200, { t: 'step', step: reasoningStep('done', 'Thought for 3s', REASONING) }],
+  ...tool('query', 'query', 'Querying attack events...', 'Queried attack events', '1,204'),
+  ...tool('apps', 'scan', 'Checking applications...', 'Checked 3 applications'),
+  ...tool(
+    'policy',
+    'read',
+    'Reading the policy for api.example.com...',
+    'Read the policy for api.example.com',
+  ),
+  ...tokens(ANSWER).map((delta, i) => [i === 0 ? 400 : TOKEN_MS, { t: 'text', delta }] as const),
+  [300, { t: 'summary', text: 'Worked for 12s' }],
+  [100, { t: 'end' }],
+];
+
+// ---------------------------------------------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------------------------------------------
+
+const userText = (id: string, text: string, createdAt?: string): ChatMessage => ({
+  role: 'user',
+  id,
+  createdAt,
+  parts: [{ type: 'text', id: `${id}:text`, text }],
+});
+
+const SUGGESTIONS: ChatSnapshot['suggestions'] = [
+  { id: 'top-attacks', label: 'Show top attacks today' },
+  {
+    id: 'blocked',
+    label: 'Which requests were blocked?',
+    prompt: 'Which requests were blocked in the last hour?',
+  },
+  { id: 'rule', label: 'Create a mitigation rule' },
+];
+
+const FOLLOW_UPS: ChatSnapshot['suggestions'] = [
+  { id: 'deny', label: 'Add 203.0.113.7 to the denylist' },
+  { id: 'details', label: 'Show attack details' },
+];
+
+/** No messages: the greeting with suggestion pills. */
+export const EMPTY: ChatSnapshot = { messages: [], status: 'ready', suggestions: SUGGESTIONS };
+
+/** Two finished turns plus follow-up suggestions and tool permissions. Timestamps are fixed: pass a fixed
+ *  `formatTimestamp` in screenshots. */
+export const CONVERSATION: ChatSnapshot = {
+  status: 'ready',
+  messages: [
+    userText('u1', 'Show me the top attacks from the last 24 hours', '2026-10-21T09:00:00.000Z'),
+    {
+      role: 'assistant',
+      id: 'u1:reply',
+      createdAt: '2026-10-21T09:00:12.000Z',
+      parts: [
+        {
+          type: 'chain-of-thought',
+          id: 'u1:reply:cot:0',
+          summary: 'Worked for 12s',
+          steps: [
+            reasoningStep('done', 'Thought for 3s', REASONING),
+            {
+              id: 'query',
+              kind: 'tool',
+              icon: 'query',
+              status: 'done',
+              label: 'Queried attack events',
+              metric: '1,204',
+            },
+            {
+              id: 'apps',
+              kind: 'tool',
+              icon: 'scan',
+              status: 'done',
+              label: 'Checked 3 applications',
+            },
+          ],
+        },
+        { type: 'text', id: 'u1:reply:text:1', text: ANSWER },
+      ],
+    },
+    userText('u2', 'Which of them were blocked?', '2026-10-21T09:01:00.000Z'),
+    {
+      role: 'assistant',
+      id: 'u2:reply',
+      createdAt: '2026-10-21T09:01:05.000Z',
+      feedback: 'positive',
+      parts: [
+        {
+          type: 'chain-of-thought',
+          id: 'u2:reply:cot:0',
+          steps: [{ id: 'reasoning', kind: 'reasoning', status: 'done', label: 'Thought for 2s' }],
+        },
+        {
+          type: 'text',
+          id: 'u2:reply:text:1',
+          text: '1,019 of the 1,204 attacks were blocked by the `sqli-default` rule. The other 185 came from `203.0.113.7`, which is not on the denylist yet.',
+        },
+      ],
+    },
+  ],
+  suggestions: FOLLOW_UPS,
+  permissions: [
+    {
+      id: 'deny',
+      title: 'propose_add_to_denylist',
+      description: 'Propose a denylist entry for an IP',
+      allowed: true,
+    },
+    { id: 'rules', title: 'create_mitigation_rule', allowed: false },
+  ],
+};
+
+/** A reply waiting on a pending approval. `status` stays 'ready', as with CopilotKit HITL tools (§7.5). */
+export const APPROVAL_PENDING: ChatSnapshot = {
+  status: 'ready',
+  messages: [
+    userText('u1', 'Block 203.0.113.7 for a day'),
+    {
+      role: 'assistant',
+      id: 'u1:reply',
+      parts: [
+        {
+          type: 'chain-of-thought',
+          id: 'u1:reply:cot:0',
+          steps: [
+            {
+              id: 'policy',
+              kind: 'tool',
+              icon: 'read',
+              status: 'done',
+              label: 'Read the policy for api.example.com',
+            },
+            {
+              id: 'deny',
+              kind: 'tool',
+              name: 'propose_add_to_denylist',
+              icon: 'create',
+              status: 'awaiting-approval',
+              label: 'Proposing a denylist entry...',
+            },
+          ],
+        },
+        {
+          type: 'approval',
+          id: 'u1:reply:approval',
+          status: 'pending',
+          content:
+            'Wally wants to run `propose_add_to_denylist`:\n\n```json\n{ "ip": "203.0.113.7", "duration": "24h" }\n```',
+        },
+      ],
+    },
+  ],
+};
+
+/** A run that failed before any output: an assistant message with only a retryable error part. */
+export const ERROR_TURN: ChatSnapshot = {
+  status: 'error',
+  messages: [
+    userText('u1', 'Show me the top attacks from the last 24 hours'),
+    {
+      role: 'assistant',
+      id: 'u1:reply',
+      parts: [
+        {
+          type: 'error',
+          id: 'u1:reply:error',
+          text: "Wally couldn't reach the attack store.",
+          retryable: true,
+        },
+      ],
+    },
+  ],
+};
+
+/** `n` finished messages, alternating user and assistant, for the perf test. */
+export const longThread = (n: number): ChatSnapshot => ({
+  status: 'ready',
+  messages: Array.from({ length: n }, (_, i): ChatMessage => {
+    const turn = Math.floor(i / 2) + 1;
+    return i % 2 === 0
+      ? userText(`u${turn}`, `Question ${turn}`)
+      : {
+          role: 'assistant',
+          id: `u${turn}:reply`,
+          parts: [{ type: 'text', id: `u${turn}:reply:text:0`, text: `Answer ${turn}` }],
+        };
+  }),
+});
+
+// ---------------------------------------------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------------------------------------------
+
+export interface UseMockWallyOptions {
+  /** Default `EMPTY`. */
+  initial?: ChatSnapshot;
+  /** Default `WALLY_SCRIPT`. */
+  script?: readonly (readonly [number, WallyEvent])[];
+  /** Delay multiplier: 1 = about 30ms per token, 0 = as fast as timers allow. Default 1. */
+  speed?: number;
+}
+
+export interface MockWally {
+  snapshot: ChatSnapshot;
+  /** Appends a user message (`u1`, `u2`, …) and replays the script. */
+  send: (text: string) => void;
+  /** Clears the timers, cancels live steps and pending approvals. */
+  stop: () => void;
+  /** Same signature as `onApprovalRespond`: resolves the approval in the next snapshot. */
+  respond: (response: ChatApprovalResponse, approval: ChatApprovalPart) => void;
+}
+
+/** Replays `script` against `reduceWally` with a `setTimeout` chain. Deterministic ids for stable screenshots. */
+export function useMockWally({
+  initial = EMPTY,
+  script = WALLY_SCRIPT,
+  speed = 1,
+}: UseMockWallyOptions = {}): MockWally {
+  const [snapshot, dispatch] = useReducer(reduceWally, initial);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  useEffect(() => () => clearTimeout(timer.current), []);
+
+  const play = (i: number) => {
+    const entry = script[i];
+    if (!entry) return;
+    const [delay, event] = entry;
+    timer.current = setTimeout(() => {
+      dispatch(event);
+      play(i + 1);
+    }, delay * speed);
+  };
+
+  const send = (text: string) => {
+    clearTimeout(timer.current);
+    const n = snapshot.messages.filter(m => m.role === 'user').length + 1;
+    dispatch({ t: 'user', id: `u${n}`, text });
+    play(0);
+  };
+
+  const stop = () => {
+    clearTimeout(timer.current);
+    dispatch({ t: 'end', stopped: true });
+  };
+
+  const respond = (response: ChatApprovalResponse, approval: ChatApprovalPart) => {
+    dispatch({
+      t: 'approval',
+      approval: { ...approval, status: response.approved ? 'approved' : 'rejected' },
+    });
+    // The reducer marks the reply as streaming; outside a run, put the status back to 'ready'.
+    if (!isRunningStatus(snapshot.status)) dispatch({ t: 'end' });
+  };
+
+  return { snapshot, send, stop, respond };
+}
+````
+
+### WallyAssistant/model/deriveChatState.ts
+
+```tsx
+import type {
+  ChatApprovalPart,
+  ChatId,
+  ChatMessage,
+  ChatStatus,
+  ChatStep,
+  ChatStepStatus,
+} from './model';
+
+export interface ChatViewState {
+  /** `messages`, plus an empty reply `{ role: 'assistant', id: `${lastUserMessageId}:reply`, parts: [] }` while
+   *  running and the last message is the user's (the loading row; the same id as the recommended mapper reply). */
+  rows: readonly ChatMessage[];
+  /** `messages.length === 0`. */
+  empty: boolean;
+  /** `status` is 'submitted' or 'streaming'. */
+  running: boolean;
+  /** The last row has a pending approval part. */
+  awaitingApproval: boolean;
+  /** `running && !awaitingApproval` → `aria-busy`. */
+  busy: boolean;
+  /** → Conversation `autoScrollKey`. */
+  lastUserMessageId?: ChatId;
+  /** Placement 'docked' only (§7.5). Render each with
+   *  `<ChatPartView part message={rows.at(-1)} isLast placement='docked' />`. */
+  dockedApprovals: readonly ChatApprovalPart[];
+}
+
+const LIVE_STEP_STATUSES: ReadonlySet<string> = new Set<ChatStepStatus>([
+  'pending',
+  'running',
+  'awaiting-approval',
+]);
+const NO_APPROVALS: readonly ChatApprovalPart[] = [];
+
+/** 'submitted' | 'streaming'. Unknown statuses behave like 'ready'. */
+export const isRunningStatus = (status: ChatStatus | undefined): boolean =>
+  status === 'submitted' || status === 'streaming';
+
+/** The step's own status is pending, running or awaiting-approval. */
+export const isLiveStepStatus = (status: ChatStepStatus): boolean => LIVE_STEP_STATUSES.has(status);
+
+/** The step or any nested step is live (§7.3). */
+export const isLiveStep = (step: ChatStep): boolean =>
+  isLiveStepStatus(step.status) || (step.steps?.some(isLiveStep) ?? false);
+
+const approvalsOf = (message: ChatMessage | undefined): ChatApprovalPart[] =>
+  message?.role === 'assistant'
+    ? message.parts.filter((p): p is ChatApprovalPart => p.type === 'approval')
+    : [];
+
+export const hasPendingApproval = (message: ChatMessage | undefined): boolean =>
+  approvalsOf(message).some(p => p.status === 'pending');
+
+/** The last row's pending approvals; when none is pending, its last approval (decision 11). */
+export const getDockedApprovals = (
+  lastRow: ChatMessage | undefined,
+): readonly ChatApprovalPart[] => {
+  const approvals = approvalsOf(lastRow);
+  const pending = approvals.filter(p => p.status === 'pending');
+  if (pending.length) return pending;
+  const last = approvals[approvals.length - 1];
+  return last ? [last] : NO_APPROVALS;
+};
+
+/** What Copy copies: `copyText`, or the non-empty text parts joined by a blank line. */
+export const copyTextOf = (message: ChatMessage): string =>
+  (message.role === 'assistant' && message.copyText) ||
+  message.parts.flatMap(p => (p.type === 'text' && p.text ? [p.text] : [])).join('\n\n');
+
+const lastUserIdOf = (messages: readonly ChatMessage[]): ChatId | undefined => {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role === 'user') return m.id;
+  }
+  return undefined;
+};
+
+/** Every derived rule of the chat, in one pure function shared by WallyAssistant and custom layouts (§7.1).
+ *  `approvalPlacement` must match the `ChatViewProvider`'s, or a docked approval renders twice or never. */
+export function deriveChatState(
+  messages: readonly ChatMessage[],
+  status: ChatStatus = 'ready',
+  approvalPlacement: 'docked' | 'inline' = 'inline',
+): ChatViewState {
+  const running = isRunningStatus(status);
+  const lastUserMessageId = lastUserIdOf(messages);
+  const last = messages[messages.length - 1];
+  const rows: readonly ChatMessage[] =
+    running && last?.role === 'user'
+      ? [...messages, { role: 'assistant', id: `${last.id}:reply`, parts: [] }]
+      : messages;
+  const lastRow = rows[rows.length - 1];
+  const awaitingApproval = hasPendingApproval(lastRow);
+
+  return {
+    rows,
+    empty: messages.length === 0,
+    running,
+    awaitingApproval,
+    busy: running && !awaitingApproval,
+    lastUserMessageId,
+    dockedApprovals: approvalPlacement === 'docked' ? getDockedApprovals(lastRow) : NO_APPROVALS,
+  };
+}
+```