@lostgradient/cinder 0.7.0 → 0.9.0

package/src/components/approval-card/approval-card.types.ts

@@ -2,6 +2,9 @@ import type { HTMLAttributes } from 'svelte/elements';
 
 export type ApprovalToolRisk = 'low' | 'medium' | 'high';
 
+/** Heading level rendered for the card title. Section headings render one level deeper. */
+export type ApprovalCardHeadingLevel = 2 | 3 | 4 | 5 | 6;
+
 /** @schemaObject */
 export type ApprovalTool = {
   /** Human-readable tool name requesting approval. */
@@ -28,7 +31,7 @@ export type ApprovalCommandOperation = {
   kind: 'command';
   /** Shell command for command approvals. */
   command: string;
-  /** File paths that the operation may read or write. */
+  /** File paths that the operation may read or write. Duplicate paths are collapsed for display. */
   filesTouched?: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -42,7 +45,7 @@ export type ApprovalCommandOperation = {
 export type ApprovalFileWriteOperation = {
   /** Operation family being approved. */
   kind: 'file-write';
-  /** File paths that the operation may read or write. File-write approvals require at least one path. */
+  /** File paths that the operation may read or write. File-write approvals require at least one path. Duplicate paths are collapsed for display. */
   filesTouched: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -56,7 +59,7 @@ export type ApprovalFileWriteOperation = {
 export type ApprovalPatchOperation = {
   /** Operation family being approved. */
   kind: 'patch';
-  /** File paths that the operation may read or write. */
+  /** File paths that the operation may read or write. Duplicate paths are collapsed for display. */
   filesTouched?: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -72,7 +75,7 @@ export type ApprovalPatchOperation = {
 export type ApprovalOtherOperation = {
   /** Operation family being approved. */
   kind: 'other';
-  /** File paths that the operation may read or write. */
+  /** File paths that the operation may read or write. Duplicate paths are collapsed for display. */
   filesTouched?: string[];
   /**
    * JSON-like argument preview shown to the approver.
@@ -117,18 +120,8 @@ export type ApprovalResolution = {
 };
 
 export type ApprovalCardCallbacks = {
-  /** Called for approve, approve-with-edits, deny, and cancel with the complete resolution payload. */
+  /** Called for approve, approve-with-edits, deny, and dismiss with the complete resolution payload. */
   onresolve?: (resolution: ApprovalResolution) => void;
-  /** Called when the approver accepts the operation as presented. */
-  onapprove?: () => void;
-  /** Called with parsed JSON arguments when the approver accepts edited arguments. */
-  onapprovewithedits?: (editedArgs: unknown) => void;
-  /** Called when the approver denies the operation. */
-  ondeny?: () => void;
-  /** Called when the approver asks the host application to remember the decision. */
-  onremember?: () => void;
-  /** Called when the approver cancels the approval prompt. */
-  oncancel?: () => void;
 };
 
 /** Props for the ApprovalCard component. */
@@ -154,6 +147,8 @@ export type ApprovalCardProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'chi
     state: ApprovalState;
     /** Whether approving with edited JSON arguments is available. Default `false`. */
     editableArgs?: boolean;
+    /** Heading level for the card title; section headings render one level deeper. Default `3`. */
+    headingLevel?: ApprovalCardHeadingLevel;
     /** Additional CSS classes applied to the root element. */
     class?: string;
   };
@@ -161,8 +156,8 @@ export type ApprovalCardProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'chi
 /**
  * Cinder-specific schema surface for ApprovalCard.
  *
- * Callback props are documented but marked unsupported because functions cannot
- * be represented as JSON Schema controls.
+ * The resolution callback is documented but marked unsupported because
+ * functions cannot be represented as JSON Schema controls.
  */
 export type ApprovalCardSchemaProps = {
   /** Tool requesting approval. */
@@ -185,18 +180,10 @@ export type ApprovalCardSchemaProps = {
   state: ApprovalState;
   /** Whether approving with edited JSON arguments is available. Default `false`. */
   editableArgs?: boolean;
-  /** Called when the approver accepts the operation as presented. */
-  onapprove?: () => void;
-  /** Called for approve, approve-with-edits, deny, and cancel with the complete resolution payload. */
+  /** Heading level for the card title; section headings render one level deeper. Default `3`. */
+  headingLevel?: ApprovalCardHeadingLevel;
+  /** Called for approve, approve-with-edits, deny, and dismiss with the complete resolution payload. */
   onresolve?: (resolution: ApprovalResolution) => void;
-  /** Called with parsed JSON arguments when the approver accepts edited arguments. */
-  onapprovewithedits?: (editedArgs: unknown) => void;
-  /** Called when the approver denies the operation. */
-  ondeny?: () => void;
-  /** Called when the approver asks the host application to remember the decision. */
-  onremember?: () => void;
-  /** Called when the approver cancels the approval prompt. */
-  oncancel?: () => void;
   /** Additional CSS classes applied to the root element. */
   class?: string;
 };

package/src/components/approval-card/index.ts

@@ -4,6 +4,7 @@ import ApprovalCard from './approval-card.svelte';
 export default ApprovalCard;
 export type {
   ApprovalCardCallbacks,
+  ApprovalCardHeadingLevel,
   ApprovalCardProps,
   ApprovalCardSchemaProps,
   ApprovalOperation,

package/src/components/card/card.css

@@ -95,6 +95,11 @@
     padding: 0;
   }
 
+  .cinder-card[data-cinder-padding='none'] > .cinder-card__header,
+  .cinder-card[data-cinder-padding='none'] > .cinder-card__footer {
+    padding: 0;
+  }
+
   .cinder-card[data-cinder-variant='well'] > .cinder-card__body {
     background: var(--cinder-surface-inset);
   }

package/src/components/card/card.schema.json

@@ -28,7 +28,7 @@
     },
     "padding": {
       "enum": ["none", "default"],
-      "description": "Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image)."
+      "description": "Region padding. `none` removes body, header, and footer padding for flush or full-bleed content (e.g. an image)."
     },
     "headingLevel": {
       "enum": [2, 3, 4, 5, 6],

package/src/components/card/card.schema.ts

@@ -32,7 +32,7 @@ const schema = {
     padding: {
       enum: ['none', 'default'],
       description:
-        'Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image).',
+        'Region padding. `none` removes body, header, and footer padding for flush or full-bleed content (e.g. an image).',
     },
     headingLevel: {
       enum: [2, 3, 4, 5, 6],

package/src/components/card/card.svelte

@@ -37,6 +37,7 @@ const labelAttributes = $derived(hasGeneratedHeader
   data-cinder-variant={variant}
   data-cinder-tone={tone}
   data-cinder-edge-to-edge-mobile={edgeToEdgeOnMobile ? '' : undefined}
+  data-cinder-padding={padding}
   {...labelAttributes}
 >
   {#if header}

package/src/components/card/card.types.ts

@@ -3,7 +3,7 @@ import type { HTMLAttributes } from 'svelte/elements';
 export type CardVariant = 'card' | 'well';
 export type CardTone = 'default' | 'muted';
 export type CardSurfaceTone = 'default' | 'danger';
-/** Controls body padding. `none` removes all padding for flush/full-bleed content. Future values like `compact` may be added. */
+/** Controls region padding. `none` removes body, header, and footer padding for flush/full-bleed content. Future values like `compact` may be added. */
 export type CardPadding = 'default' | 'none';
 /** Heading level for the generated card title, so the document outline stays correct. */
 export type CardHeadingLevel = 2 | 3 | 4 | 5 | 6;
@@ -19,7 +19,7 @@ type CardBase = HTMLAttributes<HTMLDivElement> & {
   footerTone?: CardTone;
   /** Remove side borders/radius and bleed to the viewport edge on narrow screens. */
   edgeToEdgeOnMobile?: boolean;
-  /** Body padding. `none` removes all padding for flush or full-bleed content (e.g. an image). */
+  /** Region padding. `none` removes body, header, and footer padding for flush or full-bleed content (e.g. an image). */
   padding?: CardPadding;
 };
 /** Basic card with no generated header. */

package/src/components/chat/chat.schema.json

@@ -50,6 +50,26 @@
       "type": "string",
       "description": "Optional status label displayed in the typing indicator while `streaming` is `true` and no streaming content has arrived yet (e.g. `\"Thinking…\"` or `\"Analyzing file…\"`). When omitted, three animated dots are shown."
     },
+    "composerRole": {
+      "type": "string",
+      "description": "Explicit role for the composer textarea, for overlay patterns such as ARIA comboboxes."
+    },
+    "composerAriaExpanded": {
+      "enum": [false, true, "true", "false"],
+      "description": "`aria-expanded` passed to the composer textarea for overlays such as slash-command menus."
+    },
+    "composerAriaControls": {
+      "type": "string",
+      "description": "`aria-controls` passed to the composer textarea for overlays such as slash-command menus."
+    },
+    "composerAriaActiveDescendant": {
+      "type": "string",
+      "description": "`aria-activedescendant` passed to the composer textarea for overlays such as slash-command menus."
+    },
+    "composerAriaAutocomplete": {
+      "enum": ["none", "inline", "list", "both"],
+      "description": "`aria-autocomplete` passed to the composer textarea for overlays such as slash-command menus."
+    },
     "virtualized": {
       "type": "boolean",
       "description": "Use the virtualized message render path for long transcripts. The complete `ConversationHistory` remains unchanged; only the DOM window is reduced. Default `false`."
@@ -164,6 +184,26 @@
         "name": "onattachmentremove",
         "reason": "function-or-snippet"
       },
+      {
+        "name": "oncomposerblur",
+        "reason": "function-or-snippet",
+        "description": "Called when focus leaves the composer textarea. Overlay primitives can use\nthis to dismiss without preventing native focus movement."
+      },
+      {
+        "name": "oncomposerinput",
+        "reason": "function-or-snippet",
+        "description": "Called with the composer's current plain-text value on every composer\ninput event. The optional event exposes the textarea for composer-bound\noverlays without reaching into `.chat-input-editor` DOM directly."
+      },
+      {
+        "name": "oncomposerkeydown",
+        "reason": "function-or-snippet",
+        "description": "Called before Chat's internal composer key handling when a keydown\noriginates from the composer textarea. Call `event.preventDefault()` to\nlet an overlay consume Arrow keys, Enter, or Escape before Enter-to-send.\nChat does not call this hook during IME composition, so Enter can still\nconfirm the active candidate instead of sending."
+      },
+      {
+        "name": "oncomposerselectionchange",
+        "reason": "function-or-snippet",
+        "description": "Called after pointer or selection activity may have moved the composer\ncaret without changing text. Overlay primitives can resync their active\ntoken from the textarea selection."
+      },
       {
         "name": "ondeny",
         "reason": "function-or-snippet",

package/src/components/chat/chat.schema.ts

@@ -63,6 +63,31 @@ const schema = {
       description:
         'Optional status label displayed in the typing indicator while `streaming` is `true` and no streaming content has arrived yet (e.g. `"Thinking…"` or `"Analyzing file…"`). When omitted, three animated dots are shown.',
     },
+    composerRole: {
+      type: 'string',
+      description:
+        'Explicit role for the composer textarea, for overlay patterns such as ARIA comboboxes.',
+    },
+    composerAriaExpanded: {
+      enum: [false, true, 'true', 'false'],
+      description:
+        '`aria-expanded` passed to the composer textarea for overlays such as slash-command menus.',
+    },
+    composerAriaControls: {
+      type: 'string',
+      description:
+        '`aria-controls` passed to the composer textarea for overlays such as slash-command menus.',
+    },
+    composerAriaActiveDescendant: {
+      type: 'string',
+      description:
+        '`aria-activedescendant` passed to the composer textarea for overlays such as slash-command menus.',
+    },
+    composerAriaAutocomplete: {
+      enum: ['none', 'inline', 'list', 'both'],
+      description:
+        '`aria-autocomplete` passed to the composer textarea for overlays such as slash-command menus.',
+    },
     virtualized: {
       type: 'boolean',
       description:
@@ -191,6 +216,30 @@ const schema = {
         name: 'onattachmentremove',
         reason: 'function-or-snippet',
       },
+      {
+        name: 'oncomposerblur',
+        reason: 'function-or-snippet',
+        description:
+          'Called when focus leaves the composer textarea. Overlay primitives can use\nthis to dismiss without preventing native focus movement.',
+      },
+      {
+        name: 'oncomposerinput',
+        reason: 'function-or-snippet',
+        description:
+          "Called with the composer's current plain-text value on every composer\ninput event. The optional event exposes the textarea for composer-bound\noverlays without reaching into `.chat-input-editor` DOM directly.",
+      },
+      {
+        name: 'oncomposerkeydown',
+        reason: 'function-or-snippet',
+        description:
+          "Called before Chat's internal composer key handling when a keydown\noriginates from the composer textarea. Call `event.preventDefault()` to\nlet an overlay consume Arrow keys, Enter, or Escape before Enter-to-send.\nChat does not call this hook during IME composition, so Enter can still\nconfirm the active candidate instead of sending.",
+      },
+      {
+        name: 'oncomposerselectionchange',
+        reason: 'function-or-snippet',
+        description:
+          'Called after pointer or selection activity may have moved the composer\ncaret without changing text. Overlay primitives can resync their active\ntoken from the textarea selection.',
+      },
       {
         name: 'ondeny',
         reason: 'function-or-snippet',

package/src/components/chat/chat.svelte

@@ -30,6 +30,14 @@ export function pushToken(token) {
 export function endStreaming() {
     impl?.endStreaming();
 }
+/**
+ * Announce consumer-rendered status text through Chat's existing live regions.
+ * No-op until mounted. Built-in tool-approval announcements take precedence
+ * over consumer assertive announcements to avoid duplicate urgent output.
+ */
+export function announce(message, level = 'polite') {
+    impl?.announce(message, level);
+}
 /** Scroll the message viewport to the bottom. No-op until mounted. */
 export function scrollToBottom() {
     impl?.scrollToBottom();
@@ -42,6 +50,18 @@ export function scrollToTop() {
 export function focusInput() {
     impl?.focusInput();
 }
+/** Clear the composer's current content. No-op until mounted. */
+export function clearInput() {
+    impl?.clearInput();
+}
+/** Read the composer's current plain-text value. Returns '' until mounted. */
+export function getComposerValue() {
+    return impl?.getComposerValue() ?? '';
+}
+/** Read the composer textarea element. Returns null until mounted. */
+export function getEditorElement() {
+    return impl?.getEditorElement() ?? null;
+}
 </script>
 
 <ChatImplementation bind:this={impl} class={mergedClassName} {...rest} />

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

@@ -49,6 +49,9 @@ export type ReadReceipt = {
   readBy?: string[];
 };
 
+/** Live-region channel for imperative Chat announcements. */
+export type ChatAnnounceLevel = 'polite' | 'assertive';
+
 /**
  * Full-row override snippet. Inversion of control: receives the message AND a
  * `renderDefault` snippet that renders the built-in row, so a consumer can wrap
@@ -127,6 +130,16 @@ export type ChatProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'onsubmit'>
    * rather than as five separate boolean props.
    */
   capabilities?: ChatCapabilities;
+  /** Explicit role for the composer textarea, for overlay patterns such as ARIA comboboxes. */
+  composerRole?: string | undefined;
+  /** `aria-expanded` passed to the composer textarea for overlays such as slash-command menus. */
+  composerAriaExpanded?: boolean | 'true' | 'false' | undefined;
+  /** `aria-controls` passed to the composer textarea for overlays such as slash-command menus. */
+  composerAriaControls?: string | undefined;
+  /** `aria-activedescendant` passed to the composer textarea for overlays such as slash-command menus. */
+  composerAriaActiveDescendant?: string | undefined;
+  /** `aria-autocomplete` passed to the composer textarea for overlays such as slash-command menus. */
+  composerAriaAutocomplete?: 'none' | 'inline' | 'list' | 'both' | undefined;
   /** Use the virtualized message render path for long transcripts. The complete `ConversationHistory` remains unchanged; only the DOM window is reduced. Default `false`. */
   virtualized?: boolean;
   /** Estimated row height in pixels for virtualized message rows. Default `88`. */
@@ -243,4 +256,29 @@ export type ChatProps = Omit<HTMLAttributes<HTMLElement>, 'class' | 'onsubmit'>
   onattachmentadd?: (attachment: ChatAttachment) => void;
   onattachmentremove?: (attachment: ChatAttachment) => void;
   onattachmentfailure?: (file: File, error: string) => void;
+  /**
+   * Called with the composer's current plain-text value on every composer
+   * input event. The optional event exposes the textarea for composer-bound
+   * overlays without reaching into `.chat-input-editor` DOM directly.
+   */
+  oncomposerinput?: (value: string, event?: Event) => void;
+  /**
+   * Called before Chat's internal composer key handling when a keydown
+   * originates from the composer textarea. Call `event.preventDefault()` to
+   * let an overlay consume Arrow keys, Enter, or Escape before Enter-to-send.
+   * Chat does not call this hook during IME composition, so Enter can still
+   * confirm the active candidate instead of sending.
+   */
+  oncomposerkeydown?: (event: KeyboardEvent) => void;
+  /**
+   * Called after pointer or selection activity may have moved the composer
+   * caret without changing text. Overlay primitives can resync their active
+   * token from the textarea selection.
+   */
+  oncomposerselectionchange?: (event: Event) => void;
+  /**
+   * Called when focus leaves the composer textarea. Overlay primitives can use
+   * this to dismiss without preventing native focus movement.
+   */
+  oncomposerblur?: (event: FocusEvent) => void;
 };

package/src/components/chat/container/chat.svelte

@@ -26,7 +26,8 @@ import { useChatReadReceipts } from './use-chat-read-receipts.svelte.ts';
 import ChatParticipantTyping from './chat-participant-typing.svelte';
 import ChatReadReceipt from '../message/chat-read-receipt.svelte';
 const noopAttachment = () => { };
-let { id, conversation, atBottom = $bindable(true), unreadCount = $bindable(0), newMessageIndicatorVisible = $bindable(false), class: className, surfaceMode = 'default', density = 'comfortable', variant = 'bubble', bottomThreshold = DEFAULT_SCROLL_CONFIGURATION.bottomThreshold, jumpThreshold = DEFAULT_SCROLL_CONFIGURATION.jumpThreshold, streaming = false, streamingStatus, capabilities, virtualized = false, virtualizationEstimatedRowHeight = 88, virtualizationOverscan = 3, virtualizationInitialHeight = 640, moreHistoryAvailable = true, loadEarlierLabel = 'Load earlier messages', loadingEarlierLabel = 'Loading earlier messages', header, empty, emptyPrompts, messageActions, messageStatus, row, messagePart, viewportAttachment, typingParticipants, readReceipts, adapter, onadaptererror, onpushmessage, ontypingchange, onreadreceipt, onsubmit, onretry, onedit, onapprove, ondeny, messageReasoning, messageSteps, messageSuggestions, onsuggestionselect, onloadhistory, onstopgenerating, onjumptolatest, onscrollstatechange, onunreadindicatorchange, onexpandedchange, onattachmentadd, onattachmentremove, onattachmentfailure, ...rest } = $props();
+const CONSUMER_ANNOUNCEMENT_CLEAR_DELAY_MS = 1000;
+let { id, conversation, atBottom = $bindable(true), unreadCount = $bindable(0), newMessageIndicatorVisible = $bindable(false), class: className, surfaceMode = 'default', density = 'comfortable', variant = 'bubble', bottomThreshold = DEFAULT_SCROLL_CONFIGURATION.bottomThreshold, jumpThreshold = DEFAULT_SCROLL_CONFIGURATION.jumpThreshold, streaming = false, streamingStatus, capabilities, virtualized = false, virtualizationEstimatedRowHeight = 88, virtualizationOverscan = 3, virtualizationInitialHeight = 640, moreHistoryAvailable = true, loadEarlierLabel = 'Load earlier messages', loadingEarlierLabel = 'Loading earlier messages', header, empty, emptyPrompts, messageActions, messageStatus, row, messagePart, viewportAttachment, typingParticipants, readReceipts, adapter, onadaptererror, onpushmessage, ontypingchange, onreadreceipt, onsubmit, onretry, onedit, onapprove, ondeny, messageReasoning, messageSteps, messageSuggestions, onsuggestionselect, onloadhistory, onstopgenerating, onjumptolatest, onscrollstatechange, onunreadindicatorchange, onexpandedchange, onattachmentadd, onattachmentremove, onattachmentfailure, oncomposerinput, oncomposerkeydown, oncomposerselectionchange, oncomposerblur, composerRole, composerAriaExpanded, composerAriaControls, composerAriaActiveDescendant, composerAriaAutocomplete, ...rest } = $props();
 // ==========================================================================
 // Refs and Internal State
 // ==========================================================================
@@ -84,10 +85,15 @@ $effect(() => {
     toolCallState.reset();
     typingIndicatorState.reset();
     readReceiptsState.reset();
+    clearConsumerAnnouncements();
 });
 let isLoadingHistory = $state(false);
 let adapterHasMoreHistory = $state(undefined);
 let historyAnnouncement = $state('');
+let consumerPoliteAnnouncement = $state('');
+let consumerAssertiveAnnouncement = $state('');
+let consumerPoliteAnnouncementTimeout;
+let consumerAssertiveAnnouncementTimeout;
 let pendingHistoryScroll = $state(null);
 let deferredAdapterHasMoreHistory = null;
 let historyAnchorMessageId = $state(null);
@@ -325,6 +331,13 @@ const toolApprovalAssertiveMessage = $derived.by(() => {
     }
     return '';
 });
+const assertiveAnnouncement = $derived(toolApprovalAssertiveMessage || consumerAssertiveAnnouncement);
+const politeAnnouncement = $derived(consumerPoliteAnnouncement || historyAnnouncement || unreadState.announcerMessage);
+$effect(() => {
+    if (toolApprovalAssertiveMessage && consumerAssertiveAnnouncement) {
+        clearConsumerAssertiveAnnouncement();
+    }
+});
 // ==========================================================================
 // Scroll Anchoring via $effect.pre
 // ==========================================================================
@@ -516,6 +529,7 @@ $effect(() => {
             cancelAnimationFrame(streamingScrollRaf);
             streamingScrollRaf = undefined;
         }
+        clearConsumerAnnouncements();
     };
 });
 // ==========================================================================
@@ -588,6 +602,50 @@ const historyAnchorScrollAttachment = $derived(historyAnchorMessageId === null |
 // ==========================================================================
 // Actions
 // ==========================================================================
+export function announce(message, level = 'polite') {
+    const trimmedMessage = message.trim();
+    if (!trimmedMessage)
+        return;
+    if (level === 'assertive') {
+        if (toolApprovalAssertiveMessage)
+            return;
+        setConsumerAssertiveAnnouncement(trimmedMessage);
+        return;
+    }
+    setConsumerPoliteAnnouncement(trimmedMessage);
+}
+function setConsumerPoliteAnnouncement(message) {
+    clearTimeout(consumerPoliteAnnouncementTimeout);
+    consumerPoliteAnnouncement = message;
+    consumerPoliteAnnouncementTimeout = setTimeout(() => {
+        if (consumerPoliteAnnouncement === message)
+            consumerPoliteAnnouncement = '';
+        consumerPoliteAnnouncementTimeout = undefined;
+    }, CONSUMER_ANNOUNCEMENT_CLEAR_DELAY_MS);
+}
+function setConsumerAssertiveAnnouncement(message) {
+    clearTimeout(consumerAssertiveAnnouncementTimeout);
+    consumerAssertiveAnnouncement = message;
+    consumerAssertiveAnnouncementTimeout = setTimeout(() => {
+        if (consumerAssertiveAnnouncement === message)
+            consumerAssertiveAnnouncement = '';
+        consumerAssertiveAnnouncementTimeout = undefined;
+    }, CONSUMER_ANNOUNCEMENT_CLEAR_DELAY_MS);
+}
+function clearConsumerPoliteAnnouncement() {
+    clearTimeout(consumerPoliteAnnouncementTimeout);
+    consumerPoliteAnnouncementTimeout = undefined;
+    consumerPoliteAnnouncement = '';
+}
+function clearConsumerAssertiveAnnouncement() {
+    clearTimeout(consumerAssertiveAnnouncementTimeout);
+    consumerAssertiveAnnouncementTimeout = undefined;
+    consumerAssertiveAnnouncement = '';
+}
+function clearConsumerAnnouncements() {
+    clearConsumerPoliteAnnouncement();
+    clearConsumerAssertiveAnnouncement();
+}
 function handleJumpToLatest() {
     if (isVirtualized) {
         chatVirtualizer.scrollToIndex(Math.max(0, renderRows.length - 1), {
@@ -1061,6 +1119,18 @@ export function scrollToTop() {
 export function focusInput() {
     inputRef?.focus();
 }
+/** Clear the composer's current content. */
+export function clearInput() {
+    inputRef?.clear();
+}
+/** Read the composer's current plain-text value. */
+export function getComposerValue() {
+    return inputRef?.getValue() ?? '';
+}
+/** Read the composer textarea element. Returns null until mounted. */
+export function getEditorElement() {
+    return inputRef?.getEditorElement() ?? null;
+}
 /**
  * Begin streaming content for a specific message.
  * The message should already exist in the conversation.
@@ -1405,6 +1475,15 @@ function virtualRowAttachment(row) {
         sending={streaming}
         {allowAttachments}
         onstop={streaming ? handleStopGenerating : undefined}
+        {oncomposerinput}
+        {oncomposerkeydown}
+        {oncomposerselectionchange}
+        {oncomposerblur}
+        {composerRole}
+        {composerAriaExpanded}
+        {composerAriaControls}
+        {composerAriaActiveDescendant}
+        {composerAriaAutocomplete}
         {onattachmentadd}
         {onattachmentremove}
         {onattachmentfailure}
@@ -1415,8 +1494,8 @@ function virtualRowAttachment(row) {
   <ChatStatusAnnouncer
     {statusId}
     messageCount={messages.length}
-    announcerMessage={historyAnnouncement || unreadState.announcerMessage}
-    assertiveMessage={toolApprovalAssertiveMessage}
+    announcerMessage={politeAnnouncement}
+    assertiveMessage={assertiveAnnouncement}
   />
 
   <!-- Typing-participant live region: outside role="log" to avoid double announcement.

package/src/components/chat/index.ts

@@ -13,7 +13,13 @@ import './chat.css';
 import Chat from './chat.svelte';
 
 export default Chat;
-export type { ChatCapabilities, ChatProps, ReadReceipt, TypingParticipant } from './chat.types.ts';
+export type {
+  ChatAnnounceLevel,
+  ChatCapabilities,
+  ChatProps,
+  ReadReceipt,
+  TypingParticipant,
+} from './chat.types.ts';
 export { Chat };
 
 // Adapter seam — the optional event/transport boundary around <Chat>. Type-only.
@@ -80,8 +86,14 @@ export {
 } from './utilities';
 
 // Input
-export { ChatAttachmentPreview, ChatInput, deriveAttachmentKind } from './input';
-export type { AttachmentKind } from './input';
+export {
+  ChatAttachmentPreview,
+  ChatInput,
+  deriveAttachmentKind,
+  serializeChatAttachment,
+  serializeChatAttachments,
+} from './input';
+export type { AttachmentKind, ChatAttachment, SerializedChatAttachment } from './input';
 
 // Message
 export {

package/src/components/chat/input/chat-attachment-serialization.ts

@@ -0,0 +1,63 @@
+import type { ChatAttachment } from './chat-attachment.ts';
+
+const BASE64_CHUNK_SIZE = 0x8000;
+
+type Base64Runtime = typeof globalThis & {
+  btoa?: (data: string) => string;
+  Buffer?: {
+    from: (data: Uint8Array) => { toString: (encoding: 'base64') => string };
+  };
+};
+
+export interface SerializedChatAttachment {
+  name: string;
+  mimeType: string;
+  kind: ChatAttachment['kind'];
+  content: string;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  const runtime = globalThis as Base64Runtime;
+
+  if (typeof runtime.btoa === 'function') {
+    let binary = '';
+
+    for (let start = 0; start < bytes.length; start += BASE64_CHUNK_SIZE) {
+      const chunk = bytes.subarray(start, start + BASE64_CHUNK_SIZE);
+      binary += String.fromCharCode(...chunk);
+    }
+
+    return runtime.btoa(binary);
+  }
+
+  if (typeof runtime.Buffer?.from === 'function') {
+    return runtime.Buffer.from(bytes).toString('base64');
+  }
+
+  throw new Error('serializeChatAttachment requires btoa or Buffer for base64 encoding.');
+}
+
+export async function serializeChatAttachment(
+  attachment: ChatAttachment,
+): Promise<SerializedChatAttachment> {
+  const bytes = new Uint8Array(await attachment.file.arrayBuffer());
+
+  return {
+    name: attachment.file.name,
+    mimeType: attachment.file.type,
+    kind: attachment.kind,
+    content: bytesToBase64(bytes),
+  };
+}
+
+export async function serializeChatAttachments(
+  attachments: readonly ChatAttachment[],
+): Promise<SerializedChatAttachment[]> {
+  const serializedAttachments: SerializedChatAttachment[] = [];
+
+  for (const attachment of attachments) {
+    serializedAttachments.push(await serializeChatAttachment(attachment));
+  }
+
+  return serializedAttachments;
+}