@runtypelabs/persona 3.34.0 → 3.35.0

package/dist/index.d.ts

@@ -48,7 +48,7 @@ interface AgentWidgetPlugin {
         defaultRenderer: () => HTMLElement;
         onSubmit: (text: string) => void;
         /**
-         * When true, the assistant stream is active — same moment `session.isStreaming()` becomes true.
+         * When true, the assistant stream is active: same moment `session.isStreaming()` becomes true.
          * Prefer wiring controls to `data-persona-composer-disable-when-streaming` plus `setComposerDisabled`
          * in the host, or react to `footer.dataset.personaComposerStreaming === "true"`.
          */
@@ -97,14 +97,14 @@ interface AgentWidgetPlugin {
      * Custom renderer for `ask_user_question` tool calls.
      *
      * When a plugin returns an `HTMLElement`, it is inserted into the transcript
-     * in place of the default (which is no transcript bubble — the built-in
+     * in place of the default (which is no transcript bubble: the built-in
      * renders a sheet over the composer). The built-in composer-overlay sheet
      * is suppressed so the plugin's UI fully owns the interaction.
      *
      * Return `null` to fall through to the built-in overlay sheet.
      *
      * The context gives you a pre-parsed `payload` (may be partial while the
-     * tool call is still streaming — check `complete`) and two callbacks:
+     * tool call is still streaming: check `complete`) and two callbacks:
      * `resolve(answer)` resumes the paused LOCAL tool with the user's answer,
      * and `dismiss()` cancels with the sentinel `"(dismissed)"`.
      *
@@ -153,8 +153,8 @@ interface AgentWidgetPlugin {
      *
      * Return an `HTMLElement` to fully own the approval UI, `defaultRenderer()`
      * to render (or wrap) the built-in bubble, or `null` to fall through to the
-     * default. Unlike the built-in bubble — whose Approve/Deny buttons are wired
-     * via delegation — a fully custom element resolves the approval by calling
+     * default. Unlike the built-in bubble: whose Approve/Deny buttons are wired
+     * via delegation: a fully custom element resolves the approval by calling
      * the `approve`/`deny` callbacks. Both route through the same path the
      * built-in buttons use (optimistic update, `onDecision`, in-place anchoring).
      *
@@ -1055,6 +1055,7 @@ type RuntypeFlowSSEEvent = {
     totalSteps?: number;
     type: "flow_start";
 } | {
+    claudeManagedAgentId?: string;
     completedAt?: string;
     completedSteps?: number;
     duration?: number;
@@ -1169,6 +1170,7 @@ type RuntypeFlowSSEEvent = {
         toolId: string;
     };
     type: "step_complete";
+    unresolvedVariables?: Array<string>;
 }) | {
     error: string;
     executionId?: string;
@@ -1605,6 +1607,7 @@ type RuntypeDispatchSSEEvent = {
     totalSteps?: number;
     type: "flow_start";
 } | {
+    claudeManagedAgentId?: string;
     completedAt?: string;
     completedSteps?: number;
     duration?: number;
@@ -1719,6 +1722,7 @@ type RuntypeDispatchSSEEvent = {
         toolId: string;
     };
     type: "step_complete";
+    unresolvedVariables?: Array<string>;
 }) | {
     error: string;
     executionId?: string;
@@ -2005,6 +2009,7 @@ type RuntypeClientFeedbackRequest = {
     metadata?: Record<string, unknown>;
     rating?: number;
     sessionId: string;
+    token: string;
     type: "upvote" | "downvote" | "copy" | "csat" | "nps";
 };
 type RuntypeClientFeedbackResponse = {
@@ -2180,7 +2185,7 @@ type AgentConfig = {
     temperature?: number;
     /** Tool configuration for the agent */
     tools?: AgentToolsConfig;
-    /** Persona artifacts — sibling of tools (virtual agent / API parity) */
+    /** Persona artifacts: sibling of tools (virtual agent / API parity) */
     artifacts?: ArtifactConfigPayload;
     /** Loop configuration for multi-turn execution */
     loopConfig?: AgentLoopConfig;
@@ -2208,7 +2213,7 @@ type AgentWidgetAgentRequestPayload = {
     context?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     /**
-     * Per-turn page-discovered tools (WebMCP) — same shape as
+     * Per-turn page-discovered tools (WebMCP): same shape as
      * `AgentWidgetRequestPayload.clientTools`.
      */
     clientTools?: ClientToolDefinition[];
@@ -2217,7 +2222,7 @@ type AgentWidgetAgentRequestPayload = {
  * Wire shape for a single client-discovered tool sent on `dispatch.clientTools[]`.
  *
  * Mirrors the SDK's `ClientToolDefinition` in `@runtypelabs/sdk`. Only the
- * JSON-serializable surface of a WebMCP tool — the `execute` function stays
+ * JSON-serializable surface of a WebMCP tool: the `execute` function stays
  * client-side; the server merges these into the agent's tool catalog under
  * the `webmcp:` namespace.
  */
@@ -2225,16 +2230,16 @@ type ClientToolDefinition = {
     /** Bare tool name; the server prepends `webmcp:` on the wire. */
     name: string;
     description: string;
-    /** JSON Schema (per WebMCP spec) — passed through as-is. */
+    /** JSON Schema (per WebMCP spec): passed through as-is. */
     parametersSchema?: object;
     /**
      * `'webmcp'` for tools discovered via the polyfill (server prepends the
      * `webmcp:` wire prefix); `'sdk'` for widget/SDK-provided tools (name stays
-     * bare on the wire). Matches the server's accepted enum — any other value
+     * bare on the wire). Matches the server's accepted enum: any other value
      * fails dispatch validation.
      */
     origin?: 'webmcp' | 'sdk';
-    /** Origin of the page that registered the tool — for server-side audit. */
+    /** Origin of the page that registered the tool: for server-side audit. */
     pageOrigin?: string;
     /**
      * WebMCP `Tool.annotations` (spec). Not used for gating server-side; the
@@ -2266,7 +2271,7 @@ type WebMcpConfirmInfo = {
         untrustedContentHint?: boolean;
     };
     /**
-     * Why the confirm was requested. Currently always `'gate'` — the default
+     * Why the confirm was requested. Currently always `'gate'`: the default
      * confirm-by-default gate that fires before every `webmcp:*` call. (The
      * `@mcp-b/webmcp-polyfill` owns the spec's `requestUserInteraction` callback
      * internally, so Persona no longer surfaces a nested in-tool confirm.)
@@ -2299,7 +2304,7 @@ type WebMcpToolResult = {
 /**
  * Widget-level WebMCP configuration. Set `enabled: true` to opt in. The
  * surface's server-side `webmcp` policy is the source of truth for which
- * tools are accepted — these client-side options are convenience filters.
+ * tools are accepted: these client-side options are convenience filters.
  */
 type AgentWidgetWebMcpConfig = {
     /** Master switch. Default: `false` (widget never installs the polyfill). */
@@ -2315,7 +2320,7 @@ type AgentWidgetWebMcpConfig = {
      * `webmcp:*` call; return `true` to approve immediately and skip the
      * confirmation UI entirely. Use this to auto-allow read-only tools (e.g.
      * a catalog search) while still gating mutating ones. Only consulted on
-     * the default-UI path — a custom `onConfirm` takes full control instead.
+     * the default-UI path: a custom `onConfirm` takes full control instead.
      */
     autoApprove?: (info: WebMcpConfirmInfo) => boolean;
     /**
@@ -2372,7 +2377,7 @@ type AgentMessageMetadata = {
      * `flow_await` events for a LOCAL tool (core#3878). Present only when the
      * server emits it. Two PARALLEL calls to the same tool in one turn share a
      * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
-     * so this is the key the widget batches a single `/resume` on — preferred
+     * so this is the key the widget batches a single `/resume` on: preferred
      * over tool name, which collides for same-tool parallel calls. Absent →
      * fall back to the legacy name-keyed resume contract.
      */
@@ -2462,10 +2467,35 @@ type AgentWidgetVoiceStateEvent = {
     source: "user" | "auto" | "restore" | "system";
     timestamp: number;
 };
+/**
+ * Fired on every voice `VoiceStatus` transition (listening / processing /
+ * speaking / idle / …). Unlike `voice:state` (a coarse active on/off), this
+ * exposes the granular status so consumers can render their own per-state UI
+ * (e.g. a listening/speaking status dock).
+ */
+type AgentWidgetVoiceStatusEvent = {
+    status: VoiceStatus;
+    timestamp: number;
+};
 type AgentWidgetActionEventPayload = {
     action: AgentWidgetParsedAction;
     message: AgentWidgetMessage;
 };
+/**
+ * Fired on every "Read aloud" (text-to-speech) state transition for a message:
+ * `loading` (press) → `playing` → `paused`/`playing` → `idle` (finished or
+ * stopped). On the terminal `idle` transition, `messageId`/`message` still
+ * identify the message that just stopped.
+ */
+type AgentWidgetReadAloudEvent = {
+    /** The message being read aloud (or that just finished/stopped), if known. */
+    messageId: string | null;
+    /** The message object, when still present in the thread. */
+    message: AgentWidgetMessage | null;
+    /** The new playback state for this message. */
+    state: ReadAloudState;
+    timestamp: number;
+};
 /**
  * Feedback event payload for upvote/downvote actions on messages
  */
@@ -2517,6 +2547,14 @@ type AgentWidgetMessageActionsConfig = {
      * @default false
      */
     showDownvote?: boolean;
+    /**
+     * Show a "Read aloud" button that speaks the assistant message via
+     * text-to-speech (play / pause / resume). Uses the browser Web Speech API by
+     * default, or a hosted engine supplied via `textToSpeech.createEngine`.
+     * Voice, rate and pitch are read from the `textToSpeech` config.
+     * @default false
+     */
+    showReadAloud?: boolean;
     /**
      * Visibility mode: 'always' shows buttons always, 'hover' shows on hover only
      * @default 'hover'
@@ -2567,6 +2605,7 @@ type AgentWidgetControllerEventMap = {
     "assistant:message": AgentWidgetMessage;
     "assistant:complete": AgentWidgetMessage;
     "voice:state": AgentWidgetVoiceStateEvent;
+    "voice:status": AgentWidgetVoiceStatusEvent;
     "action:detected": AgentWidgetActionEventPayload;
     "action:resubmit": AgentWidgetActionEventPayload;
     "widget:opened": AgentWidgetStateEvent;
@@ -2574,6 +2613,7 @@ type AgentWidgetControllerEventMap = {
     "widget:state": AgentWidgetStateSnapshot;
     "message:feedback": AgentWidgetMessageFeedback;
     "message:copy": AgentWidgetMessage;
+    "message:read-aloud": AgentWidgetReadAloudEvent;
     "eventStream:opened": {
         timestamp: number;
     };
@@ -2629,8 +2669,8 @@ type AgentWidgetArtifactsLayoutConfig = {
     resizableMaxWidth?: string;
     /**
      * Visual treatment for the artifact column in split mode.
-     * - `'panel'` — bordered sidebar with left border, gap, and shadow (default).
-     * - `'seamless'` — flush with chat: no border or shadow, container background, zero gap.
+     * - `'panel'`: bordered sidebar with left border, gap, and shadow (default).
+     * - `'seamless'`: flush with chat: no border or shadow, container background, zero gap.
      * @default 'panel'
      */
     paneAppearance?: "panel" | "seamless";
@@ -2644,7 +2684,7 @@ type AgentWidgetArtifactsLayoutConfig = {
      */
     paneBorder?: string;
     /**
-     * `border-left` shorthand only — typical for split view next to chat (with or without resizer).
+     * `border-left` shorthand only: typical for split view next to chat (with or without resizer).
      * Ignored if `paneBorder` is set. Example: `"1px solid #cccccc"`.
      */
     paneBorderLeft?: string;
@@ -2671,8 +2711,8 @@ type AgentWidgetArtifactsLayoutConfig = {
     panePadding?: string;
     /**
      * Toolbar layout preset.
-     * - `default` — "Artifacts" title, horizontal tabs, text close.
-     * - `document` — view/source toggle, document title, copy / refresh / close; tab strip hidden when only one artifact.
+     * - `default`: "Artifacts" title, horizontal tabs, text close.
+     * - `document`: view/source toggle, document title, copy / refresh / close; tab strip hidden when only one artifact.
      * @default 'default'
      */
     toolbarPreset?: "default" | "document";
@@ -2684,7 +2724,7 @@ type AgentWidgetArtifactsLayoutConfig = {
      * When `toolbarPreset` is `document`, show a small chevron after the copy control (e.g. menu affordance).
      */
     documentToolbarShowCopyChevron?: boolean;
-    /** Document toolbar icon buttons (view, code, copy, refresh, close) — CSS color. Sets `--persona-artifact-doc-toolbar-icon-color` on the widget root. */
+    /** Document toolbar icon buttons (view, code, copy, refresh, close): CSS color. Sets `--persona-artifact-doc-toolbar-icon-color` on the widget root. */
     documentToolbarIconColor?: string;
     /** Active view/source toggle background. Sets `--persona-artifact-doc-toggle-active-bg`. */
     documentToolbarToggleActiveBackground?: string;
@@ -2828,11 +2868,11 @@ type AgentWidgetToolCallDisplayFeature = {
     expandable?: boolean;
     /**
      * Animation mode applied to the tool call header text while the tool is active.
-     * - "none" — static text, no animation
-     * - "pulse" — opacity pulse on the entire header text
-     * - "shimmer" — monochrome opacity sweep per character
-     * - "shimmer-color" — color gradient sweep per character
-     * - "rainbow" — rainbow color cycle per character
+     * - "none": static text, no animation
+     * - "pulse": opacity pulse on the entire header text
+     * - "shimmer": monochrome opacity sweep per character
+     * - "shimmer-color": color gradient sweep per character
+     * - "rainbow": rainbow color cycle per character
      * @default "none"
      */
     loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
@@ -2861,11 +2901,11 @@ type AgentWidgetReasoningDisplayFeature = {
     /**
      * Animation mode applied to the reasoning header text while reasoning is active.
      * Reuses the same modes as tool call animations.
-     * - "none" — static text, no animation
-     * - "pulse" — opacity pulse on the entire header text
-     * - "shimmer" — monochrome opacity sweep per character
-     * - "shimmer-color" — color gradient sweep per character
-     * - "rainbow" — rainbow color cycle per character
+     * - "none": static text, no animation
+     * - "pulse": opacity pulse on the entire header text
+     * - "shimmer": monochrome opacity sweep per character
+     * - "shimmer-color": color gradient sweep per character
+     * - "rainbow": rainbow color cycle per character
      * @default "none"
      */
     loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
@@ -2874,34 +2914,34 @@ type AgentWidgetReasoningDisplayFeature = {
  * Reveal animation applied to assistant message text while it is streaming.
  *
  * Built-in types always available:
- * - `none` — text appears as tokens arrive (default).
- * - `typewriter` — characters fade in with a blinking caret.
- * - `pop-bubble` — the bubble scales in; text streams normally afterward.
- * - `letter-rise` — per-char translateY + fade reveal.
- * - `word-fade` — per-word blur + translateY fade-in.
+ * - `none`: text appears as tokens arrive (default).
+ * - `typewriter`: characters fade in with a blinking caret.
+ * - `pop-bubble`: the bubble scales in; text streams normally afterward.
+ * - `letter-rise`: per-char translateY + fade reveal.
+ * - `word-fade`: per-word blur + translateY fade-in.
  *
  * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
  * - `wipe`, `glyph-cycle`.
  *
- * Custom types are allowed — register a plugin with any string name and
+ * Custom types are allowed: register a plugin with any string name and
  * reference it by that name in `type`.
  */
 type AgentWidgetStreamAnimationBuiltinType = "none" | "typewriter" | "word-fade" | "letter-rise" | "glyph-cycle" | "wipe" | "pop-bubble";
 type AgentWidgetStreamAnimationType = AgentWidgetStreamAnimationBuiltinType | (string & {});
 /**
  * Placeholder shown inside a streaming assistant bubble before the first token arrives.
- * - `none` — use the default typing-dots indicator (existing behavior).
- * - `skeleton` — shimmer bars, replaced by streaming content once it starts.
+ * - `none`: use the default typing-dots indicator (existing behavior).
+ * - `skeleton`: shimmer bars, replaced by streaming content once it starts.
  */
 type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
 /**
  * How much of the accumulated streaming content to display while tokens are
  * still arriving. Trimming to a boundary means in-progress words or lines
- * stay hidden until they complete — useful for animations that benefit from
+ * stay hidden until they complete: useful for animations that benefit from
  * unit-complete reveals (e.g. wipe, glyph-cycle).
- * - `none` — show every character as it arrives (default).
- * - `word` — trim to the last whitespace boundary.
- * - `line` — trim to the last newline boundary.
+ * - `none`: show every character as it arrives (default).
+ * - `word`: trim to the last whitespace boundary.
+ * - `line`: trim to the last newline boundary.
  */
 type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
 /**
@@ -2932,7 +2972,7 @@ type StreamAnimationContext = {
  *   widget's style host.
  * - For each streaming assistant message whose `type` matches `name`, the
  *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
- *   and — if `useCaret` is true — appends a blinking caret.
+ *   and, if `useCaret` is true, appends a blinking caret.
  * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
  *   and `data-preserve-animation` to safely mutate per-char or per-word spans
  *   without idiomorph clobbering in-flight work.
@@ -2948,7 +2988,7 @@ type StreamAnimationPlugin = {
     wrap?: "none" | "char" | "word";
     /**
      * HTML tags whose descendant text is skipped during wrapping. Defaults to
-     * `["pre", "code", "a", "script", "style"]` — useful for keeping code
+     * `["pre", "code", "a", "script", "style"]`: useful for keeping code
      * blocks legible and link click-targets intact. Plugins that want to
      * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
      * the list.
@@ -2977,8 +3017,7 @@ type StreamAnimationPlugin = {
     /**
      * Report whether the plugin still has in-flight animation work for a
      * message. When `true`, the widget keeps rendering the message in its
-     * "streaming-animated" mode even after `message.streaming` flips false —
-     * preventing the final non-animated render from yanking the rug out from
+     * "streaming-animated" mode even after `message.streaming` flips false:   * preventing the final non-animated render from yanking the rug out from
      * under unfinished per-char cycles or reveals.
      */
     isAnimating?: (message: AgentWidgetMessage) => boolean;
@@ -2991,7 +3030,7 @@ type AgentWidgetStreamAnimationFeature = {
     /**
      * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
      * and per-unit plugin animations. Each arriving character/word animates from
-     * invisible to visible over this duration, independent of its position — the
+     * invisible to visible over this duration, independent of its position: the
      * streaming cadence itself provides the visible stagger.
      * @default 120
      */
@@ -3051,7 +3090,7 @@ type AgentWidgetFeatureFlags = {
      * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
      * the tool, the widget shows the suggestions as tappable chips above the
      * composer (reusing the suggestion-chips surface) and immediately resumes
-     * the execution — fire-and-forget, no user input awaited.
+     * the execution: fire-and-forget, no user input awaited.
      */
     suggestReplies?: AgentWidgetSuggestRepliesFeature;
 };
@@ -3065,14 +3104,14 @@ type AgentWidgetFeatureFlags = {
 type AgentWidgetSuggestRepliesFeature = {
     /**
      * Enable the feature. Defaults to true. When false, `suggest_replies`
-     * renders as a regular tool bubble and is NOT auto-resumed — only set this
+     * renders as a regular tool bubble and is NOT auto-resumed: only set this
      * with no server-side `suggest_replies` declaration, or the execution
      * parks awaiting a resume that never comes.
      */
     enabled?: boolean;
     /**
      * Advertise the built-in `suggest_replies` tool to the agent on every
-     * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+     * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
      * needed. Defaults to `false`: flows that already declare the tool via
      * `runtimeTools` would otherwise present it to the model twice. Ignored
      * when `enabled` is `false`.
@@ -3088,7 +3127,7 @@ type AskUserQuestionOption = {
     label: string;
     /** Optional long-form description (shown as a subtitle on tap-hover). */
     description?: string;
-    /** Optional rich preview — reserved for future rendering; ignored in v1. */
+    /** Optional rich preview: reserved for future rendering; ignored in v1. */
     preview?: string;
 };
 /**
@@ -3140,14 +3179,14 @@ type AgentWidgetAskUserQuestionFeature = {
     enabled?: boolean;
     /**
      * Advertise the built-in `ask_user_question` tool to the agent on every
-     * dispatch via `clientTools[]` — no server-side `runtimeTools` declaration
+     * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
      * needed. The tool ships with a model-facing description and JSON schema
      * matching {@link AskUserQuestionPayload}; when the model calls it, the
      * existing answer-pill sheet renders and the answer resumes the execution.
      *
      * Defaults to `false`: flows that already declare `ask_user_question` via
      * `runtimeTools` would otherwise present the tool to the model twice.
-     * Ignored when `enabled` is `false` — never offer the agent a question
+     * Ignored when `enabled` is `false`: never offer the agent a question
      * tool the widget can't render an answer UI for.
      */
     expose?: boolean;
@@ -3168,17 +3207,17 @@ type AgentWidgetAskUserQuestionFeature = {
     /**
      * In grouped (multi-question) mode, auto-advance to the next page after a
      * single-select pill pick or free-text submit on intermediate pages.
-     * Defaults to `true`. The final page never auto-submits — users always
+     * Defaults to `true`. The final page never auto-submits: users always
      * confirm with an explicit "Submit all" click. Multi-select pages always
      * require an explicit Next regardless of this setting.
      */
     groupedAutoAdvance?: boolean;
     /**
      * Visual layout for the option list.
-     * - `"rows"` (default) — full-width stacked rows with always-visible
+     * - `"rows"` (default): full-width stacked rows with always-visible
      *   descriptions, right-edge number badges (single-select) or checkboxes
      *   (multi-select), and an always-visible inline "Other" input.
-     * - `"pills"` — legacy compact pill list with horizontal wrap; description
+     * - `"pills"`: legacy compact pill list with horizontal wrap; description
      *   surfaces as a tooltip and the "Other…" pill expands on click.
      */
     layout?: "rows" | "pills";
@@ -3346,7 +3385,7 @@ type AgentWidgetDockConfig = {
      *
      * - Set a CSS length (e.g. `"600px"`, `"80vh"`) to override the cap.
      * - Set `false` to disable the guard entirely (the panel then sizes purely
-     *   from the surrounding layout — make sure your page provides a definite
+     *   from the surrounding layout: make sure your page provides a definite
      *   height all the way down to the dock target's parent).
      *
      * @default "100dvh"
@@ -3420,7 +3459,7 @@ type AgentWidgetComposerBarConfig = {
      */
     modalMaxHeight?: string;
     /**
-     * Configuration for the "peek" banner — the chrome-less row above the
+     * Configuration for the "peek" banner: the chrome-less row above the
      * collapsed pill that previews the most recent assistant message.
      */
     peek?: AgentWidgetComposerBarPeekConfig;
@@ -3435,7 +3474,7 @@ type AgentWidgetComposerBarConfig = {
  * - Otherwise the peek inherits from `features.streamAnimation`.
  *
  * Per-surface carve-outs:
- * - `bubbleClass` from a plugin (used by `pop-bubble`) is ignored — the peek
+ * - `bubbleClass` from a plugin (used by `pop-bubble`) is ignored: the peek
  *   has no bubble analog.
  * - `containerClass`, `wrap` ("char" | "word"), `useCaret`, `placeholder`
  *   ("skeleton"), `buffer` ("word" | "line"), `speed`, `duration`, and
@@ -3681,6 +3720,11 @@ type AgentWidgetVoiceRecognitionConfig = {
     /** Button border color while speaking. Inherits idle borderColor if not set */
     speakingBorderColor?: string;
     autoResume?: boolean | "assistant";
+    /**
+     * Called with per-turn latency metrics on the realtime (`runtype`) voice path.
+     * Fires once per turn after the reply completes.
+     */
+    onMetrics?: (metrics: VoiceMetrics) => void;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -3689,15 +3733,31 @@ type AgentWidgetVoiceRecognitionConfig = {
         };
         runtype?: {
             agentId: string;
-            clientToken: string;
+            /** Defaults to the widget's `clientToken` when omitted. */
+            clientToken?: string;
+            /** Defaults to the widget's `apiUrl` when omitted. */
             host?: string;
             voiceId?: string;
-            /** Duration of silence (ms) before auto-stopping recording. Default: 2000 */
+            /**
+             * Optional custom streaming playback engine. Defaults to the built-in
+             * `AudioPlaybackManager`. Import `createWorkletPlaybackEngine` from
+             * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
+             */
+            createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
-            /** RMS volume threshold below which counts as silence. Default: 0.01 */
+            /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             silenceThreshold?: number;
         };
-        custom?: any;
+        /**
+         * Bring-your-own voice provider. Set `type: 'custom'` and pass either a
+         * ready {@link VoiceProvider} instance or a `() => VoiceProvider` factory
+         * (the factory defers construction until voice is set up). STT-style
+         * providers deliver a final transcript via `onResult` (sent as a user
+         * message); full-duplex providers can drive `onTranscript`/`onMetrics` like
+         * the realtime `runtype` provider.
+         */
+        custom?: VoiceProvider | (() => VoiceProvider);
     };
 };
 /**
@@ -3720,18 +3780,68 @@ type TextToSpeechConfig = {
     enabled: boolean;
     /**
      * TTS provider.
-     * - `'browser'` — Use the Web Speech API for all assistant messages (default).
-     * - `'runtype'` — Server handles TTS for voice interactions.
-     *   Set `browserFallback: true` to also speak text-typed responses via the browser.
+     * - `'browser'`: Use the Web Speech API for all assistant messages (default).
+     * - `'runtype'`: Use Runtype-hosted TTS. The realtime voice path speaks
+     *   replies during a voice call, and the per-message "Read aloud" button (and
+     *   auto-speak of text-typed replies) stream from Runtype's
+     *   `POST {host}/v1/agents/:agentId/speak` endpoint via the built-in
+     *   {@link SpeechEngine}. `host`/`agentId`/`clientToken` are derived from the
+     *   widget config (see `agentId`/`host` below); unless `browserFallback` is
+     *   `false`, a missing endpoint or transient failure falls back to the browser
+     *   voice so the button is never broken.
      */
     provider?: 'browser' | 'runtype';
     /**
-     * When `provider` is `'runtype'`, fall back to browser TTS for assistant
-     * messages that the server didn't already speak (e.g. text-typed messages).
+     * When `provider` is `'runtype'`:
+     * - Read-aloud / auto-speak: acts as a safety net — if Runtype TTS is
+     *   unreachable (no endpoint yet, network/auth failure) or the Runtype config
+     *   is incomplete, speech falls back to the browser Web Speech API instead of
+     *   erroring. Set to `false` to surface Runtype errors instead. **Defaults to
+     *   on for this path.**
+     * - Auto-speak of text-typed replies also requires this to be truthy (the
+     *   realtime voice path already speaks voice-call replies).
+     *
      * Has no effect when provider is `'browser'` (browser TTS is always used).
-     * @default false
      */
     browserFallback?: boolean;
+    /**
+     * When `provider` is `'runtype'`, the agent whose configured voice synthesizes
+     * read-aloud / auto-speak audio. Falls back to
+     * `voiceRecognition.provider.runtype.agentId` when omitted. Required (here or
+     * there) for Runtype TTS to activate; without it the browser voice is used.
+     */
+    agentId?: string;
+    /**
+     * When `provider` is `'runtype'`, the Runtype API host (e.g.
+     * `https://api.runtype.com`). Defaults to the widget's `apiUrl`.
+     */
+    host?: string;
+    /**
+     * When `provider` is `'runtype'`, audio (ms) the streaming player buffers
+     * before the first sample and after an underrun. Lower = snappier start;
+     * higher = rides out delivery hiccups. Default 200. Applies to the default
+     * in-bundle player; a custom `createPlaybackEngine` manages its own prebuffer.
+     */
+    prebufferMs?: number;
+    /**
+     * When `provider` is `'runtype'`, an optional factory for the streaming PCM
+     * player that synthesizes read-aloud / auto-speak audio. Defaults to the
+     * in-bundle, main-thread `AudioPlaybackManager` (smooth for steady Runtype
+     * streams, no AudioWorklet — keeps the widget bundle lean).
+     *
+     * For the higher-quality, jitter-buffered AudioWorklet player, import
+     * `createPcmStreamPlayer` from `@runtypelabs/persona/voice-worklet-player` and
+     * pass it here — it then ships in your bundle, not Persona's:
+     *
+     * @example
+     * import { createPcmStreamPlayer } from '@runtypelabs/persona/voice-worklet-player'
+     * textToSpeech: {
+     *   enabled: true,
+     *   provider: 'runtype',
+     *   createPlaybackEngine: () => createPcmStreamPlayer({ prebufferMs: 400 }),
+     * }
+     */
+    createPlaybackEngine?: () => PcmStreamPlayer | Promise<PcmStreamPlayer>;
     /** Voice name to use for browser TTS (e.g., 'Google US English'). If not found, uses auto-detect. */
     voice?: string;
     /**
@@ -3750,7 +3860,73 @@ type TextToSpeechConfig = {
     rate?: number;
     /** Speech pitch (0 - 2). Default: 1 */
     pitch?: number;
+    /**
+     * Factory for a custom {@link SpeechEngine}, used by both the auto-speak path
+     * and the per-message "Read aloud" action. When omitted, the browser Web
+     * Speech API engine is used. Return a hosted engine here to use server-side
+     * TTS (e.g. Runtype) — such an engine can stream audio through the realtime
+     * voice {@link VoicePlaybackEngine}. May be async (it is resolved on first
+     * playback, inside the user gesture).
+     */
+    createEngine?: () => SpeechEngine | Promise<SpeechEngine>;
 };
+/**
+ * Playback state of the per-message "Read aloud" action.
+ * - `idle`: not reading this message.
+ * - `loading`: the engine is preparing audio (e.g. a hosted TTS fetch). Browser
+ *   engines pass through this state almost instantly.
+ * - `playing`: audio is playing.
+ * - `paused`: playback is paused and resumable.
+ */
+type ReadAloudState = "idle" | "loading" | "playing" | "paused";
+/** A unit of speech handed to a {@link SpeechEngine}. */
+interface SpeechRequest {
+    /** Plain text to speak. The widget strips Markdown before calling the engine. */
+    text: string;
+    /** Preferred voice identifier (engine-specific; browser = voice name). */
+    voice?: string;
+    /** Speech rate (engine-specific range; browser: 0.1–10, default 1). */
+    rate?: number;
+    /** Speech pitch (engine-specific range; browser: 0–2, default 1). */
+    pitch?: number;
+}
+/** Lifecycle callbacks a {@link SpeechEngine} invokes during playback. */
+interface SpeechCallbacks {
+    /** Audio has started playing. */
+    onStart?: () => void;
+    /** Playback finished naturally (or was canceled). */
+    onEnd?: () => void;
+    /** Playback failed. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Pluggable text-to-speech engine behind the "Read aloud" message action.
+ *
+ * The widget ships a browser Web Speech API engine by default. Provide a hosted
+ * engine (Runtype TTS, ElevenLabs, a server proxy, …) by implementing this
+ * interface and returning it from {@link TextToSpeechConfig.createEngine}; a
+ * server engine can stream audio into the realtime voice
+ * {@link VoicePlaybackEngine}.
+ */
+interface SpeechEngine {
+    /** Stable identifier, e.g. `"browser"`, `"runtype"`, or a custom id. */
+    readonly id: string;
+    /**
+     * Whether {@link pause}/{@link resume} are supported. When `false`, the UI
+     * offers play/stop only (tapping a playing message stops it).
+     */
+    readonly supportsPause: boolean;
+    /** Begin speaking. Drives the lifecycle through `callbacks`. */
+    speak(request: SpeechRequest, callbacks: SpeechCallbacks): void;
+    /** Pause playback (no-op if unsupported). */
+    pause(): void;
+    /** Resume paused playback (no-op if unsupported). */
+    resume(): void;
+    /** Stop playback and discard any queued audio. */
+    stop(): void;
+    /** Optional teardown of engine resources. */
+    destroy?(): void;
+}
 /**
  * Voice recognition result with transcript and optional audio
  */
@@ -3770,6 +3946,66 @@ type VoiceResult = {
  * Voice provider status states
  */
 type VoiceStatus = 'disconnected' | 'connected' | 'listening' | 'processing' | 'speaking' | 'error' | 'idle';
+/**
+ * Per-turn latency metrics emitted by the realtime voice path.
+ * The wire frame is snake_case (`metrics`); decoded to camelCase at the
+ * provider boundary before being surfaced through `onMetrics`.
+ */
+type VoiceMetrics = {
+    /** LLM generation time (ms). */
+    llmMs?: number;
+    /** Text-to-speech synthesis time (ms). */
+    ttsMs?: number;
+    /** Time to first audio frame (ms). */
+    firstAudioMs?: number;
+    /** Total turn time (ms). */
+    totalMs?: number;
+};
+/**
+ * Streaming PCM playback engine used by the realtime voice provider.
+ *
+ * The provider feeds raw PCM16 LE mono @ 24kHz (WAV header already stripped)
+ * via `enqueue`, signals end-of-reply with `markStreamEnd`, and learns when
+ * playback has fully drained via `onFinished`. The default implementation is
+ * `AudioPlaybackManager`; an optional jitter-buffered AudioWorklet engine ships
+ * from `@runtypelabs/persona/voice-worklet-player` and can be injected via the
+ * `runtype.createPlaybackEngine` config hook.
+ */
+interface VoicePlaybackEngine {
+    /** Enqueue a raw PCM16 LE mono @ 24kHz chunk (no WAV header). */
+    enqueue(pcm: Uint8Array): void;
+    /** Signal that no more chunks will arrive for the current reply. */
+    markStreamEnd(): void;
+    /** Immediately stop playback and discard queued audio. */
+    flush(): void;
+    /** Register a callback fired once all queued audio has finished playing. */
+    onFinished(callback: () => void): void;
+    /** Release all audio resources. */
+    destroy(): Promise<void> | void;
+}
+/**
+ * A {@link VoicePlaybackEngine} that also supports pause/resume. Returned by
+ * `createPcmStreamPlayer` (`@runtypelabs/persona/voice-worklet-player`): a
+ * jitter-buffered AudioWorklet player for raw PCM16 / 24 kHz / mono streams.
+ * Reuse it inside a hosted {@link SpeechEngine} to get gapless playback with a
+ * configurable prebuffer and graceful underrun handling — feed each streamed
+ * chunk to {@link VoicePlaybackEngine.enqueue} and the worklet does the rest.
+ */
+interface PcmStreamPlayer extends VoicePlaybackEngine {
+    /** Pause playback; the audio clock suspends and {@link resume} continues in place. */
+    pause(): void;
+    /** Resume playback after {@link pause}. */
+    resume(): void;
+    /**
+     * Register a callback fired once audible playback actually begins — i.e. the
+     * prebuffer waterline filled and the first sample reached the output. Use this
+     * (rather than "first chunk enqueued") to flip a UI from loading to playing, so
+     * the spinner holds through the prebuffer. Fires once per playback session
+     * (cleared by {@link VoicePlaybackEngine.flush}); a mid-reply underrun re-buffer
+     * does not re-fire it.
+     */
+    onStarted(callback: () => void): void;
+}
 /**
  * Voice provider configuration
  * Determines which voice provider to use and its specific settings
@@ -3782,15 +4018,29 @@ type VoiceConfig = {
     };
     runtype?: {
         agentId: string;
-        clientToken: string;
+        /** Defaults to the widget's `clientToken` when omitted. */
+        clientToken?: string;
+        /** Defaults to the widget's `apiUrl` (as a ws(s):// base) when omitted. */
         host?: string;
         voiceId?: string;
-        /** Duration of silence (ms) before auto-stopping recording. Default: 2000 */
+        /**
+         * Optional custom streaming playback engine. Defaults to the built-in
+         * `AudioPlaybackManager`. Import `createWorkletPlaybackEngine` from
+         * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
+         */
+        createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+        /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
         pauseDuration?: number;
-        /** RMS volume threshold below which counts as silence. Default: 0.01 */
+        /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
         silenceThreshold?: number;
     };
-    custom?: any;
+    /**
+     * Bring-your-own voice provider for `type: 'custom'`: either a ready
+     * {@link VoiceProvider} instance or a `() => VoiceProvider` factory. The
+     * factory form defers construction (WebSocket/AudioContext/etc.) until
+     * `createVoiceProvider` runs.
+     */
+    custom?: VoiceProvider | (() => VoiceProvider);
 };
 /**
  * Voice provider interface
@@ -3807,11 +4057,21 @@ interface VoiceProvider {
     onStatusChange(callback: (status: VoiceStatus) => void): void;
     /** Register a callback fired when recording stops and audio is about to be sent */
     onProcessingStart?(callback: () => void): void;
+    /**
+     * Register a callback for incremental transcript updates during a voice turn.
+     * `isFinal=false` is a live interim update (user partials, or assistant deltas
+     * on providers that stream them); `isFinal=true` finalizes that role's text.
+     * On the realtime `runtype` path, interim updates fire for the `user` only and
+     * the `assistant` arrives as a single final.
+     */
+    onTranscript?(callback: (role: 'user' | 'assistant', text: string, isFinal: boolean) => void): void;
+    /** Register a callback for per-turn latency metrics (realtime path). */
+    onMetrics?(callback: (metrics: VoiceMetrics) => void): void;
     /** Returns the current interruption mode (only meaningful for Runtype provider) */
     getInterruptionMode?(): "none" | "cancel" | "barge-in";
     /** Returns true if the barge-in mic stream is alive (hot mic between turns) */
     isBargeInActive?(): boolean;
-    /** Tear down the barge-in mic pipeline — "hang up" the always-on mic */
+    /** Tear down the barge-in mic pipeline: "hang up" the always-on mic */
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
@@ -3824,7 +4084,7 @@ type AgentWidgetApprovalDecisionOptions = {
     /**
      * The user chose a "remember this" affordance (e.g. an "Always allow"
      * button) rather than a one-time decision. The widget resolves the *current*
-     * approval identically whether or not this is set — an approval bubble is a
+     * approval identically whether or not this is set: an approval bubble is a
      * single binary gate (`approved`/`denied`). Persisting a don't-ask-again
      * policy for *future* approvals (auto-resolving them, or not surfacing them)
      * is the integrator's responsibility, typically inside `onDecision`.
@@ -3878,9 +4138,9 @@ type AgentWidgetApprovalConfig = {
     /**
      * How the technical details (the tool's agent-facing description and the
      * raw parameters JSON) are presented:
-     * - `"collapsed"` (default) — hidden behind a "Show details" toggle
-     * - `"expanded"` — visible, with the toggle available to hide them
-     * - `"hidden"` — never rendered
+     * - `"collapsed"` (default): hidden behind a "Show details" toggle
+     * - `"expanded"`: visible, with the toggle available to hide them
+     * - `"hidden"`: never rendered
      */
     detailsDisplay?: "collapsed" | "expanded" | "hidden";
     /** Label for the toggle that reveals the technical details */
@@ -3902,7 +4162,7 @@ type AgentWidgetApprovalConfig = {
         displayTitle?: string;
         /**
          * Agent-authored justification for this specific call, when the agent
-         * provided one. It is the agent's own claim — if you fold it into the
+         * provided one. It is the agent's own claim: if you fold it into the
          * summary, keep it attributed to the agent.
          */
         reason?: string;
@@ -4008,7 +4268,7 @@ type AgentWidgetToolCallConfig = {
      *
      * **Placeholders:** `{toolName}` (tool name), `{duration}` (live-updating elapsed time).
      *
-     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — parsed at render time and
+     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: parsed at render time and
      * applied as styled `<span>` elements. Works with all animation modes.
      *
      * When not set, falls back to the current `collapsedMode` behavior.
@@ -4021,7 +4281,7 @@ type AgentWidgetToolCallConfig = {
      *
      * **Placeholders:** `{toolName}` (tool name), `{duration}` (final elapsed time).
      *
-     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — same syntax as `activeTextTemplate`.
+     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: same syntax as `activeTextTemplate`.
      *
      * When not set, falls back to the existing "Used tool for X seconds" text.
      * @example "Finished {toolName} ~{duration}~"
@@ -4082,7 +4342,7 @@ type AgentWidgetReasoningConfig = {
      *
      * **Placeholders:** `{duration}` (live-updating elapsed time).
      *
-     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — parsed at render time.
+     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: parsed at render time.
      *
      * When not set, falls back to the default "Thinking..." text.
      * @example "Thinking... ~{duration}~"
@@ -4093,7 +4353,7 @@ type AgentWidgetReasoningConfig = {
      *
      * **Placeholders:** `{duration}` (final elapsed time).
      *
-     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**` — same syntax as `activeTextTemplate`.
+     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: same syntax as `activeTextTemplate`.
      *
      * When not set, falls back to the default "Thought for X seconds" text.
      * @example "Thought for ~{duration}~"
@@ -4192,7 +4452,7 @@ type AgentWidgetSSEEventResult = {
     done?: boolean;
     /** Error message if an error occurred */
     error?: string;
-    /** Text segment identity — when this changes, a new assistant message bubble is created */
+    /** Text segment identity: when this changes, a new assistant message bubble is created */
     partId?: string;
 } | null;
 /**
@@ -4264,7 +4524,7 @@ type ClientChatRequest = {
     /** Per-turn inputs for Runtype prompt templates (e.g. {{page_url}}). */
     inputs?: Record<string, unknown>;
     context?: Record<string, unknown>;
-    /** WebMCP page-discovered tools — same shape as `dispatch.clientTools[]`. */
+    /** WebMCP page-discovered tools: same shape as `dispatch.clientTools[]`. */
     clientTools?: ClientToolDefinition[];
     /**
      * Diff-only / send-once: order-independent fingerprint of the client tool set.
@@ -5237,7 +5497,7 @@ type AgentWidgetConfig = {
          * Per-stop-reason copy for the inline notice rendered on assistant
          * bubbles when the runtime reports a non-natural stop (e.g. the agent
          * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
-         * optional — keys you omit fall back to the built-in defaults. Set a
+         * optional: keys you omit fall back to the built-in defaults. Set a
          * key to an empty string to suppress the notice for that reason.
          */
         stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
@@ -5330,12 +5590,12 @@ type AgentWidgetConfig = {
      */
     approval?: AgentWidgetApprovalConfig | false;
     /**
-     * WebMCP — consume page-registered tools (`document.modelContext.registerTool`).
+     * WebMCP: consume page-registered tools (`document.modelContext.registerTool`).
      * When `enabled`, the widget installs `@mcp-b/webmcp-polyfill`, snapshots the
      * registry on every dispatch, ships it as `clientTools[]`, and executes
      * returned `webmcp:*` tool calls with confirm-by-default gating.
      *
-     * Server-side policy on the chat surface is the source of truth — these
+     * Server-side policy on the chat surface is the source of truth: these
      * fields layer on top.
      *
      * @example
@@ -5369,7 +5629,7 @@ type AgentWidgetConfig = {
      * This hook runs synchronously and must return the (potentially modified) state.
      *
      * Returning `{ state, open: true }` also signals that the widget panel should
-     * open after initialization — useful when injecting a post-navigation message
+     * open after initialization: useful when injecting a post-navigation message
      * that the user should immediately see.
      *
      * @example
@@ -5688,7 +5948,7 @@ type AgentWidgetConfig = {
      * Setting this to `false` is the explicit kill-switch: it disables UI-state
      * persistence **and** message-history persistence. When `false`, any
      * `storageAdapter` you configure is ignored and the default localStorage
-     * adapter is not created — no chat history is read or written. Pass `true`
+     * adapter is not created: no chat history is read or written. Pass `true`
      * (or omit) to keep the default behavior of persisting messages via the
      * configured `storageAdapter` (or the built-in localStorage adapter).
      *
@@ -5717,7 +5977,7 @@ type AgentWidgetConfig = {
      *
      * @example
      * ```typescript
-     * // Ephemeral widget — no message history written anywhere
+     * // Ephemeral widget: no message history written anywhere
      * config: {
      *   persistState: false
      * }
@@ -5784,7 +6044,7 @@ type AgentWidgetApproval = {
      * Agent-authored justification for this specific call (the agent's own
      * claim about its intent, extracted server-side from the reserved
      * `_approvalReason` parameter). Render it attributed to the agent and as
-     * plain text — it is approver context, not a system statement.
+     * plain text: it is approver context, not a system statement.
      */
     reason?: string;
     parameters?: unknown;
@@ -5794,16 +6054,16 @@ type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval"
 /**
  * Per-turn / per-step stop reason emitted by the runtime on
  * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
- * owned by the upstream Runtype API — do not extend without coordination.
+ * owned by the upstream Runtype API: do not extend without coordination.
  *
- * - `end_turn` — natural completion (no affordance needed)
- * - `max_tool_calls` — agent loop tripped the configured tool-call ceiling
- * - `length` — provider hit max output tokens
- * - `content_filter` — provider content filter intervened
- * - `error` — provider/runtime error (prefer existing error rendering)
- * - `unknown` — explicitly reported but uninformative
+ * - `end_turn`: natural completion (no affordance needed)
+ * - `max_tool_calls`: agent loop tripped the configured tool-call ceiling
+ * - `length`: provider hit max output tokens
+ * - `content_filter`: provider content filter intervened
+ * - `error`: provider/runtime error (prefer existing error rendering)
+ * - `unknown`: explicitly reported but uninformative
  *
- * Absent (`undefined`) means "not reported" — distinct from `'unknown'`.
+ * Absent (`undefined`) means "not reported": distinct from `'unknown'`.
  */
 type StopReasonKind = RuntypeStopReasonKind;
 /**
@@ -5973,7 +6233,7 @@ type InjectMessageOptions = {
     voiceProcessing?: boolean;
     /**
      * Raw structured payload (typically a JSON string) representing the
-     * full directive that produced this message — e.g. `{ "text": "...",
+     * full directive that produced this message: e.g. `{ "text": "...",
      * "component": "Foo", "props": {...} }`.
      *
      * Mirrors the field populated by stream parsers during normal LLM
@@ -6005,7 +6265,7 @@ type InjectUserMessageOptions = Omit<InjectMessageOptions, "role">;
 type InjectSystemMessageOptions = Omit<InjectMessageOptions, "role">;
 /**
  * Options for injecting an assistant message that renders as a component
- * directive — sugar over `injectAssistantMessage` for the common case of
+ * directive: sugar over `injectAssistantMessage` for the common case of
  * "render this registered component, same as if the LLM had emitted it".
  *
  * Equivalent to calling `injectAssistantMessage({ content: text, rawContent:
@@ -6146,8 +6406,8 @@ declare class AgentWidgetClient {
      * Refresh config in place WITHOUT tearing down the live connection or the
      * WebMCP bridge. `AgentWidgetSession.updateConfig` calls this when only
      * connection-irrelevant fields changed (theme, copy, layout, suggestions, …),
-     * so a UI update that lands mid-turn — e.g. a `webmcp:*` tool restyling the
-     * widget while the agent's turn is still streaming — doesn't abandon the
+     * so a UI update that lands mid-turn: e.g. a `webmcp:*` tool restyling the
+     * widget while the agent's turn is still streaming: doesn't abandon the
      * in-flight stream/resume. Connection or request-shaping changes (apiUrl,
      * clientToken, webmcp, headers, parser, …) take the full client rebuild path
      * in the session instead, which is the only place the bridge is recreated.
@@ -6155,7 +6415,7 @@ declare class AgentWidgetClient {
      * Only the live-read `config` is refreshed (e.g. `iterationDisplay`); the
      * constructor-derived request-shaping fields (apiUrl, headers, parser,
      * contextProviders, middleware, …) are left untouched because the session
-     * routes any change to those down the full-rebuild path instead — so they are
+     * routes any change to those down the full-rebuild path instead, so they are
      * guaranteed unchanged here. The `webMcpBridge` instance and its
      * installed-polyfill memo are deliberately preserved, which keeps any
      * in-flight resolve alive.
@@ -6182,7 +6442,7 @@ declare class AgentWidgetClient {
      * WebMCP: execute a returned `webmcp:<name>` tool call against the page's
      * registry and return the normalized MCP-shaped result for `/resume`. The
      * bridge handles confirm-bubble gating, the 30s timeout, error
-     * normalization, and `signal`-driven abort — callers never see throws.
+     * normalization, and `signal`-driven abort: callers never see throws.
      *
      * Returns `null` when WebMCP is not enabled on this client (signal to the
      * session that it should fall back to the legacy local-tool resume path,
@@ -6326,10 +6586,10 @@ declare class AgentWidgetClient {
      * Routes by mode:
      *  - **client-token mode**: POST `${apiBase}/v1/client/resume` (the
      *    session-authenticated sibling of `/v1/client/chat`; runtypelabs/core#3889),
-     *    with the active `sessionId` in the body and no Bearer key — a browser
+     *    with the active `sessionId` in the body and no Bearer key: a browser
      *    client-token page holds no secret. `clientTools` are already persisted
      *    server-side from the dispatch turn, so only `toolOutputs` is re-sent.
-     *  - **dispatch / proxy mode**: POST `${apiUrl}/resume` — Runtype mounts
+     *  - **dispatch / proxy mode**: POST `${apiUrl}/resume`: Runtype mounts
      *    resume as a child of `/v1/dispatch`, so the URL is `${apiUrl}/resume`,
      *    and proxies follow the same shape (`/api/chat/dispatch/resume`).
      *
@@ -6354,6 +6614,75 @@ declare class AgentWidgetClient {
     private streamResponse;
 }
 
+declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
+declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
+declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
+
+/**
+ * Pick the best available English voice from the browser's voice list.
+ * Prefers high-quality remote/natural voices, then enhanced local voices,
+ * then standard local voices, then any English voice, then the first voice.
+ */
+declare function pickBestVoice(voices: SpeechSynthesisVoice[]): SpeechSynthesisVoice;
+interface BrowserSpeechEngineOptions {
+    /** Custom voice picker, used when no exact `voice` name is requested. */
+    pickVoice?: (voices: SpeechSynthesisVoice[]) => SpeechSynthesisVoice;
+}
+/** Default `SpeechEngine` backed by the browser Web Speech API. */
+declare class BrowserSpeechEngine implements SpeechEngine {
+    private options;
+    readonly id = "browser";
+    readonly supportsPause = true;
+    constructor(options?: BrowserSpeechEngineOptions);
+    /** Whether the Web Speech API is available in this environment. */
+    static isSupported(): boolean;
+    speak(request: SpeechRequest, callbacks: SpeechCallbacks): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+}
+
+interface FallbackSpeechEngineOptions {
+    /**
+     * Called once when the primary engine fails before audio starts and the
+     * fallback takes over — so a silent downgrade is still observable in dev/
+     * telemetry even though the user keeps hearing speech.
+     */
+    onFallback?: (error: Error) => void;
+}
+
+type ReadAloudListener = (activeId: string | null, state: ReadAloudState) => void;
+declare class ReadAloudController {
+    private resolveEngine;
+    private engine;
+    private activeId;
+    private state;
+    private listeners;
+    private generation;
+    constructor(resolveEngine: () => SpeechEngine | Promise<SpeechEngine> | null);
+    /** Whether the active engine supports pause/resume (vs. stop-only). */
+    get supportsPause(): boolean;
+    /** Playback state for a message id (`idle` unless it's the active message). */
+    stateFor(id: string): ReadAloudState;
+    /** The message currently being read aloud, if any. */
+    activeMessageId(): string | null;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    onChange(listener: ReadAloudListener): () => void;
+    /**
+     * Primary entry point for the button: cycle this message through
+     * play → pause → resume (or play → stop when the engine can't pause), and
+     * start fresh when a different message is requested.
+     */
+    toggle(id: string, request: SpeechRequest): void;
+    /** Start (or restart) playback for a message, stopping any current playback. */
+    play(id: string, request: SpeechRequest): Promise<void>;
+    /** Stop playback and return to idle. */
+    stop(): void;
+    /** Drop the controller and its engine (called on widget teardown). */
+    destroy(): void;
+    private set;
+}
+
 type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error";
 type SessionCallbacks = {
     onMessagesChanged: (messages: AgentWidgetMessage[]) => void;
@@ -6390,6 +6719,16 @@ declare class AgentWidgetSession {
     private voiceActive;
     private voiceStatus;
     constructor(config: AgentWidgetConfig | undefined, callbacks: SessionCallbacks);
+    /**
+     * Warm the deferred Runtype TTS engine chunk at init so it's resolved before
+     * the first "Read aloud" click. Module fetch only — no AudioContext (that
+     * still waits for the user gesture on first playback). In the IIFE/CDN build
+     * this fetches the standalone `runtype-tts.js`; in bundler builds the module
+     * is already inlined, so this is a cheap no-op. Errors are swallowed: a failed
+     * prefetch just means the chunk loads on first click instead (or, on a hard
+     * failure, the browser-voice fallback kicks in).
+     */
+    private prefetchRuntypeTts;
     /**
      * Set callback for capturing raw SSE events (forwards to client)
      */
@@ -6433,11 +6772,24 @@ declare class AgentWidgetSession {
     stopVoicePlayback(): void;
     /** Returns true if the barge-in mic stream is alive (hot mic between turns) */
     isBargeInActive(): boolean;
-    /** Tear down the barge-in mic pipeline — "hang up" the always-on mic */
+    /** Tear down the barge-in mic pipeline: "hang up" the always-on mic */
     deactivateBargeIn(): Promise<void>;
     private pendingVoiceUserMessageId;
     private pendingVoiceAssistantMessageId;
     private ttsSpokenMessageIds;
+    private readAloud;
+    /**
+     * Resolve the speech engine behind read-aloud (and auto-speak):
+     *   1. An explicit `textToSpeech.createEngine` always wins (full BYO control).
+     *   2. `provider: 'runtype'` builds the hosted {@link RuntypeSpeechEngine}
+     *      from the widget config (host = `apiUrl`, `agentId`, `clientToken`),
+     *      wrapped in a browser {@link FallbackSpeechEngine} unless
+     *      `browserFallback: false` — so a missing endpoint or transient failure
+     *      degrades to the browser voice instead of erroring, and auto-upgrades to
+     *      Runtype voices the day the endpoint ships.
+     *   3. Otherwise the browser Web Speech API engine.
+     */
+    private createSpeechEngine;
     /**
      * Setup voice recognition with the given configuration
      */
@@ -6584,7 +6936,7 @@ declare class AgentWidgetSession {
     injectMessageBatch(optionsList: InjectMessageOptions[]): AgentWidgetMessage[];
     /**
      * Convenience method for injecting a registered component directive as
-     * an assistant message — the same shape Persona produces from a streamed
+     * an assistant message: the same shape Persona produces from a streamed
      * `{ "text": "...", "component": "...", "props": {...} }` payload.
      *
      * Sets `content` to `text`, `rawContent` to the JSON directive (so
@@ -6679,7 +7031,7 @@ declare class AgentWidgetSession {
      * Flip an `ask_user_question` tool message from awaiting → answered so
      * render passes stop re-mounting its answer-pill sheet. Idempotent.
      * When `answers` is provided, persists the full structured answer Record
-     * atomically with the answered flag — guarding against later events that
+     * atomically with the answered flag: guarding against later events that
      * could re-emit the tool message and clobber the per-pick persisted
      * answers via top-level merge.
      */
@@ -6700,17 +7052,17 @@ declare class AgentWidgetSession {
      * before a resolve grabs it.
      *
      * Awaits without an `executionId` or `toolCall.id` can't be batched (no key)
-     * — route them straight to the single-call path, which surfaces the malformed
+     *: route them straight to the single-call path, which surfaces the malformed
      * wire shape via `onError` / an `isError` resume.
      */
     private enqueueWebMcpAwait;
     /**
      * Flush every buffered local-tool await batch, one `/resume` per executionId.
-     * Called once a stream ends (`status: idle` / `error`) — by then all parallel
+     * Called once a stream ends (`status: idle` / `error`): by then all parallel
      * `step_await`s the stream carried have been collected, even if split across
      * SSE chunks. Deferred via `queueMicrotask` (epoch-guarded) so the idle
      * handler returns first and the stream's end-of-stream teardown (streaming /
-     * abortController) settles before a resolve grabs them — the same ordering the
+     * abortController) settles before a resolve grabs them: the same ordering the
      * single-call resolve always relied on.
      */
     private scheduleWebMcpBatchFlush;
@@ -6728,7 +7080,7 @@ declare class AgentWidgetSession {
      * Persisted-resolution guard for `suggest_replies`. The in-memory dedupe
      * sets (`webMcpInflightKeys` / `webMcpResolvedKeys`) are cleared by
      * hydrateMessages/clearMessages/cancel, but `suggestRepliesResolved`
-     * survives on the stored message — so a stale `step_await` re-emit after a
+     * survives on the stored message, so a stale `step_await` re-emit after a
      * hydration must not re-POST `/resume` for an already-resolved call (the
      * historical double-resume failure mode the batching work exists to avoid).
      * Checks the LIVE message first; the handleEvent snapshot is a fresh wire
@@ -6740,7 +7092,7 @@ declare class AgentWidgetSession {
     /**
      * Resolve TWO OR MORE parallel local-tool awaits sharing one paused
      * executionId with a SINGLE `/resume` (core#3878). Each call is executed
-     * against the page registry concurrently — every gated call renders its own
+     * against the page registry concurrently: every gated call renders its own
      * native approval bubble, and a sibling's confirm Promise never blocks
      * another's execution. Outputs are keyed by per-call `webMcpToolCallId`
      * (server prefers it over tool name; name-keying remains the fallback for
@@ -6760,13 +7112,13 @@ declare class AgentWidgetSession {
      * list, not from this resolve).
      *
      * Triggered automatically from `handleEvent` when a `step_await`-derived
-     * message arrives for such a tool — the user does not click a pill; the
+     * message arrives for such a tool: the user does not click a pill; the
      * bridge's confirm-bubble gate (WebMCP only) is the only interactive
      * surface.
      *
      * Idempotent on the message's `toolCall.id`: re-emits of the same step_await
      * (e.g. from message coalescing) won't double-fire `tool.execute`. Failure
-     * modes — declined, timed out, throw, unknown tool — all resolve into a
+     * modes, declined, timed out, throw, unknown tool, all resolve into a
      * `{ isError: true, content: [...] }` payload that resumes the dispatch
      * cleanly so the agent can recover.
      */
@@ -6789,8 +7141,7 @@ declare class AgentWidgetSession {
      * resolve owns a dedicated AbortController (chained/parallel resolves don't
      * share one), so we abort them individually; the aborts propagate into the
      * bridge's execute race and into each `/resume` fetch signal. Bumping
-     * `webMcpEpoch` strands any resolve still deferred in a queued microtask —
-     * it captured the prior epoch and bails before installing a fresh
+     * `webMcpEpoch` strands any resolve still deferred in a queued microtask:   * it captured the prior epoch and bails before installing a fresh
      * controller, so it can't escape this teardown. Called from every stop /
      * new-turn boundary (cancel, clearMessages, hydrateMessages, sendMessage).
      */
@@ -6816,19 +7167,26 @@ declare class AgentWidgetSession {
      * if text-to-speech is enabled in the config.
      */
     private speakLatestAssistantMessage;
-    /**
-     * Speak text using the Web Speech API.
-     * Cancels any in-progress speech before starting.
-     */
-    private speak;
     /**
      * Pick the best available English voice from a list of SpeechSynthesisVoices.
      * Prefers high-quality remote/natural voices, then enhanced local voices,
-     * then standard local voices.
+     * then standard local voices. Retained for backwards compatibility; delegates
+     * to the browser speech engine's picker.
      */
     static pickBestVoice(voices: SpeechSynthesisVoice[]): SpeechSynthesisVoice;
     /**
-     * Stop any in-progress text-to-speech playback.
+     * Toggle the per-message "Read aloud" action: play → pause → resume (or
+     * play → stop when the engine can't pause). Speaks the assistant message's
+     * text via the configured speech engine (browser Web Speech API by default,
+     * or a hosted engine from `textToSpeech.createEngine`).
+     */
+    toggleReadAloud(messageId: string): void;
+    /** Current read-aloud playback state for a message (`idle` unless active). */
+    getReadAloudState(messageId: string): ReadAloudState;
+    /** Subscribe to read-aloud state changes. Returns an unsubscribe function. */
+    onReadAloudChange(listener: ReadAloudListener): () => void;
+    /**
+     * Stop any in-progress text-to-speech / read-aloud playback.
      */
     stopSpeaking(): void;
     private appendMessage;
@@ -6928,7 +7286,7 @@ type Controller = {
     injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
     /**
      * Convenience method for injecting an assistant message that renders as a
-     * registered component — same shape Persona produces from a streamed
+     * registered component: same shape Persona produces from a streamed
      * `{ "text": "...", "component": "...", "props": {...} }` payload.
      */
     injectComponentDirective: (options: InjectComponentDirectiveOptions) => AgentWidgetMessage;
@@ -6944,6 +7302,10 @@ type Controller = {
     off: <K extends keyof AgentWidgetControllerEventMap>(event: K, handler: (payload: AgentWidgetControllerEventMap[K]) => void) => void;
     isOpen: () => boolean;
     isVoiceActive: () => boolean;
+    toggleReadAloud: (messageId: string) => void;
+    stopReadAloud: () => void;
+    getReadAloudState: (messageId: string) => ReadAloudState;
+    onReadAloudChange: (listener: (activeId: string | null, state: ReadAloudState) => void) => () => void;
     getState: () => AgentWidgetStateSnapshot;
     showCSATFeedback: (options?: Partial<CSATFeedbackOptions>) => void;
     showNPSFeedback: (options?: Partial<NPSFeedbackOptions>) => void;
@@ -7007,7 +7369,7 @@ declare const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
 declare const isAskUserQuestionMessage: (message: AgentWidgetMessage) => boolean;
 /**
  * Parse an `ask_user_question` tool-variant message into a partial payload.
- * Safe to call mid-stream — will walk the tool call's `chunks` via
+ * Safe to call mid-stream: will walk the tool call's `chunks` via
  * `partial-json` and return `{ payload: null, complete: false }` when there
  * isn't enough data yet. `complete` flips to `true` once the tool call
  * reports status `"complete"`.
@@ -7020,13 +7382,13 @@ declare const parseAskUserQuestionPayload: (message: AgentWidgetMessage) => {
 };
 /**
  * Create the small in-transcript stub for an `ask_user_question` tool call.
- * The stub is passive — the interactive sheet is mounted separately into
+ * The stub is passive: the interactive sheet is mounted separately into
  * the composer overlay via `ensureAskUserQuestionSheet`.
  */
 declare const createAskUserQuestionBubble: (message: AgentWidgetMessage, config?: AgentWidgetConfig) => HTMLElement;
 /**
  * Mount or update the interactive answer-pill sheet for a given message.
- * Idempotent — if a sheet already exists for the tool-call id, it is hydrated
+ * Idempotent: if a sheet already exists for the tool-call id, it is hydrated
  * in-place instead of remounted, so streaming updates don't flicker.
  */
 declare const ensureAskUserQuestionSheet: (message: AgentWidgetMessage, config: AgentWidgetConfig | undefined, overlay: HTMLElement | null | undefined) => void;
@@ -7040,7 +7402,7 @@ declare const removeAskUserQuestionSheet: (overlay: HTMLElement | null | undefin
  * Built-in `ask_user_question` client tool.
  *
  * The widget can advertise this tool to the agent on every dispatch via
- * `clientTools[]` (set `features.askUserQuestion.expose: true`) — the same
+ * `clientTools[]` (set `features.askUserQuestion.expose: true`): the same
  * wire surface WebMCP page tools ride. The server registers it as a LOCAL
  * tool under its bare name (`origin: 'sdk'` tools are not `webmcp:`-prefixed),
  * so when the model calls it the execution pauses with a `step_await`
@@ -7051,13 +7413,12 @@ declare const removeAskUserQuestionSheet: (overlay: HTMLElement | null | undefin
  * This replaces the previous integrator burden of hand-declaring the tool in
  * a flow's `runtimeTools` and keeping that schema in sync with the renderer.
  * Flows that already declare `ask_user_question` server-side should leave
- * `expose` off — the model would otherwise see the tool twice.
+ * `expose` off: the model would otherwise see the tool twice.
  */
 
 /**
  * JSON Schema for the tool's parameters. Mirrors {@link AskUserQuestionPayload}
- * — the shape `parseAskUserQuestionPayload` hydrates the answer sheet from —
- * so the schema the model is held to and the schema the renderer expects can
+ *, the shape `parseAskUserQuestionPayload` hydrates the answer sheet from,  * so the schema the model is held to and the schema the renderer expects can
  * never drift.
  */
 declare const ASK_USER_QUESTION_PARAMETERS_SCHEMA: {
@@ -7084,7 +7445,7 @@ declare const ASK_USER_QUESTION_PARAMETERS_SCHEMA: {
                         readonly type: "array";
                         readonly minItems: 2;
                         readonly maxItems: 4;
-                        readonly description: "2-4 distinct choices. Do NOT add an \"Other\" option — free text is automatic.";
+                        readonly description: "2-4 distinct choices. Do NOT add an \"Other\" option: free text is automatic.";
                         readonly items: {
                             readonly type: "object";
                             readonly properties: {
@@ -7132,8 +7493,7 @@ declare const ASK_USER_QUESTION_CLIENT_TOOL: ClientToolDefinition;
  *
  * Each tool is gated on BOTH of its feature flags: `expose` opts the tool
  * into the agent's catalog, and `enabled !== false` guarantees the widget can
- * actually render UI (and, for fire-and-forget tools, auto-resume) for it —
- * exposing a tool with its feature disabled would park the execution on a
+ * actually render UI (and, for fire-and-forget tools, auto-resume) for it: * exposing a tool with its feature disabled would park the execution on a
  * generic tool bubble with no way to advance.
  */
 declare const builtInClientToolsForDispatch: (config: AgentWidgetConfig | undefined) => ClientToolDefinition[];
@@ -7142,11 +7502,11 @@ declare const builtInClientToolsForDispatch: (config: AgentWidgetConfig | undefi
  * Built-in `suggest_replies` client tool.
  *
  * The widget can advertise this tool to the agent on every dispatch via
- * `clientTools[]` (set `features.suggestReplies.expose: true`) — the same
+ * `clientTools[]` (set `features.suggestReplies.expose: true`): the same
  * wire surface as `ask_user_question` and WebMCP page tools. When the model
  * calls it, the execution pauses with a `step_await`
  * (`awaitReason: "local_tool_required"`); unlike `ask_user_question`, the
- * widget resolves it FIRE-AND-FORGET — it renders the suggestions as tappable
+ * widget resolves it FIRE-AND-FORGET: it renders the suggestions as tappable
  * chips above the composer and immediately resumes the execution with a
  * canned "shown" result, so the agent's turn completes without waiting on the
  * user. Tapping a chip sends its text verbatim as the user's next message.
@@ -7237,15 +7597,15 @@ declare const createWidgetHostLayout: (target: HTMLElement, config?: AgentWidget
  * with no MCP-B-only extensions. The spec standardizes the *producer* side;
  * Persona is an in-page *consumer*, so it reads the registry via the
  * producer-facing preview API:
- *   - `getTools()` — async; returns `{ name, description, inputSchema }` where
+ *   - `getTools()`: async; returns `{ name, description, inputSchema }` where
  *     `inputSchema` is a JSON *string*. Annotations are not exposed here.
- *   - `executeTool(toolInfo, inputArgsJson, { signal })` — async; validates args
+ *   - `executeTool(toolInfo, inputArgsJson, { signal })`: async; validates args
  *     against the tool's schema, runs `execute()`, and returns the raw result as
  *     a JSON *string* (or `null` for `undefined`). Honors `signal` for abort.
  *
  * The polyfill auto-installs `document.modelContext` at module-evaluation time,
  * so it is imported *dynamically* and only when `config.webmcp.enabled === true`
- * — a static import would install the global for every widget consumer,
+ *: a static import would install the global for every widget consumer,
  * including those that never opted into WebMCP.
  *
  * Confirm model: every `webmcp:*` call goes through one confirm gate before
@@ -7279,7 +7639,7 @@ declare class WebMcpBridge {
     setConfirmHandler(handler: WebMcpConfirmHandler | null): void;
     /**
      * `true` when the bridge can both snapshot the registry AND execute returned
-     * tool calls — i.e. the polyfill is installed and `document.modelContext`
+     * tool calls: i.e. the polyfill is installed and `document.modelContext`
      * exposes the consumer surface (`getTools` / `executeTool`). Native browsers
      * that ship `document.modelContext` satisfy this too.
      *
@@ -7290,7 +7650,7 @@ declare class WebMcpBridge {
     isOperational(): boolean;
     /**
      * Per-turn snapshot for `dispatch.clientTools[]`. Returns the JSON-only
-     * surface — `execute` stays client-side, reached later via `executeToolCall`.
+     * surface: `execute` stays client-side, reached later via `executeToolCall`.
      *
      * Async because the strict polyfill's `getTools()` is async. Both payload
      * builders in `client.ts` already `await`, so this adds no new ceremony.
@@ -7300,7 +7660,7 @@ declare class WebMcpBridge {
      * Execute a `webmcp:<name>` tool call returned by the agent and return the
      * normalized MCP-shaped result for `/resume`.
      *
-     * Failure modes — all return `{ isError: true, content: [...] }` rather than
+     * Failure modes: all return `{ isError: true, content: [...] }` rather than
      * throwing, so the dispatch can resume cleanly:
      *   - bridge not operational
      *   - tool not in registry (e.g. unmounted between snapshot and call)
@@ -7324,7 +7684,7 @@ declare class WebMcpBridge {
      * widget consumers that never enable WebMCP.
      *
      * Producer pages should still install the polyfill themselves (or import it)
-     * before registering tools — Persona's install is a fallback, and a page that
+     * before registering tools: Persona's install is a fallback, and a page that
      * registers tools at load before Persona's first dispatch needs the global to
      * already exist.
      */
@@ -7562,14 +7922,14 @@ declare function validateImageFile(file: File, acceptedTypes?: string[], maxSize
  * Enriched DOM context collection for providing richer page information to AI.
  *
  * Captures interactive elements, stable CSS selectors, ARIA roles, data attributes,
- * and visibility state — giving the LLM much better context than basic className/innerText.
+ * and visibility state: giving the LLM much better context than basic className/innerText.
  *
  * ## Modes
  *
  * - **structured** (default): collects candidates, scores them with optional {@link ParseRule}
  *   hooks, then applies `maxElements`. Rich containers (e.g. product cards) can surface
  *   before unrelated static noise.
- * - **simple**: legacy behavior — cap during traversal, interactive-first ordering, no rule
+ * - **simple**: legacy behavior: cap during traversal, interactive-first ordering, no rule
  *   scoring or {@link EnrichedPageElement.formattedSummary}.
  */
 interface EnrichedPageElement {
@@ -7601,7 +7961,7 @@ type DomContextMode = "simple" | "structured";
 interface ParseOptionsConfig {
     /**
      * `structured` (default): score candidates with rules, then apply `maxElements`.
-     * `simple`: legacy traversal cap and ordering only — rules are ignored (with a warning
+     * `simple`: legacy traversal cap and ordering only: rules are ignored (with a warning
      * if `rules` was passed on {@link DomContextOptions}).
      */
     mode?: DomContextMode;
@@ -7680,7 +8040,7 @@ declare function generateStableSelector(el: HTMLElement): string;
  * - **Default (structured):** walks up to `maxCandidates` nodes, scores with
  *   {@link defaultParseRules} (or `rules`), suppresses redundant descendants when a
  *   formatting rule matches, then keeps the top `maxElements` by score (DOM order tie-break).
- * - **simple:** legacy path — stops once `maxElements` nodes are collected during traversal
+ * - **simple:** legacy path: stops once `maxElements` nodes are collected during traversal
  *   and sorts interactive before static.
  *
  * Pass `options: { mode: "simple" }` to disable rules. If `mode` is `simple` and `rules` is
@@ -8196,7 +8556,7 @@ interface ComboButtonHandle {
     destroy: () => void;
 }
 /**
- * Creates a combo button — a clickable label with a chevron that opens a dropdown menu.
+ * Creates a combo button: a clickable label with a chevron that opens a dropdown menu.
  *
  * The entire label + chevron area acts as a single interactive unit with an optional
  * hover pill effect. Clicking anywhere on it toggles the dropdown.
@@ -8780,10 +9140,6 @@ declare const getHeaderLayout: (layoutName: string) => HeaderLayoutRenderer;
  */
 declare const buildHeaderWithLayout: (config: AgentWidgetConfig, layoutConfig?: AgentWidgetHeaderLayoutConfig, context?: Partial<HeaderLayoutContext>) => HeaderElements;
 
-declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
-declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
-declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
-
 type CodeFormat = "esm" | "script-installer" | "script-manual" | "script-advanced" | "react-component" | "react-advanced";
 /**
  * Hook code templates for code generation.
@@ -8983,4 +9339,4 @@ interface DemoCarouselHandle {
 }
 declare function createDemoCarousel(container: HTMLElement, options: DemoCarouselOptions): DemoCarouselHandle;
 
-export { ASK_USER_QUESTION_CLIENT_TOOL, ASK_USER_QUESTION_PARAMETERS_SCHEMA, ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetActionContext, type AgentWidgetActionEventPayload, type AgentWidgetActionHandler, type AgentWidgetActionHandlerResult, type AgentWidgetActionParser, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetApprovalDecisionOptions, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetContextProvider, type AgentWidgetContextProviderContext, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetParsedAction, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type AgentWidgetWebMcpConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, type AskUserQuestionOption, type AskUserQuestionPayload, type AskUserQuestionPrompt, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type ClientToolDefinition, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComboButtonHandle, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateComboButtonOptions, type CreateDropdownOptions, type CreateIconButtonOptions, type CreateLabelButtonOptions, type CreateStandardBubbleOptions, type CreateThemeOptions, type CreateToggleGroupOptions, DEFAULT_COMPONENTS, DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH, DEFAULT_FLOATING_LAUNCHER_WIDTH, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DemoCarouselHandle, type DemoCarouselItem, type DemoCarouselOptions, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IconName, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectComponentDirectiveOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LabelButtonTokens, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type RuntypeAgentSSEEvent, type RuntypeAgentTurnCompleteEvent, type RuntypeClientChatRequest, type RuntypeClientChatStreamEvent, type RuntypeClientFeedbackRequest, type RuntypeClientFeedbackResponse, type RuntypeClientFeedbackType, type RuntypeClientInitRequest, type RuntypeClientInitResponse, type RuntypeClientResumeRequest, type RuntypeClientResumeStreamEvent, type RuntypeDispatchSSEEvent, type RuntypeFlowSSEEvent, type RuntypeStepCompleteEvent, type RuntypeStopReasonKind, type RuntypeStreamEventOf, type SSEEventCallback, type SSEEventRecord, SUGGEST_REPLIES_CLIENT_TOOL, SUGGEST_REPLIES_PARAMETERS_SCHEMA, SUGGEST_REPLIES_TOOL_NAME, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type StreamAnimationContext, type StreamAnimationPlugin, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, WEBMCP_TOOL_PREFIX, WebMcpBridge, type WebMcpConfirmHandler, type WebMcpConfirmInfo, type WebMcpToolResult, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, builtInClientToolsForDispatch, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createAskUserQuestionBubble, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDemoCarousel, createDirectivePostprocessor, createDropdownMenu, createFlexibleJsonStreamParser, createIconButton, createImagePart, createJsonStreamParser, createLabelButton, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createToggleGroup, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, ensureAskUserQuestionSheet, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isAskUserQuestionMessage, isComponentDirectiveType, isDockedMountMode, isSuggestRepliesMessage, isVoiceSupported, isWebMcpToolName, latestAgentSuggestions, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, parseSuggestRepliesPayload, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, renderLucideIcon, resolveDockConfig, resolveSanitizer, resolveTokens, stripWebMcpPrefix, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };
+export { ASK_USER_QUESTION_CLIENT_TOOL, ASK_USER_QUESTION_PARAMETERS_SCHEMA, ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetActionContext, type AgentWidgetActionEventPayload, type AgentWidgetActionHandler, type AgentWidgetActionHandlerResult, type AgentWidgetActionParser, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetApprovalDecisionOptions, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetContextProvider, type AgentWidgetContextProviderContext, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetParsedAction, type AgentWidgetPlugin, type AgentWidgetReadAloudEvent, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type AgentWidgetVoiceStatusEvent, type AgentWidgetWebMcpConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, type AskUserQuestionOption, type AskUserQuestionPayload, type AskUserQuestionPrompt, AttachmentManager, type AttachmentManagerConfig, type BorderScale, BrowserSpeechEngine, type BrowserSpeechEngineOptions, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type ClientToolDefinition, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComboButtonHandle, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateComboButtonOptions, type CreateDropdownOptions, type CreateIconButtonOptions, type CreateLabelButtonOptions, type CreateStandardBubbleOptions, type CreateThemeOptions, type CreateToggleGroupOptions, DEFAULT_COMPONENTS, DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH, DEFAULT_FLOATING_LAUNCHER_WIDTH, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DemoCarouselHandle, type DemoCarouselItem, type DemoCarouselOptions, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FallbackSpeechEngineOptions, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IconName, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectComponentDirectiveOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LabelButtonTokens, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PcmStreamPlayer, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, ReadAloudController, type ReadAloudListener, type ReadAloudState, type RuleScoringContext, type RuntypeAgentSSEEvent, type RuntypeAgentTurnCompleteEvent, type RuntypeClientChatRequest, type RuntypeClientChatStreamEvent, type RuntypeClientFeedbackRequest, type RuntypeClientFeedbackResponse, type RuntypeClientFeedbackType, type RuntypeClientInitRequest, type RuntypeClientInitResponse, type RuntypeClientResumeRequest, type RuntypeClientResumeStreamEvent, type RuntypeDispatchSSEEvent, type RuntypeFlowSSEEvent, type RuntypeStepCompleteEvent, type RuntypeStopReasonKind, type RuntypeStreamEventOf, type SSEEventCallback, type SSEEventRecord, SUGGEST_REPLIES_CLIENT_TOOL, SUGGEST_REPLIES_PARAMETERS_SCHEMA, SUGGEST_REPLIES_TOOL_NAME, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type SpeechCallbacks, type SpeechEngine, type SpeechRequest, type StreamAnimationContext, type StreamAnimationPlugin, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceMetrics, type VoicePlaybackEngine, type VoiceProvider, type VoiceResult, type VoiceStatus, WEBMCP_TOOL_PREFIX, WebMcpBridge, type WebMcpConfirmHandler, type WebMcpConfirmInfo, type WebMcpToolResult, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, builtInClientToolsForDispatch, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createAskUserQuestionBubble, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDemoCarousel, createDirectivePostprocessor, createDropdownMenu, createFlexibleJsonStreamParser, createIconButton, createImagePart, createJsonStreamParser, createLabelButton, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createToggleGroup, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, ensureAskUserQuestionSheet, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isAskUserQuestionMessage, isComponentDirectiveType, isDockedMountMode, isSuggestRepliesMessage, isVoiceSupported, isWebMcpToolName, latestAgentSuggestions, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, parseSuggestRepliesPayload, pickBestVoice, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, renderLucideIcon, resolveDockConfig, resolveSanitizer, resolveTokens, stripWebMcpPrefix, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };