@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/chat/README.md

@@ -6,8 +6,96 @@ Opinionated conversation surface bundling message list, composer, attachments, a
 
 ```svelte
 <script lang="ts">
-  import { Chat } from '@lostgradient/cinder/chat';
+  import {
+    Chat,
+    appendAssistantMessage,
+    appendUserMessage,
+    createConversation,
+  } from '@lostgradient/cinder/chat';
+
+  const conversation = appendAssistantMessage(
+    appendUserMessage(createConversation({ id: 'demo' }), 'Can you summarize this plan?'),
+    'The plan is ready to implement.',
+  );
 </script>
+
+<!-- Chat fills its parent; give the ancestor a definite height. -->
+<div style="height: 34rem;">
+  <Chat id="demo-chat" {conversation} />
+</div>
+```
+
+> [!IMPORTANT] Chat needs a definite-height ancestor
+> Chat's root element fills its parent (`height: 100%`). Place it inside an
+> ancestor with a resolved height—a fixed height, a flex or grid cell, or
+> `height: 100dvh`—or the message viewport collapses and Chat renders as a
+> small card instead of filling its space. See [Layout and sizing](#layout-and-sizing).
+
+## Layout and sizing
+
+Chat's root (`.chat-container`) is `height: 100%`. When no ancestor on the
+chain resolves to a definite height, that `100%` resolves against `auto` and
+Chat collapses to the intrinsic height of its empty state plus composer. There
+is no browser error: it just silently shrinks to a small card. Give Chat a
+sized ancestor with one of the three patterns below.
+
+**Fixed-height container.** The simplest option—wrap Chat in an element with
+an explicit height. This is what every example in this component uses.
+
+```svelte
+<div style="height: 34rem;">
+  <Chat id="support-chat" {conversation} />
+</div>
+```
+
+**Full-viewport flex column.** For an app shell where Chat should fill the
+remaining space, give the column a definite height and let the Chat cell
+`flex: 1` with `min-height: 0` (so it can shrink below its content and scroll
+internally rather than overflowing the page).
+
+```svelte
+<div class="chat-page">
+  <header>…</header>
+  <Chat id="app-chat" class="chat-page-surface" {conversation} />
+</div>
+
+<style>
+  .chat-page {
+    display: flex;
+    flex-direction: column;
+    height: 100dvh;
+  }
+
+  /* `:global` because the class lands on Chat's own root element. */
+  .chat-page :global(.chat-page-surface) {
+    flex: 1;
+    min-height: 0;
+  }
+</style>
+```
+
+**Grid cell.** The same shape works in a grid: give the container a resolved
+track (`grid-template-rows: auto 1fr`), place Chat in the `1fr` row, and keep
+`min-height: 0` on the Chat cell so it can shrink and scroll internally instead
+of overflowing the page.
+
+```svelte
+<div class="chat-grid">
+  <header>…</header>
+  <Chat id="grid-chat" class="chat-grid-surface" {conversation} />
+</div>
+
+<style>
+  .chat-grid {
+    display: grid;
+    grid-template-rows: auto 1fr;
+    height: 100dvh;
+  }
+
+  .chat-grid :global(.chat-grid-surface) {
+    min-height: 0;
+  }
+</style>
 ```
 
 ## Guidance
@@ -26,41 +114,66 @@ Opinionated conversation surface bundling message list, composer, attachments, a
 
 <!-- generated:props:start -->
 
-| Prop                      | Type                           | Required | Default | Description                                                                                                                |
-| ------------------------- | ------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `allowAttachments`        | `boolean`                      | no       | —       |                                                                                                                            |
-| `allowCopy`               | `boolean`                      | no       | —       |                                                                                                                            |
-| `allowEditing`            | `boolean`                      | no       | —       |                                                                                                                            |
-| `allowRetry`              | `boolean`                      | no       | —       |                                                                                                                            |
-| `allowSearch`             | `boolean`                      | no       | —       |                                                                                                                            |
-| `bottomThreshold`         | `number`                       | no       | —       |                                                                                                                            |
-| `class`                   | `string`                       | no       | —       |                                                                                                                            |
-| `emptyPrompts`            | `string`[]                     | no       | —       |                                                                                                                            |
-| `hasNewMessageIndicator`  | `boolean`                      | no       | —       |                                                                                                                            |
-| `id`                      | `string`                       | yes      | —       |                                                                                                                            |
-| `isAtBottom`              | `boolean`                      | no       | —       |                                                                                                                            |
-| `isStreaming`             | `boolean`                      | no       | —       |                                                                                                                            |
-| `jumpThreshold`           | `number`                       | no       | —       |                                                                                                                            |
-| `streamingStatus`         | `string`                       | no       | —       |                                                                                                                            |
-| `surfaceMode`             | `"default"` \| `"transparent"` | no       | —       |                                                                                                                            |
-| `unreadCount`             | `number`                       | no       | —       |                                                                                                                            |
-| `conversation`            | `(opaque)`                     | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
-| `empty`                   | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `header`                  | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `messageActions`          | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `messageStatus`           | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onattachmentadd`         | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onattachmentfailure`     | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onattachmentremove`      | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onedit`                  | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onexpandedchange`        | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onjumptolatest`          | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onretry`                 | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onscrollstatechange`     | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onstopgenerating`        | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onsubmit`                | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onunreadindicatorchange` | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `viewportAttachment`      | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop                               | Type                           | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------------------- | ------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allowAttachments`                 | `boolean`                      | no       | —       | Whether file attachments are enabled in the composer. When `false`, the attachment button is hidden and drag-and-drop onto the chat surface is suppressed. Default `true`.                                                                                                                                                                                                                                                             |
+| `allowCopy`                        | `boolean`                      | no       | —       | Whether per-message copy buttons are shown in the message action bar. Default `true`.                                                                                                                                                                                                                                                                                                                                                  |
+| `allowEditing`                     | `boolean`                      | no       | —       | Whether user messages can be edited inline. Default `true`.                                                                                                                                                                                                                                                                                                                                                                            |
+| `allowRetry`                       | `boolean`                      | no       | —       | Whether failed assistant messages show a retry button. Default `true`.                                                                                                                                                                                                                                                                                                                                                                 |
+| `allowSearch`                      | `boolean`                      | no       | —       | Whether in-conversation search is enabled. When `true`, pressing Ctrl+F / Cmd+F opens a search bar that highlights matching messages. Default `true`.                                                                                                                                                                                                                                                                                  |
+| `bottomThreshold`                  | `number`                       | no       | —       | Distance in pixels from the bottom of the scroll viewport within which the chat is considered "at bottom" and will auto-scroll on new messages. Default `150`.                                                                                                                                                                                                                                                                         |
+| `class`                            | `string`                       | no       | —       | Additional class name merged onto the `.chat-container` root element.                                                                                                                                                                                                                                                                                                                                                                  |
+| `density`                          | `"comfortable"` \| `"compact"` | no       | —       | Controls spacing density of the message timeline. - `'comfortable'` (default): standard padding and gap. - `'compact'`: tighter spacing for data-dense contexts (e.g., embedded panels). Action buttons keep `min-height: var(--cinder-touch-target-min)` regardless.                                                                                                                                                                  |
+| `emptyPrompts`                     | `string`[]                     | no       | —       | List of suggested starter prompt strings shown as clickable buttons in the default empty state. Clicking a prompt submits it immediately as a user message. Has no effect when a custom `empty` snippet is provided.                                                                                                                                                                                                                   |
+| `hasMoreHistory`                   | `boolean`                      | no       | —       | Whether the explicit "Load earlier messages" trigger is shown when a load handler exists. Default `true`.                                                                                                                                                                                                                                                                                                                              |
+| `hasNewMessageIndicator`           | `boolean`                      | no       | —       | Whether the "new messages" indicator is currently visible above the composer. Bindable; cleared automatically when the viewport reaches the bottom. Default `false`.                                                                                                                                                                                                                                                                   |
+| `id`                               | `string`                       | yes      | —       | Unique identifier used to scope accessibility attributes across the chat surface.                                                                                                                                                                                                                                                                                                                                                      |
+| `isAtBottom`                       | `boolean`                      | no       | —       | Whether the message viewport is scrolled to the bottom. Bindable; updated automatically as the user scrolls. Default `true`.                                                                                                                                                                                                                                                                                                           |
+| `isStreaming`                      | `boolean`                      | no       | —       | Whether a streaming response is currently in progress. When `true`, the composer is disabled and a stop-generating button is shown. Default `false`.                                                                                                                                                                                                                                                                                   |
+| `jumpThreshold`                    | `number`                       | no       | —       | Distance in pixels scrolled up from the bottom required before the jump-to-latest button appears. Must be greater than `bottomThreshold` to prevent button flickering. Default `200`.                                                                                                                                                                                                                                                  |
+| `loadEarlierLabel`                 | `string`                       | no       | —       | Label for the history pagination trigger. Default `"Load earlier messages"`.                                                                                                                                                                                                                                                                                                                                                           |
+| `loadingEarlierLabel`              | `string`                       | no       | —       | Status text while older messages are loading. Default `"Loading earlier messages"`.                                                                                                                                                                                                                                                                                                                                                    |
+| `streamingStatus`                  | `string`                       | no       | —       | Optional status label displayed in the typing indicator while `isStreaming` is `true` and no streaming content has arrived yet (e.g. `"Thinking…"` or `"Analyzing file…"`). When omitted, three animated dots are shown.                                                                                                                                                                                                               |
+| `surfaceMode`                      | `"default"` \| `"transparent"` | no       | —       | Controls the background of the chat surface. Use `'transparent'` to inherit the host element's background when embedding chat inside a card or panel. Default `'default'`.                                                                                                                                                                                                                                                             |
+| `unreadCount`                      | `number`                       | no       | —       | Number of messages received while the viewport was scrolled away from the bottom. Bindable; resets to `0` when the user scrolls to the bottom. Default `0`.                                                                                                                                                                                                                                                                            |
+| `variant`                          | `"bubble"` \| `"flat"`         | no       | —       | Visual treatment for message bubbles. - `'bubble'` (default): colored backgrounds differentiate user from assistant. - `'flat'`: no bubble backgrounds; role is communicated via alignment and role label. Text-on-surface contrast meets WCAG AA via `--cinder-text` on `--cinder-surface-inset`.                                                                                                                                     |
+| `virtualizationEstimatedRowHeight` | `number`                       | no       | —       | Estimated row height in pixels for virtualized message rows. Default `88`.                                                                                                                                                                                                                                                                                                                                                             |
+| `virtualizationInitialHeight`      | `number`                       | no       | —       | Initial virtualized viewport height used before measurement. Default `640`.                                                                                                                                                                                                                                                                                                                                                            |
+| `virtualizationOverscan`           | `number`                       | no       | —       | Number of extra virtual rows rendered before and after the viewport. Default `3`.                                                                                                                                                                                                                                                                                                                                                      |
+| `virtualized`                      | `boolean`                      | no       | —       | Use the virtualized message render path for long transcripts. The complete `ConversationHistory` remains unchanged; only the DOM window is reduced. Default `false`.                                                                                                                                                                                                                                                                   |
+| `adapter`                          | `(opaque)`                     | no       | —       | Optional command/transport boundary around `conversation`. Its methods take precedence over the matching callback props (e.g. `sendMessage` over `onsubmit`); omit it and Chat behaves exactly as with plain callbacks. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                     |
+| `conversation`                     | `(opaque)`                     | yes      | —       | The conversation transcript to render. Pass a {@link ConversationHistory} snapshot; consumers holding a stateful conversation object pass its current snapshot (e.g. `conversation.current`). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                               |
+| `empty`                            | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `header`                           | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `messageActions`                   | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `messagePart`                      | `(opaque)`                     | no       | —       | Per-message-part override. Replaces the rendering of an individual body part (markdown, tool call, tool result) while delegating the rest to the built-ins via the `renderDefault` snippet it receives. Image parts are excluded — they render through the grouped attachment grid, not this override. Not expressible in JSON Schema; see the component types for the signature.                                                      |
+| `messageReasoning`                 | `(opaque)`                     | no       | —       | Override or supplement the reasoning text for a message. Called per-message; return a non-empty string to show a reasoning block, `undefined` to fall back to `message.metadata['cinder:reasoning']`, empty string to suppress reasoning. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                   |
+| `messageStatus`                    | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `messageSteps`                     | `(opaque)`                     | no       | —       | Override or supplement the step list for a message. Called per-message; return an array to show step indicators, `undefined` to fall back to `message.metadata['cinder:steps']`. An empty array suppresses steps. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                           |
+| `messageSuggestions`               | `(opaque)`                     | no       | —       | Override or supplement the suggestion list for a message. Called per-message; return an array of label strings to show suggestion chips, `undefined` to fall back to `message.metadata['cinder:suggestions']`. An empty array suppresses suggestions. Not expressible in JSON Schema; see the component types for the signature.                                                                                                       |
+| `onadaptererror`                   | `(opaque)`                     | no       | —       | Called when an adapter command fails — either a rejected promise or a synchronous throw from the method. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                    |
+| `onapprove`                        | `(opaque)`                     | no       | —       | Called when the user approves an action-required tool call. The consumer is responsible for updating its transcript (e.g. calling conversationalist to unblock the pending tool) and triggering a new generation. When an adapter is also wired, Chat calls `adapter.approveToolCall(toolCallId)` first and then this callback. Not expressible in JSON Schema; see the component types for the signature.                             |
+| `onattachmentadd`                  | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onattachmentfailure`              | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onattachmentremove`               | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `ondeny`                           | `(opaque)`                     | no       | —       | Called when the user denies an action-required tool call. When an adapter is also wired, Chat calls `adapter.denyToolCall(toolCallId)` first and then this callback. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                        |
+| `onedit`                           | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onexpandedchange`                 | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onjumptolatest`                   | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onloadhistory`                    | `(opaque)`                     | no       | —       | Called when the explicit history trigger is activated. The consumer prepends compatible messages into `conversation`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                       |
+| `onpushmessage`                    | `(opaque)`                     | no       | —       | Forwarded from the adapter's real-time `onMessage` push (consumer owns the transcript). Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                     |
+| `onreadreceipt`                    | `(opaque)`                     | no       | —       | Forwarded from the adapter's real-time `onReadReceipt` push. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                |
+| `onretry`                          | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onscrollstatechange`              | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onstopgenerating`                 | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onsubmit`                         | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `onsuggestionselect`               | `(opaque)`                     | no       | —       | Called when the user selects a suggestion chip. The label string is passed back. The consumer is responsible for submitting it as a new user message. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                       |
+| `ontypingchange`                   | `(opaque)`                     | no       | —       | Forwarded from the adapter's real-time `onTypingChange` push. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                               |
+| `onunreadindicatorchange`          | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
+| `readReceipts`                     | `(opaque)`                     | no       | —       | Per-message read receipt state. Out-of-band UI state — NOT stored on `Message`. Pass a `Map` keyed by message id with a {@link ReadReceipt} value; the component renders a receipt badge on USER messages only. The adapter's `onReadReceipt` push handler populates the same state when an adapter is wired. Default `undefined` (no receipts shown). Not expressible in JSON Schema; see the component types for the signature.      |
+| `row`                              | `(opaque)`                     | no       | —       | Full-row override. Renders an entire message row; receives the message and a `renderDefault` snippet for the built-in row (inversion of control), so a consumer can wrap or fully replace specific rows. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                    |
+| `typingParticipants`               | `(opaque)`                     | no       | —       | Participants who are currently typing. Out-of-band UI state — NOT stored on `Message`. Pass an array of {@link TypingParticipant} objects; the component renders a per-participant typing indicator above the input. The adapter's `onTypingChange` push handler feeds the same indicator when an adapter is wired. Default `undefined` (indicator hidden). Not expressible in JSON Schema; see the component types for the signature. |
+| `viewportAttachment`               | `(opaque)`                     | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                                                                                                             |
 
 <!-- generated:props:end -->
 

package/src/components/chat/adapter/chat-adapter.ts

@@ -0,0 +1,132 @@
+/**
+ * Optional adapter event/transport seam for the Chat component.
+ *
+ * `ChatAdapter` names the send / retry / edit / stop / tool-approval / history /
+ * real-time contract around the existing `conversation` prop WITHOUT coupling
+ * Chat to any transport. It is purely an event boundary — NOT a second
+ * conversation model. Every method parameter and every push payload uses the
+ * structural mirror types from `../conversation-model.ts`, so a consumer whose
+ * authoritative transcript lives in `conversationalist` can pass a plain
+ * `ConversationHistory` snapshot to `<Chat>` and wire an adapter with zero
+ * adaptation. This module is TYPE-ONLY — it ships no runtime code and imports
+ * nothing at runtime, so it is trivially SSR-safe.
+ *
+ * The adapter is always optional. When omitted, Chat behaves exactly as it does
+ * with its plain callback props (`onsubmit` / `onretry` / `onedit` /
+ * `onstopgenerating`); the internal command dispatcher routes both paths
+ * identically (adapter method first, callback fallback).
+ *
+ * @module
+ */
+
+import type { Message, MessageInput, ToolCall, ToolResult } from '../conversation-model.ts';
+import type { ChatAttachment } from '../input/chat-attachment.ts';
+
+/**
+ * A read-receipt push event: a message was read at a point in time. The payload
+ * is an object (not positional args) so later tasks can extend it — e.g. with a
+ * participant id — without a breaking signature change.
+ */
+export type ChatReadReceiptEvent = {
+  /** The id of the message that was read. */
+  messageId: string;
+  /** ISO-8601 timestamp at which the message was read. */
+  readAt: string;
+  /**
+   * Optional list of reader display names. When present, the read receipt badge
+   * will show "Read by Alice, Bob" in its accessible label.
+   */
+  readBy?: string[];
+};
+
+/**
+ * Push handlers Chat hands to {@link ChatAdapter.subscribe}. The adapter invokes
+ * these as real-time transport events arrive.
+ *
+ * Streaming handlers drive Chat's own imperative streaming buffer
+ * (`onStreamBegin`/`onTokenPush`/`onStreamEnd` → `beginStreaming`/`pushToken`/
+ * `endStreaming`), so a push-driven stream is fully self-contained — the
+ * consumer does not also have to call the imperative API by hand.
+ *
+ * Transcript/peripheral handlers (`onMessage`/`onTypingChange`/`onReadReceipt`)
+ * concern state Chat does NOT own (the consumer owns `conversation`), so Chat
+ * forwards them verbatim to the matching pass-through callback props. It never
+ * mutates `conversation` in response.
+ */
+export type ChatPushHandlers = {
+  /** A new (or updated) message arrived. Forwarded to the consumer; Chat does not mutate the transcript. */
+  onMessage: (message: Message) => void;
+  /** A participant's typing state changed. Forwarded to the consumer. */
+  onTypingChange: (isTyping: boolean) => void;
+  /** A read receipt arrived. Forwarded to the consumer. */
+  onReadReceipt: (event: ChatReadReceiptEvent) => void;
+  /** Streaming began for a message — drives Chat's `beginStreaming(messageId)`. */
+  onStreamBegin: (messageId: string) => void;
+  /** A streaming token arrived — drives Chat's `pushToken(token)`. */
+  onTokenPush: (token: string) => void;
+  /** Streaming ended — drives Chat's `endStreaming()`. */
+  onStreamEnd: () => void;
+};
+
+/**
+ * Optional command/transport boundary around `<Chat conversation={…}>`.
+ *
+ * Only `sendMessage` is required; everything else is optional so an adapter can
+ * opt into exactly the capabilities its transport supports. Command methods
+ * return `Promise<void>` — Chat awaits them and routes any failure (a rejected
+ * promise OR a synchronous throw from the method) to `onadaptererror` rather
+ * than swallowing it.
+ *
+ * The optional `approveToolCall`/`denyToolCall` (consumed by the tool-approval
+ * task) and `loadOlderMessages` (consumed by the load-history task) are declared
+ * here so the seam is complete; their UI wiring lands with those tasks.
+ */
+export type ChatAdapter = {
+  /** Send a composed message with its attachments. */
+  sendMessage: (message: MessageInput, attachments: ChatAttachment[]) => Promise<void>;
+  /** Retry a previously-failed message by id. */
+  retryMessage?: (messageId: string) => Promise<void>;
+  /** Commit an edit to a user message. */
+  editMessage?: (event: { messageId: string; content: string }) => Promise<void>;
+  /** Stop an in-progress generation for a message. */
+  stopGenerating?: (messageId: string) => Promise<void>;
+  /**
+   * Load a page of older messages for the given conversation. Returns whether
+   * more remain. (UI wired by the load-history task.)
+   */
+  loadOlderMessages?: (conversationId: string) => Promise<{ hasMore: boolean }>;
+  /**
+   * Subscribe to real-time events for a conversation. Receives the conversation
+   * id (so the transport knows which channel to open) plus the push handlers,
+   * and returns an unsubscribe function Chat calls on teardown.
+   */
+  subscribe?: (conversationId: string, handlers: ChatPushHandlers) => () => void;
+  /** Approve an action-required tool call by id. (UI wired by the tool-approval task.) */
+  approveToolCall?: (toolCallId: string) => Promise<void>;
+  /** Reject an action-required tool call by id. (UI wired by the tool-approval task.) */
+  denyToolCall?: (toolCallId: string) => Promise<void>;
+};
+
+/**
+ * The set of commands the internal dispatcher routes. Used to tag an
+ * {@link ChatAdapterErrorEvent} so a consumer can tell which command failed.
+ */
+export type ChatCommand =
+  | 'sendMessage'
+  | 'retryMessage'
+  | 'editMessage'
+  | 'stopGenerating'
+  | 'loadOlderMessages'
+  | 'approveToolCall'
+  | 'denyToolCall';
+
+/** Error event surfaced when an adapter command fails (rejection or sync throw). */
+export type ChatAdapterErrorEvent = {
+  /** Which command's adapter method failed. */
+  command: ChatCommand;
+  /** The thrown value. */
+  error: unknown;
+};
+
+/** Re-export the mirror types an adapter author needs, from one place. */
+export type { Message, MessageInput, ToolCall, ToolResult };

package/src/components/chat/adapter/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Chat adapter seam — the optional event/transport boundary around `<Chat>`.
+ *
+ * Type-only; see `./chat-adapter.ts`.
+ *
+ * @module
+ */
+
+export type {
+  ChatAdapter,
+  ChatAdapterErrorEvent,
+  ChatCommand,
+  ChatPushHandlers,
+  ChatReadReceiptEvent,
+} from './chat-adapter.ts';

package/src/components/chat/chat.examples.json

@@ -7,13 +7,19 @@
       "id": "basic",
       "title": "Basic chat",
       "description": "A conversation with editable input and markdown rendering.",
-      "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendAssistantMessage,\n    appendUserMessage,\n    createConversation,\n  } from '@lostgradient/cinder/chat';\n\n  let conversation = $state(\n    appendAssistantMessage(\n      appendUserMessage(createConversation({ id: 'basic-chat' }), 'Can you summarize this plan?'),\n      `The plan is ready to implement.\n\n1. Port the component surface.\n2. Add focused demos.\n3. Keep the public API importable by subpath.`,\n    ),\n  );\n</script>\n\n<div style=\"height: 34rem;\">\n  <Chat id=\"playground-basic-chat\" {conversation} allowAttachments={false} />\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendAssistantMessage,\n    appendUserMessage,\n    createConversation,\n  } from '@lostgradient/cinder/chat';\n\n  // `id` below is the conversation snapshot's data key — it never reaches a DOM\n  // element id (Chat derives every rendered id from its `id` prop, scoped above\n  // as `chatId`), so it needs no mount-prefix scoping.\n  let conversation = $state(\n    appendAssistantMessage(\n      appendUserMessage(createConversation({ id: 'basic-chat' }), 'Can you summarize this plan?'),\n      `The plan is ready to implement.\n\n1. Port the component surface.\n2. Add focused demos.\n3. Keep the public API importable by subpath.`,\n    ),\n  );\n</script>\n\n<div style=\"height: 34rem;\">\n  <Chat id=\"chat\" {conversation} allowAttachments={false} />\n</div>\n"
+    },
+    {
+      "id": "density-and-variant",
+      "title": "Density and variant",
+      "description": "Compare comfortable vs compact density and bubble vs flat visual variant on the same conversationalist-shaped transcript.",
+      "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendAssistantMessage,\n    appendUserMessage,\n    createConversation,\n  } from '@lostgradient/cinder/chat';\n  import { Select } from '@lostgradient/cinder/select';\n\n  // Build a shared conversationalist-shaped transcript (no Cinder-only fields).\n  const baseConversation = appendAssistantMessage(\n    appendUserMessage(\n      appendAssistantMessage(\n        appendUserMessage(\n          createConversation({ id: 'density-variant-chat' }),\n          'What are the density and variant props for?',\n        ),\n        'The `density` prop controls spacing — `comfortable` uses standard padding and gap, `compact` tightens them for data-dense contexts like embedded side panels.\\n\\nThe `variant` prop controls visual treatment — `bubble` uses colored backgrounds to differentiate roles; `flat` removes backgrounds and relies on alignment and the role label instead.',\n      ),\n      'Does compact affect the action buttons?',\n    ),\n    'No — action buttons keep `min-height: var(--cinder-touch-target-min)` regardless of density. Only padding and gap change.',\n  );\n\n  type Density = 'comfortable' | 'compact';\n  type Variant = 'bubble' | 'flat';\n\n  const densityOptions = [\n    { value: 'comfortable', label: 'comfortable' },\n    { value: 'compact', label: 'compact' },\n  ] satisfies { value: Density; label: string }[];\n\n  const variantOptions = [\n    { value: 'bubble', label: 'bubble' },\n    { value: 'flat', label: 'flat' },\n  ] satisfies { value: Variant; label: string }[];\n\n  let density = $state<Density>('comfortable');\n  let variant = $state<Variant>('bubble');\n</script>\n\n<div style=\"display: grid; gap: 1rem;\">\n  <div style=\"display: flex; gap: 1rem; align-items: flex-end; flex-wrap: wrap;\">\n    <Select id=\"density-select\" bind:value={density} options={densityOptions} label=\"Density\" />\n    <Select id=\"variant-select\" bind:value={variant} options={variantOptions} label=\"Variant\" />\n  </div>\n\n  <div style=\"height: 28rem;\">\n    <Chat\n      id=\"density-variant\"\n      conversation={baseConversation}\n      {density}\n      {variant}\n      allowAttachments={false}\n    />\n  </div>\n</div>\n"
     },
     {
       "id": "interactive-harness",
       "title": "Interactive harness",
       "description": "Drive Chat from a control panel: reply as the other side (instant / typing / streaming), inject tool calls, toggle features, and watch every callback fire.",
-      "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendAssistantMessage,\n    appendMessages,\n    appendUserMessage,\n    createConversation,\n    type ChatSubmitEvent,\n    type ConversationHistory,\n    type JSONValue,\n    type Message,\n    type ToolErrorCategory,\n  } from '@lostgradient/cinder/chat';\n  import { Button } from '@lostgradient/cinder/button';\n  import { Segment } from '@lostgradient/cinder/segment';\n  import { SegmentedControl } from '@lostgradient/cinder/segmented-control';\n  import { Select } from '@lostgradient/cinder/select';\n  import { Toggle } from '@lostgradient/cinder/toggle';\n  import { onDestroy } from 'svelte';\n\n  // Out of scope for this harness (documented, not silently dropped):\n  // bottomThreshold / jumpThreshold (kept at defaults so overflow + jump are\n  // testable without tuning), viewportAttachment (advanced escape hatch), and\n  // the isAtBottom / unreadCount / hasNewMessageIndicator bindables (read-only\n  // mirrors of behavior the wired callbacks already surface).\n\n  // --- Chat instance (for the imperative streaming + scroll API) ---\n  // Plain `let`: only read via `chat?.method()` calls, never reactively.\n  let chat: ReturnType<typeof Chat> | undefined;\n\n  // --- Conversation state (immutable snapshots via the cinder/chat builders) ---\n  let conversation = $state<ConversationHistory>(createConversation({ id: 'harness' }));\n\n  // --- Feature toggles wired straight onto <Chat> ---\n  let allowAttachments = $state(true);\n  let allowSearch = $state(true);\n  let allowCopy = $state(true);\n  let allowEditing = $state(true);\n  let allowRetry = $state(true);\n  let transparentSurface = $state(false);\n  let withEmptyPrompts = $state(true);\n  let autoReply = $state(true);\n\n  // --- Reply controls ---\n  let replyText = $state('Here is the answer, delivered in a few deliberate chunks.');\n  let replyMode = $state<'instant' | 'typing' | 'streaming'>('typing');\n  let streamMechanism = $state<'imperative' | 'content-mutation'>('imperative');\n  let isStreaming = $state(false);\n  let streamingStatus = $state('');\n\n  // --- Tool-call controls ---\n  let toolName = $state('exports_check');\n  let toolArguments = $state('{ \"package\": \"@lostgradient/cinder\" }');\n  let toolOutcome = $state<'success' | 'error' | 'action_required'>('success');\n  const parsedToolArguments = $derived.by<{ ok: boolean; value: JSONValue }>(() => {\n    try {\n      return { ok: true, value: JSON.parse(toolArguments) as JSONValue };\n    } catch {\n      return { ok: false, value: null };\n    }\n  });\n\n  // --- Event log (queryable: data-event + data-payload per entry) ---\n  // Chat emits a burst of identical onunreadindicatorchange events while its\n  // empty state settles on mount (all `{unreadCount:0, hasNewMessageIndicator:\n  // false}`). We de-duplicate: a callback whose (event, payload) is identical to\n  // the most recent entry for that event is dropped. That kills the mount noise\n  // deterministically (no timing dependency) while still recording every real,\n  // distinct callback so tests can assert \"this fired because of my action\".\n  type LogEntry = { id: number; event: string; payload: string };\n  let log = $state<LogEntry[]>([]);\n  let logCounter = 0;\n  const lastPayloadByEvent = new Map<string, string>();\n  function record(event: string, payload: unknown = ''): void {\n    const text = typeof payload === 'string' ? payload : JSON.stringify(payload);\n    if (lastPayloadByEvent.get(event) === text) return;\n    lastPayloadByEvent.set(event, text);\n    logCounter += 1;\n    log = [{ id: logCounter, event, payload: text }, ...log].slice(0, 50);\n  }\n\n  // --- Pending-operation discipline (instance-local; NEVER module scope) ---\n  // A single in-flight typing/streaming op at a time. Timers are tracked so we\n  // can cancel deterministically; streamingPartial holds the accumulated text so\n  // Stop can preserve it.\n  let pendingTimers = new Set<ReturnType<typeof setTimeout>>();\n  // Plain `let`: read only inside the streaming functions, never in the\n  // template (the assistant message content comes from `conversation`).\n  let streamingPartial = '';\n  let streamingMessageId: string | null = null;\n  // Monotonic token identifying the current stream/typing op. Each scheduled\n  // chunk captures the token active when it was queued and bails if a newer op\n  // has started — so an already-dequeued timer can't write into a fresh stream.\n  let activeOperation = 0;\n\n  function later(callback: () => void, delay: number): void {\n    const handle = setTimeout(() => {\n      pendingTimers.delete(handle);\n      callback();\n    }, delay);\n    pendingTimers.add(handle);\n  }\n\n  function clearTimers(): void {\n    for (const handle of pendingTimers) clearTimeout(handle);\n    pendingTimers.clear();\n  }\n\n  /**\n   * Cancel the in-flight op. Modes differ in how they treat partial content:\n   * - preservePartial (Stop): keep what streamed so far, commit it to the message.\n   * - discard (Clear / Seed / mode switch / new reply): drop the in-flight\n   *   (possibly empty) assistant message so no blank bubble is left behind.\n   * - destroy (onDestroy): just clear timers.\n   */\n  function cancelPending(mode: 'preservePartial' | 'discard' | 'destroy'): void {\n    clearTimers();\n    // Invalidate the current op so any timer callback already dequeued (past\n    // clearTimers) bails instead of mutating freshly-reset state.\n    activeOperation += 1;\n    if (mode === 'destroy') return;\n\n    if (streamingMessageId) {\n      if (mode === 'preservePartial') {\n        conversation = replaceMessageContent(conversation, streamingMessageId, streamingPartial);\n      } else {\n        conversation = removeMessage(conversation, streamingMessageId);\n      }\n      chat?.endStreaming();\n    }\n    streamingMessageId = null;\n    streamingPartial = '';\n    isStreaming = false;\n    streamingStatus = '';\n  }\n\n  // --- Immutable message helpers (replace/remove by id) ---\n  function replaceMessageContent(\n    current: ConversationHistory,\n    id: string,\n    content: string,\n  ): ConversationHistory {\n    const existing = current.messages[id];\n    if (!existing) return current;\n    return {\n      ...current,\n      messages: { ...current.messages, [id]: { ...existing, content } },\n      updatedAt: new Date().toISOString(),\n    };\n  }\n\n  function removeMessage(current: ConversationHistory, id: string): ConversationHistory {\n    if (!current.messages[id]) return current;\n    const messages = { ...current.messages };\n    delete messages[id];\n    return {\n      ...current,\n      ids: current.ids.filter((existing) => existing !== id),\n      messages,\n      updatedAt: new Date().toISOString(),\n    };\n  }\n\n  function lastMessageId(current: ConversationHistory): string {\n    return current.ids[current.ids.length - 1] ?? '';\n  }\n\n  // --- Reply as the other side ---\n  function sendReply(text: string): void {\n    const trimmed = text.trim();\n    if (!trimmed) return;\n    cancelPending('discard');\n    // Start a new operation; stale timers from a prior op will no longer match.\n    const operation = ++activeOperation;\n\n    if (replyMode === 'instant') {\n      conversation = appendAssistantMessage(conversation, trimmed);\n      return;\n    }\n\n    if (replyMode === 'typing') {\n      isStreaming = true;\n      streamingStatus = 'Assistant is typing…';\n      // A deliberately long-ish window so the \"typing\" state is comfortably\n      // observable (by a person and by a test) before the reply lands.\n      later(() => {\n        if (operation !== activeOperation) return;\n        isStreaming = false;\n        streamingStatus = '';\n        conversation = appendAssistantMessage(conversation, trimmed);\n      }, 1200);\n      return;\n    }\n\n    // streaming: append one empty assistant message, then grow ITS content.\n    conversation = appendAssistantMessage(conversation, '');\n    const messageId = lastMessageId(conversation);\n    streamingMessageId = messageId;\n    streamingPartial = '';\n    // `isStreaming` drives the composer's Stop affordance for BOTH mechanisms;\n    // only `beginStreaming()` (the rAF-buffered token path) is imperative-only.\n    isStreaming = true;\n    streamingStatus = 'Streaming…';\n    if (streamMechanism === 'imperative') {\n      chat?.beginStreaming(messageId);\n    }\n    // Deterministic cadence: a fixed number of chunks at a fixed delay so an\n    // intermediate partial state is reliably observable before completion.\n    const chunks = splitIntoChunks(trimmed, 5);\n    streamChunk(chunks, 0, activeOperation);\n  }\n\n  function streamChunk(chunks: string[], index: number, operation: number): void {\n    // A newer reply/clear/seed started — this is a stale continuation, bail.\n    if (operation !== activeOperation) return;\n\n    if (index >= chunks.length) {\n      // Commit the final content into the message, then end the stream.\n      conversation = replaceMessageContent(\n        conversation,\n        streamingMessageId ?? '',\n        streamingPartial,\n      );\n      if (streamMechanism === 'imperative') chat?.endStreaming();\n      streamingMessageId = null;\n      isStreaming = false;\n      streamingStatus = '';\n      return;\n    }\n    const chunk = chunks[index] ?? '';\n    streamingPartial += chunk;\n    if (streamMechanism === 'imperative') {\n      chat?.pushToken(chunk);\n    } else {\n      conversation = replaceMessageContent(\n        conversation,\n        streamingMessageId ?? '',\n        streamingPartial,\n      );\n    }\n    later(() => streamChunk(chunks, index + 1, operation), 120);\n  }\n\n  function splitIntoChunks(text: string, count: number): string[] {\n    const words = text.split(' ');\n    const perChunk = Math.max(1, Math.ceil(words.length / count));\n    const chunks: string[] = [];\n    for (let index = 0; index < words.length; index += perChunk) {\n      const slice = words.slice(index, index + perChunk).join(' ');\n      chunks.push(index === 0 ? slice : ` ${slice}`);\n    }\n    return chunks;\n  }\n\n  // --- Inject a tool call + paired result (all outcomes) ---\n  function injectToolCall(): void {\n    if (!parsedToolArguments.ok) return;\n    // Unique per injection — deriving from logCounter would reuse the same id\n    // for repeated injections that don't add a log entry, breaking pairing.\n    const callId = `call-${crypto.randomUUID()}`;\n    const result =\n      toolOutcome === 'error'\n        ? {\n            callId,\n            outcome: 'error' as const,\n            content: null,\n            error: {\n              code: 'tool_failed',\n              category: 'transient' as ToolErrorCategory,\n              retryable: true,\n              message: 'The tool failed: upstream returned a transient error.',\n            },\n          }\n        : toolOutcome === 'action_required'\n          ? {\n              callId,\n              outcome: 'action_required' as const,\n              content: null,\n              action: {\n                type: 'approval' as const,\n                message: 'Approve running this tool before it executes?',\n              },\n            }\n          : { callId, outcome: 'success' as const, content: { status: 'ok' } };\n\n    conversation = appendMessages(\n      conversation,\n      {\n        role: 'tool-call',\n        content: '',\n        toolCall: { id: callId, name: toolName, arguments: parsedToolArguments.value },\n      },\n      { role: 'tool-result', content: '', toolResult: result },\n    );\n  }\n\n  // --- Seed / clear ---\n  function seedThread(): void {\n    cancelPending('discard');\n    let next = createConversation({ id: 'harness-seeded' });\n    // Repeated token \"alpha\" for deterministic search assertions, plus enough\n    // messages to overflow the fixed-height viewport.\n    next = appendUserMessage(next, 'Tell me about alpha.');\n    next = appendAssistantMessage(next, 'alpha is the first item we track.');\n    for (let index = 0; index < 12; index += 1) {\n      next = appendUserMessage(next, `Follow-up question number ${index + 1}.`);\n      next = appendAssistantMessage(\n        next,\n        `Detailed answer number ${index + 1}, with alpha context.`,\n      );\n    }\n    conversation = next;\n  }\n\n  function seedFailedMessage(): void {\n    conversation = appendMessages(conversation, {\n      role: 'user',\n      content: 'This message failed to send.',\n      metadata: { _deliveryStatus: 'failed' },\n    });\n  }\n\n  function clearConversation(): void {\n    cancelPending('discard');\n    conversation = createConversation({ id: 'harness-cleared' });\n  }\n\n  // --- Chat callbacks ---\n  function handleSubmit(event: ChatSubmitEvent): void {\n    const content = typeof event.message.content === 'string' ? event.message.content : '';\n    record('onsubmit', content);\n    conversation = appendMessages(conversation, {\n      role: 'user',\n      content: event.message.content,\n    });\n    if (autoReply) sendReply(replyText);\n  }\n\n  function handleEdit(event: { messageId: string; content: string }): void {\n    record('onedit', event);\n    conversation = replaceMessageContent(conversation, event.messageId, event.content);\n  }\n\n  onDestroy(() => cancelPending('destroy'));\n\n  const surfaceMode = $derived<'default' | 'transparent'>(\n    transparentSurface ? 'transparent' : 'default',\n  );\n  // `emptyPrompts` is included only when ON. Under exactOptionalPropertyTypes an\n  // optional prop must be omitted, not passed as `undefined`, so spread it\n  // conditionally rather than passing `emptyPrompts={undefined}`.\n  const emptyPromptsProp = $derived(\n    withEmptyPrompts ? { emptyPrompts: ['Tell me about alpha', 'Summarize the thread'] } : {},\n  );\n</script>\n\n<div style=\"display: grid; grid-template-columns: 22rem 1fr; gap: 1rem; align-items: start;\">\n  <!-- Control panel -->\n  <div\n    data-testid=\"harness-controls\"\n    style=\"display: grid; gap: 1rem; padding: 1rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-md); background: var(--cinder-surface-inset);\"\n  >\n    <section style=\"display: grid; gap: 0.5rem;\">\n      <strong>Reply as the other side</strong>\n      <textarea\n        data-testid=\"reply-text\"\n        aria-label=\"Reply text\"\n        bind:value={replyText}\n        rows=\"2\"\n        style=\"width: 100%; font: inherit; padding: 0.5rem; border-radius: var(--cinder-radius-sm); border: 1px solid var(--cinder-border-muted);\"\n      ></textarea>\n      <SegmentedControl\n        id=\"harness-reply-mode\"\n        selectionMode=\"single\"\n        bind:value={replyMode}\n        label=\"Reply mode\"\n      >\n        <Segment value=\"instant\">Instant</Segment>\n        <Segment value=\"typing\">Typing</Segment>\n        <Segment value=\"streaming\">Streaming</Segment>\n      </SegmentedControl>\n      {#if replyMode === 'streaming'}\n        <SegmentedControl\n          id=\"harness-stream-mechanism\"\n          selectionMode=\"single\"\n          bind:value={streamMechanism}\n          label=\"Streaming mechanism\"\n        >\n          <Segment value=\"imperative\">Imperative</Segment>\n          <Segment value=\"content-mutation\">Content</Segment>\n        </SegmentedControl>\n      {/if}\n      <Button data-testid=\"send-reply\" onclick={() => sendReply(replyText)}>Send reply</Button>\n    </section>\n\n    <section style=\"display: grid; gap: 0.5rem;\">\n      <strong>Inject tool call</strong>\n      <input\n        data-testid=\"tool-name\"\n        aria-label=\"Tool name\"\n        bind:value={toolName}\n        style=\"font: inherit; padding: 0.4rem; border-radius: var(--cinder-radius-sm); border: 1px solid var(--cinder-border-muted);\"\n      />\n      <textarea\n        data-testid=\"tool-arguments\"\n        aria-label=\"Tool arguments (JSON)\"\n        bind:value={toolArguments}\n        rows=\"2\"\n        style=\"font: var(--cinder-font-mono); padding: 0.4rem; border-radius: var(--cinder-radius-sm); border: 1px solid var(--cinder-border-muted);\"\n      ></textarea>\n      {#if !parsedToolArguments.ok}\n        <span\n          data-testid=\"tool-arguments-error\"\n          style=\"color: var(--cinder-danger); font-size: var(--cinder-text-xs);\"\n        >\n          Arguments must be valid JSON.\n        </span>\n      {/if}\n      <Select\n        id=\"harness-tool-outcome\"\n        label=\"Outcome\"\n        bind:value={toolOutcome}\n        options={[\n          { value: 'success', label: 'success' },\n          { value: 'error', label: 'error' },\n          { value: 'action_required', label: 'action_required' },\n        ]}\n      />\n      <Button data-testid=\"inject-tool\" disabled={!parsedToolArguments.ok} onclick={injectToolCall}>\n        Inject tool call\n      </Button>\n    </section>\n\n    <section style=\"display: grid; gap: 0.4rem;\">\n      <strong>Features</strong>\n      <Toggle id=\"t-attachments\" label=\"allowAttachments\" bind:checked={allowAttachments} />\n      <Toggle id=\"t-search\" label=\"allowSearch\" bind:checked={allowSearch} />\n      <Toggle id=\"t-copy\" label=\"allowCopy\" bind:checked={allowCopy} />\n      <Toggle id=\"t-editing\" label=\"allowEditing\" bind:checked={allowEditing} />\n      <Toggle id=\"t-retry\" label=\"allowRetry\" bind:checked={allowRetry} />\n      <Toggle id=\"t-surface\" label=\"transparent surface\" bind:checked={transparentSurface} />\n      <Toggle id=\"t-prompts\" label=\"emptyPrompts\" bind:checked={withEmptyPrompts} />\n      <Toggle id=\"t-autoreply\" label=\"auto-reply on submit\" bind:checked={autoReply} />\n    </section>\n\n    <section style=\"display: grid; gap: 0.4rem;\">\n      <strong>State</strong>\n      <Button data-testid=\"seed-thread\" variant=\"secondary\" onclick={seedThread}\n        >Seed sample thread</Button\n      >\n      <Button data-testid=\"seed-failed\" variant=\"secondary\" onclick={seedFailedMessage}\n        >Seed failed message</Button\n      >\n      <Button data-testid=\"clear\" variant=\"secondary\" onclick={clearConversation}>Clear</Button>\n      <Button data-testid=\"scroll-top\" variant=\"ghost\" onclick={() => chat?.scrollToTop()}\n        >Scroll to top</Button\n      >\n      <Button data-testid=\"scroll-bottom\" variant=\"ghost\" onclick={() => chat?.scrollToBottom()}\n        >Scroll to bottom</Button\n      >\n      <Button data-testid=\"focus-input\" variant=\"ghost\" onclick={() => chat?.focusInput()}\n        >Focus composer</Button\n      >\n    </section>\n\n    <section style=\"display: grid; gap: 0.25rem;\">\n      <strong>Event log</strong>\n      <!-- tabindex=0 gives the scrollable region keyboard access (axe\n           scrollable-region-focusable). A group label names it without a `log`\n           role, which would collide with the chat timeline's own role=\"log\". -->\n      <div\n        data-testid=\"event-log\"\n        role=\"group\"\n        aria-label=\"Event log\"\n        tabindex=\"0\"\n        style=\"display: grid; gap: 0.15rem; max-height: 10rem; overflow: auto; font-size: var(--cinder-text-xs); font-family: var(--cinder-font-mono);\"\n      >\n        {#each log as entry (entry.id)}\n          <div data-testid=\"event-log-entry\" data-event={entry.event} data-payload={entry.payload}>\n            {entry.event}: {entry.payload}\n          </div>\n        {/each}\n      </div>\n    </section>\n  </div>\n\n  <!-- The Chat under test, in a fixed-height box so the thread overflows. -->\n  <div style=\"height: 34rem;\">\n    <Chat\n      bind:this={chat}\n      id=\"harness-chat\"\n      {conversation}\n      {isStreaming}\n      {streamingStatus}\n      {allowAttachments}\n      {allowSearch}\n      {allowCopy}\n      {allowEditing}\n      {allowRetry}\n      {surfaceMode}\n      {...emptyPromptsProp}\n      onsubmit={handleSubmit}\n      onedit={handleEdit}\n      onretry={(messageId: string) => record('onretry', messageId)}\n      onstopgenerating={(event: { messageId: string }) => {\n        cancelPending('preservePartial');\n        record('onstopgenerating', event.messageId);\n      }}\n      onjumptolatest={() => record('onjumptolatest')}\n      onscrollstatechange={(event: { isAtBottom: boolean }) =>\n        record('onscrollstatechange', { isAtBottom: event.isAtBottom })}\n      onunreadindicatorchange={(event: { unreadCount: number; hasNewMessageIndicator: boolean }) =>\n        record('onunreadindicatorchange', event)}\n      onexpandedchange={(expanded: boolean) => record('onexpandedchange', { expanded })}\n      onattachmentadd={(attachment: { id: string }) => record('onattachmentadd', attachment.id)}\n      onattachmentremove={(attachment: { id: string }) =>\n        record('onattachmentremove', attachment.id)}\n      onattachmentfailure={(_file: File, error: string) => record('onattachmentfailure', error)}\n    >\n      {#snippet header()}\n        <div\n          data-testid=\"harness-header\"\n          style=\"padding: 0.5rem 0.75rem; font-weight: var(--cinder-font-semibold);\"\n        >\n          Harness conversation\n        </div>\n      {/snippet}\n      {#snippet messageActions(message: Message)}\n        <button type=\"button\" data-testid=\"harness-message-action\" data-message-id={message.id}\n          >★</button\n        >\n      {/snippet}\n      {#snippet messageStatus(message: Message)}\n        <span data-testid=\"harness-message-status\" data-message-id={message.id}>·</span>\n      {/snippet}\n    </Chat>\n  </div>\n</div>\n"
+      "code": "<script lang=\"ts\" module>\n  export const title = 'Interactive harness';\n  export const description =\n    'Drive Chat from a control panel: reply as the other side (instant / typing / streaming), inject tool calls, toggle features, and watch every callback fire.';\n\n  export function createHistoryMessageTimestamp(page: number, index: number): string {\n    return new Date(Date.UTC(2026, 4, 30 - page, 12, index)).toISOString();\n  }\n</script>\n\n<script lang=\"ts\">\n  import {\n    Chat,\n    appendAssistantMessage,\n    appendMessages,\n    appendUserMessage,\n    createConversation,\n    type ChatSubmitEvent,\n    type ConversationHistory,\n    type JSONValue,\n    type Message,\n    type ToolErrorCategory,\n  } from '@lostgradient/cinder/chat';\n  import { Button } from '@lostgradient/cinder/button';\n  import { Input } from '@lostgradient/cinder/input';\n  import { Segment } from '@lostgradient/cinder/segment';\n  import { SegmentedControl } from '@lostgradient/cinder/segmented-control';\n  import { Select } from '@lostgradient/cinder/select';\n  import { Textarea } from '@lostgradient/cinder/textarea';\n  import { Toggle } from '@lostgradient/cinder/toggle';\n  import { onDestroy } from 'svelte';\n\n  // Out of scope for this harness (documented, not silently dropped):\n  // bottomThreshold / jumpThreshold (kept at defaults so overflow + jump are\n  // testable without tuning), viewportAttachment (advanced escape hatch), and\n  // the isAtBottom / unreadCount / hasNewMessageIndicator bindables (read-only\n  // mirrors of behavior the wired callbacks already surface).\n\n  // --- Chat instance (for the imperative streaming + scroll API) ---\n  // Plain `let`: only read via `chat?.method()` calls, never reactively.\n  let chat: ReturnType<typeof Chat> | undefined;\n\n  // --- Conversation state (immutable snapshots via the cinder/chat builders) ---\n  let conversation = $state<ConversationHistory>(createConversation({ id: 'harness' }));\n\n  // --- Feature toggles wired straight onto <Chat> ---\n  let allowAttachments = $state(true);\n  let allowSearch = $state(true);\n  let allowCopy = $state(true);\n  let allowEditing = $state(true);\n  let allowRetry = $state(true);\n  let transparentSurface = $state(false);\n  let withEmptyPrompts = $state(true);\n  let autoReply = $state(true);\n  let virtualized = $state(false);\n  let historyEnabled = $state(false);\n  let historyPage = 0;\n\n  // --- Reply controls ---\n  let replyText = $state('Here is the answer, delivered in a few deliberate chunks.');\n  let replyMode = $state<'instant' | 'typing' | 'streaming'>('typing');\n  let streamMechanism = $state<'imperative' | 'content-mutation'>('imperative');\n  let isStreaming = $state(false);\n  let streamingStatus = $state('');\n\n  // --- Tool-call controls ---\n  let toolName = $state('exports_check');\n  let toolArguments = $state('{ \"package\": \"@lostgradient/cinder\" }');\n  let toolOutcome = $state<'success' | 'error' | 'action_required'>('success');\n  const parsedToolArguments = $derived.by<{ ok: boolean; value: JSONValue }>(() => {\n    try {\n      return { ok: true, value: JSON.parse(toolArguments) as JSONValue };\n    } catch {\n      return { ok: false, value: null };\n    }\n  });\n\n  // --- Event log (queryable: data-event + data-payload per entry) ---\n  // Chat emits a burst of identical onunreadindicatorchange events while its\n  // empty state settles on mount (all `{unreadCount:0, hasNewMessageIndicator:\n  // false}`). We de-duplicate: a callback whose (event, payload) is identical to\n  // the most recent entry for that event is dropped. That kills the mount noise\n  // deterministically (no timing dependency) while still recording every real,\n  // distinct callback so tests can assert \"this fired because of my action\".\n  type LogEntry = { id: number; event: string; payload: string };\n  let log = $state<LogEntry[]>([]);\n  let logCounter = 0;\n  const lastPayloadByEvent = new Map<string, string>();\n  function record(event: string, payload: unknown = ''): void {\n    const text = typeof payload === 'string' ? payload : JSON.stringify(payload);\n    if (lastPayloadByEvent.get(event) === text) return;\n    lastPayloadByEvent.set(event, text);\n    logCounter += 1;\n    log = [{ id: logCounter, event, payload: text }, ...log].slice(0, 50);\n  }\n\n  // --- Pending-operation discipline (instance-local; NEVER module scope) ---\n  // A single in-flight typing/streaming op at a time. Timers are tracked so we\n  // can cancel deterministically; streamingPartial holds the accumulated text so\n  // Stop can preserve it.\n  let pendingTimers = new Set<ReturnType<typeof setTimeout>>();\n  // Plain `let`: read only inside the streaming functions, never in the\n  // template (the assistant message content comes from `conversation`).\n  let streamingPartial = '';\n  let streamingMessageId: string | null = null;\n  // Monotonic token identifying the current stream/typing op. Each scheduled\n  // chunk captures the token active when it was queued and bails if a newer op\n  // has started — so an already-dequeued timer can't write into a fresh stream.\n  let activeOperation = 0;\n\n  function later(callback: () => void, delay: number): void {\n    const handle = setTimeout(() => {\n      pendingTimers.delete(handle);\n      callback();\n    }, delay);\n    pendingTimers.add(handle);\n  }\n\n  function clearTimers(): void {\n    for (const handle of pendingTimers) clearTimeout(handle);\n    pendingTimers.clear();\n  }\n\n  /**\n   * Cancel the in-flight op. Modes differ in how they treat partial content:\n   * - preservePartial (Stop): keep what streamed so far, commit it to the message.\n   * - discard (Clear / Seed / mode switch / new reply): drop the in-flight\n   *   (possibly empty) assistant message so no blank bubble is left behind.\n   * - destroy (onDestroy): just clear timers.\n   */\n  function cancelPending(mode: 'preservePartial' | 'discard' | 'destroy'): void {\n    clearTimers();\n    // Invalidate the current op so any timer callback already dequeued (past\n    // clearTimers) bails instead of mutating freshly-reset state.\n    activeOperation += 1;\n    if (mode === 'destroy') return;\n\n    if (streamingMessageId) {\n      if (mode === 'preservePartial') {\n        conversation = replaceMessageContent(conversation, streamingMessageId, streamingPartial);\n      } else {\n        conversation = removeMessage(conversation, streamingMessageId);\n      }\n      chat?.endStreaming();\n    }\n    streamingMessageId = null;\n    streamingPartial = '';\n    isStreaming = false;\n    streamingStatus = '';\n  }\n\n  // --- Immutable message helpers (replace/remove by id) ---\n  function replaceMessageContent(\n    current: ConversationHistory,\n    id: string,\n    content: string,\n  ): ConversationHistory {\n    const existing = current.messages[id];\n    if (!existing) return current;\n    return {\n      ...current,\n      messages: { ...current.messages, [id]: { ...existing, content } },\n      updatedAt: new Date().toISOString(),\n    };\n  }\n\n  function removeMessage(current: ConversationHistory, id: string): ConversationHistory {\n    if (!current.messages[id]) return current;\n    const messages = { ...current.messages };\n    delete messages[id];\n    return {\n      ...current,\n      ids: current.ids.filter((existing) => existing !== id),\n      messages,\n      updatedAt: new Date().toISOString(),\n    };\n  }\n\n  function lastMessageId(current: ConversationHistory): string {\n    return current.ids[current.ids.length - 1] ?? '';\n  }\n\n  function prependHistoryMessages(current: ConversationHistory): ConversationHistory {\n    historyPage += 1;\n    const olderMessages: Message[] = Array.from({ length: 6 }, (_, index) => {\n      const id = `older-${historyPage}-${index}`;\n      return {\n        id,\n        role: index % 2 === 0 ? 'user' : 'assistant',\n        content: `Earlier context ${historyPage}.${index + 1}`,\n        position: index,\n        createdAt: createHistoryMessageTimestamp(historyPage, index),\n        metadata: {},\n        hidden: false,\n      };\n    });\n    const messages = Object.fromEntries(olderMessages.map((message) => [message.id, message]));\n    for (const [index, id] of current.ids.entries()) {\n      const message = current.messages[id];\n      if (message) {\n        messages[id] = { ...message, position: olderMessages.length + index };\n      }\n    }\n    return {\n      ...current,\n      ids: [...olderMessages.map((message) => message.id), ...current.ids],\n      messages,\n      updatedAt: new Date().toISOString(),\n    };\n  }\n\n  // --- Reply as the other side ---\n  function sendReply(text: string): void {\n    const trimmed = text.trim();\n    if (!trimmed) return;\n    cancelPending('discard');\n    // Start a new operation; stale timers from a prior op will no longer match.\n    const operation = ++activeOperation;\n\n    if (replyMode === 'instant') {\n      conversation = appendAssistantMessage(conversation, trimmed);\n      return;\n    }\n\n    if (replyMode === 'typing') {\n      isStreaming = true;\n      streamingStatus = 'Assistant is typing…';\n      // A deliberately long-ish window so the \"typing\" state is comfortably\n      // observable (by a person and by a test) before the reply lands.\n      later(() => {\n        if (operation !== activeOperation) return;\n        isStreaming = false;\n        streamingStatus = '';\n        conversation = appendAssistantMessage(conversation, trimmed);\n      }, 1200);\n      return;\n    }\n\n    // streaming: append one empty assistant message, then grow ITS content.\n    conversation = appendAssistantMessage(conversation, '');\n    const messageId = lastMessageId(conversation);\n    streamingMessageId = messageId;\n    streamingPartial = '';\n    // `isStreaming` drives the composer's Stop affordance for BOTH mechanisms;\n    // only `beginStreaming()` (the rAF-buffered token path) is imperative-only.\n    isStreaming = true;\n    streamingStatus = 'Streaming…';\n    if (streamMechanism === 'imperative') {\n      chat?.beginStreaming(messageId);\n    }\n    // Deterministic cadence: a fixed number of chunks at a fixed delay so an\n    // intermediate partial state is reliably observable before completion.\n    const chunks = splitIntoChunks(trimmed, 5);\n    streamChunk(chunks, 0, activeOperation);\n  }\n\n  function streamChunk(chunks: string[], index: number, operation: number): void {\n    // A newer reply/clear/seed started — this is a stale continuation, bail.\n    if (operation !== activeOperation) return;\n\n    if (index >= chunks.length) {\n      // Commit the final content into the message, then end the stream.\n      conversation = replaceMessageContent(\n        conversation,\n        streamingMessageId ?? '',\n        streamingPartial,\n      );\n      if (streamMechanism === 'imperative') chat?.endStreaming();\n      streamingMessageId = null;\n      isStreaming = false;\n      streamingStatus = '';\n      return;\n    }\n    const chunk = chunks[index] ?? '';\n    streamingPartial += chunk;\n    if (streamMechanism === 'imperative') {\n      chat?.pushToken(chunk);\n    } else {\n      conversation = replaceMessageContent(\n        conversation,\n        streamingMessageId ?? '',\n        streamingPartial,\n      );\n    }\n    later(() => streamChunk(chunks, index + 1, operation), 120);\n  }\n\n  function splitIntoChunks(text: string, count: number): string[] {\n    const words = text.split(' ');\n    const perChunk = Math.max(1, Math.ceil(words.length / count));\n    const chunks: string[] = [];\n    for (let index = 0; index < words.length; index += perChunk) {\n      const slice = words.slice(index, index + perChunk).join(' ');\n      chunks.push(index === 0 ? slice : ` ${slice}`);\n    }\n    return chunks;\n  }\n\n  // --- Inject a tool call + paired result (all outcomes) ---\n  function injectToolCall(): void {\n    if (!parsedToolArguments.ok) return;\n    // Unique per injection — deriving from logCounter would reuse the same id\n    // for repeated injections that don't add a log entry, breaking pairing.\n    const callId = `call-${crypto.randomUUID()}`;\n    const result =\n      toolOutcome === 'error'\n        ? {\n            callId,\n            outcome: 'error' as const,\n            content: null,\n            error: {\n              code: 'tool_failed',\n              category: 'transient' as ToolErrorCategory,\n              retryable: true,\n              message: 'The tool failed: upstream returned a transient error.',\n            },\n          }\n        : toolOutcome === 'action_required'\n          ? {\n              callId,\n              outcome: 'action_required' as const,\n              content: null,\n              action: {\n                type: 'approval' as const,\n                message: 'Approve running this tool before it executes?',\n              },\n            }\n          : { callId, outcome: 'success' as const, content: { status: 'ok' } };\n\n    conversation = appendMessages(\n      conversation,\n      {\n        role: 'tool-call',\n        content: '',\n        toolCall: { id: callId, name: toolName, arguments: parsedToolArguments.value },\n      },\n      { role: 'tool-result', content: '', toolResult: result },\n    );\n  }\n\n  // --- Seed / clear ---\n  function seedThread(): void {\n    cancelPending('discard');\n    let next = createConversation({ id: 'harness-seeded' });\n    // Repeated token \"alpha\" for deterministic search assertions, plus enough\n    // messages to overflow the fixed-height viewport.\n    next = appendUserMessage(next, 'Tell me about alpha.');\n    next = appendAssistantMessage(next, 'alpha is the first item we track.');\n    for (let index = 0; index < 12; index += 1) {\n      next = appendUserMessage(next, `Follow-up question number ${index + 1}.`);\n      next = appendAssistantMessage(\n        next,\n        `Detailed answer number ${index + 1}, with alpha context.`,\n      );\n    }\n    conversation = next;\n  }\n\n  function seedFailedMessage(): void {\n    conversation = appendMessages(conversation, {\n      role: 'user',\n      content: 'This message failed to send.',\n      metadata: { _deliveryStatus: 'failed' },\n    });\n  }\n\n  function clearConversation(): void {\n    cancelPending('discard');\n    conversation = createConversation({ id: 'harness-cleared' });\n    historyPage = 0;\n  }\n\n  // --- Chat callbacks ---\n  function handleSubmit(event: ChatSubmitEvent): void {\n    const content = typeof event.message.content === 'string' ? event.message.content : '';\n    record('onsubmit', content);\n    conversation = appendMessages(conversation, {\n      role: 'user',\n      content: event.message.content,\n    });\n    if (autoReply) sendReply(replyText);\n  }\n\n  function handleEdit(event: { messageId: string; content: string }): void {\n    record('onedit', event);\n    conversation = replaceMessageContent(conversation, event.messageId, event.content);\n  }\n\n  async function handleLoadHistory(): Promise<void> {\n    conversation = prependHistoryMessages(conversation);\n    record('onloadhistory', historyPage);\n  }\n\n  onDestroy(() => cancelPending('destroy'));\n\n  const surfaceMode = $derived<'default' | 'transparent'>(\n    transparentSurface ? 'transparent' : 'default',\n  );\n  // `emptyPrompts` is included only when ON. Under exactOptionalPropertyTypes an\n  // optional prop must be omitted, not passed as `undefined`, so spread it\n  // conditionally rather than passing `emptyPrompts={undefined}`.\n  const emptyPromptsProp = $derived(\n    withEmptyPrompts ? { emptyPrompts: ['Tell me about alpha', 'Summarize the thread'] } : {},\n  );\n  const historyProps = $derived(\n    historyEnabled ? { hasMoreHistory: true, onloadhistory: handleLoadHistory } : {},\n  );\n</script>\n\n<div style=\"display: grid; grid-template-columns: 22rem 1fr; gap: 1rem; align-items: start;\">\n  <!-- Control panel -->\n  <div\n    data-testid=\"harness-controls\"\n    style=\"display: grid; gap: 1rem; padding: 1rem; border: 1px solid var(--cinder-border-muted); border-radius: var(--cinder-radius-md); background: var(--cinder-surface-inset);\"\n  >\n    <section style=\"display: grid; gap: 0.5rem;\">\n      <strong>Reply as the other side</strong>\n      <Textarea\n        id=\"harness-reply-text\"\n        data-testid=\"reply-text\"\n        label=\"Reply text\"\n        bind:value={replyText}\n        rows={2}\n      />\n      <SegmentedControl\n        id=\"harness-reply-mode\"\n        selectionMode=\"single\"\n        bind:value={replyMode}\n        label=\"Reply mode\"\n      >\n        <Segment value=\"instant\">Instant</Segment>\n        <Segment value=\"typing\">Typing</Segment>\n        <Segment value=\"streaming\">Streaming</Segment>\n      </SegmentedControl>\n      {#if replyMode === 'streaming'}\n        <SegmentedControl\n          id=\"harness-stream-mechanism\"\n          selectionMode=\"single\"\n          bind:value={streamMechanism}\n          label=\"Streaming mechanism\"\n        >\n          <Segment value=\"imperative\">Imperative</Segment>\n          <Segment value=\"content-mutation\">Content</Segment>\n        </SegmentedControl>\n      {/if}\n      <Button data-testid=\"send-reply\" onclick={() => sendReply(replyText)}>Send reply</Button>\n    </section>\n\n    <section style=\"display: grid; gap: 0.5rem;\">\n      <strong>Inject tool call</strong>\n      <Input\n        id=\"harness-tool-name\"\n        data-testid=\"tool-name\"\n        label=\"Tool name\"\n        bind:value={toolName}\n      />\n      <Textarea\n        id=\"harness-tool-arguments\"\n        data-testid=\"tool-arguments\"\n        label=\"Tool arguments (JSON)\"\n        bind:value={toolArguments}\n        rows={2}\n      />\n      {#if !parsedToolArguments.ok}\n        <span\n          data-testid=\"tool-arguments-error\"\n          style=\"color: var(--cinder-danger); font-size: var(--cinder-text-xs);\"\n        >\n          Arguments must be valid JSON.\n        </span>\n      {/if}\n      <Select\n        id=\"harness-tool-outcome\"\n        label=\"Outcome\"\n        bind:value={toolOutcome}\n        options={[\n          { value: 'success', label: 'success' },\n          { value: 'error', label: 'error' },\n          { value: 'action_required', label: 'action_required' },\n        ]}\n      />\n      <Button data-testid=\"inject-tool\" disabled={!parsedToolArguments.ok} onclick={injectToolCall}>\n        Inject tool call\n      </Button>\n    </section>\n\n    <section style=\"display: grid; gap: 0.4rem;\">\n      <strong>Features</strong>\n      <Toggle id=\"t-attachments\" label=\"allowAttachments\" bind:checked={allowAttachments} />\n      <Toggle id=\"t-search\" label=\"allowSearch\" bind:checked={allowSearch} />\n      <Toggle id=\"t-copy\" label=\"allowCopy\" bind:checked={allowCopy} />\n      <Toggle id=\"t-editing\" label=\"allowEditing\" bind:checked={allowEditing} />\n      <Toggle id=\"t-retry\" label=\"allowRetry\" bind:checked={allowRetry} />\n      <Toggle id=\"t-surface\" label=\"transparent surface\" bind:checked={transparentSurface} />\n      <Toggle id=\"t-prompts\" label=\"emptyPrompts\" bind:checked={withEmptyPrompts} />\n      <Toggle id=\"t-autoreply\" label=\"auto-reply on submit\" bind:checked={autoReply} />\n      <Toggle id=\"t-virtualized\" label=\"virtualized transcript\" bind:checked={virtualized} />\n      <Toggle id=\"t-history\" label=\"history pagination\" bind:checked={historyEnabled} />\n    </section>\n\n    <section style=\"display: grid; gap: 0.4rem;\">\n      <strong>State</strong>\n      <Button data-testid=\"seed-thread\" variant=\"secondary\" onclick={seedThread}\n        >Seed sample thread</Button\n      >\n      <Button data-testid=\"seed-failed\" variant=\"secondary\" onclick={seedFailedMessage}\n        >Seed failed message</Button\n      >\n      <Button data-testid=\"clear\" variant=\"secondary\" onclick={clearConversation}>Clear</Button>\n      <Button data-testid=\"scroll-top\" variant=\"ghost\" onclick={() => chat?.scrollToTop()}\n        >Scroll to top</Button\n      >\n      <Button data-testid=\"scroll-bottom\" variant=\"ghost\" onclick={() => chat?.scrollToBottom()}\n        >Scroll to bottom</Button\n      >\n      <Button data-testid=\"focus-input\" variant=\"ghost\" onclick={() => chat?.focusInput()}\n        >Focus composer</Button\n      >\n    </section>\n\n    <section style=\"display: grid; gap: 0.25rem;\">\n      <strong>Event log</strong>\n      <!-- tabindex=0 gives the scrollable region keyboard access (axe\n           scrollable-region-focusable). A group label names it without a `log`\n           role, which would collide with the chat timeline's own role=\"log\".\n           svelte:element keeps the rendered DOM as a div while avoiding the\n           static a11y warning for this focusable scroll-region pattern. -->\n      <svelte:element\n        this={'div'}\n        data-testid=\"event-log\"\n        role=\"group\"\n        aria-label=\"Event log\"\n        tabindex={0}\n        style=\"display: grid; gap: 0.15rem; max-height: 10rem; overflow: auto; font-size: var(--cinder-text-xs); font-family: var(--cinder-font-mono);\"\n      >\n        {#each log as entry (entry.id)}\n          <div data-testid=\"event-log-entry\" data-event={entry.event} data-payload={entry.payload}>\n            {entry.event}: {entry.payload}\n          </div>\n        {/each}\n      </svelte:element>\n    </section>\n  </div>\n\n  <!-- The Chat under test, in a fixed-height box so the thread overflows. -->\n  <div style=\"height: 34rem;\">\n    <Chat\n      bind:this={chat}\n      id=\"harness-chat\"\n      {conversation}\n      {isStreaming}\n      {streamingStatus}\n      {allowAttachments}\n      {allowSearch}\n      {allowCopy}\n      {allowEditing}\n      {allowRetry}\n      {surfaceMode}\n      {virtualized}\n      virtualizationEstimatedRowHeight={72}\n      virtualizationInitialHeight={480}\n      virtualizationOverscan={2}\n      {...emptyPromptsProp}\n      {...historyProps}\n      onsubmit={handleSubmit}\n      onedit={handleEdit}\n      onretry={(messageId: string) => record('onretry', messageId)}\n      onstopgenerating={(event: { messageId: string }) => {\n        cancelPending('preservePartial');\n        record('onstopgenerating', event.messageId);\n      }}\n      onjumptolatest={() => record('onjumptolatest')}\n      onscrollstatechange={(event: { isAtBottom: boolean }) =>\n        record('onscrollstatechange', { isAtBottom: event.isAtBottom })}\n      onunreadindicatorchange={(event: { unreadCount: number; hasNewMessageIndicator: boolean }) =>\n        record('onunreadindicatorchange', event)}\n      onexpandedchange={(expanded: boolean) => record('onexpandedchange', { expanded })}\n      onattachmentadd={(attachment: { id: string }) => record('onattachmentadd', attachment.id)}\n      onattachmentremove={(attachment: { id: string }) =>\n        record('onattachmentremove', attachment.id)}\n      onattachmentfailure={(_file: File, error: string) => record('onattachmentfailure', error)}\n    >\n      {#snippet header()}\n        <div\n          data-testid=\"harness-header\"\n          style=\"padding: 0.5rem 0.75rem; font-weight: var(--cinder-font-semibold);\"\n        >\n          Harness conversation\n        </div>\n      {/snippet}\n      {#snippet messageActions(message: Message)}\n        <Button\n          iconOnly={true}\n          label=\"Message action\"\n          size=\"xs\"\n          variant=\"ghost\"\n          data-testid=\"harness-message-action\"\n          data-message-id={message.id}\n        >\n          ★\n        </Button>\n      {/snippet}\n      {#snippet messageStatus(message: Message)}\n        <span data-testid=\"harness-message-status\" data-message-id={message.id}>·</span>\n      {/snippet}\n    </Chat>\n  </div>\n</div>\n"
     },
     {
       "id": "streaming",
@@ -21,6 +27,24 @@
       "description": "Streaming status keeps the composer in stop mode.",
       "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendAssistantMessage,\n    appendUserMessage,\n    createConversation,\n  } from '@lostgradient/cinder/chat';\n\n  let conversation = $state(\n    appendAssistantMessage(\n      appendUserMessage(\n        createConversation({ id: 'streaming-chat' }),\n        'What is happening in the current run?',\n      ),\n      'The assistant is applying the port, checking compiler feedback, and updating the demos as each component lands.',\n    ),\n  );\n</script>\n\n<div style=\"height: 34rem;\">\n  <Chat\n    id=\"playground-streaming-chat\"\n    {conversation}\n    isStreaming\n    streamingStatus=\"Writing response...\"\n    allowAttachments={false}\n  />\n</div>\n"
     },
