@lostgradient/cinder 0.4.0 → 0.5.0

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

@@ -13,13 +13,13 @@
       "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      capabilities={{ attachments: false }}\n    />\n  </div>\n</div>\n"
+      "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 transcript.\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      capabilities={{ attachments: 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\" 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 atBottom / unreadCount / newMessageIndicatorVisible 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 attachments = $state(true);\n  let search = $state(true);\n  let copy = $state(true);\n  let editing = $state(true);\n  let retry = $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 streaming = $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, newMessageIndicatorVisible:\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    streaming = 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      streaming = 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        streaming = 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    // `streaming` drives the composer's Stop affordance for BOTH mechanisms;\n    // only `beginStreaming()` (the rAF-buffered token path) is imperative-only.\n    streaming = 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      streaming = 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 ? { moreHistoryAvailable: 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=\"attachments\" bind:checked={attachments} />\n      <Toggle id=\"t-search\" label=\"search\" bind:checked={search} />\n      <Toggle id=\"t-copy\" label=\"copy\" bind:checked={copy} />\n      <Toggle id=\"t-editing\" label=\"editing\" bind:checked={editing} />\n      <Toggle id=\"t-retry\" label=\"retry\" bind:checked={retry} />\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      {streaming}\n      {streamingStatus}\n      capabilities={{ attachments, search, copy, editing, retry }}\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: { atBottom: boolean }) =>\n        record('onscrollstatechange', { atBottom: event.atBottom })}\n      onunreadindicatorchange={(event: {\n        unreadCount: number;\n        newMessageIndicatorVisible: 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"
+      "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 atBottom / unreadCount / newMessageIndicatorVisible 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 attachments = $state(true);\n  let search = $state(true);\n  let copy = $state(true);\n  let editing = $state(true);\n  let retry = $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 streaming = $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, newMessageIndicatorVisible:\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    streaming = 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      streaming = 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        streaming = 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    // `streaming` drives the composer's Stop affordance for BOTH mechanisms;\n    // only `beginStreaming()` (the rAF-buffered token path) is imperative-only.\n    streaming = 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      streaming = 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 ? { moreHistoryAvailable: true, onloadhistory: handleLoadHistory } : {},\n  );\n</script>\n\n<!--\n  flex-wrap (not a media-query grid) so this collapses to a single stacked\n  column on narrow viewports without a breakpoint: controls and chat both\n  carry a flex-basis, and once their combined basis exceeds the container\n  width the chat pane wraps below the controls instead of squeezing into a\n  sliver next to a fixed-width column.\n-->\n<div style=\"display: flex; flex-wrap: wrap; gap: 1rem; align-items: flex-start;\">\n  <!-- Control panel. tabindex=0 gives the scrollable region keyboard access\n       (axe scrollable-region-focusable) in addition to its normal focusable\n       descendants (inputs, buttons) — mirrors the Event log pattern below.\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=\"harness-controls\"\n    role=\"group\"\n    aria-label=\"Harness controls\"\n    tabindex={0}\n    style=\"flex: 1 1 20rem; min-width: 0; max-height: min(80vh, 44rem); overflow-y: auto; 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\n      style=\"display: grid; gap: 0.5rem; border-block-start: 1px solid var(--cinder-border-muted); padding-block-start: 1rem;\"\n    >\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\n      style=\"display: grid; gap: 0.5rem; border-block-start: 1px solid var(--cinder-border-muted); padding-block-start: 1rem;\"\n    >\n      <strong>Features</strong>\n      <div\n        style=\"display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0.4rem 0.75rem;\"\n      >\n        <Toggle id=\"t-attachments\" label=\"Attachments\" bind:checked={attachments} />\n        <Toggle id=\"t-search\" label=\"Search\" bind:checked={search} />\n        <Toggle id=\"t-copy\" label=\"Copy\" bind:checked={copy} />\n        <Toggle id=\"t-editing\" label=\"Editing\" bind:checked={editing} />\n        <Toggle id=\"t-retry\" label=\"Retry\" bind:checked={retry} />\n        <Toggle id=\"t-surface\" label=\"Transparent surface\" bind:checked={transparentSurface} />\n        <Toggle id=\"t-prompts\" label=\"Empty prompts\" 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      </div>\n    </section>\n\n    <section\n      style=\"display: grid; gap: 0.5rem; border-block-start: 1px solid var(--cinder-border-muted); padding-block-start: 1rem;\"\n    >\n      <strong>State</strong>\n      <div style=\"display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0.4rem;\">\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      </div>\n    </section>\n\n    <section\n      style=\"display: grid; gap: 0.5rem; border-block-start: 1px solid var(--cinder-border-muted); padding-block-start: 1rem;\"\n    >\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  </svelte:element>\n\n  <!-- The Chat under test. flex-grow 3 (vs the controls' 1) means it claims\n       most of any extra width once both fit on one line; the basis + generous\n       viewport-relative height keep it usable even when wrapped below the\n       controls on a narrow viewport. -->\n  <div style=\"flex: 3 1 24rem; min-width: 0; height: min(70vh, 42rem); min-height: 26rem;\">\n    <Chat\n      bind:this={chat}\n      id=\"harness-chat\"\n      {conversation}\n      {streaming}\n      {streamingStatus}\n      capabilities={{ attachments, search, copy, editing, retry }}\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: { atBottom: boolean }) =>\n        record('onscrollstatechange', { atBottom: event.atBottom })}\n      onunreadindicatorchange={(event: {\n        unreadCount: number;\n        newMessageIndicatorVisible: 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",

