@lostgradient/cinder 0.1.0

package/src/components/chart.types.ts

@@ -0,0 +1,104 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+export type ChartXValue = string | number | Date;
+export type ChartNumericValue = number | null | undefined;
+export type ChartLegendPosition = 'top' | 'bottom' | 'none';
+export type ChartDataTableVisibility = 'screen-reader-only' | 'visible' | 'hidden';
+
+export type ChartFormatterContext = {
+  seriesId?: string;
+  seriesLabel?: string;
+  index: number;
+};
+
+export type ChartTickFormatter = (
+  value: string | number | Date,
+  context: ChartFormatterContext,
+) => string;
+
+export type ChartValueFormatter = (value: number, context: ChartFormatterContext) => string;
+
+export type ChartAxisConfiguration = {
+  label?: string;
+  tickCount?: number;
+  format?: ChartTickFormatter;
+};
+
+export type ChartPoint = {
+  x: ChartXValue;
+  y: ChartNumericValue;
+};
+
+export type ChartCartesianSeries = {
+  id: string;
+  label: string;
+  data: ChartPoint[];
+  color?: string;
+  valueFormatter?: ChartValueFormatter;
+};
+
+export type ChartSharedProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  label: string;
+  description?: string;
+  height?: number;
+  xAxis?: ChartAxisConfiguration;
+  yAxis?: ChartAxisConfiguration;
+  legendPosition?: ChartLegendPosition;
+  hiddenSeriesIds?: string[];
+  loading?: boolean;
+  dataTableCaption?: string;
+  dataTableVisibility?: ChartDataTableVisibility;
+  maximumInteractivePoints?: number;
+  class?: string;
+  empty?: Snippet;
+  loadingContent?: Snippet;
+};
+
+export type BarChartOrientation = 'vertical' | 'horizontal';
+export type BarChartMode = 'grouped' | 'stacked';
+export type AreaChartMode = 'single' | 'stacked';
+
+export type BarChartDatum = Record<string, string | number | Date | null | undefined>;
+
+export type BarChartSeries = {
+  id: string;
+  label: string;
+  valueKey: string;
+  color?: string;
+  valueFormatter?: ChartValueFormatter;
+};
+
+export type ChartJsonXValue = string | number;
+export type ChartJsonValue = string | number | null;
+
+/** @schemaObject */
+export type ChartAxisSchemaConfiguration = {
+  label?: string;
+  tickCount?: number;
+};
+
+/** @schemaObject */
+export type ChartSchemaPoint = {
+  x: ChartJsonXValue;
+  y?: number | null;
+};
+
+/** @schemaObject */
+export type ChartCartesianSchemaSeries = {
+  id: string;
+  label: string;
+  /** @schemaObject */
+  data: ChartSchemaPoint[];
+  color?: string;
+};
+
+export type BarChartSchemaDatum = Record<string, ChartJsonValue>;
+
+/** @schemaObject */
+export type BarChartSchemaSeries = {
+  id: string;
+  label: string;
+  valueKey: string;
+  color?: string;
+};

package/src/components/chat/artifact/artifact-panel.svelte