+    {
+      "id": "with-reasoning-and-steps",
+      "title": "With reasoning and steps",
+      "description": "Assistant messages can surface a collapsible reasoning block (extended thinking) and an ordered step list before the final answer. Both are UI-only overlays derived from message metadata — the underlying transcript is unchanged.",
+      "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendMessages,\n    appendUserMessage,\n    createConversation,\n  } from '@lostgradient/cinder/chat';\n\n  const reasoningContent =\n    'The user is asking me to walk them through solving a quadratic equation step by step. I should break this down into a structured sequence of steps: first identify the coefficients, then apply the quadratic formula, then simplify the result. I should also surface my reasoning process so the user can see my thinking before I present the final answer.';\n\n  const conversation = appendMessages(\n    appendUserMessage(\n      createConversation({ id: 'reasoning-steps-chat' }),\n      'Can you solve 2x² - 4x - 6 = 0 and walk me through the steps?',\n    ),\n    {\n      role: 'assistant',\n      content:\n        'The solutions are **x = 3** and **x = -1**.\\n\\nYou can verify these by substituting back: 2(9) − 4(3) − 6 = 18 − 12 − 6 = 0 ✓ and 2(1) − 4(−1) − 6 = 2 + 4 − 6 = 0 ✓',\n      metadata: {\n        'cinder:reasoning': reasoningContent,\n        'cinder:steps': [\n          {\n            title: 'Identify coefficients',\n            content: 'a = 2, b = −4, c = −6',\n            status: 'done',\n          },\n          {\n            title: 'Apply the quadratic formula',\n            content: 'x = (4 ± √(16 + 48)) / 4 = (4 ± √64) / 4 = (4 ± 8) / 4',\n            status: 'done',\n          },\n          {\n            title: 'Calculate both solutions',\n            content: 'x₁ = (4 + 8) / 4 = 3  ·  x₂ = (4 − 8) / 4 = −1',\n            status: 'done',\n          },\n        ],\n      },\n    },\n  );\n</script>\n\n<div style=\"height: 34rem;\">\n  <Chat id=\"playground-reasoning-steps-chat\" {conversation} allowAttachments={false} />\n</div>\n"
+    },
+    {
+      "id": "with-suggestions",
+      "title": "With suggested replies",
+      "description": "After the final assistant message, suggested follow-up labels appear as clickable chips. Clicking a chip calls onsuggestionselect(label). The chips are derived from message metadata — the underlying transcript is unchanged.",
+      "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendMessages,\n    appendUserMessage,\n    createConversation,\n  } from '@lostgradient/cinder/chat';\n\n  let conversation = $state(\n    appendMessages(\n      appendUserMessage(\n        createConversation({ id: 'suggestions-chat' }),\n        'What are some good topics to learn about AI?',\n      ),\n      {\n        role: 'assistant',\n        content:\n          'Great question! Here are some foundational areas to explore:\\n\\n- **Prompt engineering** — crafting effective inputs for language models\\n- **RAG (Retrieval-Augmented Generation)** — combining search with generation\\n- **Fine-tuning** — adapting pre-trained models to specific tasks\\n- **AI safety** — understanding alignment, interpretability, and robustness\\n\\nWhich of these interests you most?',\n        metadata: {\n          'cinder:suggestions': [\n            'Tell me more about prompt engineering',\n            'Explain RAG in simple terms',\n            'How does fine-tuning work?',\n            'What is AI safety?',\n          ],\n        },\n      },\n    ),\n  );\n\n  function handleSuggestionSelect(label: string): void {\n    conversation = appendUserMessage(conversation, label);\n  }\n</script>\n\n<div style=\"height: 34rem;\">\n  <Chat\n    id=\"playground-suggestions-chat\"\n    {conversation}\n    allowAttachments={false}\n    onsuggestionselect={handleSuggestionSelect}\n    onsubmit={(event) => {\n      conversation = appendUserMessage(conversation, event.message.content as string);\n    }}\n  />\n</div>\n"
+    },
+    {
+      "id": "with-tool-approval",
+      "title": "With tool approval",
+      "description": "Action-required tool results render as approval prompts the user must accept or reject before the tool can continue.",
+      "code": "<script lang=\"ts\">\n  import {\n    Chat,\n    appendMessages,\n    appendUserMessage,\n    createConversation,\n  } from '@lostgradient/cinder/chat';\n\n  let conversation = $state(\n    appendMessages(\n      appendUserMessage(\n        createConversation({ id: 'tool-approval-chat' }),\n        'Deploy the latest build to production.',\n      ),\n      {\n        role: 'tool-call',\n        content: '',\n        toolCall: {\n          id: 'call-deploy-prod',\n          name: 'deploy_to_production',\n          arguments: { environment: 'production', version: '2.4.1' },\n        },\n      },\n      {\n        role: 'tool-result',\n        content: '',\n        toolResult: {\n          callId: 'call-deploy-prod',\n          outcome: 'action_required',\n          content: null,\n          action: {\n            type: 'approval',\n            message:\n              'Deploying version 2.4.1 to production will replace the live environment. This action cannot be undone automatically. Do you want to proceed?',\n            schema: { environment: 'production', version: '2.4.1', replicas: 3 },\n          },\n        },\n      },\n    ),\n  );\n\n  function handleApprove(toolCallId: string) {\n    conversation = appendMessages(conversation, {\n      role: 'assistant',\n      content: `Approved. Deploying version 2.4.1 to production now. Tool call ID: ${toolCallId}`,\n    });\n  }\n\n  function handleDeny(toolCallId: string) {\n    conversation = appendMessages(conversation, {\n      role: 'assistant',\n      content: `Deployment cancelled. The production environment was not modified. Tool call ID: ${toolCallId}`,\n    });\n  }\n</script>\n\n<div style=\"height: 34rem;\">\n  <Chat\n    id=\"playground-tool-approval-chat\"\n    {conversation}\n    allowAttachments={false}\n    onapprove={handleApprove}\n    ondeny={handleDeny}\n  />\n</div>\n"
+    },
     {
       "id": "with-tool-calls",
       "title": "With tool calls",