@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/chat/utilities/types.ts

@@ -2,10 +2,19 @@
  * 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.
@@ -21,3 +30,257 @@ 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/src/components/chat/utilities/utilities.ts

@@ -5,7 +5,123 @@
  * content for copy/export operations.
  */
 
-import type { Message, MultiModalContent } from '../conversation-model.ts';
+import type { Message, MultiModalContent, ToolResult } from '../conversation-model.ts';
+import type {
+  ChatMessagePart,
+  ImageMessagePart,
+  MessagePartDerivationContext,
+  StepInfo,
+  StepStatus,
+  ToolApprovalMessagePart,
+} from './types.ts';
+
+/** Namespaced metadata keys the overlay parts read (ignorable by plain rendering). */
+export const CINDER_REASONING_METADATA_KEY = 'cinder:reasoning';
+export const CINDER_STEPS_METADATA_KEY = 'cinder:steps';
+export const CINDER_SUGGESTIONS_METADATA_KEY = 'cinder:suggestions';
+
+const STEP_STATUSES: ReadonlySet<string> = new Set<StepStatus>([
+  'pending',
+  'running',
+  'done',
+  'error',
+]);
+
+/**
+ * Narrows an unknown value to a valid {@link StepInfo}. Uses `in`-operator
+ * narrowing (no `as` assertion) so each accessed field is type-safe.
+ */
+function isStepInfo(value: unknown): value is StepInfo {
+  if (value === null || typeof value !== 'object') return false;
+  if (!('title' in value) || !('content' in value) || !('status' in value)) return false;
+  return (
+    typeof value.title === 'string' &&
+    typeof value.content === 'string' &&
+    typeof value.status === 'string' &&
+    STEP_STATUSES.has(value.status)
+  );
+}
+
+/**
+ * Runs a per-message overlay callback, guarding a consumer throw (a buggy
+ * callback can never break the chat render). Returns the sentinel `undefined`
+ * for "no opinion — fall back to metadata", distinguished from a callback that
+ * returns a real (possibly empty) value meaning "this is authoritative".
+ */
+function runOverlayCallback<T>(
+  message: Message,
+  fromProp: ((message: Message) => T | undefined) | undefined,
+): { handled: boolean; value: T | undefined } {
+  if (fromProp === undefined) return { handled: false, value: undefined };
+  try {
+    const value = fromProp(message);
+    // `undefined` means "fall back to metadata"; any other return (incl. an
+    // empty string/array, which suppresses the overlay) is authoritative.
+    return value === undefined ? { handled: false, value: undefined } : { handled: true, value };
+  } catch {
+    // A throwing callback is treated as "no opinion" — fall back to metadata
+    // rather than letting the error escape and break the render.
+    return { handled: false, value: undefined };
+  }
+}
+
+/**
+ * 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 function resolveMessageReasoning(
+  message: Message,
+  fromProp?: (message: Message) => string | undefined,
+): string | undefined {
+  const fromCallback = runOverlayCallback(message, fromProp);
+  const candidate: unknown = fromCallback.handled
+    ? fromCallback.value
+    : message.metadata[CINDER_REASONING_METADATA_KEY];
+  return typeof candidate === 'string' && candidate.length > 0 ? candidate : 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 function resolveMessageSteps(
+  message: Message,
+  fromProp?: (message: Message) => StepInfo[] | undefined,
+): StepInfo[] | undefined {
+  const fromCallback = runOverlayCallback(message, fromProp);
+  const candidate: unknown = fromCallback.handled
+    ? fromCallback.value
+    : message.metadata[CINDER_STEPS_METADATA_KEY];
+  if (!Array.isArray(candidate)) return undefined;
+  const steps = candidate.filter(isStepInfo);
+  return steps.length > 0 ? steps : 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 function resolveMessageSuggestions(
+  message: Message,
+  fromProp?: (message: Message) => string[] | undefined,
+): string[] | undefined {
+  const fromCallback = runOverlayCallback(message, fromProp);
+  const candidate: unknown = fromCallback.handled
+    ? fromCallback.value
+    : message.metadata[CINDER_SUGGESTIONS_METADATA_KEY];
+  if (!Array.isArray(candidate)) return undefined;
+  const suggestions = candidate.filter((entry): entry is string => typeof entry === 'string');
+  return suggestions.length > 0 ? suggestions : undefined;
+}
 
 /**
  * Normalizes content to a multi-modal array.
@@ -74,6 +190,214 @@ export function getMessageText(message: Message): string {
     .join('\n');
 }
 
+/**
+ * Derives image render parts from a message's content array.
+ *
+ * One {@link ImageMessagePart} per image segment, keyed by the image's index in
+ * the original content array so identity is stable as a streaming text body
+ * grows alongside it. A string body has no images and yields an empty array.
+ */
+function deriveImageParts(message: Message): ImageMessagePart[] {
+  if (typeof message.content === 'string') return [];
+
+  const parts: ImageMessagePart[] = [];
+  message.content.forEach((segment, index) => {
+    if (segment.type === 'image') {
+      parts.push({
+        type: 'image',
+        key: `${message.id}:image:${index}`,
+        image: segment,
+      });
+    }
+  });
+  return parts;
+}
+
+/**
+ * Builds a {@link ToolApprovalMessagePart} from an `action_required` tool result.
+ *
+ * Shared by both the standalone `tool-result` branch and the paired `tool-call`
+ * branch of {@link deriveMessageParts} so the approval prompt renders for either
+ * transcript shape. The human-readable tool name resolves from the paired
+ * tool-call when available (else the call id); the approval state comes from the
+ * container's approved/denied id sets. Caller guarantees `result.action` exists.
+ */
+function deriveToolApprovalPart(
+  messageId: string,
+  result: ToolResult,
+  context: MessagePartDerivationContext,
+): ToolApprovalMessagePart {
+  const approved = context.approvedToolCallIds?.has(result.callId)
+    ? true
+    : context.deniedToolCallIds?.has(result.callId)
+      ? false
+      : undefined;
+  return {
+    type: 'tool-approval',
+    key: `${messageId}:tool-approval:${result.callId}`,
+    toolCallId: result.callId,
+    toolName: context.toolCallPair?.call.name ?? result.callId,
+    action: result.action!,
+    approved,
+  };
+}
+
+/**
+ * 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 function deriveMessageParts(
+  message: Message,
+  context: MessagePartDerivationContext = {},
+): ChatMessagePart[] {
+  // Images render below the body for every role (the historical attachment view
+  // was unconditional), so each branch appends them after its body part.
+  const imageParts = deriveImageParts(message);
+
+  // Tool-call body: emit a tool-call part only when the container resolved a
+  // pair for this message (mirrors the original `isToolCall && toolPair`
+  // guard). With no pair, fall through to the markdown body below — the same
+  // text rendering the original showed for an unpaired tool-call message.
+  //
+  // When that pair's result is `action_required` with an action, ALSO emit a
+  // tool-approval part after the call card. In the common paired transcript the
+  // standalone `tool-result` row is folded into this card (the container hides
+  // paired results), so without this the approval prompt would never render for
+  // the call-plus-result shape — only for a rare standalone action_required
+  // result. The card shows what is being called; the approval gates consent.
+  if (message.role === 'tool-call' && message.toolCall && context.toolCallPair) {
+    const result = context.toolCallPair.result;
+    const approvalPart =
+      result && result.outcome === 'action_required' && result.action
+        ? deriveToolApprovalPart(message.id, result, context)
+        : undefined;
+    return [
+      {
+        type: 'tool-call',
+        key: `${message.id}:tool-call:${message.toolCall.id}`,
+        pair: context.toolCallPair,
+      },
+      ...(approvalPart ? [approvalPart] : []),
+      ...imageParts,
+    ];
+  }
+
+  // Tool-result body: when the outcome is `action_required` and an action is
+  // present, emit a `tool-approval` part instead of the plain `tool-result`
+  // part. The approval part carries the action, the tool call id (used to
+  // look up the tool name from the paired tool-call), and the resolved
+  // approval state from the container's approved/denied id sets. A plain
+  // `success` or `error` result falls through to the standard `tool-result`
+  // part, so this branch is a strict superset that adds zero visual change
+  // for non-approval results.
+  if (message.role === 'tool-result' && message.toolResult) {
+    const result = message.toolResult;
+    if (result.outcome === 'action_required' && result.action) {
+      return [deriveToolApprovalPart(message.id, result, context), ...imageParts];
+    }
+    return [
+      {
+        type: 'tool-result',
+        key: `${message.id}:tool-result:${result.callId}`,
+        result,
+      },
+      ...imageParts,
+    ];
+  }
+
+  // Default body: markdown text (streaming override resolved in) followed by
+  // images. `body` is a representation-independent key, so a streaming body
+  // never remounts as its text grows, and an attachment landing after it keeps
+  // its own index-based key.
+  //
+  // C4: Composition order is steps → reasoning → markdown → images.
+  // Steps surface the plan, reasoning surfaces extended thinking, markdown is
+  // the final answer. When neither is present the branch is identical to today.
+  const content = context.overrideContent ?? getMessageText(message);
+
+  const bodyParts: ChatMessagePart[] = [];
+
+  // C4: Step parts — one per entry in context.steps[], in order.
+  if (context.steps && context.steps.length > 0) {
+    for (let index = 0; index < context.steps.length; index++) {
+      const step = context.steps[index]!;
+      bodyParts.push({
+        type: 'step',
+        key: `${message.id}:step:${index}`,
+        index,
+        title: step.title,
+        content: step.content,
+        status: step.status,
+      });
+    }
+  }
+
+  // C4: Reasoning part — emitted before the markdown body when present.
+  if (context.reasoning && context.reasoning.length > 0) {
+    bodyParts.push({
+      type: 'reasoning',
+      key: `${message.id}:reasoning`,
+      content: context.reasoning,
+      streaming: context.streaming ?? false,
+    });
+  }
+
+  bodyParts.push({
+    type: 'markdown',
+    key: `${message.id}:body`,
+    content,
+    streaming: context.streaming ?? false,
+    expanded: context.expanded ?? true,
+  });
+
+  // C5: Suggestion parts — one per entry in context.suggestions[], after the
+  // markdown body but before images. An empty or absent array adds nothing,
+  // keeping the plain-transcript path identical to before.
+  if (context.suggestions && context.suggestions.length > 0) {
+    for (let index = 0; index < context.suggestions.length; index++) {
+      const label = context.suggestions[index]!;
+      bodyParts.push({
+        type: 'suggestion',
+        key: `${message.id}:suggestion:${index}`,
+        index,
+        label,
+      });
+    }
+  }
+
+  return [...bodyParts, ...imageParts];
+}
+
 /**
  * Gets the role label for a message.
  * Maps internal role values to human-readable labels.

package/src/components/chat-conversation-header/README.md

@@ -0,0 +1,40 @@
+# ChatConversationHeader
+
+Header primitive for the active Chat conversation, composed as a sibling above Chat rather than inside it.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import ChatConversationHeader from '@lostgradient/cinder/chat-conversation-header';
+</script>
+
+<ChatConversationHeader conversation={activeConversation} />
+```
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                | Type              | Required | Default | Description                                                                                                                                       |
+| ------------------- | ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`             | `string`          | no       | —       | Additional class name merged with `.cinder-chat-conversation-header`.                                                                             |
+| `headingLevel`      | `2` \| `3` \| `4` | no       | —       | Heading level for the conversation title. Default `2`.                                                                                            |
+| `showExportActions` | `boolean`         | no       | —       | Whether to render the built-in conversation export actions. Default `true`.                                                                       |
+| `actions`           | `(opaque)`        | no       | —       | Additional action controls rendered after the built-in export actions. Not expressible in JSON Schema; see the component types for the signature. |
+| `conversation`      | `(opaque)`        | yes      | —       | Active compatible conversation snapshot. Not expressible in JSON Schema; see the component types for the signature.                               |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+<!-- generated:subcomponents:end -->