@runtypelabs/persona 4.23.2 → 4.24.0

package/dist/event-stream-view.d.cts

@@ -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. */
@@ -4293,6 +4368,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"
@@ -4323,9 +4406,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.
      *
@@ -4356,6 +4440,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
@@ -5051,8 +5143,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.
@@ -5436,7 +5528,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[];
     /**
@@ -5647,6 +5739,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;
@@ -6390,9 +6484,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
@@ -6404,7 +6498,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;
     /**
@@ -6418,8 +6512,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"
@@ -6461,7 +6556,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;
@@ -7236,7 +7338,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;
@@ -7247,7 +7350,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 & {
@@ -7301,8 +7404,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";
 /**
@@ -7356,7 +7459,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
@@ -7369,19 +7475,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.
@@ -7389,7 +7498,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;
     /**
@@ -7881,6 +7991,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
@@ -8494,7 +8607,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;
     /**
@@ -8649,6 +8785,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
@@ -8681,13 +8857,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.
@@ -9361,6 +9544,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";