@@ -0,0 +1,127 @@
+<script lang="ts" module>
+  import type { Snippet } from 'svelte';
+
+  export type ArtifactPanelProps = {
+    /**
+     * Unique identifier for this panel instance. Used to namespace the title
+     * element's DOM ID so that multiple ArtifactPanel instances on the same
+     * page do not produce duplicate IDs.
+     */
+    instanceId?: string;
+    title?: string | undefined;
+    onclose?: (() => void) | undefined;
+    children: Snippet;
+  };
+</script>
+
+<script lang="ts">
+  import X from 'lucide-svelte/icons/x';
+
+  let { instanceId = 'artifact', title, onclose, children }: ArtifactPanelProps = $props();
+
+  const titleId = $derived(`${instanceId}-panel-title`);
+
+  function focusOnMount(element: HTMLButtonElement) {
+    element.focus();
+  }
+</script>
+
+<div class="artifact-panel" role="complementary" aria-label={title ?? 'Artifact panel'}>
+  <div class="artifact-panel-header">
+    <span class="artifact-panel-title" id={titleId}>
+      {title ?? 'Artifact'}
+    </span>
+
+    <button
+      type="button"
+      class="artifact-panel-close"
+      onclick={onclose}
+      aria-label="Close artifact panel"
+      {@attach focusOnMount}
+    >
+      <X class="icon-sm" />
+    </button>
+  </div>
+
+  <div class="artifact-panel-content">
+    {@render children()}
+  </div>
+</div>
+
+<style>
+  .artifact-panel {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    border-inline-start: 1px solid var(--cinder-border);
+    background: var(--cinder-surface);
+    min-width: 0;
+    overflow: hidden;
+  }
+
+  .artifact-panel-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: var(--cinder-space-3) var(--cinder-space-4);
+    border-bottom: 1px solid var(--cinder-border);
+    flex-shrink: 0;
+    gap: var(--cinder-space-2);
+  }
+
+  .artifact-panel-title {
+    font-size: var(--cinder-text-sm);
+    font-weight: var(--cinder-font-medium);
+    color: var(--cinder-text);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    flex: 1;
+  }
+
+  .artifact-panel-close {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--cinder-touch-target-min);
+    height: var(--cinder-touch-target-min);
+    padding: 0;
+    background: transparent;
+    border: none;
+    border-radius: var(--cinder-radius-md);
+    color: var(--cinder-text-muted);
+    cursor: pointer;
+    flex-shrink: 0;
+    transition:
+      background var(--cinder-duration-fast) var(--cinder-ease-standard),
+      color var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  @media (hover: hover) {
+    .artifact-panel-close:hover {
+      background: var(--cinder-surface-hover);
+      color: var(--cinder-text);
+    }
+  }
+
+  /* Close button sits in the panel corner; an outset ring would overhang the
+     panel edge, so paint an INSET ring (Strategy B-inset). */
+  .artifact-panel-close:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: inset 0 0 0 var(--cinder-ring-width)
+      var(--_cinder-artifact-panel-close-ring, var(--cinder-ring-color));
+  }
+
+  @media (forced-colors: active) {
+    .artifact-panel-close:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(var(--cinder-ring-width) * -1);
+    }
+  }
+
+  .artifact-panel-content {
+    flex: 1;
+    overflow-y: auto;
+    overflow-x: hidden;
+  }
+</style>

package/src/components/chat/artifact/artifact-viewer.svelte

@@ -0,0 +1,110 @@
+<script lang="ts" module>
+  export type ArtifactContentType = 'html' | 'svg' | 'code' | 'mermaid';
+
+  export type ArtifactViewerProps = {
+    type: ArtifactContentType;
+    content: string;
+    language?: string;
+    title?: string;
+  };
+
+  /**
+   * Wrap SVG content in a minimal HTML document for sandboxed iframe rendering.
+   * This is the safe approach: the SVG runs in a sandboxed origin rather than
+   * the page's origin, so JavaScript (even if injected) cannot access the DOM
+   * or credentials of the parent page.
+   */
+  function wrapSvgInHtml(svg: string): string {
+    return `<!DOCTYPE html><html><body style="margin:0;display:flex;align-items:center;justify-content:center;min-height:100vh;">${svg}</body></html>`;
+  }
+</script>
+
+<script lang="ts">
+  let { type, content, language, title }: ArtifactViewerProps = $props();
+
+  const svgDocument = $derived(type === 'svg' ? wrapSvgInHtml(content) : '');
+</script>
+
+{#if type === 'html'}
+  <iframe
+    class="artifact-viewer artifact-viewer-html"
+    srcdoc={content}
+    sandbox=""
+    title={title ?? 'HTML artifact'}
+    aria-label={title ?? 'HTML artifact'}
+  ></iframe>
+{:else if type === 'svg'}
+  <iframe
+    class="artifact-viewer artifact-viewer-svg"
+    srcdoc={svgDocument}
+    sandbox=""
+    title={title ?? 'SVG artifact'}
+    aria-label={title ?? 'SVG artifact'}
+  ></iframe>
+{:else if type === 'code'}
+  <div class="artifact-viewer artifact-viewer-code">
+    <pre class="artifact-code-block" data-language={language}><code>{content}</code></pre>
+  </div>
+{:else if type === 'mermaid'}
+  <div class="artifact-viewer artifact-viewer-mermaid">
+    <pre class="artifact-code-block" data-language="mermaid"><code>{content}</code></pre>
+    <p class="artifact-mermaid-note" aria-live="polite">
+      Mermaid diagram source. Install the Mermaid library to render diagrams.
+    </p>
+  </div>
+{/if}
+
+<style>
+  .artifact-viewer {
+    width: 100%;
+    height: 100%;
+    display: block;
+  }
+
+  /* HTML iframe */
+  .artifact-viewer-html {
+    border: none;
+    min-height: 200px;
+  }
+
+  /* SVG sandboxed iframe */
+  .artifact-viewer-svg {
+    border: none;
+    min-height: 200px;
+  }
+
+  /* Code and Mermaid */
+  .artifact-viewer-code,
+  .artifact-viewer-mermaid {
+    height: auto;
+    padding: var(--cinder-space-4);
+  }
+
+  .artifact-code-block {
+    margin: 0;
+    padding: var(--cinder-space-4);
+    background: var(--cinder-surface-raised);
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md);
+    overflow-x: auto;
+    font-family: var(--cinder-font-mono);
+    font-size: var(--cinder-text-sm);
+    line-height: var(--leading-relaxed);
+    color: var(--cinder-text);
+    white-space: pre;
+  }
+
+  .artifact-code-block code {
+    font-family: inherit;
+    font-size: inherit;
+    background: none;
+    padding: 0;
+  }
+
+  .artifact-mermaid-note {
+    margin-top: var(--cinder-space-3);
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-muted);
+    font-style: italic;
+  }
+</style>

