@lostgradient/cinder 0.2.0 → 0.4.0

package/dist/components/chat/input/chat-input.svelte.d.ts

@@ -10,12 +10,14 @@ export type ChatInputProps = Omit<HTMLFormAttributes, 'onsubmit' | 'class'> & {
     value?: string;
     /** Placeholder text */
     placeholder?: string;
+    /** Accessible label passed to the inner message editor */
+    composerLabel?: string;
     /** Whether the input is disabled */
     disabled?: boolean;
     /** Whether a submission is in progress */
     sending?: boolean;
     /** Error message to display */
-    error?: string | undefined;
+    error?: string;
     /** Additional CSS class */
     class?: string;
     /** Form action URL (enables form action mode) */

package/dist/components/chat/message/chat-message-parts-renderer.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type ChatMessagePartsRendererProps } from './chat-message-parts.ts';
+declare const ChatMessagePartsRenderer: import("svelte").Component<ChatMessagePartsRendererProps, {}, "">;
+type ChatMessagePartsRenderer = ReturnType<typeof ChatMessagePartsRenderer>;
+export default ChatMessagePartsRenderer;

package/dist/components/chat/message/chat-message-parts.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 declare function toRenderUnits(parts: ChatMessagePart[]): RenderUnit[];

package/dist/components/chat/message/chat-message.svelte.d.ts

@@ -1,6 +1,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.
  * Maps message roles to human-readable labels.
@@ -21,6 +23,12 @@ export type ChatMessageProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
     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 */
@@ -36,6 +44,35 @@ export type ChatMessageProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
         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;
 };
 declare const ChatMessage: import("svelte").Component<ChatMessageProps, {}, "expanded">;
 type ChatMessage = ReturnType<typeof ChatMessage>;

package/dist/components/chat/message/chat-read-receipt.svelte.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-message read receipt badge for the Chat component.
+ *
+ * Rendered inside the `messageStatus` snippet slot of the user's message bubble.
+ * Shows delivery/read state with BOTH an icon AND a text label (never color-only).
+ *
+ * Three states:
+ *   - `sent`      — single check icon + "Sent" label (text-muted)
+ *   - `delivered` — double-check icon + "Delivered" label (text-muted)
+ *   - `read`      — double-check icon + "Read" label (accent color)
+ *
+ * Accessibility:
+ *   - The wrapper has aria-label="Sent" / "Delivered" / "Read by …" (full text).
+ *   - Icon is aria-hidden="true".
+ *   - Visible text label is exposed in the accessibility tree (no aria-hidden).
+ *   - data-cinder-receipt-status=sent|delivered|read on the wrapper element.
+ *
+ * NOT shown on non-user messages — the caller gates this based on message.role.
+ */
+import type { ReadReceipt } from '../chat.types.ts';
+export type ChatReadReceiptProps = {
+    /** The receipt to render. */
+    receipt: ReadReceipt;
+};
+declare const ChatReadReceipt: import("svelte").Component<ChatReadReceiptProps, {}, "">;
+type ChatReadReceipt = ReturnType<typeof ChatReadReceipt>;
+export default ChatReadReceipt;

package/dist/components/chat/message/parts/image-part.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { ImageMessagePart } from '../../utilities/types.ts';
+export type ImagePartProps = {
+    /**
+     * The contiguous run of image parts to render as one attachment group.
+     *
+     * Images are grouped rather than rendered one-per-component because the
+     * attachment grid lays out by total count (`data-count`): one image is
+     * centered, two sit side by side, three or more flow in an auto-fit grid.
+     * Splitting them into independent single-image components would each render
+     * with count 1 and break that layout — so the renderer collects adjacent
+     * image parts and hands the whole run here.
+     */
+    parts: ImageMessagePart[];
+};
+declare const ImagePart: import("svelte").Component<ImagePartProps, {}, "">;
+type ImagePart = ReturnType<typeof ImagePart>;
+export default ImagePart;

package/dist/components/chat/message/parts/markdown-part.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { MarkdownMessagePart } from '../../utilities/types.ts';
+export type MarkdownPartProps = {
+    /** The markdown render part to display. */
+    part: MarkdownMessagePart;
+};
+declare const MarkdownPart: import("svelte").Component<MarkdownPartProps, {}, "">;
+type MarkdownPart = ReturnType<typeof MarkdownPart>;
+export default MarkdownPart;