package/src/components/chat/container/chat.svelte

@@ -49,7 +49,7 @@
     type ChatRenderRow,
   } from './use-chat-message-groups.svelte.ts';
   import { ChatVirtualizer } from './use-chat-virtualizer.svelte.ts';
-  import { useChatReasoningState } from './use-chat-reasoning-state.svelte.ts';
+  import { useChatDisclosureState } from './use-chat-disclosure-state.svelte.ts';
   import type { VirtualItem } from '../../../_internal/virtual-item.ts';
   import { useChatTypingIndicator } from './use-chat-typing-indicator.svelte.ts';
   import { useChatReadReceipts } from './use-chat-read-receipts.svelte.ts';
@@ -167,23 +167,26 @@
   let approvedToolCallIds = $state(new Set<string>());
   let deniedToolCallIds = $state(new Set<string>());
 
-  // C4 — reasoning expansion state. UI-only; not written to the transcript.
-  // Collapsed by default; toggling triggers a virtualizer remeasure when wired.
-  const reasoningState = useChatReasoningState({
-    onRemeasureRow: (messageId) => {
-      if (!isVirtualized || !viewport) return;
-      // Find the message row DOM node via the stable id and re-measure it so
-      // the virtualizer updates the row's height after the disclosure transitions.
-      const rowNode = viewport.querySelector<HTMLElement>(`#message-${CSS.escape(messageId)}`);
-      if (rowNode) {
-        chatVirtualizer.measureElementNode(rowNode);
-      }
-    },
-  });
+  // Per-message disclosure state (reasoning blocks + tool-call cards). UI-only;
+  // never written to the transcript. Both are collapsed by default; toggling
+  // triggers a virtualizer remeasure so the row's height tracks the expanded
+  // content. Kept as separate instances so a message carrying both a reasoning
+  // block and a tool-call card discloses each independently.
+  function remeasureRow(messageId: string): void {
+    if (!isVirtualized || !viewport) return;
+    // Find the message row DOM node via the stable id and re-measure it so
+    // the virtualizer updates the row's height after the disclosure transitions.
+    const rowNode = viewport.querySelector<HTMLElement>(`#message-${CSS.escape(messageId)}`);
+    if (rowNode) {
+      chatVirtualizer.measureElementNode(rowNode);
+    }
+  }
+  const reasoningState = useChatDisclosureState({ onRemeasureRow: remeasureRow });
+  const toolCallState = useChatDisclosureState({ onRemeasureRow: remeasureRow });
 
-  // Reset UI-only approval/reasoning/typing/receipt state on conversation change
-  // so stale approved/denied sets, expanded reasoning blocks, adapter-derived
-  // typing state, and accumulated read receipts from the previous conversation
+  // Reset UI-only approval/disclosure/typing/receipt state on conversation change
+  // so stale approved/denied sets, expanded reasoning/tool-call disclosures,
+  // adapter-derived typing state, and accumulated read receipts from the previous conversation
   // are cleared (their message ids can collide). The void reference to
   // `conversationId` at the start of the effect body is the Svelte 5 pattern for
   // declaring a reactive dependency on a derived without reading its value.
@@ -192,6 +195,7 @@
     approvedToolCallIds = new Set();
     deniedToolCallIds = new Set();
     reasoningState.reset();
+    toolCallState.reset();
     typingIndicatorState.reset();
     readReceiptsState.reset();
   });
@@ -1449,7 +1453,7 @@
 <div
   bind:this={containerRef}
   {id}
-  class={classNames('chat-container', className)}
+  class={classNames('cinder-chat', 'chat-container', className)}
   data-surface-mode={surfaceMode}
   data-cinder-density={density}
   data-cinder-variant={variant}
@@ -1552,6 +1556,8 @@
         suggestions={derivedSuggestions}
         reasoningExpanded={reasoningState.isExpanded(message.id)}
         onreasoning={() => reasoningState.toggle(message.id)}
+        toolCallExpanded={toolCallState.isExpanded(message.id)}
+        ontoolcalltoggle={() => toolCallState.toggle(message.id)}
         onsuggestionselect={handleSuggestionSelect}
       >
         {#snippet actions()}

package/src/components/chat/container/use-chat-disclosure-state.svelte.ts

@@ -0,0 +1,96 @@
+/**
+ * Runes helper for tracking which per-message disclosures are expanded.
+ *
+ * Owns a set of expanded message ids and provides a toggle function. Used for
+ * any collapsed-by-default disclosure that is keyed by message id and lives in
+ * a virtualized transcript — reasoning blocks and tool-call cards both use one
+ * instance each. When a virtualizer remeasure callback is registered
+ * (optional), toggling fires it so the virtualizer can remeasure the row after
+ * the disclosure opens/closes.
+ */
+
+/** Options for the disclosure state helper. */
+export type UseChatDisclosureStateOptions = {
+  /**
+   * Optional callback to trigger a virtualizer remeasure for a specific message
+   * row after the disclosure state changes. If the virtualizer is not wired
+   * (e.g. in non-virtualized mode), pass `undefined` or omit — the toggle
+   * still works, no remeasure fires.
+   */
+  onRemeasureRow?: ((messageId: string) => void) | undefined;
+};
+
+/** Return type for the disclosure state helper. */
+export type UseChatDisclosureStateReturn = {
+  /** Whether the disclosure for the given message id is expanded. */
+  isExpanded: (messageId: string) => boolean;
+  /**
+   * Toggle the expanded state for the given message id. Also fires the
+   * remeasure callback when wired (virtualizer support).
+   */
+  toggle: (messageId: string) => void;
+  /**
+   * Reset all expanded state to empty. Called on conversation change so stale
+   * expanded disclosures from the previous conversation are cleared.
+   */
+  reset: () => void;
+};
+
+/**
+ * Creates reactive state for per-message disclosure expansion.
+ *
+ * The returned `isExpanded` and `toggle` are stable references — safe to pass
+ * as props without triggering extra re-renders.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useChatDisclosureState } from './use-chat-disclosure-state.svelte';
+ *
+ *   const reasoningState = useChatDisclosureState({});
+ * </script>
+ *
+ * <!-- in template: -->
+ * <ReasoningPart
+ *   {part}
+ *   expanded={reasoningState.isExpanded(message.id)}
+ *   ontoggle={() => reasoningState.toggle(message.id)}
+ * />
+ * ```
+ */
+export function useChatDisclosureState(
+  options: UseChatDisclosureStateOptions,
+): UseChatDisclosureStateReturn {
+  const { onRemeasureRow } = options;
+
+  // Set of message ids whose disclosures are currently expanded.
+  // Collapsed by default (disclosures start closed).
+  let expandedIds = $state(new Set<string>());
+
+  function isExpanded(messageId: string): boolean {
+    return expandedIds.has(messageId);
+  }
+
+  function toggle(messageId: string): void {
+    const next = new Set(expandedIds);
+    if (next.has(messageId)) {
+      next.delete(messageId);
+    } else {
+      next.add(messageId);
+    }
+    expandedIds = next;
+    // Notify the virtualizer so it can remeasure the row after the DOM
+    // transitions to its new open/closed height. No-op when not wired.
+    onRemeasureRow?.(messageId);
+  }
+
+  function reset(): void {
+    expandedIds = new Set();
+  }
+
+  return {
+    isExpanded,
+    toggle,
+    reset,
+  };
+}

package/src/components/chat/container/use-chat-scroll-state.svelte.ts

@@ -173,6 +173,10 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
   // Non-reactive bookkeeping
   let scrollTicking = false;
   let isUserScrolling = false; // Prevents auto-scroll from interrupting user-initiated smooth scroll
+  // Cancel function for the in-flight withForcedLayout session, if any. A new
+  // session cancels the previous one's listeners/timer before starting its
+  // own — see withForcedLayout below for why this matters.
+  let activeForcedLayoutCancel: (() => void) | null = null;
 
   /**
    * Set atBottom state directly.
@@ -269,11 +273,89 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
     return () => observer.disconnect();
   }
 
+  /**
+   * Forces every row to lay out at its real height before a programmatic
+   * scroll-to-bottom, then restores the content-visibility optimization once
+   * the scroll settles.
+   *
+   * Off-screen `.chat-message` rows use `content-visibility: auto` with a
+   * 180px estimate (`contain-intrinsic-size`) until they're painted. Calling
+   * `scrollTo({ top: viewport.scrollHeight, behavior: 'smooth' })` captures a
+   * target computed from those estimates; as the animation scrolls estimated
+   * rows into view, they resize to their real height, which shifts content
+   * under the fixed pixel target mid-flight — visible as a jerk right as the
+   * scroll finishes. Forcing layout up front (`data-cinder-force-visible`)
+   * makes the target accurate from the start.
+   *
+   * The `scrollend` listener restores the optimization as soon as the
+   * animation actually finishes. The timeout is a backstop for environments
+   * without `scrollend` support and for a zero-distance scroll (already at
+   * the bottom), where neither `scroll` nor `scrollend` ever fires — but it
+   * re-arms on every `scroll` tick rather than firing once on a fixed clock,
+   * so a scroll animation that legitimately runs longer than the backstop
+   * duration (a long transcript, a slower device) can never have the
+   * optimization restored out from under it mid-flight, which would let
+   * off-screen rows resize again before the scroll settles — the exact jerk
+   * this exists to prevent.
+   *
+   * A second call before the first session settles (e.g. a double-click on
+   * jump-to-latest, or auto-scroll firing while a prior scroll is still in
+   * flight) cancels the earlier session's listeners/timer first. Without
+   * this, the OLDER session's own scrollend/backstop could still fire and
+   * strip the attribute while the NEWER scroll animation is still running —
+   * the same jerk this whole mechanism exists to prevent, just reintroduced
+   * by an overlapping call instead of a single long one.
+   */
+  function withForcedLayout(viewport: HTMLElement, scroll: () => void): void {
+    activeForcedLayoutCancel?.();
+
+    viewport.setAttribute('data-cinder-force-visible', '');
+    // Force a synchronous layout so scrollHeight (read inside `scroll`)
+    // reflects every row's real height, not the content-visibility estimate.
+    void viewport.offsetHeight;
+
+    let settled = false;
+    let backstop: ReturnType<typeof setTimeout>;
+    const backstopDuration = reducedMotion.current ? 50 : 500;
+
+    function cancel() {
+      if (settled) return;
+      settled = true;
+      clearTimeout(backstop);
+      viewport.removeEventListener('scrollend', restore);
+      viewport.removeEventListener('scroll', armBackstop);
+    }
+
+    const restore = () => {
+      if (settled) return;
+      cancel();
+      activeForcedLayoutCancel = null;
+      viewport.removeAttribute('data-cinder-force-visible');
+    };
+
+    function armBackstop() {
+      clearTimeout(backstop);
+      backstop = setTimeout(restore, backstopDuration);
+    }
+
+    activeForcedLayoutCancel = cancel;
+    viewport.addEventListener('scrollend', restore, { once: true });
+    viewport.addEventListener('scroll', armBackstop, { passive: true });
+    // Covers the zero-distance case (already at bottom): no scroll/scrollend
+    // event will ever fire, so this is the only thing that restores it.
+    armBackstop();
+
+    scroll();
+  }
+
   /**
    * Scroll to the bottom of the viewport.
    */
   function scrollToBottom(viewport: HTMLElement | null): void {
-    viewport?.scrollTo({ top: viewport.scrollHeight, behavior: getScrollBehavior() });
+    if (!viewport) return;
+    withForcedLayout(viewport, () => {
+      viewport.scrollTo({ top: viewport.scrollHeight, behavior: getScrollBehavior() });
+    });
   }
 
   /**
@@ -292,8 +374,9 @@ export function useChatScrollState(options?: UseChatScrollStateOptions): UseChat
     // Prevent auto-scroll from interrupting the smooth scroll animation
     isUserScrolling = true;
 
-    const behavior = getScrollBehavior();
-    viewport.scrollTo({ top: viewport.scrollHeight, behavior });
+    withForcedLayout(viewport, () => {
+      viewport.scrollTo({ top: viewport.scrollHeight, behavior: getScrollBehavior() });
+    });
     onReachBottom?.();
     onComplete?.();
 

package/src/components/chat/conversation-model.ts

@@ -1,157 +1,44 @@
 /**
- * Vendored conversation data model for the Chat component.
+ * Conversationalist data model types for the Chat component.
  *
- * Chat renders conversation transcripts but does not manage conversation state,
- * so it depends only on the *shape* of the data it displays — not on any runtime
- * library. This module is a faithful structural mirror of the message/content/tool
- * shapes produced by the `conversationalist` library (and the shared
- * `interoperability` tool types it builds on), so a `conversationalist` `Message`
- * or an `armorer` tool call/result satisfies these types with zero adaptation.
- *
- * This file is the single authority for the contract. Provenance: agent-bureau
- * commit `4ca94f7af6b06e0310b81c1706aebc092804879a`
- * (`packages/conversationalist/src/{types,multi-modal}.ts`,
- * `packages/interoperability/src/types.ts`). If provenance ever drifts from this
- * file, this file wins and the discrepancy is raised separately.
+ * Chat renders immutable transcript snapshots and keeps its public `conversation`
+ * prop aligned with the published `conversationalist` package. This file is a
+ * type-only bridge so Cinder does not maintain a stale structural mirror.
  *
  * @module
  */
 
-/** A JSON-serializable primitive. */
-export type JSONPrimitive = string | number | boolean | null;
-
-/** Any JSON-serializable value. */
-export type JSONValue = JSONPrimitive | ReadonlyArray<JSONValue> | { [key: string]: JSONValue };
-
-/** A text segment of message content. */
-export type TextContent = { type: 'text'; text: string };
-
-/** An image segment of message content. */
-export type ImageContent = { type: 'image'; url: string; mimeType?: string; text?: string };
-
-/** A single segment of multi-modal message content. */
-export type MultiModalContent = TextContent | ImageContent;
-
-/** Classification of a tool execution failure. */
-export type ToolErrorCategory =
-  | 'validation'
-  | 'permission'
-  | 'not_found'
-  | 'conflict'
-  | 'transient'
-  | 'timeout'
-  | 'cancelled'
-  | 'internal';
-
-/** Structured error metadata attached to a failed tool result. */
-export type ToolError = {
-  code: string;
-  category: ToolErrorCategory;
-  retryable: boolean;
-  message: string;
-  details?: JSONValue | undefined;
-};
-
-/** A follow-up action a tool result can request before it can complete. */
-export type ToolAction = {
-  type: 'approval' | 'input';
-  message?: string | undefined;
-  schema?: JSONValue | undefined;
-};
-
-/** A request to invoke a tool. */
-export type ToolCall = { id: string; name: string; arguments: JSONValue };
-
-/** The outcome of executing a tool call. */
-export type ToolResult = {
-  callId: string;
-  outcome: 'success' | 'error' | 'action_required';
-  content: JSONValue;
-  error?: ToolError | undefined;
-  action?: ToolAction | undefined;
-};
-
-/** A tool call paired with its result, if one exists yet. */
-export type ToolCallPair = { call: ToolCall; result?: ToolResult | undefined };
-
-/** The role a message plays in a conversation. */
-export type MessageRole =
-  | 'user'
-  | 'assistant'
-  | 'system'
-  | 'developer'
-  | 'tool-call'
-  | 'tool-result'
-  | 'snapshot';
-
-/** Token accounting for a single message. */
-export type TokenUsage = { prompt: number; completion: number; total: number };
-
-/** The mutable input shape used to create a message. */
-export type MessageInput = {
-  role: MessageRole;
-  content: string | MultiModalContent[];
-  metadata?: Record<string, JSONValue> | undefined;
-  hidden?: boolean | undefined;
-  toolCall?: ToolCall | undefined;
-  toolResult?: ToolResult | undefined;
-  tokenUsage?: TokenUsage | undefined;
-};
-
-/** An immutable message in a conversation transcript. */
-export type Message = {
-  id: string;
-  role: MessageRole;
-  content: string | ReadonlyArray<MultiModalContent>;
-  position: number;
-  createdAt: string;
-  metadata: Readonly<Record<string, JSONValue>>;
-  hidden: boolean;
-  toolCall?: Readonly<ToolCall> | undefined;
-  toolResult?: Readonly<ToolResult> | undefined;
-  tokenUsage?: Readonly<TokenUsage> | undefined;
-};
-
-/** Lifecycle status of a conversation. */
-export type ConversationStatus = 'active' | 'archived' | 'deleted';
-
-/**
- * An immutable conversation transcript snapshot.
- *
- * `ids` is the canonical message ordering; `messages` is a record keyed by id
- * (NOT an array). Resolve a message by walking `ids` and looking each up in
- * `messages` — see {@link getMessages} in `./utilities/conversation.ts`.
- */
-export type ConversationHistory = {
-  schemaVersion: number;
-  id: string;
-  title?: string | undefined;
-  status: ConversationStatus;
-  metadata: Readonly<Record<string, JSONValue>>;
-  ids: ReadonlyArray<string>;
-  messages: Readonly<Record<string, Message>>;
-  createdAt: string;
-  updatedAt: string;
-};
+import type { ToMarkdownOptions as ConversationalistToMarkdownOptions } from 'conversationalist/markdown';
+
+export type {
+  AssistantMessage,
+  ContainerUploadContent,
+  ConversationHistory,
+  ConversationStatus,
+  ImageContent,
+  JSONValue,
+  Message,
+  MessageInput,
+  MessageRole,
+  MultiModalContent,
+  RedactedThinkingContent,
+  ServerToolResultContent,
+  ServerToolResultType,
+  ServerToolUseContent,
+  TextContent,
+  ThinkingContent,
+  TokenUsage,
+  ToolAction,
+  ToolCall,
+  ToolError,
+  ToolErrorCategory,
+  ToolResult,
+  WebSearchToolResultContent,
+} from 'conversationalist';
+export type { ToolCallPair } from 'conversationalist/utilities';
 
 /** Base options shared by all transcript export operations. */
-export type ExportOptions = {
-  /** When true, strips transient metadata (keys starting with '_'). @default false */
-  stripTransient?: boolean;
-  /** When false, hidden messages are omitted from export output. @default true */
-  includeHidden?: boolean;
-  /** When true, hidden message content is replaced with a redacted placeholder. @default false */
-  redactHiddenContent?: boolean;
-  /** Placeholder used when redacting tool or hidden content. @default "[REDACTED]" */
-  redactedPlaceholder?: string;
-  /** When true, redacts tool call arguments with '[REDACTED]'. @default false */
-  redactToolArguments?: boolean;
-  /** When true, redacts tool result content with '[REDACTED]'. @default false */
-  redactToolResults?: boolean;
-};
+export type ExportOptions = Omit<ConversationalistToMarkdownOptions, 'includeMetadata'>;
 
 /** Options for exporting a transcript to markdown. */
-export type ToMarkdownOptions = ExportOptions & {
-  /** When true, includes YAML frontmatter with full metadata for lossless round-trip. @default false */
-  includeMetadata?: boolean;
-};
+export type ToMarkdownOptions = ConversationalistToMarkdownOptions;