@runtypelabs/persona 4.23.2 → 4.25.0

package/dist/theme-reference.d.cts

@@ -196,6 +196,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'>;
@@ -218,6 +220,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 {
@@ -244,10 +255,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.
@@ -286,6 +303,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`). */
@@ -460,6 +485,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'>;
@@ -473,6 +504,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;
     };
@@ -591,12 +624,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
@@ -730,6 +791,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" */
@@ -748,12 +813,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. */
@@ -929,6 +1000,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. */
@@ -977,6 +1050,7 @@ interface ComponentTokens {
     voice: VoiceTokens;
     approval: ApprovalTokens;
     attachment: AttachmentTokens;
+    activity?: ActivityTokens;
     toolBubble: ToolBubbleTokens;
     reasoningBubble: ReasoningBubbleTokens;
     /** Event-stream inspector badge chips. */
@@ -1035,12 +1109,1444 @@ type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
 
+type RuntypeExecutionStreamEvent = ({
+    agentId?: string;
+    agentName?: string;
+    config?: Record<string, unknown>;
+    executionId: string;
+    flowId?: string;
+    flowName?: string;
+    kind: "agent" | "flow";
+    maxTurns?: number;
+    resumed?: boolean;
+    seq: number;
+    source?: string;
+    startedAt: string;
+    totalSteps?: number;
+    type: "execution_start";
+}) | ({
+    claudeManagedAgentId?: string;
+    completedAt?: string;
+    durationMs?: number;
+    executionId: string;
+    externalAgent?: {
+        contextId?: string;
+        taskId?: string;
+    };
+    failedSteps?: number;
+    finalOutput?: string;
+    iterations?: number;
+    kind: "agent" | "flow";
+    seq: number;
+    stepErrorCount?: number;
+    stopReason?: string;
+    success: boolean;
+    successfulSteps?: number;
+    totalCost?: number;
+    totalSteps?: number;
+    totalTokens?: {
+        input: number;
+        output: number;
+    };
+    totalTokensUsed?: number;
+    type: "execution_complete";
+}) | ({
+    blockReason?: string;
+    code?: string;
+    completedAt?: string;
+    error: string | {
+        code: string;
+        details?: Record<string, unknown>;
+        message: string;
+    };
+    executionId: string;
+    finalOutput?: string;
+    kind: "agent" | "flow";
+    seq: number;
+    stopReason?: string;
+    type: "execution_error";
+    upgradeUrl?: string;
+}) | ({
+    executionId: string;
+    id: string;
+    iteration?: number;
+    role: "user" | "assistant" | "system";
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    turnIndex?: number;
+    type: "turn_start";
+}) | ({
+    attributes?: Record<string, string | number | boolean>;
+    completedAt?: string;
+    content?: string;
+    cost?: number;
+    estimatedContextBreakdown?: {
+        categories: Record<string, {
+            chars: number;
+            estimatedTokens: number;
+        }>;
+        contextWindowSize?: number;
+        estimatedTotalTokens: number;
+        estimatedUtilizationPercent?: number;
+    };
+    executionId: string;
+    fallback?: {
+        attempts: Array<{
+            attempt: number;
+            error?: string;
+            model?: string;
+            success: boolean;
+            type: "retry" | "model" | "message" | "flow";
+        }>;
+        exhausted: boolean;
+        model?: string;
+        reason?: string | null;
+        used: boolean;
+    };
+    id: string;
+    iteration?: number;
+    role: "user" | "assistant" | "system";
+    seq: number;
+    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    tokens?: {
+        input: number;
+        output: number;
+    };
+    type: "turn_complete";
+}) | {
+    executionId: string;
+    id: string;
+    iteration?: number;
+    model?: string;
+    ordinal: number;
+    provider?: string;
+    seq: number;
+    startedAt?: string;
+    stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    turnId?: string;
+    type: "model_call_start";
+} | ({
+    attributes?: Record<string, string | number | boolean>;
+    completedAt?: string;
+    cost?: number;
+    durationMs?: number;
+    executionId: string;
+    finishReason?: string;
+    id: string;
+    iteration?: number;
+    model?: string;
+    ordinal: number;
+    provider?: string;
+    responseModel?: string;
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    success?: boolean;
+    tokens?: {
+        cacheRead?: number;
+        cacheWrite?: number;
+        input: number;
+        output: number;
+        reasoning?: number;
+    };
+    turnId?: string;
+    type: "model_call_complete";
+}) | {
+    executionId: string;
+    id: string;
+    index?: number;
+    name?: string;
+    outputVariable?: string;
+    seq: number;
+    startedAt?: string;
+    stepType?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    totalSteps?: number;
+    type: "step_start";
+} | ({
+    completedAt?: string;
+    cost?: number;
+    durationMs?: number;
+    error?: string;
+    executionId: string;
+    fallback?: {
+        attempts: Array<{
+            attempt: number;
+            error?: string;
+            model?: string;
+            success: boolean;
+            type: "retry" | "model" | "message" | "flow";
+        }>;
+        exhausted: boolean;
+        model?: string;
+        reason?: string | null;
+        used: boolean;
+    };
+    id: string;
+    name?: string;
+    result?: unknown;
+    seq: number;
+    stepType?: string;
+    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    success?: boolean;
+    tokensUsed?: number;
+    type: "step_complete";
+    unresolvedVariables?: Array<string>;
+}) | {
+    executionId: string;
+    id: string;
+    index?: number;
+    name?: string;
+    seq: number;
+    skippedAt?: string;
+    stepType?: string;
+    totalSteps?: number;
+    type: "step_skip";
+    when?: string;
+} | ({
+    executionId: string;
+    id: string;
+    parentToolCallId?: string;
+    role?: "user" | "assistant" | "system";
+    seq: number;
+    stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    turnId?: string;
+    type: "text_start";
+}) | {
+    delta: string;
+    executionId: string;
+    id: string;
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    type: "text_delta";
+} | {
+    executionId: string;
+    id: string;
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    text?: string;
+    type: "text_complete";
+} | ({
+    executionId: string;
+    id: string;
+    parentToolCallId?: string;
+    scope?: "turn" | "loop";
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    type: "reasoning_start";
+}) | {
+    delta: string;
+    executionId: string;
+    id: string;
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    type: "reasoning_delta";
+} | ({
+    executionId: string;
+    id: string;
+    scope?: "turn" | "loop";
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    text?: string;
+    type: "reasoning_complete";
+}) | ({
+    executionId: string;
+    id: string;
+    mediaType: string;
+    role?: "user" | "assistant" | "system";
+    seq: number;
+    toolCallId?: string;
+    type: "media_start";
+}) | {
+    delta: string;
+    executionId: string;
+    id: string;
+    seq: number;
+    type: "media_delta";
+} | {
+    data?: string;
+    executionId: string;
+    id: string;
+    mediaType?: string;
+    seq: number;
+    toolCallId?: string;
+    type: "media_complete";
+    url?: string;
+} | ({
+    artifactType: "markdown" | "component";
+    component?: string;
+    executionId?: string;
+    file?: {
+        language?: string;
+        mimeType: string;
+        path: string;
+    };
+    id: string;
+    seq?: number;
+    title?: string;
+    type: "artifact_start";
+}) | {
+    delta: string;
+    executionId?: string;
+    id: string;
+    seq?: number;
+    type: "artifact_delta";
+} | {
+    component: string;
+    executionId?: string;
+    id: string;
+    props: Record<string, unknown>;
+    seq?: number;
+    type: "artifact_update";
+} | {
+    executionId?: string;
+    id: string;
+    seq?: number;
+    type: "artifact_complete";
+} | {
+    executionId: string;
+    id?: string;
+    seq: number;
+    sourceType?: string;
+    title?: string;
+    type: "source";
+    url?: string;
+    [key: string]: unknown;
+} | {
+    executionId: string;
+    iteration?: number;
+    seq: number;
+    state: Record<string, unknown>;
+    type: "state_snapshot";
+} | ({
+    executionId: string;
+    iteration?: number;
+    patch: Array<{
+        from?: string;
+        op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+        path: string;
+        value?: unknown;
+    }>;
+    seq: number;
+    type: "state_delta";
+}) | ({
+    executionId: string;
+    hiddenParameterNames?: Array<string>;
+    iteration?: number;
+    origin?: "webmcp" | "sdk";
+    pageOrigin?: string;
+    parameters?: Record<string, unknown>;
+    seq: number;
+    startedAt?: string;
+    stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    toolCallId: string;
+    toolName: string;
+    toolType: string;
+    type: "tool_start";
+}) | {
+    delta: string;
+    executionId: string;
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    toolCallId: string;
+    type: "tool_input_delta";
+} | {
+    executionId: string;
+    hiddenParameterNames?: Array<string>;
+    parameters: Record<string, unknown>;
+    seq: number;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    toolCallId: string;
+    toolName?: string;
+    type: "tool_input_complete";
+} | {
+    delta: string;
+    executionId: string;
+    seq: number;
+    toolCallId: string;
+    type: "tool_output_delta";
+} | {
+    error?: string;
+    executionId: string;
+    executionTime?: number;
+    iteration?: number;
+    result?: unknown;
+    seq: number;
+    stepId?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    success: boolean;
+    toolCallId: string;
+    toolCost?: number;
+    toolName?: string;
+    type: "tool_complete";
+} | {
+    approvalId: string;
+    description?: string;
+    executionId: string;
+    externalAgent?: {
+        contextId?: string;
+        taskId?: string;
+    };
+    iteration?: number;
+    parameters?: Record<string, unknown>;
+    reason?: string;
+    seq: number;
+    startedAt?: string;
+    subagent?: {
+        agentName?: string;
+        parentToolCallId?: string;
+        toolName: string;
+    };
+    timeout?: number;
+    toolCallId?: string;
+    toolName: string;
+    toolType?: string;
+    type: "approval_start";
+} | ({
+    approvalId: string;
+    completedAt?: string;
+    decision: "approved" | "denied" | "timeout";
+    executionId: string;
+    resolvedBy?: "user" | "system";
+    seq: number;
+    type: "approval_complete";
+}) | ({
+    awaitReason?: string;
+    awaitedAt?: string;
+    crawlId?: string;
+    elicitation?: {
+        message: string;
+        mode: "form" | "url";
+        pauseCount?: number;
+        requestedSchema?: Record<string, unknown>;
+        requests?: Array<{
+            message: string;
+            mode: "form" | "url";
+            name: string;
+            requestedSchema?: Record<string, unknown>;
+            url?: string;
+        }>;
+        serverName?: string;
+        url?: string;
+    };
+    executionId: string;
+    externalAgent?: {
+        contextId?: string;
+        taskId?: string;
+    };
+    origin?: "webmcp" | "sdk";
+    pageOrigin?: string;
+    parameters?: Record<string, unknown>;
+    seq: number;
+    stepId?: string;
+    toolCallId?: string;
+    toolId?: string;
+    toolName?: string;
+    type: "await";
+}) | ({
+    error: string | {
+        code: string;
+        details?: Record<string, unknown>;
+        message: string;
+    };
+    executionId: string;
+    recoverable?: boolean;
+    seq: number;
+    type: "error";
+}) | ({
+    epoch: number;
+    executionId: string;
+    kind: "compaction";
+    outcome?: "ok" | "failed" | "gap" | "skipped";
+    phase: "start" | "complete";
+    reason: "threshold" | "overflow" | "manual" | "surface_policy" | "provider_mismatch";
+    seq: number;
+    strategy: "provider_native" | "summary";
+    tier: number;
+    tokensAfter?: number;
+    tokensBefore?: number;
+    type: "context_notice";
+}) | {
+    executionId: string;
+    seq: number;
+    timestamp: string;
+    type: "ping";
+} | {
+    executionId?: string;
+    name: string;
+    seq?: number;
+    type: "custom";
+    value?: unknown;
+};
+type RuntypeStreamEventOf<U, T extends string> = Extract<U, {
+    type: T;
+}>;
+type RuntypeTurnCompleteEvent = RuntypeStreamEventOf<RuntypeExecutionStreamEvent, "turn_complete">;
+type RuntypeStepCompleteEvent = RuntypeStreamEventOf<RuntypeExecutionStreamEvent, "step_complete">;
+type RuntypeStopReasonKind = NonNullable<RuntypeTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]>;
+
+/**
+ * Text content part for multi-modal messages
+ */
+type TextContentPart = {
+    type: 'text';
+    text: string;
+};
+/**
+ * Image content part for multi-modal messages
+ * Supports base64 data URIs or URLs
+ */
+type ImageContentPart = {
+    type: 'image';
+    image: string;
+    mimeType?: string;
+    alt?: string;
+};
+/**
+ * File content part for multi-modal messages
+ * Supports PDF, TXT, DOCX, and other document types
+ */
+type FileContentPart = {
+    type: 'file';
+    data: string;
+    mimeType: string;
+    filename: string;
+};
+/**
+ * Audio content part for multi-modal messages
+ * Supports base64 data URIs or URLs
+ */
+type AudioContentPart = {
+    type: 'audio';
+    audio: string;
+    mimeType?: string;
+};
+/**
+ * Video content part for multi-modal messages
+ * Supports base64 data URIs or URLs
+ */
+type VideoContentPart = {
+    type: 'video';
+    video: string;
+    mimeType?: string;
+};
+/**
+ * Union type for all content part types
+ */
+type ContentPart = TextContentPart | ImageContentPart | FileContentPart | AudioContentPart | VideoContentPart;
+/** Reference stored on a sent message for transcript fidelity + chip rendering. */
+type AgentWidgetContextMentionRef = {
+    sourceId: string;
+    itemId: string;
+    label: string;
+    iconName?: string;
+    /** Accent color for the inline token (see `AgentWidgetContextMentionItem.color`). */
+    color?: string;
+};
+/**
+ * One ordered segment of a sent message's prose, for inline mention rendering
+ * (`contextMentions.display: "inline"`). Text runs and atomic mention tokens
+ * interleave in document order so the sent bubble re-renders `@tokens` in place
+ * and composer history can round-trip them. Display/transcript concern only —
+ * the model still sees resolved bodies via `llmContent`/`contentParts`.
+ */
+type AgentWidgetContentSegment = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "mention";
+    ref: AgentWidgetContextMentionRef;
+};
+/** Wire shape for the per-turn composer selections. */
+type ComposerOptionsPayload = {
+    selectedModelId?: string;
+    activeModeIds?: string[];
+};
+/**
+ * Metadata attached to messages created during agent execution.
+ */
+type AgentMessageMetadata = {
+    executionId?: string;
+    iteration?: number;
+    turnId?: string;
+    agentName?: string;
+    /**
+     * When this message was produced by a step inside a nested flow executed
+     * as a tool, identifies the parent tool call id. Enables renderers to
+     * visually group or indent nested-flow output under its parent tool.
+     */
+    parentToolId?: string;
+    /**
+     * Nested flow step id that produced this message (e.g. a `send-stream`
+     * or `prompt` step inside the nested flow). Stable key for that step.
+     */
+    parentStepId?: string;
+    /**
+     * Set to `true` on a tool-variant message produced from an `await`
+     * event (`awaitReason: "local_tool_required"`). Signals to UI code that
+     * the tool call is a LOCAL tool and the server is paused waiting for a
+     * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
+     */
+    awaitingLocalTool?: boolean;
+    /**
+     * The provider per-call id (`toolu_…`) carried on the `await`
+     * event 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
+     * over tool name, which collides for same-tool parallel calls. Absent →
+     * fall back to the legacy name-keyed resume contract.
+     */
+    webMcpToolCallId?: string;
+    /**
+     * Set to `true` once the user has picked / typed / dismissed an answer for
+     * an `ask_user_question` tool call, so renderers stop re-mounting the
+     * answer-pill sheet for this tool call on subsequent render passes.
+     */
+    askUserQuestionAnswered?: boolean;
+    /**
+     * In-progress answers for a multi-question `ask_user_question` payload,
+     * keyed by question text. Persisted across refresh so the user lands back
+     * where they were if the page reloads mid-flow. Cleared once
+     * `askUserQuestionAnswered` flips to `true`.
+     */
+    askUserQuestionAnswers?: Record<string, string | string[]>;
+    /**
+     * Current page index for a multi-question `ask_user_question` payload's
+     * paginated stepper. Persists alongside `askUserQuestionAnswers`.
+     */
+    askUserQuestionIndex?: number;
+    /**
+     * Set to `true` once a `suggest_replies` tool call's fire-and-forget
+     * `/resume` has been accepted by the server. Persisted belt-and-suspenders
+     * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
+     * never re-resume the call.
+     */
+    suggestRepliesResolved?: boolean;
+    /**
+     * The client-tool answer the server accepted through `/resume`, kept so
+     * later proxy/agent turns can replay the call and its result to the model.
+     * `toolName` is the widget's internal name (`webmcp:<name>` or a bare
+     * built-in). Set only after the resume succeeds; preserved across
+     * re-emissions of the tool message.
+     */
+    clientToolAnswer?: {
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+        result: unknown;
+        /**
+         * Shared by the answers posted in one `/resume`, i.e. one assistant
+         * turn's parallel calls; a chained call gets a new batch.
+         */
+        batch?: string;
+    };
+};
+/**
+ * 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.
+ *
+ * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
+ * - `wipe`, `glyph-cycle`.
+ *
+ * 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.
+ */
+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
+ * 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.
+ */
+type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
+/**
+ * Context passed to plugin lifecycle hooks. Carries the live DOM references
+ * and resolved animation settings for the currently-streaming message.
+ */
+type StreamAnimationContext = {
+    /** The `.persona-message-content` element owning the streamed text. */
+    container: HTMLElement;
+    /** The outer message bubble element. */
+    bubble: HTMLElement;
+    /** ID of the streaming message. */
+    messageId: string;
+    /** Read-only reference to the message being streamed. */
+    message: AgentWidgetMessage;
+    /** Effective `speed` from `streamAnimation.speed`. */
+    speed: number;
+    /** Effective `duration` from `streamAnimation.duration`. */
+    duration: number;
+};
 /**
- * Theme Reference: Structured documentation and examples for the Persona v2 theme system.
+ * Pluggable stream animation. Third-party packages and inline registrations
+ * implement this interface to add custom reveal effects.
  *
- * Exported via the `@runtypelabs/persona/theme-reference` entry point so it stays
- * out of the IIFE widget bundle. Intended for AI/MCP tool consumption.
+ * Lifecycle:
+ * - When the widget mounts and detects a plugin (either passed via config or
+ *   auto-registered in the IIFE bundle), it injects `styles` once into the
+ *   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.
+ * - 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.
  */
+type StreamAnimationPlugin = {
+    /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
+    name: string;
+    /** Class added to `.persona-message-content` while streaming. */
+    containerClass?: string;
+    /** Class added to the bubble element (e.g. a one-shot scale animation). */
+    bubbleClass?: string;
+    /** Wrap mode applied to text nodes during streaming. @default "none" */
+    wrap?: "none" | "char" | "word";
+    /**
+     * HTML tags whose descendant text is skipped during wrapping. Defaults to
+     * `["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.
+     */
+    skipTags?: string[];
+    /** Append a blinking caret after the last rendered char/word. */
+    useCaret?: boolean;
+    /** CSS string injected into the widget style host on first activation. */
+    styles?: string;
+    /**
+     * Optional custom buffering strategy. Returns the portion of `content`
+     * that should be rendered during streaming. Use this for buffering
+     * schemes beyond the built-in `word` / `line` strategies.
+     */
+    bufferContent?: (content: string, message: AgentWidgetMessage) => string;
+    /**
+     * Fires once when the plugin is first activated inside a widget instance.
+     * Use this to set up MutationObservers or other long-lived listeners.
+     * Return an optional cleanup function that runs on widget destroy.
+     */
+    onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
+    /** Fires after each render that reaches the live DOM. */
+    onAfterRender?: (ctx: StreamAnimationContext) => void;
+    /** Fires when a streamed message's `streaming` flag flips to false. */
+    onStreamComplete?: (ctx: StreamAnimationContext) => void;
+    /**
+     * 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
+     * under unfinished per-char cycles or reveals.
+     */
+    isAnimating?: (message: AgentWidgetMessage) => boolean;
+};
+type AgentWidgetStreamAnimationFeature = {
+    /** Reveal animation to apply while streaming. @default "none" */
+    type?: AgentWidgetStreamAnimationType;
+    /** Pre-first-token placeholder. @default "none" */
+    placeholder?: AgentWidgetStreamAnimationPlaceholder;
+    /**
+     * 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
+     * streaming cadence itself provides the visible stagger.
+     * @default 120
+     */
+    speed?: number;
+    /**
+     * Total duration of container-level animations (`pop-bubble` and custom
+     * plugin animations), in milliseconds.
+     * @default 1800
+     */
+    duration?: number;
+    /**
+     * Trim the accumulated streaming content to a word or line boundary before
+     * rendering. Hides in-progress units until they complete.
+     * @default "none"
+     */
+    buffer?: AgentWidgetStreamAnimationBuffer;
+    /**
+     * Extra animation plugins available to this widget instance. Keys are
+     * plugin names; the matching plugin activates when `type` is set to that
+     * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
+     */
+    plugins?: Record<string, StreamAnimationPlugin>;
+};
+type AgentWidgetDockConfig = {
+    /**
+     * Side of the wrapped container where the docked panel should render.
+     * @default "right"
+     */
+    side?: "left" | "right";
+    /**
+     * Expanded width of the docked panel.
+     * @default "420px"
+     */
+    width?: string;
+    /**
+     * When false, the dock column snaps between `0` and `width` with no CSS transition so main
+     * content does not reflow during the open/close animation.
+     * @default true
+     */
+    animate?: boolean;
+    /**
+     * How the dock panel is shown.
+     * - `"resize"` (default): a flex column grows/shrinks between `0` and `width` (main content reflows).
+     * - `"overlay"`: panel is absolutely positioned and translates in/out **over** full-width content.
+     * - `"push"`: a wide inner track `[content at shell width][panel]` translates horizontally so the panel
+     *   appears to push the workspace aside **without** animating the content column width (Shopify-style).
+     * - `"emerge"`: like `"resize"`, the flex column animates so **page content reflows**; the chat
+     *   panel keeps a **fixed** `dock.width` (not squeezed while the column grows), clipped by the slot so
+     *   it appears to emerge at full width like a floating widget.
+     */
+    reveal?: "resize" | "overlay" | "push" | "emerge";
+    /**
+     * Maximum height of the dock panel, applied as a viewport-overflow guard.
+     *
+     * The docked shell sizes itself with `height: 100%`, which only resolves when
+     * an ancestor (usually `html, body { height: 100% }`) provides a definite
+     * height. Without one, the dock column would otherwise grow with the
+     * conversation and scroll off the page. This cap clamps the panel to the
+     * viewport (and keeps the `resize`/`emerge` reveals pinned with
+     * `position: sticky`; `push`/`overlay` get the cap only, since their
+     * transform/absolute contexts defeat sticky) so a missing height chain
+     * degrades gracefully instead of breaking the chat.
+     *
+     * - 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
+     *   height all the way down to the dock target's parent).
+     *
+     * @default "100dvh"
+     */
+    maxHeight?: string | false;
+};
+/**
+ * Layout configuration for `mountMode: "composer-bar"`. Controls how the
+ * collapsed pill is positioned and sized, and how the panel expands when
+ * the user opens it.
+ */
+type AgentWidgetComposerBarConfig = {
+    /**
+     * Max-width of the collapsed pill composer at the bottom of the viewport.
+     * @default "720px"
+     */
+    collapsedMaxWidth?: string;
+    /**
+     * Bottom offset (CSS length) from the viewport edge in the collapsed state.
+     * @default "16px"
+     */
+    bottomOffset?: string;
+    /**
+     * Auto-expand the panel when the user submits a message while the composer
+     * is collapsed. When false, the message still sends but the panel remains
+     * collapsed (the host can drive expansion programmatically).
+     * @default true
+     */
+    expandOnSubmit?: boolean;
+    /**
+     * Size of the expanded chat panel.
+     * - `"anchored"` (default): the pill stays at the bottom of the viewport
+     *   and the chat history grows upward into a centered column above it.
+     *   Width is driven by `expandedMaxWidth`; the panel's top edge sits at
+     *   `expandedTopOffset` from the viewport top.
+     * - `"fullscreen"`: covers the entire viewport (mobile-app style). Inner
+     *   content is centered horizontally via `contentMaxWidth`.
+     * - `"modal"`: centered sheet with margins; size driven by
+     *   `modalMaxWidth` / `modalMaxHeight`.
+     * @default "anchored"
+     */
+    expandedSize?: "anchored" | "fullscreen" | "modal";
+    /**
+     * When `expandedSize === "anchored"`, max-width of the expanded panel
+     * column. Capped at `calc(100vw - 32px)` on narrow viewports.
+     * @default "880px"
+     */
+    expandedMaxWidth?: string;
+    /**
+     * When `expandedSize === "anchored"`, distance from the viewport top to
+     * the panel's top edge. Accepts any CSS length.
+     * @default "5vh"
+     */
+    expandedTopOffset?: string;
+    /**
+     * Max-width applied to messages, composer form, suggestions, and
+     * attachment previews so they center horizontally inside the expanded
+     * panel. Falls back to `layout.contentMaxWidth` when set; otherwise
+     * defaults to this value.
+     * @default "720px"
+     */
+    contentMaxWidth?: string;
+    /**
+     * When `expandedSize === "modal"`, max-width of the expanded sheet.
+     * @default "880px"
+     */
+    modalMaxWidth?: string;
+    /**
+     * When `expandedSize === "modal"`, max-height of the expanded sheet.
+     * @default "min(90vh, 800px)"
+     */
+    modalMaxHeight?: string;
+    /**
+     * Configuration for the "peek" banner: the chrome-less row above the
+     * collapsed pill that previews the most recent assistant message.
+     */
+    peek?: AgentWidgetComposerBarPeekConfig;
+};
+/**
+ * Configuration for the composer-bar peek banner. Reuses the same
+ * `streamAnimation` shape developers already configure for the main message
+ * stream, so the surface for animations is identical across both contexts.
+ *
+ * Resolution order:
+ * - If `peek.streamAnimation` is set, those values apply to the peek.
+ * - Otherwise the peek inherits from `features.streamAnimation`.
+ *
+ * Per-surface carve-outs:
+ * - `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
+ *   custom plugins all apply unchanged.
+ */
+type AgentWidgetComposerBarPeekConfig = {
+    /**
+     * Reveal animation for the peek's trailing-message preview. Same shape as
+     * `features.streamAnimation`. Omit to inherit from the main stream config.
+     */
+    streamAnimation?: AgentWidgetStreamAnimationFeature;
+};
+type AgentWidgetLauncherConfig = {
+    /** Collapsed launcher shape. V4 defaults to pill; V5 defaults to circle. */
+    variant?: "pill" | "circle";
+    enabled?: boolean;
+    title?: string;
+    subtitle?: string;
+    textHidden?: boolean;
+    iconUrl?: string;
+    agentIconText?: string;
+    agentIconName?: string;
+    agentIconHidden?: boolean;
+    /**
+     * Background color for the agent icon circle in the launcher button. Accepts
+     * any CSS color value. When set, overrides the default primary-color
+     * background (the `persona-bg-persona-primary` utility).
+     */
+    agentIconBackgroundColor?: string;
+    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    /**
+     * Controls how the launcher panel is mounted relative to the host page.
+     * - "floating": default floating launcher / panel behavior
+     * - "docked": wraps the target container and renders as a sibling dock
+     * - "composer-bar": persistent rounded-pill composer fixed to the bottom of
+     *   the viewport that morphs into a fullscreen (or modal) chat panel on
+     *   submit and minimizes back to the pill on close.
+     *
+     * @default "floating"
+     */
+    mountMode?: "floating" | "docked" | "composer-bar";
+    /**
+     * Layout configuration for docked mode.
+     */
+    dock?: AgentWidgetDockConfig;
+    /**
+     * Layout configuration for composer-bar mode.
+     * Only applies when `mountMode === "composer-bar"`.
+     */
+    composerBar?: AgentWidgetComposerBarConfig;
+    autoExpand?: boolean;
+    width?: string;
+    /**
+     * When true, the widget panel will fill the full height of its container.
+     * Useful for sidebar layouts where the chat should take up the entire viewport height.
+     * The widget will use flex layout to ensure header stays at top, messages scroll in middle,
+     * and composer stays fixed at bottom.
+     *
+     * @default false
+     */
+    fullHeight?: boolean;
+    /**
+     * When true, the widget panel will be positioned as a sidebar flush with the viewport edges.
+     * The panel will have:
+     * - No border-radius (square corners)
+     * - No margins (flush with top, left/right, and bottom edges)
+     * - Full viewport height
+     * - Subtle shadow on the edge facing the content
+     * - No border between footer and messages
+     *
+     * Use with `position` to control which side ('bottom-left' for left sidebar, 'bottom-right' for right sidebar).
+     * Automatically enables fullHeight when true.
+     *
+     * @default false
+     */
+    sidebarMode?: boolean;
+    /**
+     * When true, the widget panel renders as a detached card inset within its region,
+     * with rounded corners on all sides and elevation (shadow plus hairline border),
+     * instead of sitting flush against the region edges.
+     *
+     * The gap around the card is themed via `theme.components.panel.inset`. The
+     * background revealed behind it is themed via `theme.components.panel.canvasBackground`
+     * in docked and inline embed modes. In sidebar mode the gap stays click-through, so the
+     * host page shows through it the same way it does in floating mode, and canvasBackground
+     * is a no-op there.
+     *
+     * Applies to sidebar, docked, and inline embed modes. Ignored in mobile fullscreen,
+     * where chrome is already suppressed. Floating mode is unchanged, since it already
+     * renders as a detached card.
+     *
+     * @default false
+     */
+    detachedPanel?: boolean;
+    /**
+     * Width of the sidebar panel when sidebarMode is true.
+     * @default "420px"
+     */
+    sidebarWidth?: string;
+    /**
+     * Offset (in pixels) to subtract from the calculated panel height.
+     * Useful for adjusting the panel height when there are other fixed elements on the page.
+     * Only applies when not in fullHeight or sidebarMode.
+     *
+     * @default 0
+     */
+    heightOffset?: number;
+    /**
+     * When true, the widget panel expands to fill the full viewport on mobile devices.
+     * Removes border-radius, margins, and shadows for a native app-like experience.
+     * Applies when viewport width is at or below `mobileBreakpoint`.
+     *
+     * @default true
+     */
+    mobileFullscreen?: boolean;
+    /**
+     * Viewport width (in pixels) at or below which the widget enters mobile fullscreen mode.
+     * Only applies when `mobileFullscreen` is true.
+     *
+     * @default 640
+     */
+    mobileBreakpoint?: number;
+    /**
+     * CSS z-index applied to the widget wrapper and launcher button in all
+     * positioned modes (floating panel, mobile fullscreen, sidebar, docked
+     * mobile fullscreen). Increase this value if other elements on the host
+     * page appear on top of the widget.
+     *
+     * In viewport-covering modes (sidebar, mobile fullscreen), the widget
+     * also elevates the host element's stacking context and locks
+     * document scroll to prevent background scrolling.
+     *
+     * @default 100000
+     */
+    zIndex?: number;
+    callToActionIconText?: string;
+    callToActionIconName?: string;
+    callToActionIconColor?: string;
+    callToActionIconBackgroundColor?: string;
+    callToActionIconHidden?: boolean;
+    callToActionIconPadding?: string;
+    agentIconSize?: string;
+    callToActionIconSize?: string;
+    headerIconSize?: string;
+    headerIconName?: string;
+    headerIconHidden?: boolean;
+    closeButtonSize?: string;
+    closeButtonColor?: string;
+    closeButtonBackgroundColor?: string;
+    closeButtonBorderWidth?: string;
+    closeButtonBorderColor?: string;
+    closeButtonBorderRadius?: string;
+    closeButtonPaddingX?: string;
+    closeButtonPaddingY?: string;
+    closeButtonPlacement?: "inline" | "top-right";
+    closeButtonIconName?: string;
+    closeButtonIconText?: string;
+    closeButtonTooltipText?: string;
+    closeButtonShowTooltip?: boolean;
+    clearChat?: AgentWidgetClearChatConfig;
+    /**
+     * Border style for the launcher button.
+     * @example "1px solid #e5e7eb" | "2px solid #3b82f6" | "none"
+     * @default "1px solid #e5e7eb"
+     */
+    border?: string;
+    /**
+     * Box shadow for the launcher button.
+     * @example "0 10px 15px -3px rgba(0,0,0,0.1)" | "none"
+     * @default "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)"
+     */
+    shadow?: string;
+    /**
+     * CSS `max-width` for the floating launcher button when the panel is closed.
+     * Title and subtitle each truncate with an ellipsis when space is tight; full strings are available via the native `title` tooltip. Does not affect the open chat panel (`width` / `launcherWidth`).
+     *
+     * @example "min(380px, calc(100vw - 48px))"
+     */
+    collapsedMaxWidth?: string;
+    /**
+     * Proactive nudge bubble anchored above the collapsed floating launcher.
+     * Omit it (the default) and no teaser renders.
+     */
+    teaser?: AgentWidgetLauncherTeaserConfig;
+};
+/**
+ * Launcher teaser: a small bubble above the collapsed launcher. Clicking it
+ * opens the panel and consumes the teaser exactly like an explicit dismissal.
+ * Within a single page load the teaser appears at most once under either
+ * frequency.
+ *
+ * @example
+ * ```typescript
+ * launcher: {
+ *   teaser: { text: "Need a hand picking a plan?", delayMs: 3000 }
+ * }
+ * ```
+ */
+type AgentWidgetLauncherTeaserConfig = {
+    /** Bubble copy. An empty string renders no teaser. */
+    text: string;
+    /**
+     * Delay before the bubble appears, in milliseconds.
+     * @default 0
+     */
+    delayMs?: number;
+    /**
+     * How often the teaser may return.
+     *
+     * `"once"`: a dismissal or a click-through is remembered in `localStorage`
+     * under `` `${persistState.keyPrefix ?? "persona-"}teaser-dismissed` `` and
+     * the teaser never returns on that browser. `"always"`: shows on every page
+     * load, tracked in memory only. `persistState: false` downgrades `"once"` to
+     * in-memory too, so the teaser reappears each load.
+     *
+     * Custom `storageAdapter` implementations do not participate in teaser state.
+     *
+     * @default "once"
+     */
+    frequency?: "once" | "always";
+    /**
+     * Render an x affordance that dismisses the teaser without opening the panel.
+     * @default true
+     */
+    dismissible?: boolean;
+    /**
+     * Accessible label for the dismiss affordance.
+     * @default "Dismiss message"
+     */
+    dismissLabel?: string;
+};
+/**
+ * Structured quote/reply-to state.
+ * Set through `controller.setQuote()`; cleared by `controller.clearQuote()`, a
+ * send, or the banner's dismiss button.
+ */
+type ComposerQuote = {
+    text: string;
+    /** Transcript message the quote came from, when it came from one. */
+    messageId?: string;
+    /** Attribution shown in the banner (e.g. a page title or author). */
+    sourceLabel?: string;
+};
+type AgentWidgetClearChatConfig = {
+    enabled?: boolean;
+    placement?: "inline" | "top-right";
+    iconName?: string;
+    iconColor?: string;
+    backgroundColor?: string;
+    borderWidth?: string;
+    borderColor?: string;
+    borderRadius?: string;
+    size?: string;
+    paddingX?: string;
+    paddingY?: string;
+    tooltipText?: string;
+    showTooltip?: boolean;
+};
+type AgentWidgetMessageRole = "user" | "assistant" | "system";
+type AgentWidgetReasoning = {
+    id: string;
+    status: "pending" | "streaming" | "complete";
+    chunks: string[];
+    /**
+     * Reasoning channel scope (wire spec). `"turn"` is ordinary per-turn
+     * thinking; `"loop"` is a cross-iteration agent reflection (the fold that
+     * replaced the legacy `agent_reflection` event). Optional when the stream does not specify a scope.
+     */
+    scope?: "turn" | "loop";
+    startedAt?: number;
+    completedAt?: number;
+    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";
+    args?: unknown;
+    chunks?: string[];
+    result?: unknown;
+    /** Whether the tool succeeded; failure does not necessarily end the execution. */
+    success?: boolean;
+    error?: string;
+    duration?: number;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number;
+};
+/**
+ * Represents a tool approval request in the chat conversation.
+ * Created when the agent requires human approval before executing a tool.
+ */
+type AgentWidgetApproval = {
+    id: string;
+    status: "pending" | "approved" | "denied" | "timeout";
+    agentId: string;
+    executionId: string;
+    toolName: string;
+    toolType?: string;
+    description: string;
+    /**
+     * 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.
+     */
+    reason?: string;
+    parameters?: unknown;
+    resolvedAt?: number;
+};
+type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
+/**
+ * Per-turn / per-step stop reason emitted by the runtime on
+ * `turn_complete` and `step_complete` SSE events. The vocabulary is
+ * 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
+ *
+ * Absent (`undefined`) means "not reported": distinct from `'unknown'`.
+ */
+type StopReasonKind = RuntypeStopReasonKind;
+/**
+ * Represents a message in the chat conversation.
+ *
+ * @property id - Unique message identifier
+ * @property role - Message role: "user", "assistant", or "system"
+ * @property content - Message text content (for display)
+ * @property contentParts - Original multi-modal content parts (for API requests)
+ * @property createdAt - ISO timestamp when message was created
+ * @property streaming - Whether message is still streaming (for assistant messages)
+ * @property variant - Message variant for assistant messages: "assistant", "reasoning", or "tool"
+ * @property sequence - Message ordering number
+ * @property reasoning - Reasoning data for assistant reasoning messages
+ * @property toolCall - Tool call data for assistant tool messages
+ * @property tools - Array of tool calls
+ * @property viaVoice - Set to `true` when a user message is sent via voice recognition.
+ *                      Useful for implementing voice-specific behaviors like auto-reactivation.
+ */
+type AgentWidgetMessage = {
+    id: string;
+    role: AgentWidgetMessageRole;
+    content: string;
+    createdAt: string;
+    /**
+     * Original multi-modal content parts for this message.
+     * When present, this is sent to the API instead of `content`.
+     * The `content` field contains the text-only representation for display.
+     */
+    contentParts?: ContentPart[];
+    /**
+     * Context mentions attached to this (user) message, for transcript fidelity +
+     * chip rendering in the sent bubble. Refs only — the resolved payloads are
+     * merged into `llmContent`/`contentParts` (model-visible) at send time.
+     */
+    contextMentions?: AgentWidgetContextMentionRef[];
+    /**
+     * Ordered prose + mention blocks for inline-mode rendering and composer history
+     * recall (`contextMentions.display: "inline"`). Present only on inline-mode user
+     * messages; when omitted the sent bubble falls back to the chip row derived from
+     * `contextMentions`. Display/transcript concern only — not the model channel.
+     */
+    contentSegments?: AgentWidgetContentSegment[];
+    /**
+     * Resolved opt-in structured mention context for this (user) message, merged
+     * into the request `context` under `mentions.<sourceId>.<itemId>` by the
+     * client. Internal: set at send time from each source's `resolve().context`.
+     */
+    mentionContext?: Record<string, unknown>;
+    /**
+     * Quote/reply-to this (user) message was sent with, for transcript fidelity.
+     * The model-visible copy is a delimited text part ahead of the user's text;
+     * this field keeps the structured source separately.
+     */
+    quote?: ComposerQuote;
+    /**
+     * Per-turn composer selections this (user) message was sent with. Retained so
+     * `session.resubmitFrom(..., { reason: "retry" })` replays the same model and
+     * mode selection the original turn used.
+     */
+    composerOptions?: ComposerOptionsPayload;
+    streaming?: boolean;
+    variant?: AgentWidgetMessageVariant;
+    sequence?: number;
+    reasoning?: AgentWidgetReasoning;
+    toolCall?: AgentWidgetToolCall;
+    tools?: AgentWidgetToolCall[];
+    /** Approval data for messages with variant "approval" */
+    approval?: AgentWidgetApproval;
+    viaVoice?: boolean;
+    /**
+     * Set to `true` on placeholder messages injected during Runtype voice processing.
+     * Use this in `messageTransform` to detect and customize voice processing placeholders.
+     *
+     * @example
+     * messageTransform: ({ text, message }) => {
+     *   if (message.voiceProcessing && message.role === 'user') {
+     *     return '<div class="my-voice-spinner">Transcribing...</div>';
+     *   }
+     *   return text;
+     * }
+     */
+    voiceProcessing?: boolean;
+    /**
+     * Raw structured payload for this message (e.g., JSON action response).
+     * Populated automatically when structured parsers run.
+     */
+    rawContent?: string;
+    /**
+     * LLM-specific content for API requests.
+     * When present, this is sent to the LLM instead of `content`.
+     *
+     * Priority for API payload:
+     * 1. `contentParts` (if present, used as-is for multi-modal)
+     * 2. `llmContent` (if present, sent as string)
+     * 3. `rawContent` (backward compatibility with structured parsers)
+     * 4. `content` (fallback - display content)
+     *
+     * The `content` field is always used for UI display.
+     *
+     * @example
+     * // Show full details to user, send summary to LLM
+     * {
+     *   content: "**Product:** iPhone 15 Pro\n**Price:** $1,199\n**SKU:** IP15P-256",
+     *   llmContent: "[Product search: iPhone 15 Pro, $1199]"
+     * }
+     */
+    llmContent?: string;
+    /**
+     * Text segment identity for chronological ordering.
+     * When present, identifies which text segment this message represents
+     * (e.g., "text_0", "text_1") for messages split at tool boundaries.
+     */
+    partId?: string;
+    /**
+     * Metadata for messages created during agent loop execution.
+     * Contains execution context like iteration number and turn ID.
+     */
+    agentMetadata?: AgentMessageMetadata;
+    /**
+     * Per-turn stop reason reported by the runtime on `turn_complete`
+     * (agent-loop path) or the last `step_complete` for a prompt step
+     * (dispatch / flow path). Absent when the API did not report a value.
+     *
+     * When set to a non-natural value (`max_tool_calls`, `length`,
+     * `content_filter`, `error`), the widget renders an inline notice on
+     * the assistant bubble. See `config.copy.stopReasonNotice` to override
+     * the default copy.
+     */
+    stopReason?: StopReasonKind;
+};
+
+type ThemeDefaultsVersion = 'v4' | 'v5';
+
+type DefaultsVersion = "v4" | "v5";
 
 declare const THEME_TOKEN_DOCS: {
     overview: string;
@@ -1300,7 +2806,9 @@ declare const THEME_EXAMPLES: Record<string, ThemeExample>;
  * Returns token system docs, the default color palette and radius scale,
  * example themes, and a list of SDK-bundled presets.
  */
-declare function getThemeReference(): {
+declare function getThemeReference(future?: {
+    v5Defaults?: boolean;
+}): {
     tokenDocs: {
         overview: string;
         layers: {
@@ -1547,8 +3055,10 @@ declare function getThemeReference(): {
             };
         };
     };
+    defaultsVersion: DefaultsVersion;
+    themeDefaultsVersion: ThemeDefaultsVersion;
     defaultColorPalette: {
-        primary: {
+        gray: {
             50: string;
             100: string;
             200: string;
@@ -1561,7 +3071,7 @@ declare function getThemeReference(): {
             900: string;
             950: string;
         };
-        secondary: {
+        primary: {
             50: string;
             100: string;
             200: string;
@@ -1574,7 +3084,7 @@ declare function getThemeReference(): {
             900: string;
             950: string;
         };
-        accent: {
+        secondary: {
             50: string;
             100: string;
             200: string;
@@ -1587,7 +3097,7 @@ declare function getThemeReference(): {
             900: string;
             950: string;
         };
-        gray: {
+        accent: {
             50: string;
             100: string;
             200: string;
@@ -1685,6 +3195,7 @@ declare function getThemeReference(): {
         '2xl': string;
         full: string;
     };
+    defaultLauncher: AgentWidgetLauncherConfig | undefined;
     examples: Record<string, ThemeExample>;
     sdkPresets: string[];
 };