package/dist/components/chat/message/parts/reasoning-part.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { ReasoningMessagePart } from '../../utilities/types.ts';
+export type ReasoningPartProps = {
+    /** The reasoning render part to display. */
+    part: ReasoningMessagePart;
+    /** Whether this reasoning block is expanded. Controlled by the parent (use-chat-reasoning-state). */
+    expanded?: boolean;
+    /** Called when the disclosure toggle is activated. */
+    ontoggle?: (() => void) | undefined;
+};
+declare const ReasoningPart: import("svelte").Component<ReasoningPartProps, {}, "">;
+type ReasoningPart = ReturnType<typeof ReasoningPart>;
+export default ReasoningPart;

package/dist/components/chat/message/parts/step-part.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { StepMessagePart } from '../../utilities/types.ts';
+export type StepPartProps = {
+    /** The step render part to display. */
+    part: StepMessagePart;
+};
+declare const StepPart: import("svelte").Component<StepPartProps, {}, "">;
+type StepPart = ReturnType<typeof StepPart>;
+export default StepPart;

package/dist/components/chat/message/parts/suggestion-part.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { SuggestionMessagePart } from '../../utilities/types.ts';
+export type SuggestionPartProps = {
+    /** The suggestion render part to display. */
+    part: SuggestionMessagePart;
+    /** Called when the user selects this suggestion chip. */
+    onsuggestionselect?: ((label: string) => void) | undefined;
+    /**
+     * Roving tabindex for APG toolbar keyboard navigation. The toolbar parent
+     * sets `tabindex=0` on the active chip and `tabindex=-1` on all others so
+     * Tab enters the toolbar at the active chip, then arrow keys move focus
+     * within it. Defaults to `0` (all chips tabbable) when the toolbar does not
+     * manage roving tabindex.
+     */
+    tabindex?: 0 | -1;
+};
+declare const SuggestionPart: import("svelte").Component<SuggestionPartProps, {}, "">;
+type SuggestionPart = ReturnType<typeof SuggestionPart>;
+export default SuggestionPart;

package/dist/components/chat/message/parts/tool-approval-part.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { ToolApprovalMessagePart } from '../../utilities/types.ts';
+export type ToolApprovalPartProps = {
+    /** The tool-approval render part. */
+    part: ToolApprovalMessagePart;
+    /** Called when the user approves the action. */
+    onapprove?: ((toolCallId: string) => void) | undefined;
+    /** Called when the user denies the action. */
+    ondeny?: ((toolCallId: string) => void) | undefined;
+};
+declare const ToolApprovalPart: import("svelte").Component<ToolApprovalPartProps, {}, "">;
+type ToolApprovalPart = ReturnType<typeof ToolApprovalPart>;
+export default ToolApprovalPart;

package/dist/components/chat/message/parts/tool-call-part.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { ToolCallMessagePart } from '../../utilities/types.ts';
+export type ToolCallPartProps = {
+    /** The tool-call render part (call + optional resolved result). */
+    part: ToolCallMessagePart;
+    /** Whether the tool-call card is expanded. Owned by the message. */
+    expanded?: boolean;
+    /** Called when the card's disclosure toggle is activated. */
+    ontoggle?: (() => void) | undefined;
+};
+declare const ToolCallPart: import("svelte").Component<ToolCallPartProps, {}, "">;
+type ToolCallPart = ReturnType<typeof ToolCallPart>;
+export default ToolCallPart;

package/dist/components/chat/message/parts/tool-result-part.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { ToolResultMessagePart } from '../../utilities/types.ts';
+export type ToolResultPartProps = {
+    /** The tool-result render part (the structured outcome). */
+    part: ToolResultMessagePart;
+};
+declare const ToolResultPart: import("svelte").Component<ToolResultPartProps, {}, "">;
+type ToolResultPart = ReturnType<typeof ToolResultPart>;
+export default ToolResultPart;

package/dist/components/chat/utilities/index.d.ts

