@lostgradient/cinder 0.2.0 → 0.4.0

package/src/components/chat/message/chat-message-parts-renderer.svelte

@@ -0,0 +1,152 @@
+<script lang="ts">
+  import {
+    toRenderUnits,
+    type BodyMessagePart,
+    type ChatMessagePartsRendererProps,
+  } from './chat-message-parts.ts';
+  import MarkdownPart from './parts/markdown-part.svelte';
+  import ToolCallPart from './parts/tool-call-part.svelte';
+  import ToolResultPart from './parts/tool-result-part.svelte';
+  import ToolApprovalPart from './parts/tool-approval-part.svelte';
+  import ReasoningPart from './parts/reasoning-part.svelte';
+  import StepPart from './parts/step-part.svelte';
+  import SuggestionPart from './parts/suggestion-part.svelte';
+  import ImagePart from './parts/image-part.svelte';
+
+  let {
+    parts,
+    messagePart,
+    expanded = false,
+    ontoggle,
+    onapprove,
+    ondeny,
+    reasoningExpanded = false,
+    onreasoning,
+    onsuggestionselect,
+  }: ChatMessagePartsRendererProps = $props();
+
+  const units = $derived(toRenderUnits(parts));
+
+  // APG toolbar roving-tabindex for suggestion chips. `activeIndex` tracks the
+  // chip that holds tabindex=0. ArrowRight/ArrowLeft move focus (wrapping);
+  // Home/End jump to first/last. Tab and all other keys pass through.
+  let activeIndex = $state(0);
+
+  // The chip count can shrink between renders (a new assistant turn with fewer
+  // suggestions, or streaming). A raw `activeIndex` left beyond a toolbar's range
+  // would leave NO chip with tabindex=0, making that toolbar unreachable by Tab.
+  // Clamp against EACH toolbar's own length (not the total across units) so every
+  // rendered toolbar always has exactly one tabindex=0 entry point — floored at 0
+  // for the empty case.
+  function activeChipIndex(count: number): number {
+    return count === 0 ? 0 : Math.min(activeIndex, count - 1);
+  }
+
+  function handleToolbarKeydown(event: KeyboardEvent, toolbar: HTMLElement, count: number): void {
+    if (count === 0) return;
+    const current = Math.min(activeIndex, count - 1);
+    let next = current;
+    if (event.key === 'ArrowRight') {
+      next = (current + 1) % count;
+    } else if (event.key === 'ArrowLeft') {
+      next = (current - 1 + count) % count;
+    } else if (event.key === 'Home') {
+      next = 0;
+    } else if (event.key === 'End') {
+      next = count - 1;
+    } else {
+      return;
+    }
+    event.preventDefault();
+    activeIndex = next;
+    const chips = toolbar.querySelectorAll<HTMLElement>('[data-cinder-suggestion]');
+    chips[next]?.focus();
+  }
+</script>
+
+<!--
+  Built-in renderer for a single body part. A static `{#if part.type === ...}`
+  switch (not a dynamic component map) so the bundler can tree-shake unused part
+  components and TypeScript narrows each branch. Image parts and step parts never
+  reach here — they render through the grouped `{#each}` path below. The trailing
+  `{:else}` is the exhaustiveness sentinel: `part.type` narrows to `never` there,
+  so a later Chat task that widens ChatMessagePart without adding a branch surfaces
+  a visible dev marker in the DOM rather than silently rendering nothing.
+-->
+{#snippet renderDefault(part: BodyMessagePart)}
+  {#if part.type === 'markdown'}
+    <MarkdownPart {part} />
+  {:else if part.type === 'tool-call'}
+    <ToolCallPart {part} {expanded} {ontoggle} />
+  {:else if part.type === 'tool-result'}
+    <ToolResultPart {part} />
+  {:else if part.type === 'tool-approval'}
+    <ToolApprovalPart {part} {onapprove} {ondeny} />
+  {:else if part.type === 'reasoning'}
+    <ReasoningPart {part} expanded={reasoningExpanded} ontoggle={onreasoning} />
+  {:else}
+    <!-- Unhandled part type — a new ChatMessagePart variant was added without a
+         renderer branch. `part` narrows to `never` here, so svelte-check flags
+         the unreachable branch when the union widens, and this sentinel makes
+         the omission visible in the DOM. -->
+    <span data-cinder-unhandled-part aria-hidden="true"></span>
+  {/if}
+{/snippet}
+
+{#each units as unit (unit.key)}
+  {#if unit.kind === 'images'}
+    <ImagePart parts={unit.images} />
+  {:else if unit.kind === 'steps'}
+    <!-- Step parts are grouped and wrapped in a single <ol> stepper. -->
+    <ol class="chat-step-list" aria-label="Steps">
+      {#each unit.steps as step (step.key)}
+        <StepPart part={step} />
+      {/each}
+    </ol>
+  {:else if unit.kind === 'suggestions'}
+    <!-- Suggestion chips are grouped into a single toolbar. APG toolbar pattern:
+         Tab enters → active chip (tabindex=0); Left/Right arrows move focus
+         within (roving tabindex); Tab exits. Home/End jump to first/last.
+         [data-cinder-suggested-replies] is the selector used by useChatKeyboardNav
+         to suppress message ArrowUp/ArrowDown while focus is inside here. -->
+    <div
+      class="chat-suggestions"
+      role="toolbar"
+      aria-label="Suggested replies"
+      data-cinder-suggested-replies
+      onkeydown={(event) => {
+        handleToolbarKeydown(event, event.currentTarget as HTMLElement, unit.suggestions.length);
+      }}
+    >
+      {#each unit.suggestions as suggestion, index (suggestion.key)}
+        <SuggestionPart
+          part={suggestion}
+          {onsuggestionselect}
+          tabindex={index === activeChipIndex(unit.suggestions.length) ? 0 : -1}
+        />
+      {/each}
+    </div>
+  {:else if messagePart}
+    {@render messagePart(unit.part, renderDefault)}
+  {:else}
+    {@render renderDefault(unit.part)}
+  {/if}
+{/each}
+
+<style>
+  .chat-step-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0;
+    padding: 0;
+    margin: 0;
+    list-style: none;
+  }
+
+  .chat-suggestions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--cinder-space-2);
+    padding-block-start: var(--cinder-space-2);
+  }
+</style>

package/src/components/chat/message/chat-message-parts.ts

@@ -0,0 +1,163 @@
+/**
+ * Plain-TS support module for the message parts renderer.
+ *
+ * Types and the pure `toRenderUnits` grouping live here (not in the `.svelte`
+ * file) so they are importable under plain `tsc`/`svelte-check` — symbols
+ * exported from a `.svelte` `<script module>` are not reliably resolvable
+ * outside the Svelte language service.
+ */
+
+import type { Snippet } from 'svelte';
+
+import type {
+  ChatMessagePart,
+  ImageMessagePart,
+  StepMessagePart,
+  SuggestionMessagePart,
+} from '../utilities/types.ts';
+
+/**
+ * A body part — every renderable part EXCEPT image, step, and suggestion.
+ * Image parts render through the grouped attachment path (the grid lays out
+ * by total count). Step parts are grouped into the stepper render unit and
+ * bypass the per-part override entirely — they never reach `messagePart` or
+ * `renderDefault`. Suggestion parts render through the grouped `suggestions`
+ * toolbar path so all chips appear inside a single `role="toolbar"` wrapper.
+ * None of these flow through the per-part override; the override's type
+ * excludes them so a consumer can't write dead branches for them.
+ */
+export type BodyMessagePart = Exclude<
+  ChatMessagePart,
+  ImageMessagePart | StepMessagePart | SuggestionMessagePart
+>;
+
+/**
+ * Per-part override snippet. Inversion of control: the consumer receives the
+ * part AND a `renderDefault` snippet, and decides whether to render its own
+ * markup or delegate to the built-in renderer by calling
+ * `{@render renderDefault(part)}`. There is no "render empty to fall through"
+ * magic — Svelte snippets render DOM and have no inspectable return value, so
+ * the fallback is always explicit and SSR-safe.
+ *
+ * The part is a {@link BodyMessagePart} (image parts are excluded — see above),
+ * so the type matches what the override can actually intercept.
+ */
+export type MessagePartOverride = Snippet<
+  [part: BodyMessagePart, renderDefault: Snippet<[BodyMessagePart]>]
+>;
+
+/** Props for {@link ChatMessagePartsRenderer}. */
+export type ChatMessagePartsRendererProps = {
+  /** The ordered render parts for one message. */
+  parts: ChatMessagePart[];
+  /**
+   * Optional per-part override. Applies to body parts (markdown, tool-call,
+   * tool-result, tool-approval, reasoning). Image parts, step parts, and
+   * suggestion parts always render through the grouped default paths; they are
+   * excluded from this override's type and never flow through it. In
+   * particular, step parts are accumulated into the stepper render unit and
+   * bypass this override entirely — a consumer cannot intercept individual
+   * step parts via `messagePart`.
+   */
+  messagePart?: MessagePartOverride | undefined;
+  /** Disclosure state for tool-call parts. Owned by the message. */
+  expanded?: boolean;
+  /** Called when a tool-call part's disclosure toggle is activated. */
+  ontoggle?: (() => void) | undefined;
+  /** Called when the user approves an action-required tool call. */
+  onapprove?: ((toolCallId: string) => void) | undefined;
+  /** Called when the user denies an action-required tool call. */
+  ondeny?: ((toolCallId: string) => void) | undefined;
+  /** Whether the reasoning block for this message is expanded. */
+  reasoningExpanded?: boolean | undefined;
+  /** Called when the reasoning disclosure toggle is activated. */
+  onreasoning?: (() => void) | undefined;
+  /** Called when the user selects a suggestion chip. */
+  onsuggestionselect?: ((label: string) => void) | undefined;
+};
+
+/** A renderable unit: a single body part, a contiguous run of image parts, a group of step parts, or a group of suggestion chips. */
+export type RenderUnit =
+  | {
+      kind: 'part';
+      part: Exclude<ChatMessagePart, ImageMessagePart | StepMessagePart | SuggestionMessagePart>;
+      key: string;
+    }
+  | { kind: 'images'; images: ImageMessagePart[]; key: string }
+  | { kind: 'steps'; steps: StepMessagePart[]; key: string }
+  | { kind: 'suggestions'; suggestions: SuggestionMessagePart[]; key: string };
+
+/**
+ * Collapses a parts array into render units, grouping each maximal run of
+ * adjacent image parts into one unit, each maximal run of adjacent step parts
+ * into one stepper unit, and each maximal run of adjacent suggestion parts into
+ * one toolbar unit. Keeps non-image, non-step, non-suggestion parts individual
+ * so the per-part override applies to them; groups images so the attachment
+ * grid lays out by total count; groups steps so they render inside a single
+ * `<ol>`; groups suggestions so they render inside a single `role="toolbar"`.
+ *
+ * @param parts - The ordered render parts for one message
+ * @returns Render units in order, with image, step, and suggestion runs collapsed
+ */
+export function toRenderUnits(parts: ChatMessagePart[]): RenderUnit[] {
+  const units: RenderUnit[] = [];
+  let imageRun: ImageMessagePart[] = [];
+  let stepRun: StepMessagePart[] = [];
+  let suggestionRun: SuggestionMessagePart[] = [];
+
+  const flushImages = (): void => {
+    if (imageRun.length > 0) {
+      // The run's key is its first image key — stable as long as the run's
+      // leading image keeps identity, which it does (index-based keys).
+      units.push({ kind: 'images', images: imageRun, key: `images:${imageRun[0]!.key}` });
+      imageRun = [];
+    }
+  };
+
+  const flushSteps = (): void => {
+    if (stepRun.length > 0) {
+      units.push({ kind: 'steps', steps: stepRun, key: `steps:${stepRun[0]!.key}` });
+      stepRun = [];
+    }
+  };
+
+  const flushSuggestions = (): void => {
+    if (suggestionRun.length > 0) {
+      units.push({
+        kind: 'suggestions',
+        suggestions: suggestionRun,
+        key: `suggestions:${suggestionRun[0]!.key}`,
+      });
+      suggestionRun = [];
+    }
+  };
+
+  for (const part of parts) {
+    if (part.type === 'image') {
+      flushSteps();
+      flushSuggestions();
+      imageRun.push(part);
+      continue;
+    }
+    if (part.type === 'step') {
+      flushImages();
+      flushSuggestions();
+      stepRun.push(part);
+      continue;
+    }
+    if (part.type === 'suggestion') {
+      flushImages();
+      flushSteps();
+      suggestionRun.push(part);
+      continue;
+    }
+    flushImages();
+    flushSteps();
+    flushSuggestions();
+    units.push({ kind: 'part', part, key: part.key });
+  }
+  flushImages();
+  flushSteps();
+  flushSuggestions();
+  return units;
+}

package/src/components/chat/message/chat-message.svelte

@@ -2,6 +2,8 @@
   import type { Snippet } from 'svelte';
   import type { HTMLAttributes } from 'svelte/elements';
   import type { Message, ToolCallPair } from '../conversation-model.ts';
+  import type { MessagePartOverride } from './chat-message-parts.ts';
+  import type { StepInfo } from '../utilities/types.ts';
 
   /**
    * Role labels for display purposes.
@@ -32,6 +34,12 @@
     actions?: Snippet;
     /** Status indicator snippet (sending, delivered, error) */
     status?: Snippet;
+    /**
+     * Per-part render override. Forwarded to the parts renderer; lets a consumer
+     * replace the rendering of an individual body part while delegating the rest
+     * to the built-ins (inversion of control — see the renderer).
+     */
+    messagePart?: MessagePartOverride | undefined;
     /** Show built-in copy button alongside custom actions (default: true) */
     showDefaultActions?: boolean;
     /** Whether this message is currently streaming */
@@ -44,20 +52,45 @@
     onretry?: ((messageId: string) => void) | undefined;
     /** Called when user edits a message (fires with new content). Only applies to user messages. */
     onedit?: ((event: { messageId: string; content: string }) => void) | undefined;
+    /** The set of approved tool call IDs for deriving approval state. */
+    approvedToolCallIds?: ReadonlySet<string> | undefined;
+    /** The set of denied tool call IDs for deriving denial state. */
+    deniedToolCallIds?: ReadonlySet<string> | undefined;
+    /** Called when the user approves an action-required tool call. */
+    onapprove?: ((toolCallId: string) => void) | undefined;
+    /** Called when the user denies an action-required tool call. */
+    ondeny?: ((toolCallId: string) => void) | undefined;
+    /**
+     * Reasoning text to surface as a collapsible block before the body.
+     * When present and non-empty, a `reasoning` part is prepended to the derived parts.
+     */
+    reasoning?: string | undefined;
+    /**
+     * Step list to surface as a stepper before the body.
+     * Each entry maps to one `step` part in the derived parts.
+     */
+    steps?: ReadonlyArray<StepInfo> | undefined;
+    /** Whether the reasoning disclosure is expanded. Owned by the container's reasoning state. */
+    reasoningExpanded?: boolean | undefined;
+    /** Called when the reasoning disclosure toggle is activated. */
+    onreasoning?: (() => void) | undefined;
+    /**
+     * Suggestion labels to surface as clickable chips after the body.
+     * Each entry maps to one `suggestion` part in the derived parts.
+     */
+    suggestions?: ReadonlyArray<string> | undefined;
+    /** Called when the user selects a suggestion chip. */
+    onsuggestionselect?: ((label: string) => void) | undefined;
   };
 </script>
 
 <script lang="ts">
   import { classNames } from '../../../utilities/class-names.ts';
-  import { stringify } from '../../../utilities/stringify.ts';
-  import { getMessageText, getMessageParts } from '../utilities/utilities.js';
+  import { deriveMessageParts, getMessageText } from '../utilities/utilities.js';
   import Pencil from 'lucide-svelte/icons/pencil';
   import RotateCcw from 'lucide-svelte/icons/rotate-ccw';
   import CopyButton from '../../copy-button/copy-button.svelte';
-  import MessageContent from './message-content.svelte';
-  import MessageAttachments from './message-attachments.svelte';
-  import ToolCallGroup from './tool-call-group.svelte';
-  import ToolPayloadCode from './tool-payload-code.svelte';
+  import ChatMessagePartsRenderer from './chat-message-parts-renderer.svelte';
 
   let {
     message,
@@ -67,12 +100,23 @@
     searchMatch = false,
     actions,
     status,
+    messagePart,
     showDefaultActions = true,
     streaming = false,
     overrideContent,
     onexpandedchange,
     onretry,
     onedit,
+    approvedToolCallIds,
+    deniedToolCallIds,
+    onapprove,
+    ondeny,
+    reasoning,
+    steps,
+    suggestions,
+    reasoningExpanded = false,
+    onreasoning,
+    onsuggestionselect,
     tabindex,
     ...rest
   }: ChatMessageProps = $props();
@@ -118,51 +162,56 @@
   );
   const isFailed = $derived(deliveryStatus === 'failed');
 
-  // Derived values for content processing
-  const parts = $derived(getMessageParts(message));
+  // Derived values for content processing. `textContent` drives message chrome
+  // (copy, edit, the Show more/less control) — the rendered body itself flows
+  // through deriveMessageParts + the parts renderer below.
   const textContent = $derived(getMessageText(message));
   const roleLabel = $derived(ROLE_LABELS[message.role] ?? message.role);
 
-  // Filter image parts from content
-  const imageParts = $derived(parts.filter((part) => part.type === 'image'));
-  const hasImages = $derived(imageParts.length > 0);
-
-  // Role detection
+  // Role detection — kept for wrapper-level layout + a11y (data-tool-pair,
+  // aria-label). The body branches that used to live here are now derived parts.
   const isToolCall = $derived(message.role === 'tool-call');
-  const isToolResult = $derived(message.role === 'tool-result');
 
-  // Find matching tool pair for tool-call messages
+  // Find matching tool pair for tool-call messages. Resolved here (the container
+  // hands down the pairs for this message) and threaded into deriveMessageParts
+  // so the bridge stays pure; also gates the data-tool-pair wrapper styling.
   const toolPair = $derived.by(() => {
     if (!isToolCall || !message.toolCall) return null;
     return toolCallPairs.find((pair) => pair.call.id === message.toolCall?.id) ?? null;
   });
 
-  // Check result outcome for styling + branching.
-  const isToolResultError = $derived(isToolResult && message.toolResult?.outcome === 'error');
-  const isToolResultActionRequired = $derived(
-    isToolResult && message.toolResult?.outcome === 'action_required',
+  // The cinder-owned render parts for this message. The streaming override and
+  // expanded state are resolved into the parts here so the renderer + part
+  // components stay dumb (no override/streaming plumbing leaks into them).
+  // C3: approval id sets are threaded in so tool-approval parts derive their
+  // `approved` state without mutating the transcript.
+  const messageParts = $derived(
+    deriveMessageParts(message, {
+      toolCallPair: toolPair ?? undefined,
+      overrideContent,
+      streaming,
+      expanded,
+      approvedToolCallIds,
+      deniedToolCallIds,
+      // C4: reasoning and steps are UI-only overlays derived from metadata or
+      // explicit per-message props; never written back to the transcript.
+      reasoning,
+      steps,
+      // C5: suggestions are UI-only overlays; never written back to the transcript.
+      suggestions,
+    }),
   );
 
-  // Safe stringify for tool result content (handles circular refs, etc.).
-  // - error: prefer the structured error's message (a ToolError OBJECT, so
-  //   render `.message`, not the object — which would stringify to
-  //   `[object Object]`).
-  // - action_required: surface the requested action's message (matching
-  //   ToolCallGroup), falling back to a neutral label so it's never blank.
-  // - otherwise: stringify the content.
-  const formattedToolResult = $derived.by(() => {
-    if (!isToolResult || !message.toolResult) return null;
-    const { outcome, content, error, action } = message.toolResult;
-
-    if (outcome === 'error' && error) {
-      return error.message;
-    }
-    if (outcome === 'action_required') {
-      return action?.message ?? 'This tool call requires action.';
-    }
+  // Whether this message has a markdown body part — gates the Show more/less
+  // control (a tool-call/tool-result message has no markdown body to truncate).
+  const hasMarkdownBody = $derived(messageParts.some((part) => part.type === 'markdown'));
 
-    return stringify(content);
-  });
+  // Split the parts so the rendered DOM matches the historical structure: body
+  // parts (text/markdown/tool) live inside `.chat-message-body`, image parts
+  // render as a sibling AFTER it — exactly where MessageAttachments used to sit,
+  // so the flex layout and spacing are unchanged.
+  const bodyParts = $derived(messageParts.filter((part) => part.type !== 'image'));
+  const imageParts = $derived(messageParts.filter((part) => part.type === 'image'));
 
   // Content truncation threshold (characters)
   const TRUNCATE_THRESHOLD = 500;
@@ -204,27 +253,9 @@
     </header>
 
     <div class="chat-message-body">
-      {#if isToolCall && toolPair}
-        <ToolCallGroup pair={toolPair} {expanded} ontoggle={toggleExpanded} />
-      {:else if isToolResult && formattedToolResult !== null}
-        <div
-          class="chat-message-tool-result"
-          data-error={isToolResultError || undefined}
-          data-action-required={isToolResultActionRequired || undefined}
-        >
-          {#if isToolResultError}
-            <div class="chat-message-tool-error" role="alert">
-              {formattedToolResult}
-            </div>
-          {:else if isToolResultActionRequired}
-            <div class="chat-message-tool-action" role="status">
-              {formattedToolResult}
-            </div>
-          {:else}
-            <ToolPayloadCode code={formattedToolResult} />
-          {/if}
-        </div>
-      {:else if isEditing}
+      {#if isEditing}
+        <!-- Edit mode replaces the body parts with a textarea, but attachments
+             stay visible (they were never inside the editable body). -->
         <div class="chat-message-edit">
           <!-- svelte-ignore a11y_autofocus -->
           <textarea
@@ -245,15 +276,25 @@
           </div>
         </div>
       {:else}
-        <MessageContent
-          content={textContent}
+        <!-- Replaces the historical role-branch body: every body render shape
+             (tool call, tool result, markdown text) flows through the cinder-
+             owned parts spine. The renderer keeps stable DOM identity across
+             streaming updates via per-part keys, so the markdown body never
+             remounts as its text grows. Image parts render below, as a sibling
+             of this body div, matching the historical structure. -->
+        <ChatMessagePartsRenderer
+          parts={bodyParts}
+          {messagePart}
           {expanded}
-          {streaming}
-          {overrideContent}
-          threshold={TRUNCATE_THRESHOLD}
+          ontoggle={toggleExpanded}
+          {onapprove}
+          {ondeny}
+          {reasoningExpanded}
+          {onreasoning}
+          {onsuggestionselect}
         />
 
-        {#if textContent.length > TRUNCATE_THRESHOLD}
+        {#if hasMarkdownBody && textContent.length > TRUNCATE_THRESHOLD}
           <button type="button" class="chat-message-expand" onclick={toggleExpanded}>
             {expanded ? 'Show less' : 'Show more'}
           </button>
@@ -261,8 +302,10 @@
       {/if}
     </div>
 
-    {#if hasImages}
-      <MessageAttachments images={imageParts} />
+    {#if imageParts.length > 0}
+      <!-- Images render through the grouped default path (the attachment grid
+           lays out by total count); they do not flow through `messagePart`. -->
+      <ChatMessagePartsRenderer parts={imageParts} />
     {/if}
 
     {#if isFailed && onretry}
@@ -536,17 +579,8 @@
     line-height: 1.6;
   }
 
-  .chat-message-tool-result {
-    inline-size: 100%;
-  }
-
-  .chat-message-tool-error {
-    padding: var(--cinder-space-3);
-    background: var(--cinder-color-danger-bg);
-    border-radius: var(--cinder-radius-md);
-    color: var(--cinder-color-danger-fg);
-    font-size: var(--cinder-text-sm);
-  }
+  /* Tool-result body styling moved to tool-result-part.svelte alongside its
+     markup (the parts spine now owns that body shape). */
 
   .chat-message-expand {
     display: inline-flex;