@lostgradient/cinder 0.6.0 → 0.7.0

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

@@ -0,0 +1,507 @@
+/**
+ * Utility functions for chat message operations.
+ *
+ * These helpers work with the published {@link Message} type to extract
+ * content for copy/export operations.
+ */
+
+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. That suppression is
+ * returned as `''` so downstream part derivation can also skip transcript-native
+ * `thinking` content. Returns `undefined` when no reasoning source applies.
+ */
+export function resolveMessageReasoning(
+  message: Message,
+  fromProp?: (message: Message) => string | undefined,
+): string | undefined {
+  const fromCallback = runOverlayCallback(message, fromProp);
+  if (fromCallback.handled && fromCallback.value === '') return '';
+  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.
+ *
+ * Strings are wrapped in a single text part; a single content item is wrapped
+ * in an array; an array is returned as-is. The `ReadonlyArray` in/out signature
+ * matches {@link Message.content} so callers pass `message.content` with zero casts.
+ *
+ * @param input - String, single content item, or readonly content array
+ * @returns The content as a readonly multi-modal array
+ */
+export function toMultiModalArray(
+  input: string | MultiModalContent | ReadonlyArray<MultiModalContent>,
+): ReadonlyArray<MultiModalContent> {
+  if (typeof input === 'string') return [{ type: 'text', text: input }];
+  // A single MultiModalContent has a `type` discriminant; an array does not.
+  // (`Array.isArray` doesn't narrow a `ReadonlyArray` out of the union, so key
+  // off the discriminant instead — no cast needed.)
+  return 'type' in input ? [input] : input;
+}
+
+function formatJSONValue(value: unknown): string {
+  return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+}
+
+function getServerContentText(part: MultiModalContent): string | undefined {
+  switch (part.type) {
+    case 'text':
+      return part.text;
+    case 'server_tool_use':
+      return [`Server tool use: ${part.name}`, formatJSONValue(part.input)].join('\n');
+    case 'web_search_tool_result':
+      return [`Web search result: ${part.tool_use_id}`, formatJSONValue(part.content)].join('\n');
+    case 'code_execution_tool_result':
+    case 'bash_code_execution_tool_result':
+    case 'text_editor_code_execution_tool_result':
+    case 'web_fetch_tool_result':
+      return [`Server tool result: ${part.tool_use_id}`, formatJSONValue(part.content)].join('\n');
+    case 'container_upload':
+      return `Container upload: ${part.file_id}`;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Extracts all content parts from a message as a multi-modal array.
+ * `content` is `string | ReadonlyArray<MultiModalContent>` and never nullish.
+ * A string yields a single text part (an empty string yields one empty text
+ * part); an array is returned as-is, so an empty array yields an empty array.
+ *
+ * @param message - The message to extract parts from
+ * @returns A readonly array of content parts
+ */
+export function getMessageParts(message: Message): ReadonlyArray<MultiModalContent> {
+  // `content` is `string | ReadonlyArray<MultiModalContent>` (never nullish);
+  // toMultiModalArray handles the empty-string and empty-array cases.
+  return toMultiModalArray(message.content);
+}
+
+/**
+ * Extracts all text content from a message, joined by newlines.
+ * Non-text parts (images, etc.) are excluded from the result.
+ *
+ * This is useful for copying a message's text content to clipboard
+ * without including non-text attachments.
+ *
+ * @param message - The message to extract text from
+ * @returns The concatenated text content
+ *
+ * @example
+ * ```typescript
+ * const text = getMessageText(message);
+ * await copyToClipboard(text);
+ * ```
+ */
+export function getMessageText(message: Message): string {
+  return getMessageParts(message)
+    .map(getServerContentText)
+    .filter((text): text is string => typeof text === 'string' && text.length > 0)
+    .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;
+}
+
+function deriveReasoningContent(
+  message: Message,
+  explicitReasoning: string | undefined,
+): string | undefined {
+  if (explicitReasoning === '') return undefined;
+  const reasoningSegments =
+    explicitReasoning && explicitReasoning.length > 0 ? [explicitReasoning] : [];
+  if (typeof message.content !== 'string') {
+    let hasRedactedThinking = false;
+    for (const segment of message.content) {
+      if (segment.type === 'thinking' && segment.thinking.length > 0) {
+        reasoningSegments.push(segment.thinking);
+      }
+      if (segment.type === 'redacted_thinking') {
+        hasRedactedThinking = true;
+      }
+    }
+    if (hasRedactedThinking) {
+      reasoningSegments.push(
+        'Redacted reasoning is preserved in this transcript but cannot be displayed.',
+      );
+    }
+  }
+
+  return reasoningSegments.length > 0 ? reasoningSegments.join('\n\n') : undefined;
+}
+
+/**
+ * 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.
+  const reasoningContent = deriveReasoningContent(message, context.reasoning);
+  if (reasoningContent) {
+    bodyParts.push({
+      type: 'reasoning',
+      key: `${message.id}:reasoning`,
+      content: reasoningContent,
+      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.
+ *
+ * @param message - The message to get the role label for
+ * @returns A human-readable role label
+ */
+export function getMessageRoleLabel(message: Message): string {
+  const labels: Record<Message['role'], string> = {
+    user: 'User',
+    assistant: 'Assistant',
+    system: 'System',
+    developer: 'Developer',
+    'tool-call': 'Tool Call',
+    'tool-result': 'Tool Result',
+    snapshot: 'Snapshot',
+  };
+  return labels[message.role] ?? message.role;
+}
+
+/**
+ * Formats a single message as Markdown for copy operations.
+ *
+ * Currently returns just the text content without role labels,
+ * since the UI context makes the source obvious. The separate function
+ * exists for API clarity and future extensibility (e.g., adding code
+ * fences for tool results).
+ *
+ * @param message - The message to format
+ * @returns Markdown-formatted message content
+ */
+export function formatMessageAsMarkdown(message: Message): string {
+  return getMessageText(message);
+}
+
+/**
+ * Formats a message with role label for conversation export.
+ *
+ * @param message - The message to format
+ * @returns Markdown-formatted message with role header
+ */
+function formatMessageWithRole(message: Message): string {
+  const roleLabel = getMessageRoleLabel(message);
+  const text = getMessageText(message);
+  return `**${roleLabel}:**\n\n${text}`;
+}
+
+/**
+ * Converts a list of messages to Markdown format.
+ *
+ * This is a browser-compatible markdown serialization for chat transcripts,
+ * avoiding the Node.js APIs (createRequire) used by server-side exporters.
+ *
+ * @param messages - The messages to convert
+ * @returns Markdown-formatted conversation
+ */
+export function messagesToMarkdown(messages: Message[]): string {
+  return messages
+    .filter((msg) => msg.role !== 'system' && msg.role !== 'developer')
+    .map(formatMessageWithRole)
+    .join('\n\n---\n\n');
+}

package/src/components/chat-conversation-header/chat-conversation-header.schema.ts

@@ -0,0 +1,38 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    headingLevel: {
+      enum: [2, 3, 4],
+      description: 'Heading level for the conversation title. Default `2`.',
+    },
+    showExportActions: {
+      type: 'boolean',
+      description: 'Whether to render the built-in conversation export actions. Default `true`.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class name merged with `.cinder-chat-conversation-header`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'actions',
+        reason: 'function-or-snippet',
+        description: 'Additional action controls rendered after the built-in export actions.',
+      },
+      {
+        name: 'conversation',
+        reason: 'unknown-shape',
+        required: true,
+        description: 'Active compatible conversation snapshot.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/chat-conversation-header/chat-conversation-header.svelte

@@ -0,0 +1,49 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import ConversationExportActions from '../chat/export/conversation-export-actions.svelte';
+import { deriveConversationSummary } from '../chat-conversation-list/conversation-summary.ts';
+let { conversation, headingLevel = 2, showExportActions = true, class: className, actions, ...rest } = $props();
+const summary = $derived(deriveConversationSummary(conversation));
+const headingTag = $derived(`h${headingLevel}`);
+const participantLabel = $derived(summary.participantNames.length === 0
+    ? undefined
+    : summary.participantNames.length <= 2
+        ? summary.participantNames.join(', ')
+        : `${summary.participantNames.slice(0, 2).join(', ')} +${summary.participantNames.length - 2}`);
+const fullParticipantLabel = $derived(summary.participantNames.join(', '));
+</script>
+
+<header class={classNames('cinder-chat-conversation-header', className)} {...rest}>
+  <div class="cinder-chat-conversation-header__main">
+    <svelte:element this={headingTag} class="cinder-chat-conversation-header__title">
+      {summary.title}
+    </svelte:element>
+    <p class="cinder-chat-conversation-header__meta">
+      {summary.messageCount}
+      {summary.messageCount === 1 ? 'message' : 'messages'}
+      <span aria-hidden="true"> · </span>
+      <span class="cinder-chat-conversation-header__status">{summary.status}</span>
+      {#if participantLabel}
+        <span aria-hidden="true"> · </span>
+        <span title={fullParticipantLabel} aria-label={fullParticipantLabel}>
+          {participantLabel}
+        </span>
+      {/if}
+    </p>
+  </div>
+
+  {#if showExportActions || actions}
+    <div class="cinder-chat-conversation-header__actions">
+      {#if showExportActions}
+        <ConversationExportActions id={`${conversation.id}-export-actions`} {conversation} />
+      {/if}
+      {#if actions}
+        {@render actions(summary)}
+      {/if}
+    </div>
+  {/if}
+</header>

package/src/components/chat-conversation-header/chat-conversation-header.types.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ConversationSummary } from '../chat-conversation-list/conversation-summary.ts';
+import type { ConversationHistory } from '../chat/conversation-model.ts';
+
+export type ChatConversationHeaderHeadingLevel = 2 | 3 | 4;
+
+/** Props for the ChatConversationHeader component. */
+export type ChatConversationHeaderProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Active compatible conversation snapshot. */
+  conversation: ConversationHistory;
+  /** Heading level for the conversation title. Default `2`. */
+  headingLevel?: ChatConversationHeaderHeadingLevel;
+  /** Whether to render the built-in conversation export actions. Default `true`. */
+  showExportActions?: boolean;
+  /** Additional class name merged with `.cinder-chat-conversation-header`. */
+  class?: string;
+  /** Additional action controls rendered after the built-in export actions. */
+  actions?: Snippet<[ConversationSummary]>;
+};

package/src/components/chat-conversation-header/chat-conversation-header.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/chat-conversation-header/index.ts

@@ -0,0 +1,9 @@
+import './chat-conversation-header.css';
+import ChatConversationHeader from './chat-conversation-header.svelte';
+
+export default ChatConversationHeader;
+export type {
+  ChatConversationHeaderHeadingLevel,
+  ChatConversationHeaderProps,
+} from './chat-conversation-header.types.ts';
+export { ChatConversationHeader };

package/src/components/chat-conversation-list/chat-conversation-list.schema.ts

@@ -0,0 +1,52 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    activeConversationId: {
+      anyOf: [
+        {
+          type: 'string',
+        },
+        {
+          type: 'null',
+        },
+      ],
+      description: 'Currently active conversation id.',
+    },
+    ariaLabel: {
+      type: 'string',
+      description:
+        'Accessible name for the conversations navigation landmark. Default `"Conversations"`.',
+    },
+    emptyText: {
+      type: 'string',
+      description:
+        'Empty state text when no conversations are present. Default `"No conversations"`.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class name merged with `.cinder-chat-conversation-list`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'conversations',
+        reason: 'unknown-shape',
+        required: true,
+        description:
+          'Conversation summaries to render. Sorts by latest message/update time descending.',
+      },
+      {
+        name: 'onselectconversation',
+        reason: 'function-or-snippet',
+        description: 'Called when a conversation is selected.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;