@@ -5,5 +5,5 @@
  * and content/markdown utilities, all built on the vendored conversation model.
  */
 export { getMessages, pairToolCallsWithResults } from './conversation';
-export { type ChatExportOptions, type DeliveryStatus } from './types';
-export { formatMessageAsMarkdown, getMessageParts, getMessageRoleLabel, getMessageText, messagesToMarkdown, toMultiModalArray, } from './utilities';
+export { type ChatExportOptions, type ChatMessagePart, type DeliveryStatus, type ImageMessagePart, type MarkdownMessagePart, type MessagePartDerivationContext, type ToolCallMessagePart, type ToolResultMessagePart, } from './types';
+export { CINDER_REASONING_METADATA_KEY, CINDER_STEPS_METADATA_KEY, CINDER_SUGGESTIONS_METADATA_KEY, deriveMessageParts, formatMessageAsMarkdown, getMessageParts, getMessageRoleLabel, getMessageText, messagesToMarkdown, resolveMessageReasoning, resolveMessageSteps, resolveMessageSuggestions, toMultiModalArray, } from './utilities';

package/dist/components/chat/utilities/types.d.ts

@@ -2,9 +2,10 @@
  * Chat data model types built on top of the vendored conversation model.
  *
  * Core types live in `../conversation-model.ts`; this module provides only
- * project-specific extensions.
+ * project-specific extensions, including the cinder-OWNED render-part layer
+ * (`ChatMessagePart`) that sits on top of the structural `Message` mirror.
  */
-import type { ToMarkdownOptions } from '../conversation-model.ts';
+import type { Message, MultiModalContent, ToMarkdownOptions, ToolAction, ToolCall, ToolCallPair, ToolResult } from '../conversation-model.ts';
 /**
  * Delivery status for messages in the UI.
  * This is transient state stored in message metadata with a `_` prefix
@@ -18,3 +19,242 @@ export type DeliveryStatus = 'draft' | 'sending' | 'sent' | 'failed';
  * chat-specific name for the public `@lostgradient/cinder/chat` surface.
  */
 export type ChatExportOptions = ToMarkdownOptions;
