@runtypelabs/persona 4.23.2 → 4.25.0

package/dist/forms-ui.d.ts

@@ -21,6 +21,7 @@ interface ResolvedWelcomeConfig {
      * Optional on the interface, always populated by `resolveWelcomeConfig`:
      * a plugin literal built against an older minor must still type-check.
      */
+    layout?: "top" | "centered";
     anchor?: AgentWidgetWelcomeAnchor;
     /** Percentage string; validated, falls back to "44%". */
     anchorComposerTop?: string;
@@ -792,6 +793,8 @@ interface InputTokens extends ComponentTokenSet {
     backdropFilter?: string;
 }
 interface LauncherTokens extends ComponentTokenSet {
+    /** Distance from the viewport edges. Circle default: 20px; pill: 24px. */
+    offset?: string;
     size: string;
     iconSize: string;
     shadow: TokenReference<'shadow'>;
@@ -814,6 +817,15 @@ interface PanelTokens extends ComponentTokenSet {
     inset?: string;
     /** Background of the region revealed behind a detached panel. */
     canvasBackground?: string;
+    /** Chrome defaults by rendered panel mode. */
+    modes?: Partial<Record<'floating' | 'inline' | 'sidebar' | 'docked' | 'mobile', {
+        /** Full border shorthand (for example, `"1px solid var(--persona-border)"`). */
+        border?: string;
+        /** Box-shadow token reference or raw CSS shadow. */
+        shadow?: string;
+        /** Corner radius token reference or raw CSS radius. */
+        borderRadius?: TokenReference<'radius'>;
+    }>>;
 }
 /** Per-element text styling shared by themable text surfaces. */
 interface TextStyleTokens {
@@ -840,10 +852,16 @@ interface HeaderTokens extends ComponentTokenSet {
      */
     border?: TokenReference<'color'>;
     borderRadius: TokenReference<'radius'>;
+    /** Standard-header padding. @default "20px 24px" */
+    padding?: string;
+    /** Minimal-header padding. Explicitly wins over `padding`. @default "16px 24px" */
+    minimalPadding?: string;
     /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
     iconBackground: TokenReference<'color'>;
     /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
     iconForeground: TokenReference<'color'>;
+    /** Header identity glyph size as a fraction of its icon box. @default "0.6" */
+    iconScale?: string;
     /**
      * Legacy alias of `title.color`; `title.color` wins when both are set.
      * Unset, the title takes `foreground`, then the primary color.
@@ -882,6 +900,14 @@ interface HeaderTokens extends ComponentTokenSet {
      * sibling. @default "1.5"
      */
     controlStrokeWidth?: string;
+    /** Header control corner radius. Per-control radius overrides win. */
+    controlBorderRadius?: string;
+    /** Default control hover/focus fill. Explicit button backgrounds win. */
+    controlHoverBackground?: TokenReference<'color'>;
+    /** Default control hover/focus icon color. Explicit button colors win. */
+    controlHoverForeground?: TokenReference<'color'>;
+    /** Keyboard focus outline; unset preserves the browser default. */
+    controlFocusOutline?: string;
     /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
     shadow?: string;
     /** Override the header bottom border (e.g., `none`). */
@@ -1056,6 +1082,12 @@ interface MessageGeometryTokens {
     lineHeight?: string;
 }
 interface MessageTokens {
+    /** Height of the optional transcript top fade. Default 18px. */
+    topFadeHeight?: string;
+    /** Vertical gap between transcript turns. @default "12px" */
+    gap?: string;
+    /** Gap between turns in fullscreen mode; falls back to `gap`. */
+    fullscreenGap?: string;
     user: MessageGeometryTokens & {
         background: TokenReference<'color'>;
         text: TokenReference<'color'>;
@@ -1069,6 +1101,8 @@ interface MessageTokens {
         borderRadius: TokenReference<'radius'>;
         /** Assistant bubble border color (CSS color). */
         border?: TokenReference<'color'>;
+        /** Border width; set to 0px for a flat assistant response. @default "1px" */
+        borderWidth?: string;
         /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
         shadow?: string;
     };
@@ -1187,12 +1221,40 @@ interface AttachmentTokens {
     };
 }
 /** Tool-call row chrome (collapsible tool bubbles). */
-interface ToolBubbleTokens {
+interface ActivityTokens {
+    /** Minimum activity row height. */
+    rowHeight?: string;
+    /** Group child indentation; falls back to indent when unset. V5: 0px. */
+    groupIndent?: string;
+    /** Extra vertical gap between grouped rows. V5: 0px. */
+    groupGap?: string;
+    /** Padding around expanded group children. V5: 0px. */
+    groupPadding?: string;
+    /** Gap between consecutive activity entries. V5: 0px. */
+    transcriptGap?: string;
+    /** Gap from activity to an assistant response. V5: 12px. */
+    responseGap?: string;
+    /** Expanded body padding. V5: 4px 0. */
+    bodyPadding?: string;
+    /** Expanded reasoning text size. V5: 13px. */
+    bodySize?: string;
+    /** Expanded reasoning line height. V5: 1.5. */
+    bodyLineHeight?: string;
+    /** Expanded reasoning font weight. V5: 400. */
+    bodyFontWeight?: string;
+    /** Gap between expanded detail sections. V5: 8px. */
+    sectionGap?: string;
+    labelSize?: string;
+    iconSize?: string;
+    indent?: string;
+    bodySurface?: TokenReference<'color'>;
+}
+interface ToolBubbleTokens extends ActivityTokens {
     /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
     shadow: string;
 }
 /** Reasoning / “thinking” row chrome. */
-interface ReasoningBubbleTokens {
+interface ReasoningBubbleTokens extends ActivityTokens {
     shadow: string;
 }
 /** One event-stream badge chip: fill + text pair. The chip border derives
@@ -1326,6 +1388,10 @@ interface ComposerChromeTokens {
     shadow: string;
     /** Border color of the composer form. @default semantic.colors.border */
     borderColor?: TokenReference<'color'>;
+    /** Focused form border color; falls back to borderColor. V5: a stronger neutral border. */
+    focusBorderColor?: TokenReference<'color'>;
+    /** Outer focus ring (CSS outline shorthand). V4: none; V5: a thin neutral ring. */
+    focusRing?: string;
     /** Inner padding of the composer form (raw CSS shorthand). @default "0.75rem 1rem" */
     padding?: string;
     /** Gap between the textarea row and the actions row. @default "0.5rem" */
@@ -1344,12 +1410,18 @@ interface ComposerChromeTokens {
     controlSize?: string;
     /** Glyph box inside those controls. @default "24px" */
     controlIconSize?: string;
+    /** Send/stop glyph size. Explicit sendButton.iconSize wins. V5: 18px. */
+    sendIconSize?: string;
+    /** Icon-mode submit button radius. V4 inherits the primary button; V5: 9999px. */
+    sendButtonRadius?: string;
+    /** Footer top border (CSS shorthand). V4: 1px solid divider; V5: none. */
+    footerBorder?: string;
     /**
      * Background painted behind an overlaid composer footer
      * (`composer.placement: "overlay"`). Any CSS `background` value, gradients
      * included — same convention as the shadow tokens. Inert under
      * `placement: "block"`.
-     * @default "transparent"
+     * @default "transparent" (V4); a theme-aware 24px fade (V5)
      */
     overlayBand?: string;
     /** Segmented mode-group track. */
@@ -1525,6 +1597,8 @@ interface ScrollToBottomTokens extends ComponentTokenSet {
 }
 /** Visual tokens shared by one suggestion presentation variant. */
 interface SuggestionVariantTokens extends ComponentTokenSet {
+    /** Label weight. V4: 500; V5: 400. */
+    fontWeight?: string;
     /** Space inside one item, between its icon and its copy. */
     gap?: string;
     /** Space between suggestion items in the container. */
@@ -1573,6 +1647,7 @@ interface ComponentTokens {
     voice: VoiceTokens;
     approval: ApprovalTokens;
     attachment: AttachmentTokens;
+    activity?: ActivityTokens;
     toolBubble: ToolBubbleTokens;
     reasoningBubble: ReasoningBubbleTokens;
     /** Event-stream inspector badge chips. */
@@ -4393,6 +4468,14 @@ type AgentWidgetToolCallCollapsedMode = "tool-call" | "tool-name" | "tool-previe
  */
 type AgentWidgetToolCallLoadingAnimation = "none" | "pulse" | "shimmer" | "shimmer-color" | "rainbow";
 type AgentWidgetToolCallDisplayFeature = {
+    /** Activity chrome. Defaults to card in V4 and row with future.v5Defaults. */
+    variant?: "card" | "row";
+    /** Row status icons: always, active/attention-needed only, or never. V5 defaults to active; V4 to always. */
+    iconVisibility?: "always" | "active" | "never";
+    /** Row variant: open when the first content chunk arrives. Default false in V5; true in V4. */
+    autoExpand?: boolean;
+    /** Row variant: collapse once after completion, in ms; false disables. Default 1000. */
+    autoCollapseDelay?: number | false;
     /**
      * Controls what collapsed tool call rows show in their header/summary area.
      * @default "tool-call"
@@ -4423,9 +4506,10 @@ type AgentWidgetToolCallDisplayFeature = {
      * Controls how a grouped tool sequence is rendered.
      * - `"stack"`: show the group summary and each child tool row.
      * - `"summary"`: show one consolidated summary row only.
+     * - `"collapsible"`: expandable activity group (V5 default).
      * @default "stack"
      */
-    groupedMode?: "stack" | "summary";
+    groupedMode?: "stack" | "summary" | "collapsible";
     /**
      * What happens to a tool call row once it completes.
      *
@@ -4456,6 +4540,14 @@ type AgentWidgetToolCallDisplayFeature = {
 /** See `features.toolCallDisplay.completedVisibility`. */
 type AgentWidgetToolCallCompletedVisibility = "kept" | "removed";
 type AgentWidgetReasoningDisplayFeature = {
+    /** Activity chrome. Defaults to card in V4 and row with future.v5Defaults. */
+    variant?: "card" | "row";
+    /** Row status icons: always, active/attention-needed only, or never. V5 defaults to active; V4 to always. */
+    iconVisibility?: "always" | "active" | "never";
+    /** Row variant: open when the first content chunk arrives. Default false in V5; true in V4. */
+    autoExpand?: boolean;
+    /** Row variant: collapse once after completion, in ms; false disables. Default 1000. */
+    autoCollapseDelay?: number | false;
     /**
      * When true, active collapsed reasoning rows can render a lightweight preview block.
      * @default false
@@ -5151,8 +5243,8 @@ interface AgentWidgetHistoryFeature {
      * otherwise `"browser"`) and narrows it to what the provider advertises, so a
      * browser-only provider is never asked for a scope it cannot serve. An
      * explicit `features.history.scope` is a hard request and still fails closed
-     * with `unsupported_scope`. `getIdentityProof` is never called for a supplied
-     * provider, and `HistoryOperationContext` carries only the resolved scope;
+     * with `unsupported_scope`. History operations on a supplied provider never
+     * call `getIdentityProof`, and `HistoryOperationContext` carries only the resolved scope;
      * report your own identity through `getIdentityStatus()` /
      * `subscribeIdentityStatus()`, which is what the scope banner and its retry
      * affordance read.
@@ -5536,7 +5628,7 @@ type EventStreamConfig = {
     /**
      * Fields to extract from event payloads for description text.
      * The first matching field value is displayed after the badge.
-     * @default ["flowName", "stepName", "name", "tool", "toolName"]
+     * @default ["flowName", "stepName", "reasoningText", "text", "name", "tool", "toolName"]
      */
     descriptionFields?: string[];
     /**
@@ -5747,6 +5839,8 @@ type AgentWidgetComposerBarPeekConfig = {
     streamAnimation?: AgentWidgetStreamAnimationFeature;
 };
 type AgentWidgetLauncherConfig = {
+    /** Collapsed launcher shape. V4 defaults to pill; V5 defaults to circle. */
+    variant?: "pill" | "circle";
     enabled?: boolean;
     title?: string;
     subtitle?: string;
@@ -6502,9 +6596,9 @@ type AgentWidgetComposerConfig = {
     /**
      * Where the composer footer sits relative to the transcript.
      *
-     * - `"block"` (default): the footer is a flex sibling below the scroll body.
+     * - `"block"` (V4 default): the footer is a flex sibling below the scroll body.
      *   Nothing scrolls behind it.
-     * - `"overlay"`: the footer is absolutely overlaid on the scroll body, so the
+     * - `"overlay"` (V5 default): the footer is absolutely overlaid on the scroll body, so the
      *   transcript scrolls behind it (the chatgpt.com / claude.ai model, where the
      *   composer is sticky inside the scroller). The widget reserves the footer's
      *   live height as bottom padding on the scroll body and on a plugin welcome
@@ -6516,7 +6610,7 @@ type AgentWidgetComposerConfig = {
      * included) and `theme.components.input.backdropFilter`.
      *
      * Ignored in composer-bar mount mode, which owns its own geometry.
-     * @default "block"
+     * @default "block" (V4), "overlay" (V5)
      */
     placement?: ComposerPlacement;
     /**
@@ -6530,8 +6624,9 @@ type AgentWidgetComposerConfig = {
      *
      * `"single-row"` describes the IDLE composer only. It composes with the
      * compact state, so a wrapped draft, chips, attachment previews, a quote, a
-     * pending card, or live dictation all fall back to the stacked card, exactly
-     * as `data-persona-composer-compact` does today.
+     * pending card all fall back to the stacked card, exactly
+     * as `data-persona-composer-compact` does today. Recording alone does not
+     * expand the composer; dictated text expands it when it wraps.
      *
      * Ignored in composer-bar mount mode, whose pill is already one row.
      * @default "stacked"
@@ -6573,7 +6668,14 @@ type AgentWidgetClearChatConfig = {
     showTooltip?: boolean;
 };
 type AgentWidgetStatusIndicatorConfig = {
+    /** Show the indicator. Explicit false also hides transient connection states. */
     visible?: boolean;
+    /**
+     * "always" shows status beneath the composer; "transient" shows connecting,
+     * reconnecting, and error status above it, hiding normal idle/streaming status.
+     * Available in both defaults states. Default: "always" in v4, "transient" in v5.
+     */
+    mode?: "always" | "transient";
     /** Text alignment. Default: 'right'. */
     align?: 'left' | 'center' | 'right';
     idleText?: string;
@@ -6587,6 +6689,22 @@ type AgentWidgetStatusIndicatorConfig = {
     /** Status text while a reconnect attempt is in flight. */
     resumingText?: string;
 };
+/** Built-in `voiceRecognition.prewarm` triggers. See {@link AgentWidgetVoiceRecognitionConfig.prewarm}. */
+type AgentWidgetVoicePrewarmTrigger = 'hover';
+/**
+ * Custom `voiceRecognition.prewarm` trigger. Runs while the composer has a mic
+ * button, and again when the button is rebuilt or `update()` swaps in a
+ * different function. Call `warm()` whenever the visitor shows intent to talk
+ * (it is safe to call repeatedly). Return a cleanup to run on replacement.
+ */
+type AgentWidgetVoicePrewarmHook = (context: {
+    /** Fire-and-forget voice warm-up; latched and error-swallowing. */
+    warm: () => void;
+    /** The composer's current mic button. */
+    micButton: HTMLButtonElement;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetVoiceRecognitionConfig = {
     /**
      * Enable the mic button and voice input. The mic still only renders when the
@@ -6652,6 +6770,29 @@ type AgentWidgetVoiceRecognitionConfig = {
      * Fires once per turn after the reply completes.
      */
     onMetrics?: (metrics: VoiceMetrics) => void;
+    /**
+     * Warm the voice path when the visitor shows intent to talk, before the mic
+     * click, so the call starts faster.
+     *
+     * - `'hover'`: when the pointer enters the mic button, it receives focus, or
+     *   (on touch) the first pointer-down on it.
+     * - `false`: never.
+     * - A function: custom trigger. Called with `{ warm, micButton, mount }`
+     *   while the mic button exists (and again when the button is rebuilt or
+     *   `update()` swaps in a different function); call `warm()` whenever you
+     *   decide, e.g. when the panel opens. May return a cleanup that runs on
+     *   destroy, rebuild, or replacement. Replaces the built-in trigger.
+     *
+     * What `warm()` does depends on the provider: `runtype` fires its prewarm
+     * (see `provider.runtype.prewarmMode`), a `custom` provider's optional
+     * {@link VoiceProvider.prewarm} runs, and the browser (Web Speech) path
+     * starts the client-token session init (as `sessionInit` does), since speech
+     * recognition itself cannot start before the click. Warming is
+     * fire-and-forget, latched, and never surfaces an error or UI state.
+     *
+     * @default 'hover' in client token mode, otherwise `false`
+     */
+    prewarm?: AgentWidgetVoicePrewarmTrigger | AgentWidgetVoicePrewarmHook | false;
     provider?: {
         type: 'browser' | 'runtype' | 'custom';
         browser?: {
@@ -6673,6 +6814,23 @@ type AgentWidgetVoiceRecognitionConfig = {
              * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
              */
             createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+            /**
+             * How `prewarm()` warms the voice path (see `voiceRecognition.prewarm`).
+             *
+             * - `'request'` (default): a fire-and-forget
+             *   `POST {host}/v1/client/agents/{agentId}/voice/prewarm`.
+             * - `'attach'`: open the voice WebSocket ahead of the click without
+             *   starting a call; the click then starts the call on that socket. It can
+             *   create server work before the visitor clicks, so it is opt-in.
+             * @default 'request'
+             */
+            prewarmMode?: 'request' | 'attach';
+            /**
+             * `'attach'` mode: how long (ms) an attached socket waits for the click
+             * before it closes. The server clamps it to 30000..600000.
+             * @default 30000
+             */
+            attachIdleMs?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
             pauseDuration?: number;
             /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -6958,6 +7116,10 @@ type VoiceConfig = {
          * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
          */
         createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
+        /** See `voiceRecognition.provider.runtype.prewarmMode`. @default 'request' */
+        prewarmMode?: 'request' | 'attach';
+        /** See `voiceRecognition.provider.runtype.attachIdleMs`. @default 30000 */
+        attachIdleMs?: number;
         /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
         pauseDuration?: number;
         /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
@@ -7018,6 +7180,13 @@ interface VoiceProvider {
     deactivateBargeIn?(): Promise<void>;
     /** Stop playback / cancel in-flight request without starting recording */
     stopPlayback?(): void;
+    /**
+     * Warm the provider ahead of `startListening()` (the widget calls it on mic
+     * intent, see `voiceRecognition.prewarm`). Must be fire-and-forget: never
+     * throw, emit errors or status, or acquire the microphone. May be called
+     * repeatedly; throttle as needed.
+     */
+    prewarm?(): void;
 }
 /**
  * Extra context for an approval decision, surfaced to `onDecision` and to the
@@ -7393,7 +7562,8 @@ type AgentWidgetResolvedSuggestion = {
 };
 /** Presentation keys shared by every suggestion surface. */
 type AgentWidgetSuggestionSurfaceConfig = {
-    /** Item density. Defaults to `card` for starters and `chip` for follow-ups. */
+    /** Item density. V4 starters: card. V5 starters: chip, or card in fullscreen.
+     * Follow-ups default to chip. */
     variant?: AgentWidgetSuggestionVariant;
     /** Default click behavior, overridable per item. Defaults to `send`. */
     behavior?: AgentWidgetSuggestionBehavior;
@@ -7404,7 +7574,7 @@ type AgentWidgetSuggestionSurfaceConfig = {
      * own stacking.
      */
     overflow?: "scroll" | "wrap";
-    /** Maximum visible items. Defaults to 4. */
+    /** Maximum visible items. Defaults to 4, or 3 for V5 non-fullscreen starters. */
     maxItems?: number;
 };
 type AgentWidgetStarterSuggestionsConfig = AgentWidgetSuggestionSurfaceConfig & {
@@ -7458,8 +7628,8 @@ type AgentWidgetSuggestionsConfig = {
 type AgentWidgetWelcomeVariant = "card" | "hero" | "none";
 /**
  * When the welcome surface goes away. `"never"` is the default for `"card"`;
- * `"on-first-message"` is the default for `"hero"` and cannot be overridden
- * there.
+ * `"on-first-message"` is forced for legacy V4 `"hero"`. V5 defaults every
+ * variant to `"on-first-message"`. Explicit layout opts into overridable dismissal.
  */
 type AgentWidgetWelcomeDismiss = "never" | "on-first-message";
 /**
@@ -7513,7 +7683,10 @@ type AgentWidgetWelcomeAlign = "start" | "center";
  * host-set value from a filled-in default.
  */
 interface AgentWidgetWelcomeConfig {
-    /** Card or hero title. Defaults to "Hello 👋". */
+    /** Vertical placement: V4 defaults to top; V5 to centered. Fullscreen centered
+     * welcomes also raise the empty composer unless `anchor` is explicitly set. */
+    layout?: "top" | "centered";
+    /** Card or hero title. V4: "Hello 👋". V5: "What can I help with?". */
     title?: string;
     /**
      * Small muted line above the title, e.g. a section name. Omitted when unset
@@ -7526,19 +7699,22 @@ interface AgentWidgetWelcomeConfig {
     icon?: AgentWidgetWelcomeIcon;
     /**
      * Horizontal alignment of the kicker, title, subtitle, and starter
-     * suggestions. Unset follows the variant: `card` starts, `hero` centers.
+     * suggestions. Centered layouts default to center. Otherwise unset follows
+     * the variant: `card` starts, `hero` centers.
      */
     align?: AgentWidgetWelcomeAlign;
     /** @default "card" */
     variant?: AgentWidgetWelcomeVariant;
-    /** @default "never" for `card`, always `"on-first-message"` for `hero`. */
+    /** V4: never for card, forced on-first-message for hero. V5: on-first-message
+     * for all variants; explicit values win. Explicit layout also allows overriding
+     * the legacy hero dismissal in V4. */
     dismiss?: AgentWidgetWelcomeDismiss;
     /**
      * Vertical anchoring of the greeting-plus-composer pair in the EMPTY
      * conversation only. On the first message the pair drops to the bottom
      * (animated; see `data-persona-conversation-state`).
      *
-     * - `"bottom"` (default): the composer stays pinned at the bottom.
+     * - `"bottom"`: the composer stays pinned at the bottom.
      * - `"center"`: greeting and composer float together so the composer's top
      *   edge lands at `anchorComposerTop` of the panel column, and the welcome
      *   surface is end-anchored `composerGap` above it.
@@ -7546,7 +7722,8 @@ interface AgentWidgetWelcomeConfig {
      * Composes with either `composer.placement`. Ignored in composer-bar mount
      * mode. `renderWelcome` plugin content inherits the anchor: the widget
      * positions the overlay host and reserves the composer zone.
-     * @default "bottom"
+     * Defaults to bottom, except centered fullscreen layouts, which center the
+     * measured greeting/composer group when no anchor override is supplied.
      */
     anchor?: AgentWidgetWelcomeAnchor;
     /**
@@ -8136,6 +8313,9 @@ type AgentWidgetLayoutConfig = {
      * `launcher.composerBar.contentMaxWidth`)
      */
     contentMaxWidth?: string;
+    /** Fade the transcript's top edge when content is scrolled above it.
+     * Defaults to false in V4 and true with future.v5Defaults. */
+    topFade?: boolean;
 };
 /**
  * Token types for marked renderer methods
@@ -8749,7 +8929,30 @@ type AgentWidgetLoadingIndicatorConfig = {
      */
     renderIdle?: (context: IdleIndicatorRenderContext) => HTMLElement | null;
 };
+/** Built-in `sessionInit` triggers. See {@link AgentWidgetConfig.sessionInit}. */
+type AgentWidgetSessionInitTrigger = 'input' | 'focus' | 'mount' | 'send';
+/**
+ * Custom `sessionInit` trigger. Runs when the widget mounts in client token mode,
+ * and again if `update()` swaps in a different function. Call `warm()` whenever
+ * the visitor shows intent (it is safe to call repeatedly). Return a cleanup to
+ * run when the widget is destroyed or the hook is replaced.
+ */
+type AgentWidgetSessionInitHook = (context: {
+    /** Fire-and-forget early session init; latched and error-swallowing. */
+    warm: () => void;
+    /** The widget's mount element. */
+    mount: HTMLElement;
+}) => void | (() => void);
 type AgentWidgetConfig = {
+    /** Opt in to upcoming major-version defaults without changing explicit settings. */
+    future?: {
+        /**
+         * Use the v5 default styling as it rolls out in 4.x. Every affected setting
+         * remains independently configurable. Explicit options and theme tokens win.
+         * @default false
+         */
+        v5Defaults?: boolean;
+    };
     apiUrl?: string;
     flowId?: string;
     /**
@@ -8904,6 +9107,46 @@ type AgentWidgetConfig = {
      * ```
      */
     onSessionExpired?: () => void;
+    /**
+     * When the widget calls `/v1/client/init` in client token mode, ahead of the
+     * first send. Ignored outside client token mode.
+     *
+     * - `'input'` (default): on the composer's first user keystroke that leaves
+     *   non-empty text. Programmatic value changes (restored drafts,
+     *   `setMessage()`, history recall) do not count.
+     * - `'focus'`: when the visitor focuses the composer by pointer or Tab (and
+     *   on first input, as a fallback). Programmatic focus, such as
+     *   `autoFocusInput` on open or mount, does not count.
+     * - `'mount'`: as soon as the widget mounts (the behavior before this option
+     *   existed). Use it when a server-configured welcome message, which arrives
+     *   with the init response, must show before the visitor types.
+     * - `'send'`: no early init; the first send initializes the session.
+     * - A function: custom trigger. Called on mount (and when `update()` swaps
+     *   in a different function) with a `warm` callback to call whenever you
+     *   decide (e.g. on hover); may return a cleanup that runs on destroy or
+     *   replacement. Replaces the built-in triggers.
+     *
+     * The early init is fire-and-forget: it runs at most once per session
+     * lifetime (re-armed after expiry or a new conversation), sends exactly the
+     * same request the send would, and swallows errors. A failure resurfaces
+     * when the send retries init. A send during an in-flight early init reuses
+     * it, so only one `/v1/client/init` is issued. When visitor history is
+     * enabled the widget still initializes on mount to restore the conversation.
+     * Hosts can also trigger it imperatively with `controller.warmSession()`.
+     *
+     * @default 'input'
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   clientToken: 'ct_live_...',
+     *   sessionInit: ({ warm, mount }) => {
+     *     mount.addEventListener('pointerenter', warm, { once: true });
+     *   }
+     * }
+     * ```
+     */
+    sessionInit?: AgentWidgetSessionInitTrigger | AgentWidgetSessionInitHook;
     /**
      * Get stored session ID for session resumption (client token mode only).
      * Called when initializing a new session to check if there's a previous session_id
@@ -8936,13 +9179,20 @@ type AgentWidgetConfig = {
      */
     setStoredSessionId?: (sessionId: string) => void;
     /**
-     * Called immediately before any cross-device history request and before a
+     * With identityProvider, called before every client-token chat POST, including retries, independently of history.
+     * Also called immediately before any cross-device history request and before a
      * conversationId resume of a conversation discovered on another device.
-     * Return a fresh end-user access token (rt_eu_… / JWT). Null uses exact-browser
-     * scope only for a never-bound visitor; a previously bound visitor fails closed
-     * until resetHistoryIdentity() runs. Never cached by the widget.
+     * Return a fresh end-user access token (rt_eu_… / JWT). Null stops identity-enabled chat.
+     * For history only, null uses exact-browser scope for a never-bound visitor;
+     * a bound visitor fails closed until resetHistoryIdentity(). Never cached.
      */
     getIdentityProof?: () => string | null | Promise<string | null>;
+    /**
+     * Provider name registered with Runtype, for example "clerk". Enables per-request
+     * chat identity through getIdentityProof without enabling history. A missing or
+     * failed proof stops the turn; omitting this preserves history-only callbacks.
+     */
+    identityProvider?: string;
     /**
      * Read the persisted active conversation id (client token mode only).
      * Called only after the internal stored-state bootstrap gate resolves.
@@ -9616,6 +9866,8 @@ type AgentWidgetReasoning = {
     durationMs?: number;
 };
 type AgentWidgetToolCall = {
+    /** Optional approval state for activity-row status chrome. */
+    approvalStatus?: "pending" | "approved" | "denied" | "timeout";
     id: string;
     name?: string;
     status: "pending" | "running" | "complete";
@@ -10085,6 +10337,14 @@ declare class AgentWidgetClient {
     private currentClientTurnId;
     private clientSession;
     private sessionInitPromise;
+    /**
+     * Early-init latch for `warmSession()`. `false` = armed. Otherwise it holds
+     * the session value (`null` or an expired session) the one early attempt was
+     * made against, so a failed attempt is not retried on every keystroke. It is
+     * re-armed when a session is installed or cleared, so each session lifetime
+     * gets one early init.
+     */
+    private sessionWarmLatch;
     private lastSentClientToolsFingerprint;
     private clientToolsFingerprintSessionId;
     private sentNonEmptyClientToolsSessionId;
@@ -10193,9 +10453,27 @@ declare class AgentWidgetClient {
         after: string;
         signal: AbortSignal;
     }): Promise<Response>;
+    /**
+     * Fire-and-forget early `initSession()` for client-token mode, driven by the
+     * widget's `sessionInit` trigger (or a host calling it directly, e.g. on
+     * hover). It fires at most once per session lifetime and is a no-op while a
+     * session is live or an init is already in flight. Errors are swallowed, with
+     * no `onSessionExpired` and no UI: a send calls `initSession()` again and
+     * reuses the in-flight promise, so any failure resurfaces there exactly as it
+     * would without the early init. Sends nothing new on the wire. Outside
+     * client-token mode this does nothing.
+     *
+     * Resolves with the session this call initialized, or `null` when it was
+     * skipped or failed. It never rejects.
+     */
+    warmSession(): Promise<ClientSession | null>;
     /**
      * Initialize session for client token mode.
-     * Called automatically on first message if not already initialized.
+     * Called by the send if no live session exists. The widget normally calls
+     * it earlier, when the visitor shows intent to send (see the `sessionInit`
+     * config option and `warmSession()`), and concurrent calls share one
+     * in-flight request, so a send racing an early init issues a single
+     * `/v1/client/init`.
      */
     initSession(): Promise<ClientSession>;
     /** Visitor history rides on client-token init only, and latches off after a 403 degrade. */
@@ -10340,6 +10618,7 @@ declare class AgentWidgetClient {
     private historyUrl;
     /** Explicit per-operation scope wins; otherwise config, then evidence. */
     private resolveHistoryScope;
+    private resolveChatIdentityProof;
     /**
      * Resolve the proof for one logical request. `null` is an intentional
      * browser-scope fallback only while the visitor has never been bound.
@@ -10779,6 +11058,13 @@ declare class AgentWidgetSession {
      * Toggle voice recognition on/off
      */
     toggleVoice(): Promise<void>;
+    /**
+     * Warm the voice path ahead of the mic click (`voiceRecognition.prewarm`).
+     * Session-owned providers (`runtype`, `custom`) get `provider.prewarm()` once
+     * the lazy voice runtime has installed them; the browser (Web Speech) path
+     * warms the client-token session instead. Fire-and-forget and silent.
+     */
+    prewarmVoice(): void;
     /**
      * Cleanup voice resources
      */
@@ -10795,10 +11081,16 @@ declare class AgentWidgetSession {
      * explicitly to pre-initialize the session and get config from server.
      */
     initClientSession(): Promise<ClientSession | null>;
+    /**
+     * Early, fire-and-forget client-token init (`sessionInit` trigger or
+     * `controller.initSession()`). Failures stay silent here: no `onError`, no
+     * UI. The send re-runs `initSession()` and reports them as it always has.
+     */
+    warmClientSession(): void;
     /**
      * Set the client session after initialization
      */
-    setClientSession(session: ClientSession): void;
+    setClientSession(session: ClientSession, pristine?: boolean): void;
     /**
      * Welcome injection is skipped while `suppressWelcomeInjection` is latched:
      * reopening a stored conversation is not a new thread, and the hydrated