package/src/components/chat/artifact/chat-artifact-layout.svelte

@@ -0,0 +1,85 @@
+<script lang="ts" module>
+  import type { Snippet } from 'svelte';
+
+  export type ChatArtifactLayoutProps = {
+    /**
+     * Unique identifier for this layout instance. Passed to the ArtifactPanel
+     * to namespace the title element ID and avoid duplicate IDs when multiple
+     * instances share a page.
+     */
+    instanceId?: string;
+    /** Whether the artifact panel is open */
+    open?: boolean;
+    /** Content for the main chat area */
+    children: Snippet;
+    /** Content for the artifact panel */
+    panel?: Snippet;
+    /** Title for the artifact panel */
+    panelTitle?: string | undefined;
+    /** Called when the panel is closed */
+    onclose?: (() => void) | undefined;
+    class?: string;
+  };
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../../utilities/class-names.ts';
+  import ArtifactPanel from './artifact-panel.svelte';
+
+  let {
+    instanceId = 'artifact',
+    open = false,
+    children,
+    panel,
+    panelTitle,
+    onclose,
+    class: className,
+  }: ChatArtifactLayoutProps = $props();
+</script>
+
+<div class={classNames('chat-artifact-layout', className)} data-panel-open={open}>
+  <div class="chat-artifact-main">
+    {@render children()}
+  </div>
+
+  {#if open && panel}
+    <ArtifactPanel {instanceId} title={panelTitle} {onclose}>
+      {@render panel()}
+    </ArtifactPanel>
+  {/if}
+</div>
+
+<style>
+  .chat-artifact-layout {
+    container-type: inline-size;
+    display: grid;
+    grid-template-columns: 1fr;
+    height: 100%;
+    width: 100%;
+    transition: grid-template-columns var(--cinder-duration) var(--cinder-ease-standard);
+  }
+
+  .chat-artifact-layout[data-panel-open='true'] {
+    grid-template-columns: 1fr 40%;
+  }
+
+  .chat-artifact-main {
+    min-width: 0;
+    height: 100%;
+    overflow: hidden;
+  }
+
+  /* Narrow viewport: stack vertically */
+  @container (max-width: 768px) {
+    .chat-artifact-layout[data-panel-open='true'] {
+      grid-template-columns: 1fr;
+      grid-template-rows: 1fr 50%;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .chat-artifact-layout {
+      transition: none;
+    }
+  }
+</style>

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

@@ -0,0 +1,3 @@
+export { default as ArtifactPanel } from './artifact-panel.svelte';
+export { default as ArtifactViewer } from './artifact-viewer.svelte';
+export { default as ChatArtifactLayout } from './chat-artifact-layout.svelte';

package/src/components/chat/builders.ts

@@ -0,0 +1,107 @@
+/**
+ * Conversation builders for the Chat component.
+ *
+ * Chat renders a {@link ConversationHistory} snapshot. Apps with their own
+ * conversation state map it into this shape; these builders give everyone else
+ * (examples, demos, tests, simple apps) an ergonomic, immutable way to construct
+ * one without pulling in a conversation-state library. Each `append*` call
+ * returns a NEW snapshot with the message added in order — the immutable-update
+ * pattern Svelte reactivity expects.
+ */
+
+import type {
+  ConversationHistory,
+  ConversationStatus,
+  Message,
+  MessageInput,
+  MultiModalContent,
+} from './conversation-model.ts';
+
+const SCHEMA_VERSION = 4;
+
+/**
+ * Generates a globally-unique id for a builder-created entity. Uses
+ * `crypto.randomUUID()` (browser + Bun + Node) rather than a module-level
+ * counter, so ids never collide across simultaneously-rendered conversations or
+ * across parallel test cases sharing the cached module.
+ */
+function nextId(prefix: string): string {
+  return `${prefix}-${crypto.randomUUID()}`;
+}
+
+/** Creates a new empty conversation snapshot. */
+export function createConversation(options?: {
+  id?: string;
+  title?: string;
+  status?: ConversationStatus;
+}): ConversationHistory {
+  const now = new Date().toISOString();
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: options?.id ?? nextId('conversation'),
+    title: options?.title,
+    status: options?.status ?? 'active',
+    metadata: {},
+    ids: [],
+    messages: {},
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/** Materializes a {@link MessageInput} into an immutable {@link Message} at the given position. */
+function materializeMessage(input: MessageInput, position: number): Message {
+  const content: string | ReadonlyArray<MultiModalContent> =
+    typeof input.content === 'string' ? input.content : [...input.content];
+  return {
+    id: nextId('message'),
+    role: input.role,
+    content,
+    position,
+    createdAt: new Date().toISOString(),
+    metadata: input.metadata ?? {},
+    hidden: input.hidden ?? false,
+    ...(input.toolCall !== undefined ? { toolCall: input.toolCall } : {}),
+    ...(input.toolResult !== undefined ? { toolResult: input.toolResult } : {}),
+    ...(input.tokenUsage !== undefined ? { tokenUsage: input.tokenUsage } : {}),
+  };
+}
+
+/** Appends one or more messages, returning a new conversation snapshot. */
+export function appendMessages(
+  conversation: ConversationHistory,
+  ...inputs: MessageInput[]
+): ConversationHistory {
+  if (inputs.length === 0) return conversation;
+
+  const ids = [...conversation.ids];
+  const messages: Record<string, Message> = { ...conversation.messages };
+  for (const input of inputs) {
+    const message = materializeMessage(input, ids.length);
+    ids.push(message.id);
+    messages[message.id] = message;
+  }
+
+  return {
+    ...conversation,
+    ids,
+    messages,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+/** Appends a single user message. */
+export function appendUserMessage(
+  conversation: ConversationHistory,
+  content: string | MultiModalContent[],
+): ConversationHistory {
+  return appendMessages(conversation, { role: 'user', content });
+}
+
+/** Appends a single assistant message. */
+export function appendAssistantMessage(
+  conversation: ConversationHistory,
+  content: string | MultiModalContent[],
+): ConversationHistory {
+  return appendMessages(conversation, { role: 'assistant', content });
+}

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "chat",
+  "import": "@lostgradient/cinder/chat",
+  "examples": [
+    {
+      "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"
+    },
+    {
+      "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"
+    },
+    {
+      "id": "streaming",
+      "title": "Streaming chat",
+      "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-tool-calls",
+      "title": "With tool calls",
+      "description": "Tool call and result messages render as paired expandable groups.",
+      "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-call-chat' }),\n        'Check whether the package has drift.',\n      ),\n      {\n        role: 'tool-call',\n        content: '',\n        toolCall: {\n          id: 'call-exports-check',\n          name: 'exports_check',\n          arguments: { package: '@lostgradient/cinder' },\n        },\n      },\n      {\n        role: 'tool-result',\n        content: '',\n        toolResult: {\n          callId: 'call-exports-check',\n          outcome: 'success',\n          content: { status: 'ok', drift: false },\n        },\n      },\n      {\n        role: 'assistant',\n        content: 'The exports map is current and the component subpaths are available.',\n      },\n    ),\n  );\n</script>\n\n<div style=\"height: 34rem;\">\n  <Chat id=\"playground-tool-call-chat\" {conversation} allowAttachments={false} />\n</div>\n"
+    }
+  ]
+}