+/**
+ * A markdown render part — the effective body text of a message.
+ *
+ * `content` is always the full effective text (streaming `overrideContent` is
+ * resolved into it by `deriveMessageParts`, so the part is render-ready). The
+ * streaming/expanded flags are presentation hints the renderer forwards to the
+ * markdown sub-component; they never become authoritative transcript data.
+ */
+export type MarkdownMessagePart = {
+    type: 'markdown';
+    /** Stable identity for the keyed `{#each}` over parts. */
+    key: string;
+    content: string;
+    /** Whether this part is being streamed (drives the cursor/tail affordance). */
+    streaming: boolean;
+    /** Whether long content is fully expanded (drives truncation). */
+    expanded: boolean;
+};
+/**
+ * A tool-call render part — one tool invocation paired with its result, if one
+ * exists yet.
+ *
+ * `pair` is the resolved {@link ToolCallPair} threaded in through
+ * `MessagePartDerivationContext`. When no result has arrived (the pairing is
+ * still pending), `pair.result` is `undefined` — the part is still emitted so a
+ * pending tool call renders rather than silently falling back to text.
+ */
+export type ToolCallMessagePart = {
+    type: 'tool-call';
+    /** Stable identity, derived from the message id + the tool call id. */
+    key: string;
+    pair: ToolCallPair;
+};
+/**
+ * A tool-result render part — the outcome of a tool call rendered on its own.
+ *
+ * Used for tool-result messages that are NOT folded into a paired tool-call
+ * card (the container hides paired results). Carries the structured
+ * {@link ToolResult} so the renderer can branch on `outcome` for error /
+ * action-required / success styling, exactly as the historical role-branch did.
+ */
+export type ToolResultMessagePart = {
+    type: 'tool-result';
+    /** Stable identity, derived from the message id + the result's call id. */
+    key: string;
+    result: ToolResult;
+};
+/**
+ * An image render part — a single image segment of multi-modal message content.
+ *
+ * Carries the original {@link MultiModalContent} image so the renderer can hand
+ * it to the existing attachment view (url, alt text, lightbox).
+ */
+export type ImageMessagePart = {
+    type: 'image';
+    /** Stable identity, derived from the message id + the image's content index. */
+    key: string;
+    image: Extract<MultiModalContent, {
+        type: 'image';
+    }>;
+};
+/**
+ * A tool-approval render part — emitted in place of a `tool-result` part when
+ * the result's `outcome === 'action_required'` and an `action` is present.
+ *
+ * Renders a prompt asking the user to approve or deny a pending tool action.
+ * `approved` is a tri-state: `true` (approved), `false` (denied), or `undefined`
+ * (still pending). The `approved` field is derived from the container's
+ * `approvedToolCallIds`/`deniedToolCallIds` sets — it is never written back to
+ * the transcript.
+ */
+export type ToolApprovalMessagePart = {
+    type: 'tool-approval';
+    /** Stable identity, derived from the message id + the tool result's call id. */
+    key: string;
+    toolCallId: string;
+    toolName: string;
+    action: ToolAction;
+    /** `true` = approved, `false` = denied, `undefined` = pending. */
+    approved: boolean | undefined;
+};
+/**
+ * A reasoning render part — an extended thinking block shown before the
+ * assistant's final answer.
+ *
+ * Renders as a collapsible disclosure with a left-accent border. While
+ * streaming, the toggle is disabled and a pulsing dot is shown; the expanded
+ * region uses `aria-live="off"` during streaming to avoid token-by-token
+ * announcements, and one polite "Reasoning complete." fires when streaming ends.
+ *
+ * Source: `message.metadata['cinder:reasoning']` (a string) or the explicit
+ * `messageReasoning` prop on Chat. Never a required transcript field.
+ */
+export type ReasoningMessagePart = {
+    type: 'reasoning';
+    /** Stable identity, derived from the message id. */
+    key: string;
+    content: string;
+    /** Whether this reasoning block is currently streaming. */
+    streaming: boolean;
+};
+/**
+ * Step status for a single step in a plan/step list.
+ */
+export type StepStatus = 'pending' | 'running' | 'done' | 'error';
+/**
+ * A step render part — one entry in an ordered plan/step list shown before
+ * the final answer.
+ *
+ * Renders as a vertical stepper `<ol>`/`<li>`. Status is communicated via
+ * both an aria-hidden icon and a visually-hidden text suffix so it is not
+ * color-only. `aria-current="step"` is set on the active (running) step.
+ *
+ * Source: `message.metadata['cinder:steps']` (an array of `{title, content, status}`)
+ * or the explicit `messageSteps` prop on Chat. Never a required transcript field.
+ */
+export type StepMessagePart = {
+    type: 'step';
+    /** Stable identity, derived from the message id + the step index. */
+    key: string;
+    index: number;
+    title: string;
+    content: string;
+    status: StepStatus;
+};
+/**
+ * A suggestion render part — a single suggested follow-up reply chip shown
+ * after the assistant's final answer.
+ *
+ * Renders as a button chip inside a `role="toolbar"` container. Selecting a
+ * chip calls `onselect(label)`, clears the suggestion set from the DOM, and
+ * moves focus to the composer input. The suggestion set is derived from
+ * `message.metadata['cinder:suggestions']` (a JSONValue array of strings) or
+ * the explicit `messageSuggestions` prop on Chat. It is UI-only and never
+ * written back to the transcript.
+ */
+export type SuggestionMessagePart = {
+    type: 'suggestion';
+    /** Stable identity, derived from the message id + the suggestion index. */
+    key: string;
+    /** Zero-based position of this suggestion in the list. */
+    index: number;
+    /** The label text displayed on the chip and passed to onselect. */
+    label: string;
+};
+/**
+ * The cinder-owned discriminated union of renderable message parts.
+ *
+ * This is a UI layer derived from the compatible {@link Message} shape — it is
+ * never written back to the transcript. The union includes `markdown`,
+ * `tool-call`, `tool-result`, `image`, `tool-approval`, `reasoning`, `step`,
+ * and `suggestion`. Each widening also adds a renderer branch so the static
+ * part switch stays exhaustive (the renderer's `{:else}` sentinel + the
+ * `never` narrowing there force the new branch to be added).
+ */
+export type ChatMessagePart = MarkdownMessagePart | ToolCallMessagePart | ToolResultMessagePart | ImageMessagePart | ToolApprovalMessagePart | ReasoningMessagePart | StepMessagePart | SuggestionMessagePart;
+/**
+ * Per-message context threaded into `deriveMessageParts`.
+ *
+ * Keeps the bridge pure while informing it of conversation-global facts it
+ * cannot compute from a single {@link Message}: the resolved tool-call pairing
+ * (computed once at the container from the ordered transcript) and the live
+ * streaming override buffer. Passing the already-resolved pair — rather than the
+ * whole pairs-by-id map — avoids both a re-pairing pass inside derive and the
+ * reactive-staleness trap of mutating a shared map in place.
+ */
+export type MessagePartDerivationContext = {
+    /**
+     * The resolved tool-call pair for this message's `toolCall`, if the container
+     * found one. A tool-call message renders as a card only when this is present
+     * (mirroring the original `isToolCall && toolPair` guard); with no pair, derive
+     * falls through to the text body. A still-pending call is represented by a pair
+     * whose `result` is `undefined`, not by an absent pair.
+     */
+    toolCallPair?: ToolCallPair | undefined;
+    /**
+     * Live streaming buffer for this message. When present, it replaces the
+     * message's text body so the markdown part is render-ready (no override
+     * plumbing leaks into the part component).
+     */
+    overrideContent?: string | undefined;
+    /** Whether this message is currently streaming (drives the markdown part's cursor/tail). */
+    streaming?: boolean | undefined;
+    /** Whether long content is expanded (drives the markdown part's truncation). */
+    expanded?: boolean | undefined;
+    /**
+     * The set of tool-call IDs the consumer has already approved. Used to
+     * derive the `approved: true` state on a `tool-approval` part without mutating
+     * the transcript. Tool calls NOT in either set render as pending (`undefined`).
+     */
+    approvedToolCallIds?: ReadonlySet<string> | undefined;
+    /**
+     * The set of tool-call IDs the consumer has denied. Used to derive the
+     * `approved: false` state on a `tool-approval` part without mutating the
+     * transcript.
+     */
+    deniedToolCallIds?: ReadonlySet<string> | undefined;
+    /**
+     * Pre-body extended thinking block. When present and non-empty, a
+     * `reasoning` part is emitted before the markdown body part.
+     *
+     * Source: `message.metadata['cinder:reasoning']` (a JSONValue string) or the
+     * explicit `messageReasoning` per-message prop on Chat. Never a required
+     * transcript field — absent from a plain transcript, this is `undefined` and
+     * zero visual change results.
+     */
+    reasoning?: string | undefined;
+    /**
+     * Ordered plan/step list. When present and non-empty, one `step` part
+     * per entry is emitted before the reasoning and markdown body parts.
+     *
+     * Source: `message.metadata['cinder:steps']` (a JSONValue array) or the
+     * explicit `messageSteps` per-message prop on Chat. Never a required
+     * transcript field.
+     */
+    steps?: ReadonlyArray<StepInfo> | undefined;
+    /**
+     * Suggested follow-up labels. When present and non-empty, one
+     * `suggestion` part per entry is emitted after the markdown body part (and
+     * before any image parts).
+     *
+     * Source: `message.metadata['cinder:suggestions']` (a JSONValue array of
+     * strings) or the explicit `messageSuggestions` per-message prop on Chat.
+     * Never a required transcript field — absent from a plain transcript, this
+     * is `undefined` and zero visual change results.
+     */
+    suggestions?: ReadonlyArray<string> | undefined;
+};
+/** Re-export the part-relevant model types so part consumers import from one place. */
+export type { Message, MultiModalContent, ToolAction, ToolCall, ToolCallPair, ToolResult };
+/**
+ * Shape of a single step entry as accepted by ChatProps.messageSteps and
+ * stored in message.metadata['cinder:steps'].
+ */
+export type StepInfo = {
+    title: string;
+    content: string;
+    status: StepStatus;
+};

