@runtypelabs/persona 3.34.1 → 3.36.0

package/dist/smart-dom-reader.d.cts

@@ -1,5 +1,5 @@
 /**
- * VENDORED type declarations — @mcp-b/smart-dom-reader v2.3.1 (MIT).
+ * VENDORED type declarations: @mcp-b/smart-dom-reader v2.3.1 (MIT).
  * Copied verbatim from upstream dist/index.d.mts (only the trailing sourceMappingURL
  * comment removed). See ./index.js and ./README.md for why this is vendored.
  */
@@ -188,14 +188,14 @@ declare global {
  * 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 {
@@ -222,8 +222,8 @@ interface EnrichedPageElement {
  * Pure mapper: `@mcp-b/smart-dom-reader` output → Persona's {@link EnrichedPageElement}[].
  *
  * This module imports the smart-dom-reader types with `import type` ONLY, so the
- * library's runtime value is never pulled in here. That keeps the mapper — and its
- * unit test — free of any DOM and free of the (vendored) library at runtime; the
+ * library's runtime value is never pulled in here. That keeps the mapper, and its
+ * unit test: free of any DOM and free of the (vendored) library at runtime; the
  * types are erased during compilation.
  *
  * The smart-dom-reader returns a structured {@link SmartDOMResult} JSON object with
@@ -315,7 +315,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"`.
          */
@@ -364,14 +364,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)"`.
      *
@@ -420,8 +420,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).
      *
@@ -1295,6 +1295,7 @@ type RuntypeFlowSSEEvent = {
     totalSteps?: number;
     type: "flow_start";
 } | {
+    claudeManagedAgentId?: string;
     completedAt?: string;
     completedSteps?: number;
     duration?: number;
@@ -1409,6 +1410,7 @@ type RuntypeFlowSSEEvent = {
         toolId: string;
     };
     type: "step_complete";
+    unresolvedVariables?: Array<string>;
 }) | {
     error: string;
     executionId?: string;
@@ -1742,7 +1744,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;
@@ -1764,7 +1766,7 @@ type AgentRequestOptions = {
  * 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.
  */
@@ -1772,16 +1774,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
@@ -1813,7 +1815,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.)
@@ -1827,7 +1829,7 @@ type WebMcpConfirmHandler = (info: WebMcpConfirmInfo) => Promise<boolean>;
 /**
  * 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). */
@@ -1843,7 +1845,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;
     /**
@@ -1886,7 +1888,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.
      */
@@ -2022,6 +2024,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'
@@ -2096,8 +2106,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";
@@ -2111,7 +2121,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;
@@ -2138,8 +2148,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";
@@ -2151,7 +2161,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;
@@ -2295,11 +2305,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;
@@ -2328,11 +2338,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;
@@ -2341,34 +2351,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";
 /**
@@ -2399,7 +2409,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.
@@ -2415,7 +2425,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.
@@ -2444,8 +2454,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;
@@ -2458,7 +2467,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
      */
@@ -2518,7 +2527,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;
 };
@@ -2532,14 +2541,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`.
@@ -2555,7 +2564,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;
 };
 /**
@@ -2607,14 +2616,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;
@@ -2635,17 +2644,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";
@@ -2813,7 +2822,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"
@@ -2887,7 +2896,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;
@@ -2902,7 +2911,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
@@ -3148,6 +3157,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?: {
@@ -3156,15 +3170,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);
     };
 };
 /**
@@ -3187,18 +3217,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;
     /**
@@ -3217,7 +3297,177 @@ 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>;
 };
+/** 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
+ */
+type VoiceResult = {
+    text: string;
+    transcript?: string;
+    audio?: {
+        base64: string;
+        format: 'wav' | 'mp3' | 'ogg' | 'webm';
+        sampleRate: number;
+        duration: number;
+    };
+    confidence?: number;
+    provider: 'runtype' | 'browser' | 'custom';
+};
+/**
+ * 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 interface
+ * Abstract interface for all voice providers in the Persona SDK
+ */
+interface VoiceProvider {
+    type: 'browser' | 'runtype' | 'custom';
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    startListening(): Promise<void>;
+    stopListening(): Promise<void>;
+    onResult(callback: (result: VoiceResult) => void): void;
+    onError(callback: (error: Error) => void): void;
+    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 */
+    deactivateBargeIn?(): Promise<void>;
+    /** Stop playback / cancel in-flight request without starting recording */
+    stopPlayback?(): void;
+}
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the
  * `approve`/`deny` callbacks passed to the `renderApproval` plugin hook.
@@ -3226,7 +3476,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`.
@@ -3280,9 +3530,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 */
@@ -3304,7 +3554,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;
@@ -3410,7 +3660,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.
@@ -3423,7 +3673,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}~"
@@ -3484,7 +3734,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}~"
@@ -3495,7 +3745,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}~"
@@ -3594,7 +3844,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;
 /**
@@ -4574,7 +4824,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>>;
@@ -4667,12 +4917,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
@@ -4706,7 +4956,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
@@ -5025,7 +5275,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).
      *
@@ -5054,7 +5304,7 @@ type AgentWidgetConfig = {
      *
      * @example
      * ```typescript
-     * // Ephemeral widget — no message history written anywhere
+     * // Ephemeral widget: no message history written anywhere
      * config: {
      *   persistState: false
      * }
@@ -5121,7 +5371,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;
@@ -5131,16 +5381,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;
 /**
@@ -5257,11 +5507,10 @@ type PersonaArtifactRecord = {
  * Adapts `@mcp-b/smart-dom-reader` into Persona's enriched page-context pipeline and
  * exposes a ready-made {@link AgentWidgetContextProvider} you can drop into
  * `config.contextProviders`. This is the ONLY module that imports the smart-dom-reader
- * runtime value, so the library never reaches the main bundle or the IIFE/CDN build —
- * importing this subpath is opt-in.
+ * runtime value, so the library never reaches the main bundle or the IIFE/CDN build: * importing this subpath is opt-in.
  *
  * The library is **vendored** under `src/vendor/smart-dom-reader/` (it is mis-published
- * on npm and cannot be imported by name — see that directory's README). Vendoring it
+ * on npm and cannot be imported by name: see that directory's README). Vendoring it
  * here means consumers need no extra install: the code is bundled into this entry, and
  * consumers who never import this subpath pay nothing.
  *
@@ -5306,7 +5555,7 @@ interface SmartDomContextOptions extends SmartDomAdapterOptions {
     /** Document to extract from. Default: the global `document`. Ignored when `root` is set. */
     document?: Document;
     /**
-     * Scope extraction to this element's subtree instead of the whole document — parity
+     * Scope extraction to this element's subtree instead of the whole document: parity
      * with `collectEnrichedPageContext`'s `root`. Useful to read only a main-content region
      * and skip site chrome (nav, sidebars). Shadow DOM inside the subtree is still pierced.
      * When set, `document` is ignored.