package/dist/components/chat/utilities/utilities.d.ts

@@ -5,6 +5,35 @@
  * content for copy/export operations.
  */
 import type { Message, MultiModalContent } from '../conversation-model.ts';
+import type { ChatMessagePart, MessagePartDerivationContext, StepInfo } from './types.ts';
+/** Namespaced metadata keys the overlay parts read (ignorable by plain rendering). */
+export declare const CINDER_REASONING_METADATA_KEY = "cinder:reasoning";
+export declare const CINDER_STEPS_METADATA_KEY = "cinder:steps";
+export declare const CINDER_SUGGESTIONS_METADATA_KEY = "cinder:suggestions";
+/**
+ * Resolves the reasoning overlay for a message. An explicit per-message callback
+ * is consulted first; when it returns `undefined` (or throws) the resolution
+ * falls back to `cinder:reasoning` namespaced metadata. An empty string from the
+ * callback is authoritative and suppresses the overlay. Returns `undefined` when
+ * no reasoning applies — a plain transcript renders the feature absent.
+ */
+export declare function resolveMessageReasoning(message: Message, fromProp?: (message: Message) => string | undefined): string | undefined;
+/**
+ * Resolves the step overlay for a message. An explicit per-message callback is
+ * consulted first; when it returns `undefined` (or throws) the resolution falls
+ * back to `cinder:steps` namespaced metadata. An empty array from the callback is
+ * authoritative and suppresses the overlay. Invalid entries are dropped. Returns
+ * `undefined` when no valid steps apply.
+ */
+export declare function resolveMessageSteps(message: Message, fromProp?: (message: Message) => StepInfo[] | undefined): StepInfo[] | undefined;
+/**
+ * Resolves the suggestion overlay for a message. An explicit per-message callback
+ * is consulted first; when it returns `undefined` (or throws) the resolution
+ * falls back to `cinder:suggestions` namespaced metadata. An empty array from the
+ * callback is authoritative and suppresses the overlay. Non-string entries are
+ * dropped. Returns `undefined` when no valid suggestions apply.
+ */
+export declare function resolveMessageSuggestions(message: Message, fromProp?: (message: Message) => string[] | undefined): string[] | undefined;
 /**
  * Normalizes content to a multi-modal array.
  *
@@ -43,6 +72,41 @@ export declare function getMessageParts(message: Message): ReadonlyArray<MultiMo
  * ```
  */
 export declare function getMessageText(message: Message): string;
+/**
+ * Derives the ordered render parts for a single message.
+ *
+ * This is the cinder-OWNED bridge from the compatible {@link Message} mirror to
+ * the {@link ChatMessagePart} render layer. It is pure: every part is computed
+ * from the message plus the per-message {@link MessagePartDerivationContext}
+ * (the resolved tool-call pair and the live streaming buffer), never from
+ * conversation-global state or any runtime library. UI-only parts are never
+ * written back to the transcript.
+ *
+ * Body derivation mirrors the historical role-branch rendering exactly:
+ * - `tool-call` messages emit a single `tool-call` part ONLY when the container
+ *   resolved a pair for them (`context.toolCallPair`). This matches the original
+ *   `isToolCall && toolPair` guard: the real container always supplies a pair
+ *   for a tool-call message (with `result: undefined` while the result is still
+ *   pending), so a pending call still renders as a card; a standalone
+ *   `<ChatMessage>` given no pair falls through to the text body, exactly as
+ *   before.
+ * - `tool-result` messages with a `toolResult` emit a single `tool-result`
+ *   part (the container hides results already folded into a paired card).
+ * - every other role emits a `markdown` body part carrying the effective text
+ *   (streaming `overrideContent` resolved in).
+ *
+ * Every branch then appends one `image` part per image segment in the content,
+ * so attachments render below the body for all roles — exactly as the historical
+ * unconditional `MessageAttachments` did.
+ *
+ * A `tool-call` message with no resolved pair, or a `tool-result` message with
+ * no `toolResult`, falls back to the markdown path rather than producing nothing.
+ *
+ * @param message - The message to derive parts for
+ * @param context - Per-message pairing + streaming context (optional)
+ * @returns The ordered render parts (stable `key` on each for keyed iteration)
+ */
+export declare function deriveMessageParts(message: Message, context?: MessagePartDerivationContext): ChatMessagePart[];
 /**
  * Gets the role label for a message.
  * Maps internal role values to human-readable labels.