@runtypelabs/persona 3.5.2 → 3.7.0

package/dist/theme-editor.d.ts

@@ -0,0 +1,3888 @@
+type TokenType = 'color' | 'spacing' | 'typography' | 'shadow' | 'border' | 'radius';
+type TokenReference<_T extends TokenType = TokenType> = string;
+interface ColorShade {
+    50?: string;
+    100?: string;
+    200?: string;
+    300?: string;
+    400?: string;
+    500?: string;
+    600?: string;
+    700?: string;
+    800?: string;
+    900?: string;
+    950?: string;
+    [key: string]: string | undefined;
+}
+interface ColorPalette {
+    gray: ColorShade;
+    primary: ColorShade;
+    secondary: ColorShade;
+    accent: ColorShade;
+    success: ColorShade;
+    warning: ColorShade;
+    error: ColorShade;
+    info: ColorShade;
+    [key: string]: ColorShade;
+}
+interface SpacingScale {
+    0: string;
+    1: string;
+    2: string;
+    3: string;
+    4: string;
+    5: string;
+    6: string;
+    8: string;
+    10: string;
+    12: string;
+    16: string;
+    20: string;
+    24: string;
+    32: string;
+    40: string;
+    48: string;
+    56: string;
+    64: string;
+    [key: string]: string;
+}
+interface ShadowScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+    [key: string]: string;
+}
+interface BorderScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    [key: string]: string;
+}
+interface RadiusScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    full: string;
+    [key: string]: string;
+}
+interface TypographyScale {
+    fontFamily: {
+        sans: string;
+        serif: string;
+        mono: string;
+    };
+    fontSize: {
+        xs: string;
+        sm: string;
+        base: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        '3xl': string;
+        '4xl': string;
+    };
+    fontWeight: {
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+    };
+    lineHeight: {
+        tight: string;
+        normal: string;
+        relaxed: string;
+    };
+}
+interface SemanticColors {
+    primary: TokenReference<'color'>;
+    secondary: TokenReference<'color'>;
+    accent: TokenReference<'color'>;
+    surface: TokenReference<'color'>;
+    background: TokenReference<'color'>;
+    container: TokenReference<'color'>;
+    text: TokenReference<'color'>;
+    textMuted: TokenReference<'color'>;
+    textInverse: TokenReference<'color'>;
+    border: TokenReference<'color'>;
+    divider: TokenReference<'color'>;
+    interactive: {
+        default: TokenReference<'color'>;
+        hover: TokenReference<'color'>;
+        focus: TokenReference<'color'>;
+        active: TokenReference<'color'>;
+        disabled: TokenReference<'color'>;
+    };
+    feedback: {
+        success: TokenReference<'color'>;
+        warning: TokenReference<'color'>;
+        error: TokenReference<'color'>;
+        info: TokenReference<'color'>;
+    };
+}
+interface SemanticSpacing {
+    xs: TokenReference<'spacing'>;
+    sm: TokenReference<'spacing'>;
+    md: TokenReference<'spacing'>;
+    lg: TokenReference<'spacing'>;
+    xl: TokenReference<'spacing'>;
+    '2xl': TokenReference<'spacing'>;
+}
+interface SemanticTypography {
+    fontFamily: TokenReference<'typography'>;
+    fontSize: TokenReference<'typography'>;
+    fontWeight: TokenReference<'typography'>;
+    lineHeight: TokenReference<'typography'>;
+}
+interface SemanticTokens {
+    colors: SemanticColors;
+    spacing: SemanticSpacing;
+    typography: SemanticTypography;
+}
+interface ComponentTokenSet {
+    background?: TokenReference<'color'>;
+    foreground?: TokenReference<'color'>;
+    border?: TokenReference<'color'>;
+    borderRadius?: TokenReference<'radius'>;
+    padding?: TokenReference<'spacing'>;
+    margin?: TokenReference<'spacing'>;
+    shadow?: TokenReference<'shadow'>;
+    opacity?: number;
+}
+interface ButtonTokens extends ComponentTokenSet {
+    primary: ComponentTokenSet;
+    secondary: ComponentTokenSet;
+    ghost: ComponentTokenSet;
+}
+interface InputTokens extends ComponentTokenSet {
+    background: TokenReference<'color'>;
+    placeholder: TokenReference<'color'>;
+    focus: {
+        border: TokenReference<'color'>;
+        ring: TokenReference<'color'>;
+    };
+}
+interface LauncherTokens extends ComponentTokenSet {
+    size: string;
+    iconSize: string;
+    shadow: TokenReference<'shadow'>;
+}
+interface PanelTokens extends ComponentTokenSet {
+    width: string;
+    maxWidth: string;
+    height: string;
+    maxHeight: string;
+}
+interface HeaderTokens extends ComponentTokenSet {
+    background: TokenReference<'color'>;
+    border: TokenReference<'color'>;
+    borderRadius: TokenReference<'radius'>;
+    /** 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 title line (next to the icon, or minimal layout title). */
+    titleForeground: TokenReference<'color'>;
+    /** Header subtitle line under the title. */
+    subtitleForeground: TokenReference<'color'>;
+    /** Default color for clear / close icon buttons when launcher overrides are unset. */
+    actionIconForeground: TokenReference<'color'>;
+    /** 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`). */
+    borderBottom?: string;
+}
+interface MessageTokens {
+    user: {
+        background: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+        borderRadius: TokenReference<'radius'>;
+        /** User bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+        shadow?: string;
+    };
+    assistant: {
+        background: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+        borderRadius: TokenReference<'radius'>;
+        /** Assistant bubble border color (CSS color). */
+        border?: TokenReference<'color'>;
+        /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+        shadow?: string;
+    };
+}
+interface MarkdownTokens {
+    inlineCode: {
+        background: TokenReference<'color'>;
+        foreground: TokenReference<'color'>;
+    };
+    /** Foreground for `<a>` in rendered markdown (assistant bubbles + artifact pane). */
+    link?: {
+        foreground: TokenReference<'color'>;
+    };
+    /**
+     * Body font for rendered markdown blocks (artifact pane + markdown bubbles).
+     * Use a raw CSS `font-family` value, e.g. `Georgia, serif`.
+     */
+    prose?: {
+        fontFamily?: string;
+    };
+    /** Optional heading scale overrides (raw CSS or resolvable token paths). */
+    heading?: {
+        h1?: {
+            fontSize?: string;
+            fontWeight?: string;
+        };
+        h2?: {
+            fontSize?: string;
+            fontWeight?: string;
+        };
+    };
+}
+interface VoiceTokens {
+    recording: {
+        indicator: TokenReference<'color'>;
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+    };
+    processing: {
+        icon: TokenReference<'color'>;
+        background: TokenReference<'color'>;
+    };
+    speaking: {
+        icon: TokenReference<'color'>;
+    };
+}
+interface ApprovalTokens {
+    requested: {
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+    };
+    approve: ComponentTokenSet;
+    deny: ComponentTokenSet;
+}
+interface AttachmentTokens {
+    image: {
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+    };
+}
+/** Tool-call row chrome (collapsible tool bubbles). */
+interface ToolBubbleTokens {
+    /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
+    shadow: string;
+}
+/** Reasoning / “thinking” row chrome. */
+interface ReasoningBubbleTokens {
+    shadow: string;
+}
+/** Composer (message input) chrome. */
+interface ComposerChromeTokens {
+    /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
+    shadow: string;
+}
+/** Artifact toolbar chrome. */
+interface ArtifactToolbarTokens {
+    iconHoverColor?: string;
+    iconHoverBackground?: string;
+    iconPadding?: string;
+    iconBorderRadius?: string;
+    iconBorder?: string;
+    toggleGroupGap?: string;
+    toggleBorderRadius?: string;
+    copyBackground?: string;
+    copyBorder?: string;
+    copyColor?: string;
+    copyBorderRadius?: string;
+    copyPadding?: string;
+    copyMenuBackground?: string;
+    copyMenuBorder?: string;
+    copyMenuShadow?: string;
+    copyMenuBorderRadius?: string;
+    copyMenuItemHoverBackground?: string;
+    /** Base background of icon buttons (defaults to --persona-surface). */
+    iconBackground?: string;
+    /** Border on the toolbar (e.g., `none` to remove the bottom border). */
+    toolbarBorder?: string;
+}
+/** Artifact tab strip chrome. */
+interface ArtifactTabTokens {
+    background?: string;
+    activeBackground?: string;
+    activeBorder?: string;
+    borderRadius?: string;
+    textColor?: string;
+    /** Hover background for inactive tabs. */
+    hoverBackground?: string;
+    /** Tab list container background. */
+    listBackground?: string;
+    /** Tab list container border color. */
+    listBorderColor?: string;
+    /** Tab list container padding (CSS shorthand). */
+    listPadding?: string;
+}
+/** Artifact pane chrome. */
+interface ArtifactPaneTokens {
+    /**
+     * Background for the artifact column (toolbar + content), resolved from the theme.
+     * Defaults to `semantic.colors.container` so the pane matches assistant message surfaces.
+     * `features.artifacts.layout.paneBackground` still wins when set (layout escape hatch).
+     */
+    background?: string;
+    toolbarBackground?: string;
+}
+/** Icon button chrome (used by createIconButton). */
+interface IconButtonTokens {
+    background?: string;
+    border?: string;
+    color?: string;
+    padding?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    hoverColor?: string;
+    /** Background when aria-pressed="true". */
+    activeBackground?: string;
+    /** Border color when aria-pressed="true". */
+    activeBorder?: string;
+}
+/** Label button chrome (used by createLabelButton). */
+interface LabelButtonTokens {
+    background?: string;
+    border?: string;
+    color?: string;
+    padding?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    fontSize?: string;
+    gap?: string;
+}
+/** Scroll-to-bottom pill chrome shared by transcript + event stream. */
+interface ScrollToBottomTokens extends ComponentTokenSet {
+    size?: string;
+    gap?: string;
+    fontSize?: string;
+    iconSize?: string;
+}
+/** Toggle group chrome (used by createToggleGroup). */
+interface ToggleGroupTokens {
+    /** Gap between toggle buttons. Default: 0 (connected). */
+    gap?: string;
+    /** Border radius for first/last buttons. */
+    borderRadius?: string;
+}
+interface ComponentTokens {
+    button: ButtonTokens;
+    input: InputTokens;
+    launcher: LauncherTokens;
+    panel: PanelTokens;
+    header: HeaderTokens;
+    message: MessageTokens;
+    /** Markdown surfaces (chat + artifact pane). */
+    markdown?: MarkdownTokens;
+    voice: VoiceTokens;
+    approval: ApprovalTokens;
+    attachment: AttachmentTokens;
+    toolBubble: ToolBubbleTokens;
+    reasoningBubble: ReasoningBubbleTokens;
+    composer: ComposerChromeTokens;
+    /** Icon button styling tokens. */
+    iconButton?: IconButtonTokens;
+    /** Label button styling tokens. */
+    labelButton?: LabelButtonTokens;
+    /** Scroll-to-bottom indicator styling tokens. */
+    scrollToBottom?: ScrollToBottomTokens;
+    /** Toggle group styling tokens. */
+    toggleGroup?: ToggleGroupTokens;
+    /** Artifact toolbar, tab strip, and pane chrome. */
+    artifact?: {
+        toolbar?: ArtifactToolbarTokens;
+        tab?: ArtifactTabTokens;
+        pane?: ArtifactPaneTokens;
+    };
+}
+interface PaletteExtras {
+    transitions?: Record<string, string>;
+    easings?: Record<string, string>;
+}
+interface PersonaThemeBase {
+    palette: {
+        colors: ColorPalette;
+        spacing: SpacingScale;
+        typography: TypographyScale;
+        shadows: ShadowScale;
+        borders: BorderScale;
+        radius: RadiusScale;
+    } & PaletteExtras;
+}
+interface PersonaThemeSemantic {
+    semantic: SemanticTokens;
+}
+interface PersonaThemeComponents {
+    components: ComponentTokens;
+}
+type PersonaTheme = PersonaThemeBase & PersonaThemeSemantic & PersonaThemeComponents;
+/** Recursive partial for `config.theme` / `config.darkTheme` overrides. */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+
+/**
+ * Plugin interface for customizing widget components
+ */
+interface AgentWidgetPlugin {
+    /**
+     * Unique identifier for the plugin
+     */
+    id: string;
+    /**
+     * Optional priority (higher = runs first). Default: 0
+     */
+    priority?: number;
+    /**
+     * Custom renderer for message bubbles
+     * Return null to use default renderer
+     */
+    renderMessage?: (context: {
+        message: AgentWidgetMessage;
+        defaultRenderer: () => HTMLElement;
+        config: AgentWidgetConfig;
+    }) => HTMLElement | null;
+    /**
+     * Custom renderer for launcher button
+     * Return null to use default renderer
+     */
+    renderLauncher?: (context: {
+        config: AgentWidgetConfig;
+        defaultRenderer: () => HTMLElement;
+        onToggle: () => void;
+    }) => HTMLElement | null;
+    /**
+     * Custom renderer for panel header
+     * Return null to use default renderer
+     */
+    renderHeader?: (context: {
+        config: AgentWidgetConfig;
+        defaultRenderer: () => HTMLElement;
+        onClose?: () => void;
+    }) => HTMLElement | null;
+    /**
+     * Custom renderer for composer/input area
+     * Return null to use default renderer
+     */
+    renderComposer?: (context: {
+        config: AgentWidgetConfig;
+        defaultRenderer: () => HTMLElement;
+        onSubmit: (text: string) => void;
+        /**
+         * When true, the assistant stream is active — same moment `session.isStreaming()` becomes true.
+         * Prefer wiring controls to `data-persona-composer-disable-when-streaming` plus `setComposerDisabled`
+         * in the host, or react to `footer.dataset.personaComposerStreaming === "true"`.
+         */
+        streaming: boolean;
+        /**
+         * Legacy alias: host disables the primary submit control while `streaming` is true.
+         * @deprecated Use `streaming` for new plugins.
+         */
+        disabled: boolean;
+        /** Opens the hidden file input when `config.attachments.enabled` is true (no-op otherwise). */
+        openAttachmentPicker: () => void;
+        /** From `config.composer.models` */
+        models?: Array<{
+            id: string;
+            label: string;
+        }>;
+        /** From `config.composer.selectedModelId` */
+        selectedModelId?: string;
+        /** Updates `config.composer.selectedModelId` for the running widget instance. */
+        onModelChange?: (modelId: string) => void;
+        /**
+         * Same behavior as the built-in mic when voice is enabled.
+         * Omitted when `config.voiceRecognition.enabled` is not true.
+         */
+        onVoiceToggle?: () => void;
+    }) => HTMLElement | null;
+    /**
+     * Custom renderer for reasoning bubbles
+     * Return null to use default renderer
+     */
+    renderReasoning?: (context: {
+        message: AgentWidgetMessage;
+        defaultRenderer: () => HTMLElement;
+        config: AgentWidgetConfig;
+    }) => HTMLElement | null;
+    /**
+     * Custom renderer for tool call bubbles
+     * Return null to use default renderer
+     */
+    renderToolCall?: (context: {
+        message: AgentWidgetMessage;
+        defaultRenderer: () => HTMLElement;
+        config: AgentWidgetConfig;
+    }) => HTMLElement | null;
+    /**
+     * Custom renderer for approval bubbles
+     * Return null to use default renderer
+     */
+    renderApproval?: (context: {
+        message: AgentWidgetMessage;
+        defaultRenderer: () => HTMLElement;
+        config: AgentWidgetConfig;
+    }) => HTMLElement | null;
+    /**
+     * Custom renderer for loading indicator
+     * Return null to use default renderer (or config-based renderer)
+     *
+     * @example
+     * ```typescript
+     * renderLoadingIndicator: ({ location, defaultRenderer }) => {
+     *   if (location === 'standalone') {
+     *     const el = document.createElement('div');
+     *     el.textContent = 'Thinking...';
+     *     return el;
+     *   }
+     *   return defaultRenderer();
+     * }
+     * ```
+     */
+    renderLoadingIndicator?: (context: LoadingIndicatorRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for idle state indicator.
+     * Called when the widget is idle (not streaming) and has at least one message.
+     * Return an HTMLElement to display, or null to hide (default).
+     *
+     * @example
+     * ```typescript
+     * renderIdleIndicator: ({ lastMessage, messageCount }) => {
+     *   if (messageCount === 0) return null;
+     *   if (lastMessage?.role !== 'assistant') return null;
+     *   const el = document.createElement('div');
+     *   el.className = 'idle-pulse';
+     *   el.setAttribute('data-preserve-animation', 'true');
+     *   return el;
+     * }
+     * ```
+     */
+    renderIdleIndicator?: (context: IdleIndicatorRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for the entire event stream view.
+     * Return null to use default renderer.
+     */
+    renderEventStreamView?: (context: EventStreamViewRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for individual event stream rows.
+     * Return null to use default renderer.
+     */
+    renderEventStreamRow?: (context: EventStreamRowRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for the event stream toolbar/header bar.
+     * Return null to use default renderer.
+     */
+    renderEventStreamToolbar?: (context: EventStreamToolbarRenderContext) => HTMLElement | null;
+    /**
+     * Custom renderer for the expanded event payload display.
+     * Return null to use default renderer.
+     */
+    renderEventStreamPayload?: (context: EventStreamPayloadRenderContext) => HTMLElement | null;
+    /**
+     * Called when plugin is registered
+     */
+    onRegister?: () => void;
+    /**
+     * Called when plugin is unregistered
+     */
+    onUnregister?: () => void;
+}
+
+/**
+ * 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;
+};
+/**
+ * Union type for all content part types
+ */
+type ContentPart = TextContentPart | ImageContentPart | FileContentPart;
+/**
+ * Message content can be a simple string or an array of content parts
+ */
+type MessageContent = string | ContentPart[];
+type AgentWidgetContextProviderContext = {
+    messages: AgentWidgetMessage[];
+    config: AgentWidgetConfig;
+};
+type AgentWidgetContextProvider = (context: AgentWidgetContextProviderContext) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+type AgentWidgetRequestPayloadMessage = {
+    role: AgentWidgetMessageRole;
+    content: MessageContent;
+    createdAt: string;
+};
+type AgentWidgetRequestPayload = {
+    messages: AgentWidgetRequestPayloadMessage[];
+    flowId?: string;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    /** Per-turn template variables for /v1/client/chat (merged as root-level {{var}} in Runtype). */
+    inputs?: Record<string, unknown>;
+};
+/**
+ * Configuration for agent loop behavior.
+ */
+type AgentLoopConfig = {
+    /** Maximum number of agent turns (1-100). The loop continues while the model calls tools. */
+    maxTurns: number;
+    /** Maximum cost budget in USD. Agent stops when exceeded. */
+    maxCost?: number;
+    /** Enable periodic reflection during execution */
+    enableReflection?: boolean;
+    /** Number of iterations between reflections (1-50) */
+    reflectionInterval?: number;
+};
+/**
+ * Configuration for agent tools (search, code execution, MCP servers, etc.)
+ */
+type AgentToolsConfig = {
+    /** Tool IDs to enable (e.g., "builtin:exa", "builtin:dalle", "builtin:openai_web_search") */
+    toolIds?: string[];
+    /** Per-tool configuration overrides keyed by tool ID */
+    toolConfigs?: Record<string, Record<string, unknown>>;
+    /** Inline tool definitions for runtime-defined tools */
+    runtimeTools?: Array<Record<string, unknown>>;
+    /** Custom MCP server connections */
+    mcpServers?: Array<Record<string, unknown>>;
+    /** Maximum number of tool invocations per execution */
+    maxToolCalls?: number;
+    /** Tool approval configuration for human-in-the-loop workflows */
+    approval?: {
+        /** Tool names/patterns to require approval for, or true for all tools */
+        require: string[] | boolean;
+        /** Approval timeout in milliseconds (default: 300000 / 5 minutes) */
+        timeout?: number;
+    };
+};
+/** Artifact kinds for the Persona sidebar and dispatch payload */
+type PersonaArtifactKind = "markdown" | "component";
+/**
+ * Agent configuration for agent execution mode.
+ * When provided in the widget config, enables agent loop execution instead of flow dispatch.
+ */
+type ArtifactConfigPayload = {
+    enabled: true;
+    types: PersonaArtifactKind[];
+};
+type AgentConfig = {
+    /** Agent display name */
+    name: string;
+    /** Model identifier (e.g., 'openai:gpt-4o-mini', 'qwen/qwen3-8b') */
+    model: string;
+    /** System prompt for the agent */
+    systemPrompt: string;
+    /** Temperature for model responses */
+    temperature?: number;
+    /** Tool configuration for the agent */
+    tools?: AgentToolsConfig;
+    /** Persona artifacts — sibling of tools (virtual agent / API parity) */
+    artifacts?: ArtifactConfigPayload;
+    /** Loop configuration for multi-turn execution */
+    loopConfig?: AgentLoopConfig;
+};
+/**
+ * Options for agent execution requests.
+ */
+type AgentRequestOptions = {
+    /** Whether to stream the response (should be true for widget usage) */
+    streamResponse?: boolean;
+    /** Record mode: 'virtual' for no persistence, 'existing'/'create' for database records */
+    recordMode?: 'virtual' | 'existing' | 'create';
+    /** Whether to store results server-side */
+    storeResults?: boolean;
+    /** Enable debug mode for additional event data */
+    debugMode?: boolean;
+};
+/**
+ * Metadata attached to messages created during agent execution.
+ */
+type AgentMessageMetadata = {
+    executionId?: string;
+    iteration?: number;
+    turnId?: string;
+    agentName?: string;
+};
+type AgentWidgetRequestMiddlewareContext = {
+    payload: AgentWidgetRequestPayload;
+    config: AgentWidgetConfig;
+};
+type AgentWidgetRequestMiddleware = (context: AgentWidgetRequestMiddlewareContext) => AgentWidgetRequestPayload | void | Promise<AgentWidgetRequestPayload | void>;
+type AgentWidgetParsedAction = {
+    type: string;
+    payload: Record<string, unknown>;
+    raw?: unknown;
+};
+type AgentWidgetActionParserInput = {
+    text: string;
+    message: AgentWidgetMessage;
+};
+type AgentWidgetActionParser = (input: AgentWidgetActionParserInput) => AgentWidgetParsedAction | null | undefined;
+type AgentWidgetActionHandlerResult = {
+    handled?: boolean;
+    displayText?: string;
+    persistMessage?: boolean;
+    resubmit?: boolean;
+};
+type AgentWidgetActionContext = {
+    message: AgentWidgetMessage;
+    metadata: Record<string, unknown>;
+    updateMetadata: (updater: (prev: Record<string, unknown>) => Record<string, unknown>) => void;
+    document: Document | null;
+    /**
+     * Trigger automatic model continuation.
+     * Call this AFTER completing async operations (e.g., injecting search results)
+     * to have the model analyze the injected data.
+     *
+     * Use this instead of returning `resubmit: true` for handlers that do async work,
+     * as it ensures the continuation happens after the data is available in context.
+     *
+     * @example
+     * // In an action handler
+     * const results = await fetchProducts(query);
+     * session.injectAssistantMessage({ content: formatResults(results) });
+     * context.triggerResubmit();
+     */
+    triggerResubmit: () => void;
+};
+type AgentWidgetActionHandler = (action: AgentWidgetParsedAction, context: AgentWidgetActionContext) => AgentWidgetActionHandlerResult | void;
+type AgentWidgetStoredState = {
+    messages?: AgentWidgetMessage[];
+    metadata?: Record<string, unknown>;
+};
+interface AgentWidgetStorageAdapter {
+    load?: () => AgentWidgetStoredState | null | Promise<AgentWidgetStoredState | null>;
+    save?: (state: AgentWidgetStoredState) => void | Promise<void>;
+    clear?: () => void | Promise<void>;
+}
+type AgentWidgetVoiceStateEvent = {
+    active: boolean;
+    source: "user" | "auto" | "restore" | "system";
+    timestamp: number;
+};
+type AgentWidgetActionEventPayload = {
+    action: AgentWidgetParsedAction;
+    message: AgentWidgetMessage;
+};
+/**
+ * Feedback event payload for upvote/downvote actions on messages
+ */
+type AgentWidgetMessageFeedback = {
+    type: "upvote" | "downvote";
+    messageId: string;
+    message: AgentWidgetMessage;
+};
+/**
+ * Configuration for message action buttons (copy, upvote, downvote)
+ *
+ * **Client Token Mode**: When using `clientToken`, feedback is automatically
+ * sent to your Runtype backend. Just enable the buttons and you're done!
+ * The `onFeedback` and `onCopy` callbacks are optional for additional local handling.
+ *
+ * @example
+ * ```typescript
+ * // With clientToken - feedback is automatic!
+ * config: {
+ *   clientToken: 'ct_live_...',
+ *   messageActions: {
+ *     showUpvote: true,
+ *     showDownvote: true,
+ *     // No onFeedback needed - sent to backend automatically
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetMessageActionsConfig = {
+    /**
+     * Enable/disable message actions entirely
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Show copy button
+     * @default true
+     */
+    showCopy?: boolean;
+    /**
+     * Show upvote button.
+     * When using `clientToken`, feedback is sent to the backend automatically.
+     * @default false
+     */
+    showUpvote?: boolean;
+    /**
+     * Show downvote button.
+     * When using `clientToken`, feedback is sent to the backend automatically.
+     * @default false
+     */
+    showDownvote?: boolean;
+    /**
+     * Visibility mode: 'always' shows buttons always, 'hover' shows on hover only
+     * @default 'hover'
+     */
+    visibility?: "always" | "hover";
+    /**
+     * Horizontal alignment of action buttons
+     * @default 'right'
+     */
+    align?: "left" | "center" | "right";
+    /**
+     * Layout style for action buttons
+     * - 'pill-inside': Compact floating pill around just the buttons (default for hover)
+     * - 'row-inside': Full-width row at the bottom of the message
+     * @default 'pill-inside'
+     */
+    layout?: "pill-inside" | "row-inside";
+    /**
+     * Callback when user submits feedback (upvote/downvote).
+     *
+     * **Note**: When using `clientToken`, feedback is AUTOMATICALLY sent to your
+     * backend via `/v1/client/feedback`. This callback is called IN ADDITION to
+     * the automatic submission, useful for updating local UI or analytics.
+     */
+    onFeedback?: (feedback: AgentWidgetMessageFeedback) => void;
+    /**
+     * Callback when user copies a message.
+     *
+     * **Note**: When using `clientToken`, copy events are AUTOMATICALLY tracked
+     * via `/v1/client/feedback`. This callback is called IN ADDITION to the
+     * automatic tracking.
+     */
+    onCopy?: (message: AgentWidgetMessage) => void;
+};
+type AgentWidgetStateEvent = {
+    open: boolean;
+    source: "user" | "auto" | "api" | "system";
+    timestamp: number;
+};
+type AgentWidgetStateSnapshot = {
+    open: boolean;
+    launcherEnabled: boolean;
+    voiceActive: boolean;
+    streaming: boolean;
+};
+type AgentWidgetControllerEventMap = {
+    "user:message": AgentWidgetMessage;
+    "assistant:message": AgentWidgetMessage;
+    "assistant:complete": AgentWidgetMessage;
+    "voice:state": AgentWidgetVoiceStateEvent;
+    "action:detected": AgentWidgetActionEventPayload;
+    "action:resubmit": AgentWidgetActionEventPayload;
+    "widget:opened": AgentWidgetStateEvent;
+    "widget:closed": AgentWidgetStateEvent;
+    "widget:state": AgentWidgetStateSnapshot;
+    "message:feedback": AgentWidgetMessageFeedback;
+    "message:copy": AgentWidgetMessage;
+    "eventStream:opened": {
+        timestamp: number;
+    };
+    "eventStream:closed": {
+        timestamp: number;
+    };
+    "approval:requested": {
+        approval: AgentWidgetApproval;
+        message: AgentWidgetMessage;
+    };
+    "approval:resolved": {
+        approval: AgentWidgetApproval;
+        decision: string;
+    };
+};
+/**
+ * Layout for the artifact split / drawer (CSS lengths unless noted).
+ *
+ * **Close behavior:** In desktop split mode, the artifact chrome `Close` control uses the same
+ * dismiss path as the mobile drawer (`onDismiss` on the artifact pane): the pane is hidden until
+ * new artifact content arrives or the host calls `showArtifacts()` on the widget handle.
+ */
+type AgentWidgetArtifactsLayoutConfig = {
+    /** Flex gap between chat column and artifact pane. @default 0.5rem */
+    splitGap?: string;
+    /** Artifact column width in split mode. @default 40% */
+    paneWidth?: string;
+    /** Max width of artifact column. @default 28rem */
+    paneMaxWidth?: string;
+    /** Min width of artifact column (optional). */
+    paneMinWidth?: string;
+    /**
+     * When the floating panel is at most this wide (px), use in-panel drawer for artifacts
+     * instead of a side-by-side split (viewport can still be wide).
+     * @default 520
+     */
+    narrowHostMaxWidth?: number;
+    /**
+     * When true (default), widen the launcher panel while artifacts are visible and not user-dismissed.
+     * No-op for inline embed (`launcher.enabled === false`).
+     */
+    expandLauncherPanelWhenOpen?: boolean;
+    /** Panel width when expanded (launcher + artifacts visible). @default min(720px, calc(100vw - 24px)) */
+    expandedPanelWidth?: string;
+    /**
+     * When true, shows a drag handle between chat and artifact columns in desktop split mode only
+     * (hidden in narrow-host drawer and viewport ≤640px). Width is not persisted across reloads.
+     */
+    resizable?: boolean;
+    /** Min artifact column width while resizing. Only `px` strings are supported. @default 200px */
+    resizableMinWidth?: string;
+    /** Optional max artifact width cap while resizing (`px` only). Layout still bounds by chat min width. */
+    resizableMaxWidth?: string;
+    /**
+     * Visual treatment for the artifact column in split mode.
+     * - `'panel'` — bordered sidebar with left border, gap, and shadow (default).
+     * - `'seamless'` — flush with chat: no border or shadow, container background, zero gap.
+     * @default 'panel'
+     */
+    paneAppearance?: "panel" | "seamless";
+    /** Border radius on the artifact pane (CSS length). Works with any `paneAppearance`. */
+    paneBorderRadius?: string;
+    /** CSS `box-shadow` on the artifact pane. Set `"none"` to suppress the default shadow. */
+    paneShadow?: string;
+    /**
+     * Full `border` shorthand for the artifact `<aside>` (all sides). Overrides default pane borders.
+     * Example: `"1px solid #cccccc"`.
+     */
+    paneBorder?: string;
+    /**
+     * `border-left` shorthand only — typical for split view next to chat (with or without resizer).
+     * Ignored if `paneBorder` is set. Example: `"1px solid #cccccc"`.
+     */
+    paneBorderLeft?: string;
+    /**
+     * Desktop split only (not narrow-host drawer / not ≤640px): square the **main chat card’s**
+     * top-right and bottom-right radii, and round the **artifact pane’s** top-right and bottom-right
+     * to match `persona-rounded-2xl` (`--persona-radius-lg`) so the two columns read as one shell.
+     */
+    unifiedSplitChrome?: boolean;
+    /**
+     * When `unifiedSplitChrome` is true, outer-right corner radius on the artifact column (CSS length).
+     * @default matches theme large radius (`--persona-radius-lg`)
+     */
+    unifiedSplitOuterRadius?: string;
+    /**
+     * Strongest override: solid background for the artifact column (CSS color). Sets `--persona-artifact-pane-bg`
+     * on the widget root. Leave unset to use theme `components.artifact.pane.background` (defaults to semantic
+     * container) so light/dark stays consistent.
+     */
+    paneBackground?: string;
+    /**
+     * Horizontal padding for artifact toolbar and content (CSS length), e.g. `24px`.
+     */
+    panePadding?: string;
+    /**
+     * Toolbar layout preset.
+     * - `default` — "Artifacts" title, horizontal tabs, text close.
+     * - `document` — view/source toggle, document title, copy / refresh / close; tab strip hidden when only one artifact.
+     * @default 'default'
+     */
+    toolbarPreset?: "default" | "document";
+    /**
+     * When `toolbarPreset` is `document`, show a visible "Copy" label next to the copy icon.
+     */
+    documentToolbarShowCopyLabel?: boolean;
+    /**
+     * When `toolbarPreset` is `document`, show a small chevron after the copy control (e.g. menu affordance).
+     */
+    documentToolbarShowCopyChevron?: boolean;
+    /** Document toolbar icon buttons (view, code, copy, refresh, close) — CSS color. Sets `--persona-artifact-doc-toolbar-icon-color` on the widget root. */
+    documentToolbarIconColor?: string;
+    /** Active view/source toggle background. Sets `--persona-artifact-doc-toggle-active-bg`. */
+    documentToolbarToggleActiveBackground?: string;
+    /** Active view/source toggle border color. Sets `--persona-artifact-doc-toggle-active-border`. */
+    documentToolbarToggleActiveBorderColor?: string;
+    /**
+     * Invoked when the document toolbar Refresh control is used (before the pane re-renders).
+     * Use to replay `connectStream`, refetch, etc.
+     */
+    onDocumentToolbarRefresh?: () => void | Promise<void>;
+    /**
+     * Optional copy dropdown entries (shown when `documentToolbarShowCopyChevron` is true and this array is non-empty).
+     * The main Copy control still performs default copy unless `onDocumentToolbarCopyMenuSelect` handles everything.
+     */
+    documentToolbarCopyMenuItems?: Array<{
+        id: string;
+        label: string;
+    }>;
+    /**
+     * When set, invoked for the chevron menu (and can override default copy per `actionId`).
+     */
+    onDocumentToolbarCopyMenuSelect?: (payload: {
+        actionId: string;
+        artifactId: string | null;
+        markdown: string;
+        jsonPayload: string;
+    }) => void | Promise<void>;
+};
+type AgentWidgetArtifactsFeature = {
+    /** When true, Persona shows the artifact pane and handles artifact_* SSE events */
+    enabled?: boolean;
+    /** If set, artifact events for other types are ignored */
+    allowedTypes?: PersonaArtifactKind[];
+    /** Split / drawer dimensions and launcher widen behavior */
+    layout?: AgentWidgetArtifactsLayoutConfig;
+    /**
+     * Called when an artifact card action is triggered (open, download).
+     * Return `true` to prevent the default behavior.
+     */
+    onArtifactAction?: (action: {
+        type: 'open' | 'download';
+        artifactId: string;
+    }) => boolean | void;
+    /**
+     * Custom renderer for artifact reference cards shown in the message thread.
+     * Return an HTMLElement to replace the default card, or `null` to use the default.
+     */
+    renderCard?: (context: {
+        artifact: {
+            artifactId: string;
+            title: string;
+            artifactType: string;
+            status: string;
+        };
+        config: AgentWidgetConfig;
+        defaultRenderer: () => HTMLElement;
+    }) => HTMLElement | null;
+};
+type AgentWidgetScrollToBottomFeature = {
+    /**
+     * When true, Persona shows a scroll-to-bottom affordance when the user breaks
+     * away from the latest transcript or event stream content.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Lucide icon name used for the affordance.
+     * @default "arrow-down"
+     */
+    iconName?: string;
+    /**
+     * Optional label text shown next to the icon. Set to an empty string for an
+     * icon-only affordance.
+     * @default ""
+     */
+    label?: string;
+};
+type AgentWidgetFeatureFlags = {
+    showReasoning?: boolean;
+    showToolCalls?: boolean;
+    showEventStreamToggle?: boolean;
+    /** Shared transcript + event stream scroll-to-bottom affordance. */
+    scrollToBottom?: AgentWidgetScrollToBottomFeature;
+    /** Configuration for the Event Stream inspector view */
+    eventStream?: EventStreamConfig;
+    /** Optional artifact sidebar (split pane / mobile drawer) */
+    artifacts?: AgentWidgetArtifactsFeature;
+};
+type SSEEventRecord = {
+    id: string;
+    type: string;
+    timestamp: number;
+    payload: string;
+};
+/**
+ * Badge color configuration for event stream event types.
+ */
+type EventStreamBadgeColor = {
+    /** Background color (CSS value) */
+    bg: string;
+    /** Text color (CSS value) */
+    text: string;
+};
+/**
+ * Configuration for the Event Stream inspector view.
+ */
+type EventStreamConfig = {
+    /**
+     * Custom badge color mappings by event type prefix or exact type.
+     * Keys are matched as exact match first, then prefix match (keys ending with "_").
+     * @example { "flow_": { bg: "#dcfce7", text: "#166534" }, "error": { bg: "#fecaca", text: "#991b1b" } }
+     */
+    badgeColors?: Record<string, EventStreamBadgeColor>;
+    /**
+     * Timestamp display format.
+     * - "relative": Shows time offset from first event (+0.000s, +0.361s)
+     * - "absolute": Shows wall-clock time (HH:MM:SS.mmm)
+     * @default "relative"
+     */
+    timestampFormat?: "absolute" | "relative";
+    /**
+     * Whether to show sequential event numbers (1, 2, 3...).
+     * @default true
+     */
+    showSequenceNumbers?: boolean;
+    /**
+     * Maximum events to keep in the ring buffer.
+     * @default 500
+     */
+    maxEvents?: number;
+    /**
+     * 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"]
+     */
+    descriptionFields?: string[];
+    /**
+     * Custom CSS class names to append to event stream UI elements.
+     * Each value is a space-separated class string appended to the element's default classes.
+     */
+    classNames?: {
+        /** The toggle button in the widget header (activity icon). */
+        toggleButton?: string;
+        /** Additional classes applied to the toggle button when the event stream is open. */
+        toggleButtonActive?: string;
+        /** The outer event stream panel/container. */
+        panel?: string;
+        /** The toolbar header bar (title, filter, copy all). */
+        headerBar?: string;
+        /** The search bar wrapper. */
+        searchBar?: string;
+        /** The search text input. */
+        searchInput?: string;
+        /** Each event row wrapper. */
+        eventRow?: string;
+        /** The "new events" scroll indicator pill. */
+        scrollIndicator?: string;
+    };
+};
+/**
+ * Context for the renderEventStreamView plugin hook.
+ */
+type EventStreamViewRenderContext = {
+    config: AgentWidgetConfig;
+    events: SSEEventRecord[];
+    defaultRenderer: () => HTMLElement;
+    onClose?: () => void;
+};
+/**
+ * Context for the renderEventStreamRow plugin hook.
+ */
+type EventStreamRowRenderContext = {
+    event: SSEEventRecord;
+    index: number;
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    isExpanded: boolean;
+    onToggleExpand: () => void;
+};
+/**
+ * Context for the renderEventStreamToolbar plugin hook.
+ */
+type EventStreamToolbarRenderContext = {
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    eventCount: number;
+    filteredCount: number;
+    onFilterChange: (type: string) => void;
+    onSearchChange: (term: string) => void;
+};
+/**
+ * Context for the renderEventStreamPayload plugin hook.
+ */
+type EventStreamPayloadRenderContext = {
+    event: SSEEventRecord;
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+    parsedPayload: unknown;
+};
+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";
+};
+type AgentWidgetLauncherConfig = {
+    enabled?: boolean;
+    title?: string;
+    subtitle?: string;
+    textHidden?: boolean;
+    iconUrl?: string;
+    agentIconText?: string;
+    agentIconName?: string;
+    agentIconHidden?: boolean;
+    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
+     *
+     * @default "floating"
+     */
+    mountMode?: "floating" | "docked";
+    /**
+     * Layout configuration for docked mode.
+     */
+    dock?: AgentWidgetDockConfig;
+    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;
+    /**
+     * 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 when it is in a positioned mode
+     * (floating panel, mobile fullscreen, or sidebar). Increase this value if
+     * other elements on the host page appear on top of the widget.
+     *
+     * @default 9999 in overlay modes (mobile fullscreen / sidebar); 50 for the regular floating panel
+     */
+    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;
+};
+type AgentWidgetSendButtonConfig = {
+    borderWidth?: string;
+    borderColor?: string;
+    paddingX?: string;
+    paddingY?: string;
+    iconText?: string;
+    iconName?: string;
+    useIcon?: boolean;
+    tooltipText?: string;
+    showTooltip?: boolean;
+    backgroundColor?: string;
+    textColor?: string;
+    size?: string;
+};
+/** Optional composer UI state for custom `renderComposer` implementations. */
+type AgentWidgetComposerConfig = {
+    models?: Array<{
+        id: string;
+        label: string;
+    }>;
+    /** Current selection; host or plugin may update this at runtime. */
+    selectedModelId?: 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 AgentWidgetStatusIndicatorConfig = {
+    visible?: boolean;
+    /** Text alignment. Default: 'right'. */
+    align?: 'left' | 'center' | 'right';
+    idleText?: string;
+    /** URL to open in a new tab when the idle text is clicked. */
+    idleLink?: string;
+    connectingText?: string;
+    connectedText?: string;
+    errorText?: string;
+};
+type AgentWidgetVoiceRecognitionConfig = {
+    enabled?: boolean;
+    pauseDuration?: number;
+    /** Text shown in the user message placeholder while voice is being processed. Default: "🎤 Processing voice..." */
+    processingText?: string;
+    /** Text shown in the assistant message if voice processing fails. Default: "Voice processing failed. Please try again." */
+    processingErrorText?: string;
+    iconName?: string;
+    iconSize?: string;
+    iconColor?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    borderWidth?: string;
+    paddingX?: string;
+    paddingY?: string;
+    tooltipText?: string;
+    showTooltip?: boolean;
+    recordingIconColor?: string;
+    recordingBackgroundColor?: string;
+    recordingBorderColor?: string;
+    showRecordingIndicator?: boolean;
+    /** Icon name shown while processing voice input. Default: "loader" */
+    processingIconName?: string;
+    /** Icon color during processing. Inherits idle iconColor if not set */
+    processingIconColor?: string;
+    /** Button background color during processing. Inherits idle backgroundColor if not set */
+    processingBackgroundColor?: string;
+    /** Button border color during processing. Inherits idle borderColor if not set */
+    processingBorderColor?: string;
+    /** Icon name shown while agent is speaking. Default: "volume-2" (or "square" in cancel mode) */
+    speakingIconName?: string;
+    /** Icon color while speaking. Inherits idle iconColor if not set */
+    speakingIconColor?: string;
+    /** Button background color while speaking. Inherits idle backgroundColor if not set */
+    speakingBackgroundColor?: string;
+    /** Button border color while speaking. Inherits idle borderColor if not set */
+    speakingBorderColor?: string;
+    autoResume?: boolean | "assistant";
+    provider?: {
+        type: 'browser' | 'runtype' | 'custom';
+        browser?: {
+            language?: string;
+            continuous?: boolean;
+        };
+        runtype?: {
+            agentId: string;
+            clientToken: string;
+            host?: string;
+            voiceId?: string;
+            /** Duration of silence (ms) before auto-stopping recording. Default: 2000 */
+            pauseDuration?: number;
+            /** RMS volume threshold below which counts as silence. Default: 0.01 */
+            silenceThreshold?: number;
+        };
+        custom?: any;
+    };
+};
+/**
+ * Text-to-speech configuration for reading assistant messages aloud.
+ * Currently supports the Web Speech API (`speechSynthesis`).
+ *
+ * @example
+ * ```typescript
+ * textToSpeech: {
+ *   enabled: true,
+ *   provider: 'browser',
+ *   voice: 'Google US English',
+ *   rate: 1.2,
+ *   pitch: 1.0
+ * }
+ * ```
+ */
+type TextToSpeechConfig = {
+    /** Enable text-to-speech for assistant messages */
+    enabled: boolean;
+    /**
+     * TTS provider.
+     * - `'browser'` — Use the Web Speech API for all assistant messages (default).
+     * - `'runtype'` — Server handles TTS for voice interactions.
+     *   Set `browserFallback: true` to also speak text-typed responses via the browser.
+     */
+    provider?: 'browser' | 'runtype';
+    /**
+     * When `provider` is `'runtype'`, fall back to browser TTS for assistant
+     * messages that the server didn't already speak (e.g. text-typed messages).
+     * Has no effect when provider is `'browser'` (browser TTS is always used).
+     * @default false
+     */
+    browserFallback?: boolean;
+    /** Voice name to use for browser TTS (e.g., 'Google US English'). If not found, uses auto-detect. */
+    voice?: string;
+    /**
+     * Custom voice picker called when `voice` is not set.
+     * Receives the full list of available `SpeechSynthesisVoice` objects and
+     * should return the one to use. If not provided, the SDK auto-detects the
+     * best English voice.
+     *
+     * @example
+     * ```typescript
+     * pickVoice: (voices) => voices.find(v => v.lang === 'fr-FR') ?? voices[0]
+     * ```
+     */
+    pickVoice?: (voices: SpeechSynthesisVoice[]) => SpeechSynthesisVoice;
+    /** Speech rate (0.1 - 10). Default: 1 */
+    rate?: number;
+    /** Speech pitch (0 - 2). Default: 1 */
+    pitch?: number;
+};
+/**
+ * Configuration for tool approval bubbles.
+ * Controls styling, labels, and behavior of the approval UI.
+ */
+type AgentWidgetApprovalConfig = {
+    /** Background color of the approval bubble */
+    backgroundColor?: string;
+    /** Border color of the approval bubble */
+    borderColor?: string;
+    /** Color for the title text */
+    titleColor?: string;
+    /** Color for the description text */
+    descriptionColor?: string;
+    /** Background color for the approve button */
+    approveButtonColor?: string;
+    /** Text color for the approve button */
+    approveButtonTextColor?: string;
+    /** Background color for the deny button */
+    denyButtonColor?: string;
+    /** Text color for the deny button */
+    denyButtonTextColor?: string;
+    /** Background color for the parameters block */
+    parameterBackgroundColor?: string;
+    /** Text color for the parameters block */
+    parameterTextColor?: string;
+    /** Title text displayed above the description */
+    title?: string;
+    /** Label for the approve button */
+    approveLabel?: string;
+    /** Label for the deny button */
+    denyLabel?: string;
+    /**
+     * Custom handler for approval decisions.
+     * Return void to let the SDK auto-resolve via the API,
+     * or return a Response/ReadableStream for custom handling.
+     */
+    onDecision?: (data: {
+        approvalId: string;
+        executionId: string;
+        agentId: string;
+        toolName: string;
+    }, decision: 'approved' | 'denied') => Promise<Response | ReadableStream<Uint8Array> | void>;
+};
+type AgentWidgetToolCallConfig$1 = {
+    /** Box-shadow for tool-call bubbles; overrides `theme.toolBubbleShadow` when set. */
+    shadow?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    borderWidth?: string;
+    borderRadius?: string;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    headerPaddingX?: string;
+    headerPaddingY?: string;
+    contentBackgroundColor?: string;
+    contentTextColor?: string;
+    contentPaddingX?: string;
+    contentPaddingY?: string;
+    codeBlockBackgroundColor?: string;
+    codeBlockBorderColor?: string;
+    codeBlockTextColor?: string;
+    toggleTextColor?: string;
+    labelTextColor?: string;
+};
+type AgentWidgetSuggestionChipsConfig = {
+    fontFamily?: "sans-serif" | "serif" | "mono";
+    fontWeight?: string;
+    paddingX?: string;
+    paddingY?: string;
+};
+/**
+ * Interface for pluggable stream parsers that extract text from streaming responses.
+ * Parsers handle incremental parsing to extract text values from structured formats (JSON, XML, etc.).
+ *
+ * @example
+ * ```typescript
+ * const jsonParser: AgentWidgetStreamParser = {
+ *   processChunk: async (content) => {
+ *     // Extract text from JSON - return null if not JSON or text not available yet
+ *     if (!content.trim().startsWith('{')) return null;
+ *     const match = content.match(/"text"\s*:\s*"([^"]*)"/);
+ *     return match ? match[1] : null;
+ *   },
+ *   getExtractedText: () => extractedText
+ * };
+ * ```
+ */
+interface AgentWidgetStreamParserResult {
+    /**
+     * The extracted text to display (may be partial during streaming)
+     */
+    text: string | null;
+    /**
+     * The raw accumulated content. Built-in parsers always populate this so
+     * downstream middleware (action handlers, logging, etc.) can
+     * inspect/parse the original structured payload.
+     */
+    raw?: string;
+}
+interface AgentWidgetStreamParser {
+    /**
+     * Process a chunk of content and return the extracted text (if available).
+     * This method is called for each chunk as it arrives during streaming.
+     * Return null if the content doesn't match this parser's format or if text is not yet available.
+     *
+     * @param accumulatedContent - The full accumulated content so far (including new chunk)
+     * @returns The extracted text value and optionally raw content, or null if not yet available or format doesn't match
+     */
+    processChunk(accumulatedContent: string): Promise<AgentWidgetStreamParserResult | string | null> | AgentWidgetStreamParserResult | string | null;
+    /**
+     * Get the currently extracted text value (may be partial).
+     * This is called synchronously to get the latest extracted text without processing.
+     *
+     * @returns The currently extracted text value, or null if not yet available
+     */
+    getExtractedText(): string | null;
+    /**
+     * Clean up any resources when parsing is complete.
+     */
+    close?(): Promise<void> | void;
+}
+/**
+ * Component renderer function signature for custom components
+ */
+type AgentWidgetComponentRenderer = (props: Record<string, unknown>, context: {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    updateProps: (newProps: Record<string, unknown>) => void;
+}) => HTMLElement;
+/**
+ * Result from custom SSE event parser
+ */
+type AgentWidgetSSEEventResult = {
+    /** Text content to display */
+    text?: string;
+    /** Whether the stream is complete */
+    done?: boolean;
+    /** Error message if an error occurred */
+    error?: string;
+    /** Text segment identity — when this changes, a new assistant message bubble is created */
+    partId?: string;
+} | null;
+/**
+ * Custom SSE event parser function
+ * Allows transforming non-standard SSE event formats to persona's expected format
+ */
+type AgentWidgetSSEEventParser = (eventData: unknown) => AgentWidgetSSEEventResult | Promise<AgentWidgetSSEEventResult>;
+/**
+ * Custom fetch function for full control over API requests
+ * Use this for custom authentication, request transformation, etc.
+ */
+type AgentWidgetCustomFetch = (url: string, init: RequestInit, payload: AgentWidgetRequestPayload) => Promise<Response>;
+/**
+ * Dynamic headers function - called before each request
+ */
+type AgentWidgetHeadersFunction = () => Record<string, string> | Promise<Record<string, string>>;
+/**
+ * Session information returned after client token initialization.
+ * Contains session ID, expiry time, flow info, and config from the server.
+ */
+type ClientSession = {
+    /** Unique session identifier */
+    sessionId: string;
+    /** When the session expires */
+    expiresAt: Date;
+    /** Flow information */
+    flow: {
+        id: string;
+        name: string;
+        description: string | null;
+    };
+    /** Configuration from the server */
+    config: {
+        welcomeMessage: string | null;
+        placeholder: string;
+        theme: Record<string, unknown> | null;
+    };
+};
+/** Icon button in the header title row (minimal layout). */
+type AgentWidgetHeaderTrailingAction = {
+    id: string;
+    /** Lucide icon name, e.g. `chevron-down` */
+    icon?: string;
+    label?: string;
+    ariaLabel?: string;
+    /**
+     * When set, clicking this action opens a dropdown menu.
+     * Menu item selections fire `onAction(menuItemId)`.
+     */
+    menuItems?: Array<{
+        id: string;
+        label: string;
+        icon?: string;
+        destructive?: boolean;
+        dividerBefore?: boolean;
+    }>;
+};
+/**
+ * Context provided to header render functions
+ */
+type HeaderRenderContext = {
+    config: AgentWidgetConfig;
+    onClose?: () => void;
+    onClearChat?: () => void;
+    /** Built from `layout.header.trailingActions` for custom `render` implementations. */
+    trailingActions?: AgentWidgetHeaderTrailingAction[];
+    /** Fired when a built-in trailing action is activated (same as `layout.header.onAction`). */
+    onAction?: (actionId: string) => void;
+};
+/**
+ * Context provided to message render functions
+ */
+type MessageRenderContext = {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    streaming: boolean;
+};
+/**
+ * Context provided to slot render functions
+ */
+type SlotRenderContext = {
+    config: AgentWidgetConfig;
+    defaultContent: () => HTMLElement | null;
+};
+/**
+ * Header layout configuration
+ * Allows customization of the header section appearance and behavior
+ */
+type AgentWidgetHeaderLayoutConfig = {
+    /**
+     * Layout preset: "default" | "minimal"
+     * - default: Standard layout with icon, title, subtitle, and buttons
+     * - minimal: Simplified layout with just title and close button
+     */
+    layout?: "default" | "minimal";
+    /** Show/hide the header icon */
+    showIcon?: boolean;
+    /** Show/hide the title */
+    showTitle?: boolean;
+    /** Show/hide the subtitle */
+    showSubtitle?: boolean;
+    /** Show/hide the close button */
+    showCloseButton?: boolean;
+    /** Show/hide the clear chat button */
+    showClearChat?: boolean;
+    /**
+     * Custom renderer for complete header override
+     * When provided, replaces the entire header with custom content
+     */
+    render?: (context: HeaderRenderContext) => HTMLElement;
+    /**
+     * Shown after the title in `minimal` header layout (e.g. chevron menu affordance).
+     */
+    trailingActions?: AgentWidgetHeaderTrailingAction[];
+    /** Called when a `trailingActions` button is clicked. */
+    onAction?: (actionId: string) => void;
+    /**
+     * Called when the header title row is clicked.
+     * Useful for dropdown menus or navigation triggered from the header.
+     * When set, the title row becomes visually interactive (cursor: pointer).
+     */
+    onTitleClick?: () => void;
+    /** Style config for the title row hover effect (minimal layout). */
+    titleRowHover?: {
+        /** Hover background color. */
+        background?: string;
+        /** Hover border color. */
+        border?: string;
+        /** Border radius for the pill shape. */
+        borderRadius?: string;
+        /** Padding inside the pill. */
+        padding?: string;
+    };
+    /**
+     * Replaces the title with a combo button (label + chevron + dropdown menu).
+     * When set, `trailingActions`, `onTitleClick`, and `titleRowHover` are ignored
+     * since the combo button handles all of these internally.
+     */
+    titleMenu?: {
+        /** Dropdown menu items. */
+        menuItems: Array<{
+            id: string;
+            label: string;
+            icon?: string;
+            destructive?: boolean;
+            dividerBefore?: boolean;
+        }>;
+        /** Called when a menu item is selected. */
+        onSelect: (id: string) => void;
+        /** Hover pill style. */
+        hover?: {
+            background?: string;
+            border?: string;
+            borderRadius?: string;
+            padding?: string;
+        };
+    };
+};
+/**
+ * Avatar configuration for message bubbles
+ */
+type AgentWidgetAvatarConfig = {
+    /** Whether to show avatars */
+    show?: boolean;
+    /** Position of avatar relative to message bubble */
+    position?: "left" | "right";
+    /** URL or emoji for user avatar */
+    userAvatar?: string;
+    /** URL or emoji for assistant avatar */
+    assistantAvatar?: string;
+};
+/**
+ * Timestamp configuration for message bubbles
+ */
+type AgentWidgetTimestampConfig = {
+    /** Whether to show timestamps */
+    show?: boolean;
+    /** Position of timestamp relative to message */
+    position?: "inline" | "below";
+    /** Custom formatter for timestamp display */
+    format?: (date: Date) => string;
+};
+/**
+ * Message layout configuration
+ * Allows customization of how chat messages are displayed
+ */
+type AgentWidgetMessageLayoutConfig = {
+    /**
+     * Layout preset: "bubble" | "flat" | "minimal"
+     * - bubble: Standard chat bubble appearance (default)
+     * - flat: Flat messages without bubble styling
+     * - minimal: Minimal styling with reduced padding/borders
+     */
+    layout?: "bubble" | "flat" | "minimal";
+    /** Avatar configuration */
+    avatar?: AgentWidgetAvatarConfig;
+    /** Timestamp configuration */
+    timestamp?: AgentWidgetTimestampConfig;
+    /** Group consecutive messages from the same role */
+    groupConsecutive?: boolean;
+    /**
+     * Custom renderer for user messages
+     * When provided, replaces the default user message rendering
+     */
+    renderUserMessage?: (context: MessageRenderContext) => HTMLElement;
+    /**
+     * Custom renderer for assistant messages
+     * When provided, replaces the default assistant message rendering
+     */
+    renderAssistantMessage?: (context: MessageRenderContext) => HTMLElement;
+};
+/**
+ * Available layout slots for content injection
+ */
+type WidgetLayoutSlot = "header-left" | "header-center" | "header-right" | "body-top" | "messages" | "body-bottom" | "footer-top" | "composer" | "footer-bottom";
+/**
+ * Slot renderer function signature
+ * Returns HTMLElement to render in the slot, or null to use default content
+ */
+type SlotRenderer = (context: SlotRenderContext) => HTMLElement | null;
+/**
+ * Main layout configuration
+ * Provides comprehensive control over widget layout and appearance
+ *
+ * @example
+ * ```typescript
+ * config: {
+ *   layout: {
+ *     header: { layout: "minimal" },
+ *     messages: {
+ *       avatar: { show: true, assistantAvatar: "/bot.png" },
+ *       timestamp: { show: true, position: "below" }
+ *     },
+ *     slots: {
+ *       "footer-top": () => {
+ *         const el = document.createElement("div");
+ *         el.textContent = "Powered by AI";
+ *         return el;
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetLayoutConfig = {
+    /** Header layout configuration */
+    header?: AgentWidgetHeaderLayoutConfig;
+    /** Message layout configuration */
+    messages?: AgentWidgetMessageLayoutConfig;
+    /** Slot renderers for custom content injection */
+    slots?: Partial<Record<WidgetLayoutSlot, SlotRenderer>>;
+    /**
+     * Show/hide the header section entirely.
+     * When false, the header (including icon, title, buttons) is completely hidden.
+     * @default true
+     */
+    showHeader?: boolean;
+    /**
+     * Show/hide the footer/composer section entirely.
+     * When false, the footer (including input field, send button, suggestions) is completely hidden.
+     * Useful for read-only conversation previews.
+     * @default true
+     */
+    showFooter?: boolean;
+    /**
+     * Max width for the content area (messages + composer).
+     * Applied with `margin: 0 auto` for centering.
+     * Accepts any CSS width value (e.g. "90ch", "720px", "80%").
+     */
+    contentMaxWidth?: string;
+};
+/**
+ * Token types for marked renderer methods
+ */
+type AgentWidgetMarkdownHeadingToken = {
+    type: "heading";
+    raw: string;
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownCodeToken = {
+    type: "code";
+    raw: string;
+    text: string;
+    lang?: string;
+    escaped?: boolean;
+};
+type AgentWidgetMarkdownBlockquoteToken = {
+    type: "blockquote";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownTableToken = {
+    type: "table";
+    raw: string;
+    header: Array<{
+        text: string;
+        tokens: unknown[];
+    }>;
+    rows: Array<Array<{
+        text: string;
+        tokens: unknown[];
+    }>>;
+    align: Array<"left" | "center" | "right" | null>;
+};
+type AgentWidgetMarkdownLinkToken = {
+    type: "link";
+    raw: string;
+    href: string;
+    title: string | null;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownImageToken = {
+    type: "image";
+    raw: string;
+    href: string;
+    title: string | null;
+    text: string;
+};
+type AgentWidgetMarkdownListToken = {
+    type: "list";
+    raw: string;
+    ordered: boolean;
+    start: number | "";
+    loose: boolean;
+    items: unknown[];
+};
+type AgentWidgetMarkdownListItemToken = {
+    type: "list_item";
+    raw: string;
+    task: boolean;
+    checked?: boolean;
+    loose: boolean;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownParagraphToken = {
+    type: "paragraph";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownCodespanToken = {
+    type: "codespan";
+    raw: string;
+    text: string;
+};
+type AgentWidgetMarkdownStrongToken = {
+    type: "strong";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+type AgentWidgetMarkdownEmToken = {
+    type: "em";
+    raw: string;
+    text: string;
+    tokens: unknown[];
+};
+/**
+ * Custom renderer overrides for markdown elements.
+ * Each method receives the token and should return an HTML string.
+ * Return `false` to use the default renderer.
+ *
+ * @example
+ * ```typescript
+ * renderer: {
+ *   heading(token) {
+ *     return `<h${token.depth} class="custom-heading">${token.text}</h${token.depth}>`;
+ *   },
+ *   link(token) {
+ *     return `<a href="${token.href}" target="_blank" rel="noopener">${token.text}</a>`;
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetMarkdownRendererOverrides = {
+    /** Override heading rendering (h1-h6) */
+    heading?: (token: AgentWidgetMarkdownHeadingToken) => string | false;
+    /** Override code block rendering */
+    code?: (token: AgentWidgetMarkdownCodeToken) => string | false;
+    /** Override blockquote rendering */
+    blockquote?: (token: AgentWidgetMarkdownBlockquoteToken) => string | false;
+    /** Override table rendering */
+    table?: (token: AgentWidgetMarkdownTableToken) => string | false;
+    /** Override link rendering */
+    link?: (token: AgentWidgetMarkdownLinkToken) => string | false;
+    /** Override image rendering */
+    image?: (token: AgentWidgetMarkdownImageToken) => string | false;
+    /** Override list rendering (ul/ol) */
+    list?: (token: AgentWidgetMarkdownListToken) => string | false;
+    /** Override list item rendering */
+    listitem?: (token: AgentWidgetMarkdownListItemToken) => string | false;
+    /** Override paragraph rendering */
+    paragraph?: (token: AgentWidgetMarkdownParagraphToken) => string | false;
+    /** Override inline code rendering */
+    codespan?: (token: AgentWidgetMarkdownCodespanToken) => string | false;
+    /** Override strong/bold rendering */
+    strong?: (token: AgentWidgetMarkdownStrongToken) => string | false;
+    /** Override emphasis/italic rendering */
+    em?: (token: AgentWidgetMarkdownEmToken) => string | false;
+    /** Override horizontal rule rendering */
+    hr?: () => string | false;
+    /** Override line break rendering */
+    br?: () => string | false;
+    /** Override deleted/strikethrough rendering */
+    del?: (token: {
+        type: "del";
+        raw: string;
+        text: string;
+        tokens: unknown[];
+    }) => string | false;
+    /** Override checkbox rendering (in task lists) */
+    checkbox?: (token: {
+        checked: boolean;
+    }) => string | false;
+    /** Override HTML passthrough */
+    html?: (token: {
+        type: "html";
+        raw: string;
+        text: string;
+    }) => string | false;
+    /** Override text rendering */
+    text?: (token: {
+        type: "text";
+        raw: string;
+        text: string;
+    }) => string | false;
+};
+/**
+ * Markdown parsing options (subset of marked options)
+ */
+type AgentWidgetMarkdownOptions = {
+    /**
+     * Enable GitHub Flavored Markdown (tables, strikethrough, autolinks).
+     * @default true
+     */
+    gfm?: boolean;
+    /**
+     * Convert \n in paragraphs into <br>.
+     * @default true
+     */
+    breaks?: boolean;
+    /**
+     * Conform to original markdown.pl as much as possible.
+     * @default false
+     */
+    pedantic?: boolean;
+    /**
+     * Add id attributes to headings.
+     * @default false
+     */
+    headerIds?: boolean;
+    /**
+     * Prefix for heading id attributes.
+     * @default ""
+     */
+    headerPrefix?: string;
+    /**
+     * Mangle email addresses for spam protection.
+     * @default true
+     */
+    mangle?: boolean;
+    /**
+     * Silent mode - don't throw on parse errors.
+     * @default false
+     */
+    silent?: boolean;
+};
+/**
+ * Markdown configuration for customizing how markdown is rendered in chat messages.
+ * Provides three levels of control:
+ *
+ * 1. **CSS Variables** - Override styles via `--cw-md-*` CSS custom properties
+ * 2. **Parsing Options** - Configure marked behavior via `options`
+ * 3. **Custom Renderers** - Full control via `renderer` overrides
+ *
+ * @example
+ * ```typescript
+ * // Level 2: Configure parsing options
+ * config: {
+ *   markdown: {
+ *     options: {
+ *       gfm: true,
+ *       breaks: true,
+ *       headerIds: true
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Level 3: Custom renderers
+ * config: {
+ *   markdown: {
+ *     renderer: {
+ *       heading(token) {
+ *         return `<h${token.depth} class="custom-h${token.depth}">${token.text}</h${token.depth}>`;
+ *       },
+ *       link(token) {
+ *         return `<a href="${token.href}" target="_blank">${token.text}</a>`;
+ *       },
+ *       table(token) {
+ *         // Wrap tables in a scrollable container
+ *         return `<div class="table-scroll">${this.parser.parse(token.tokens)}</div>`;
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetMarkdownConfig = {
+    /**
+     * Markdown parsing options.
+     * These are passed directly to the marked parser.
+     */
+    options?: AgentWidgetMarkdownOptions;
+    /**
+     * Custom renderer overrides for specific markdown elements.
+     * Each method receives a token object and should return an HTML string.
+     * Return `false` to fall back to the default renderer.
+     */
+    renderer?: AgentWidgetMarkdownRendererOverrides;
+    /**
+     * Disable default markdown CSS styles.
+     * When true, the widget won't apply any default styles to markdown elements,
+     * allowing you to provide your own CSS.
+     *
+     * @default false
+     */
+    disableDefaultStyles?: boolean;
+};
+/**
+ * Configuration for file attachments in the composer.
+ * Enables users to attach images to their messages.
+ *
+ * @example
+ * ```typescript
+ * config: {
+ *   attachments: {
+ *     enabled: true,
+ *     allowedTypes: ['image/png', 'image/jpeg', 'image/gif', 'image/webp'],
+ *     maxFileSize: 5 * 1024 * 1024, // 5MB
+ *     maxFiles: 4
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetAttachmentsConfig = {
+    /**
+     * Enable/disable file attachments.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Allowed MIME types for attachments.
+     * @default ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
+     */
+    allowedTypes?: string[];
+    /**
+     * Maximum file size in bytes.
+     * @default 10485760 (10MB)
+     */
+    maxFileSize?: number;
+    /**
+     * Maximum number of files per message.
+     * @default 4
+     */
+    maxFiles?: number;
+    /**
+     * Button icon name (from Lucide icons).
+     * @default 'image-plus'
+     */
+    buttonIconName?: string;
+    /**
+     * Tooltip text for the attachment button.
+     * @default 'Attach image'
+     */
+    buttonTooltipText?: string;
+    /**
+     * Callback when a file is rejected (wrong type or too large).
+     */
+    onFileRejected?: (file: File, reason: 'type' | 'size' | 'count') => void;
+};
+/**
+ * Configuration for persisting widget state across page navigations.
+ * Stores open/closed state, voice recognition state, and voice mode in browser storage.
+ *
+ * @example
+ * ```typescript
+ * config: {
+ *   persistState: true  // Use defaults: sessionStorage, persist open state
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * config: {
+ *   persistState: {
+ *     storage: 'local',  // Use localStorage instead of sessionStorage
+ *     keyPrefix: 'myapp-',  // Custom prefix for storage keys
+ *     persist: {
+ *       openState: true,
+ *       voiceState: true,
+ *       focusInput: true
+ *     },
+ *     clearOnChatClear: true
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetPersistStateConfig = {
+    /**
+     * Storage type to use.
+     * @default 'session'
+     */
+    storage?: 'local' | 'session';
+    /**
+     * Prefix for storage keys.
+     * @default 'persona-'
+     */
+    keyPrefix?: string;
+    /**
+     * What state to persist.
+     */
+    persist?: {
+        /**
+         * Persist widget open/closed state.
+         * @default true
+         */
+        openState?: boolean;
+        /**
+         * Persist voice recognition state.
+         * @default true
+         */
+        voiceState?: boolean;
+        /**
+         * Focus input when restoring open state.
+         * @default true
+         */
+        focusInput?: boolean;
+    };
+    /**
+     * Clear persisted state when chat is cleared.
+     * @default true
+     */
+    clearOnChatClear?: boolean;
+};
+/**
+ * Context provided to loading indicator render functions.
+ * Used for customizing the loading indicator appearance.
+ */
+type LoadingIndicatorRenderContext = {
+    /**
+     * Full widget configuration for accessing theme, etc.
+     */
+    config: AgentWidgetConfig;
+    /**
+     * Current streaming state (always true when indicator is shown)
+     */
+    streaming: boolean;
+    /**
+     * Location where the indicator is rendered:
+     * - 'inline': Inside a streaming assistant message bubble (when content is empty)
+     * - 'standalone': Separate bubble while waiting for stream to start
+     */
+    location: 'inline' | 'standalone';
+    /**
+     * Function to render the default 3-dot bouncing indicator.
+     * Call this if you want to use the default for certain cases.
+     */
+    defaultRenderer: () => HTMLElement;
+};
+/**
+ * Context provided to idle indicator render functions.
+ * Used for customizing the idle state indicator appearance.
+ */
+type IdleIndicatorRenderContext = {
+    /**
+     * Full widget configuration for accessing theme, etc.
+     */
+    config: AgentWidgetConfig;
+    /**
+     * The last message in the conversation (if any).
+     * Useful for conditional rendering based on who spoke last.
+     */
+    lastMessage: AgentWidgetMessage | undefined;
+    /**
+     * Total number of messages in the conversation.
+     */
+    messageCount: number;
+};
+/**
+ * Configuration for customizing the loading indicator.
+ * The loading indicator is shown while waiting for a response or
+ * when an assistant message is streaming but has no content yet.
+ *
+ * @example
+ * ```typescript
+ * // Custom animated spinner
+ * config: {
+ *   loadingIndicator: {
+ *     render: ({ location }) => {
+ *       const el = document.createElement('div');
+ *       el.innerHTML = '<svg class="spinner">...</svg>';
+ *       el.setAttribute('data-preserve-animation', 'true');
+ *       return el;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Different indicators by location
+ * config: {
+ *   loadingIndicator: {
+ *     render: ({ location, defaultRenderer }) => {
+ *       if (location === 'inline') {
+ *         return defaultRenderer(); // Use default for inline
+ *       }
+ *       // Custom for standalone
+ *       const el = document.createElement('div');
+ *       el.textContent = 'Thinking...';
+ *       return el;
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Hide loading indicator entirely
+ * config: {
+ *   loadingIndicator: {
+ *     render: () => null
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetLoadingIndicatorConfig = {
+    /**
+     * Whether to show the bubble background and border around the standalone loading indicator.
+     * Set to false to render the loading indicator without any bubble styling.
+     * @default true
+     */
+    showBubble?: boolean;
+    /**
+     * Custom render function for the loading indicator.
+     * Return an HTMLElement to display, or null to hide the indicator.
+     *
+     * For custom animations, add `data-preserve-animation="true"` attribute
+     * to prevent the DOM morpher from interrupting the animation.
+     */
+    render?: (context: LoadingIndicatorRenderContext) => HTMLElement | null;
+    /**
+     * Render function for the idle state indicator.
+     * Called when the widget is idle (not streaming) and has at least one message.
+     * Return an HTMLElement to display, or null to hide (default).
+     *
+     * For animations, add `data-preserve-animation="true"` attribute
+     * to prevent the DOM morpher from interrupting the animation.
+     *
+     * @example
+     * ```typescript
+     * loadingIndicator: {
+     *   renderIdle: ({ lastMessage }) => {
+     *     // Only show idle indicator after assistant messages
+     *     if (lastMessage?.role !== 'assistant') return null;
+     *     const el = document.createElement('div');
+     *     el.className = 'pulse-dot';
+     *     el.setAttribute('data-preserve-animation', 'true');
+     *     return el;
+     *   }
+     * }
+     * ```
+     */
+    renderIdle?: (context: IdleIndicatorRenderContext) => HTMLElement | null;
+};
+type AgentWidgetConfig = {
+    apiUrl?: string;
+    flowId?: string;
+    /**
+     * Agent configuration for agent execution mode.
+     * When provided, the widget uses agent loop execution instead of flow dispatch.
+     * Mutually exclusive with `flowId`.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   agent: {
+     *     name: 'Assistant',
+     *     model: 'openai:gpt-4o-mini',
+     *     systemPrompt: 'You are a helpful assistant.',
+      *     loopConfig: { maxTurns: 5 }
+     *   }
+     * }
+     * ```
+     */
+    agent?: AgentConfig;
+    /**
+     * Options for agent execution requests.
+     * Only used when `agent` is configured.
+     *
+     * @default { streamResponse: true, recordMode: 'virtual' }
+     */
+    agentOptions?: AgentRequestOptions;
+    /**
+     * Controls how multiple agent iterations are displayed in the chat UI.
+     * Only used when `agent` is configured.
+     *
+     * - `'separate'`: Each iteration creates a new assistant message bubble
+     * - `'merged'`: All iterations stream into a single assistant message
+     *
+     * @default 'separate'
+     */
+    iterationDisplay?: 'separate' | 'merged';
+    /**
+     * Client token for direct browser-to-API communication.
+     * When set, the widget uses /v1/client/* endpoints instead of /v1/dispatch.
+     * Mutually exclusive with apiKey/headers authentication.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   clientToken: 'ct_live_flow01k7_a8b9c0d1e2f3g4h5i6j7k8l9'
+     * }
+     * ```
+     */
+    clientToken?: string;
+    /**
+     * Callback when session is initialized (client token mode only).
+     * Receives session info including expiry time.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   onSessionInit: (session) => {
+     *     console.log('Session started:', session.sessionId);
+     *   }
+     * }
+     * ```
+     */
+    onSessionInit?: (session: ClientSession) => void;
+    /**
+     * Callback when session expires or errors (client token mode only).
+     * Widget should prompt user to refresh.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   onSessionExpired: () => {
+     *     alert('Your session has expired. Please refresh the page.');
+     *   }
+     * }
+     * ```
+     */
+    onSessionExpired?: () => void;
+    /**
+     * 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
+     * that should be passed to /client/init to resume the same conversation record.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   getStoredSessionId: () => {
+     *     const stored = localStorage.getItem('session_id');
+     *     return stored || null;
+     *   }
+     * }
+     * ```
+     */
+    getStoredSessionId?: () => string | null;
+    /**
+     * Store session ID for session resumption (client token mode only).
+     * Called when a new session is initialized to persist the session_id
+     * so it can be used to resume the conversation later.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   setStoredSessionId: (sessionId) => {
+     *     localStorage.setItem('session_id', sessionId);
+     *   }
+     * }
+     * ```
+     */
+    setStoredSessionId?: (sessionId: string) => void;
+    /**
+     * Static headers to include with each request.
+     * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Dynamic headers function - called before each request.
+     * Useful for adding auth tokens that may change.
+     * @example
+     * ```typescript
+     * getHeaders: async () => ({
+     *   'Authorization': `Bearer ${await getAuthToken()}`
+     * })
+     * ```
+     */
+    getHeaders?: AgentWidgetHeadersFunction;
+    copy?: {
+        welcomeTitle?: string;
+        welcomeSubtitle?: string;
+        inputPlaceholder?: string;
+        sendButtonLabel?: string;
+        /**
+         * When false, the welcome / intro card is not shown above the message list.
+         * @default true
+         */
+        showWelcomeCard?: boolean;
+    };
+    /**
+     * Semantic design tokens (`palette`, `semantic`, `components`).
+     * Omit for library defaults.
+     */
+    theme?: DeepPartial<PersonaTheme>;
+    /**
+     * Dark-mode token overrides. Merged over `theme` when the active scheme is dark.
+     */
+    darkTheme?: DeepPartial<PersonaTheme>;
+    /**
+     * Color scheme mode for the widget.
+     * - 'light': Always use light theme (default)
+     * - 'dark': Always use dark theme
+     * - 'auto': Automatically detect from page (HTML class or prefers-color-scheme)
+     *
+     * When 'auto', detection order:
+     * 1. Check if `<html>` has 'dark' class
+     * 2. Fall back to `prefers-color-scheme: dark` media query
+     *
+     * @default 'light'
+     */
+    colorScheme?: 'auto' | 'light' | 'dark';
+    features?: AgentWidgetFeatureFlags;
+    /**
+     * When true, focus the chat input after the panel opens and the open animation completes.
+     * Applies to launcher mode (user click, controller.open(), autoExpand) and inline mode (on init).
+     * Skip when voice is active to avoid stealing focus from voice UI.
+     * @default false
+     */
+    autoFocusInput?: boolean;
+    launcher?: AgentWidgetLauncherConfig;
+    initialMessages?: AgentWidgetMessage[];
+    suggestionChips?: string[];
+    suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
+    debug?: boolean;
+    formEndpoint?: string;
+    launcherWidth?: string;
+    sendButton?: AgentWidgetSendButtonConfig;
+    statusIndicator?: AgentWidgetStatusIndicatorConfig;
+    voiceRecognition?: AgentWidgetVoiceRecognitionConfig;
+    /**
+     * Text-to-speech configuration for reading assistant messages aloud.
+     * Uses the browser's Web Speech API (`speechSynthesis`).
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   textToSpeech: {
+     *     enabled: true,
+     *     voice: 'Google US English',
+     *     rate: 1.0,
+     *     pitch: 1.0
+     *   }
+     * }
+     * ```
+     */
+    textToSpeech?: TextToSpeechConfig;
+    toolCall?: AgentWidgetToolCallConfig$1;
+    /**
+     * Configuration for tool approval bubbles.
+     * Set to `false` to disable built-in approval handling entirely.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   approval: {
+     *     title: "Permission Required",
+     *     approveLabel: "Allow",
+     *     denyLabel: "Block",
+     *     approveButtonColor: "#16a34a"
+     *   }
+     * }
+     * ```
+     */
+    approval?: AgentWidgetApprovalConfig | false;
+    postprocessMessage?: (context: {
+        text: string;
+        message: AgentWidgetMessage;
+        streaming: boolean;
+        raw?: string;
+    }) => string;
+    plugins?: AgentWidgetPlugin[];
+    contextProviders?: AgentWidgetContextProvider[];
+    requestMiddleware?: AgentWidgetRequestMiddleware;
+    actionParsers?: AgentWidgetActionParser[];
+    actionHandlers?: AgentWidgetActionHandler[];
+    storageAdapter?: AgentWidgetStorageAdapter;
+    /**
+     * Called after state is loaded from the storage adapter, but before the widget
+     * initializes with that state. Use this to transform or inject messages based
+     * on external state (e.g., navigation flags, checkout returns).
+     *
+     * This hook runs synchronously and must return the (potentially modified) state.
+     *
+     * Returning `{ state, open: true }` also signals that the widget panel should
+     * open after initialization — useful when injecting a post-navigation message
+     * that the user should immediately see.
+     *
+     * @example
+     * ```typescript
+     * // Plain state transform (existing form, still supported)
+     * config: {
+     *   onStateLoaded: (state) => {
+     *     const navMessage = consumeNavigationFlag();
+     *     if (navMessage) {
+     *       return {
+     *         ...state,
+     *         messages: [...(state.messages || []), {
+     *           id: `nav-${Date.now()}`,
+     *           role: 'assistant',
+     *           content: navMessage,
+     *           createdAt: new Date().toISOString()
+     *         }]
+     *       };
+     *     }
+     *     return state;
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Return { state, open: true } to also open the panel
+     * config: {
+     *   onStateLoaded: (state) => {
+     *     const navMessage = consumeNavigationFlag();
+     *     if (navMessage) {
+     *       return {
+     *         state: {
+     *           ...state,
+     *           messages: [...(state.messages || []), {
+     *             id: `nav-${Date.now()}`,
+     *             role: 'assistant',
+     *             content: navMessage,
+     *             createdAt: new Date().toISOString()
+     *           }]
+     *         },
+     *         open: true
+     *       };
+     *     }
+     *     return state;
+     *   }
+     * }
+     * ```
+     */
+    onStateLoaded?: (state: AgentWidgetStoredState) => AgentWidgetStoredState | {
+        state: AgentWidgetStoredState;
+        open?: boolean;
+    };
+    /**
+     * Registry of custom components that can be rendered from JSON directives.
+     * Components are registered by name and can be invoked via JSON responses
+     * with the format: `{"component": "ComponentName", "props": {...}}`
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   components: {
+     *     ProductCard: (props, context) => {
+     *       const card = document.createElement("div");
+     *       card.innerHTML = `<h3>${props.title}</h3><p>$${props.price}</p>`;
+     *       return card;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    components?: Record<string, AgentWidgetComponentRenderer>;
+    /**
+     * Enable component streaming. When true, component props will be updated
+     * incrementally as they stream in from the JSON response.
+     *
+     * @default true
+     */
+    enableComponentStreaming?: boolean;
+    /**
+     * When false, JSON component directives render without the default bubble chrome
+     * (surface background, border, extra padding). Use for wide custom cards in the transcript.
+     * @default true
+     */
+    wrapComponentDirectiveInBubble?: boolean;
+    /**
+     * Custom stream parser for extracting text from streaming structured responses.
+     * Handles incremental parsing of JSON, XML, or other formats.
+     * If not provided, uses the default JSON parser.
+     *
+     * @example
+     * ```typescript
+     * streamParser: () => ({
+     *   processChunk: async (content) => {
+     *     // Return null if not your format, or extracted text if available
+     *     if (!content.trim().startsWith('{')) return null;
+     *     return extractText(content);
+     *   },
+     *   getExtractedText: () => extractedText
+     * })
+     * ```
+     */
+    streamParser?: () => AgentWidgetStreamParser;
+    /**
+     * Additional localStorage key to clear when the clear chat button is clicked.
+     * The widget automatically clears `"persona-chat-history"` by default.
+     * Use this option to clear additional keys (e.g., if you're using a custom storage key).
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   clearChatHistoryStorageKey: "my-custom-chat-history"
+     * }
+     * ```
+     */
+    clearChatHistoryStorageKey?: string;
+    /**
+     * Built-in parser type selector. Provides an easy way to choose a parser without importing functions.
+     * If both `parserType` and `streamParser` are provided, `streamParser` takes precedence.
+     *
+     * - `"plain"` - Plain text parser (default). Passes through text as-is.
+     * - `"json"` - JSON parser using partial-json. Extracts `text` field from JSON objects incrementally.
+     * - `"regex-json"` - Regex-based JSON parser. Less robust but faster fallback for simple JSON.
+     * - `"xml"` - XML parser. Extracts text content from XML tags.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   parserType: "json"  // Use built-in JSON parser
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   parserType: "json",
+     *   streamParser: () => customParser()  // Custom parser overrides parserType
+     * }
+     * ```
+     */
+    parserType?: "plain" | "json" | "regex-json" | "xml";
+    /**
+     * Custom fetch function for full control over API requests.
+     * Use this for custom authentication, request/response transformation, etc.
+     *
+     * When provided, this function is called instead of the default fetch.
+     * You receive the URL, RequestInit, and the payload that would be sent.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   customFetch: async (url, init, payload) => {
+     *     // Transform request for your API format
+     *     const myPayload = {
+     *       flow: { id: 'my-flow-id' },
+     *       messages: payload.messages,
+     *       options: { stream_response: true }
+     *     };
+     *
+     *     // Add auth header
+     *     const token = await getAuthToken();
+     *
+     *     return fetch('/my-api/dispatch', {
+     *       method: 'POST',
+     *       headers: {
+     *         'Content-Type': 'application/json',
+     *         'Authorization': `Bearer ${token}`
+     *       },
+     *       body: JSON.stringify(myPayload),
+     *       signal: init.signal
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    customFetch?: AgentWidgetCustomFetch;
+    /**
+     * Custom SSE event parser for non-standard streaming response formats.
+     *
+     * Use this when your API returns SSE events in a different format than expected.
+     * Return `{ text }` for text chunks, `{ done: true }` for completion,
+     * `{ error }` for errors, or `null` to ignore the event.
+     *
+     * @example
+     * ```typescript
+     * // For Runtype API format
+     * config: {
+     *   parseSSEEvent: (data) => {
+     *     if ((data.type === 'step_delta' || data.type === 'step_chunk') && (data.delta || data.chunk)) {
+     *       return { text: data.delta ?? data.chunk };
+     *     }
+     *     if (data.type === 'flow_complete') {
+     *       return { done: true };
+     *     }
+     *     if (data.type === 'step_error') {
+     *       return { error: data.error };
+     *     }
+     *     return null; // Ignore other events
+     *   }
+     * }
+     * ```
+     */
+    parseSSEEvent?: AgentWidgetSSEEventParser;
+    /**
+     * Layout configuration for customizing widget appearance and structure.
+     * Provides control over header, messages, and content slots.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   layout: {
+     *     header: { layout: "minimal" },
+     *     messages: { avatar: { show: true } }
+     *   }
+     * }
+     * ```
+     */
+    layout?: AgentWidgetLayoutConfig;
+    /**
+     * Markdown rendering configuration.
+     * Customize how markdown is parsed and rendered in chat messages.
+     *
+     * Override methods:
+     * 1. **CSS Variables** - Override `--cw-md-*` variables in your stylesheet
+     * 2. **Options** - Configure marked parser behavior
+     * 3. **Renderers** - Custom rendering functions for specific elements
+     * 4. **postprocessMessage** - Complete control over message transformation
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   markdown: {
+     *     options: { breaks: true, gfm: true },
+     *     renderer: {
+     *       link(token) {
+     *         return `<a href="${token.href}" target="_blank">${token.text}</a>`;
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    markdown?: AgentWidgetMarkdownConfig;
+    /**
+     * HTML sanitization for rendered message content.
+     *
+     * The widget renders AI-generated markdown as HTML. By default, all HTML
+     * output is sanitized using DOMPurify to prevent XSS attacks.
+     *
+     * - `true` (default): sanitize using built-in DOMPurify
+     * - `false`: disable sanitization (only use with fully trusted content sources)
+     * - `(html: string) => string`: custom sanitizer function
+     *
+     * @default true
+     */
+    sanitize?: boolean | ((html: string) => string);
+    /**
+     * Configuration for message action buttons (copy, upvote, downvote).
+     * Shows action buttons on assistant messages for user feedback.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   messageActions: {
+     *     enabled: true,
+     *     showCopy: true,
+     *     showUpvote: true,
+     *     showDownvote: true,
+     *     visibility: 'hover',
+     *     onFeedback: (feedback) => {
+     *       console.log('Feedback:', feedback.type, feedback.messageId);
+     *     },
+     *     onCopy: (message) => {
+     *       console.log('Copied message:', message.id);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    messageActions?: AgentWidgetMessageActionsConfig;
+    /**
+     * Configuration for file attachments in the composer.
+     * When enabled, users can attach images to their messages.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   attachments: {
+     *     enabled: true,
+     *     maxFileSize: 5 * 1024 * 1024, // 5MB
+     *     maxFiles: 4
+     *   }
+     * }
+     * ```
+     */
+    attachments?: AgentWidgetAttachmentsConfig;
+    /**
+     * Composer extras for custom `renderComposer` plugins (model picker, etc.).
+     * `selectedModelId` may be updated at runtime by the host.
+     */
+    composer?: AgentWidgetComposerConfig;
+    /**
+     * Persist widget state (open/closed, voice mode) across page navigations.
+     * When `true`, uses default settings with sessionStorage.
+     * When an object, allows customizing storage type, key prefix, and what to persist.
+     *
+     * @example
+     * ```typescript
+     * // Simple usage - persist open state in sessionStorage
+     * config: {
+     *   persistState: true
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Advanced usage
+     * config: {
+     *   persistState: {
+     *     storage: 'local',  // Use localStorage
+     *     persist: {
+     *       openState: true,
+     *       voiceState: true,
+     *       focusInput: true
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    persistState?: boolean | AgentWidgetPersistStateConfig;
+    /**
+     * Configuration for customizing the loading indicator.
+     * The loading indicator is shown while waiting for a response or
+     * when an assistant message is streaming but has no content yet.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   loadingIndicator: {
+     *     render: ({ location, defaultRenderer }) => {
+     *       if (location === 'standalone') {
+     *         const el = document.createElement('div');
+     *         el.textContent = 'Thinking...';
+     *         return el;
+     *       }
+     *       return defaultRenderer();
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    loadingIndicator?: AgentWidgetLoadingIndicatorConfig;
+};
+type AgentWidgetMessageRole = "user" | "assistant" | "system";
+type AgentWidgetReasoning = {
+    id: string;
+    status: "pending" | "streaming" | "complete";
+    chunks: string[];
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number;
+};
+type AgentWidgetToolCall = {
+    id: string;
+    name?: string;
+    status: "pending" | "running" | "complete";
+    args?: unknown;
+    chunks?: string[];
+    result?: unknown;
+    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;
+    parameters?: unknown;
+    resolvedAt?: number;
+};
+type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
+/**
+ * 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[];
+    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;
+};
+/**
+ * Options for injecting a message into the conversation.
+ * Supports dual-content where UI display differs from LLM context.
+ *
+ * @example
+ * // Same content for user and LLM
+ * {
+ *   role: 'assistant',
+ *   content: 'Here are your search results...'
+ * }
+ *
+ * @example
+ * // Different content: user sees full details, LLM sees summary
+ * {
+ *   role: 'assistant',
+ *   content: '**Found 3 products:**\n- iPhone 15 Pro ($1,199)\n- iPhone 15 ($999)',
+ *   llmContent: '[Search results: 3 iPhones, $999-$1199]'
+ * }
+ */
+type InjectMessageOptions = {
+    /**
+     * Message role: "assistant", "user", or "system"
+     */
+    role: AgentWidgetMessageRole;
+    /**
+     * Content displayed to the user in the chat UI.
+     * This is what appears in the message bubble.
+     */
+    content: string;
+    /**
+     * Content sent to the LLM in API requests.
+     * When omitted, `content` is used for both display and LLM.
+     *
+     * Use cases:
+     * - Redacted content: Show full product details to user, send summary to LLM
+     * - Structured data: Show formatted markdown to user, send JSON to LLM
+     * - Token optimization: Show verbose content to user, send concise version to LLM
+     */
+    llmContent?: string;
+    /**
+     * Multi-modal content parts for the LLM (images, files).
+     * Takes precedence over `llmContent` when present.
+     * The `content` field is still used for UI display.
+     */
+    contentParts?: ContentPart[];
+    /**
+     * Optional message ID. If omitted, auto-generated based on role.
+     */
+    id?: string;
+    /**
+     * Optional creation timestamp (ISO string). If omitted, uses current time.
+     */
+    createdAt?: string;
+    /**
+     * Optional sequence number for ordering.
+     */
+    sequence?: number;
+    /**
+     * Whether the message is still streaming (for incremental updates).
+     * @default false
+     */
+    streaming?: boolean;
+    /**
+     * Mark this message as a voice processing placeholder.
+     * Consumers can detect this in `messageTransform` to render custom UI.
+     */
+    voiceProcessing?: boolean;
+};
+/**
+ * Options for injecting assistant messages (most common case).
+ * Role defaults to 'assistant'.
+ */
+type InjectAssistantMessageOptions = Omit<InjectMessageOptions, "role">;
+/**
+ * Options for injecting user messages.
+ * Role defaults to 'user'.
+ */
+type InjectUserMessageOptions = Omit<InjectMessageOptions, "role">;
+/**
+ * Options for injecting system messages.
+ * Role defaults to 'system'.
+ */
+type InjectSystemMessageOptions = Omit<InjectMessageOptions, "role">;
+type PersonaArtifactRecord = {
+    id: string;
+    artifactType: PersonaArtifactKind;
+    title?: string;
+    status: "streaming" | "complete";
+    markdown?: string;
+    component?: string;
+    props?: Record<string, unknown>;
+};
+/** Programmatic artifact upsert (controller / window API) */
+type PersonaArtifactManualUpsert = {
+    id?: string;
+    artifactType: "markdown";
+    title?: string;
+    content: string;
+} | {
+    id?: string;
+    artifactType: "component";
+    title?: string;
+    component: string;
+    props?: Record<string, unknown>;
+};
+type AgentWidgetEvent = {
+    type: "message";
+    message: AgentWidgetMessage;
+} | {
+    type: "status";
+    status: "connecting" | "connected" | "error" | "idle";
+} | {
+    type: "error";
+    error: Error;
+} | {
+    type: "artifact_start";
+    id: string;
+    artifactType: PersonaArtifactKind;
+    title?: string;
+    component?: string;
+} | {
+    type: "artifact_delta";
+    id: string;
+    artDelta: string;
+} | {
+    type: "artifact_update";
+    id: string;
+    props: Record<string, unknown>;
+    component?: string;
+} | {
+    type: "artifact_complete";
+    id: string;
+};
+
+/** Field definition types for the declarative configurator system (headless — no DOM) */
+
+type FieldType = 'color' | 'slider' | 'toggle' | 'select' | 'text' | 'chip-list' | 'color-scale' | 'token-ref' | 'role-assignment';
+interface SliderOptions {
+    min: number;
+    max: number;
+    step: number;
+    unit?: 'px' | 'rem' | 'none';
+    /** Treat max value as 9999px (border-radius: full) */
+    isRadiusFull?: boolean;
+}
+interface SelectOption {
+    value: string;
+    label: string;
+}
+interface ColorScaleOptions {
+    /** Which palette color family (e.g., 'primary', 'gray') */
+    colorFamily: string;
+}
+interface TokenRefOptions {
+    /** Token type to filter available references */
+    tokenType: 'color' | 'spacing' | 'radius' | 'shadow' | 'typography';
+    /** Available palette families to reference */
+    families?: string[];
+}
+/** Which kind of value a role target expects */
+type RoleTargetKind = 'background' | 'foreground' | 'border' | 'accent';
+/** A single token path that a role assignment writes to */
+interface RoleTarget {
+    /** Theme token path (e.g., 'components.message.user.background') */
+    path: string;
+    /** What kind of value this target expects */
+    kind: RoleTargetKind;
+}
+/** An intensity preset (e.g., Solid uses .500 shades, Soft uses .100 shades) */
+interface RoleIntensity {
+    id: string;
+    label: string;
+}
+/** Options for a role-assignment field */
+interface RoleAssignmentOptions {
+    /** Unique role identifier */
+    roleId: string;
+    /** Helper text shown below the role name */
+    helper: string;
+    /** Token paths this role writes to */
+    targets: RoleTarget[];
+    /** Available intensity presets */
+    intensities: RoleIntensity[];
+    /** Which data-persona-theme-zone this role corresponds to (for preview highlighting) */
+    previewZone?: string;
+}
+interface FieldDef {
+    id: string;
+    label: string;
+    description?: string;
+    type: FieldType;
+    /** Dot-path into the config/theme object */
+    path: string;
+    defaultValue?: unknown;
+    /** Slider-specific options */
+    slider?: SliderOptions;
+    /** Select-specific options */
+    options?: SelectOption[];
+    /** Color-scale-specific options */
+    colorScale?: ColorScaleOptions;
+    /** Token-ref-specific options */
+    tokenRef?: TokenRefOptions;
+    /** Role-assignment-specific options */
+    roleAssignment?: RoleAssignmentOptions;
+    /** CSS property hint for value formatting */
+    cssProperty?: string;
+    /** Whether this is a theme path (vs config path) */
+    isThemePath?: boolean;
+    /** Convert stored value into a control-friendly value */
+    formatValue?: (value: unknown) => unknown;
+    /** Convert control input back into the stored value shape */
+    parseValue?: (value: unknown) => unknown;
+}
+interface SectionDef {
+    id: string;
+    title: string;
+    description?: string;
+    fields: FieldDef[];
+    /** Whether the section starts collapsed */
+    collapsed?: boolean;
+    /** Preset buttons for this section */
+    presets?: SectionPreset[];
+}
+interface SectionPreset {
+    id: string;
+    label: string;
+    values: Record<string, unknown>;
+}
+interface TabDef {
+    id: string;
+    label: string;
+    icon?: string;
+    sections: SectionDef[];
+}
+interface SubGroupDef {
+    label: string;
+    sections: SectionDef[];
+    /** When true, the sub-group starts collapsed and must be explicitly expanded */
+    collapsedByDefault?: boolean;
+}
+/** Extract the toolCall config type from AgentWidgetConfig */
+type AgentWidgetToolCallConfig = NonNullable<AgentWidgetConfig['toolCall']>;
+interface ThemeEditorPreset {
+    id: string;
+    name: string;
+    description: string;
+    theme: DeepPartial<PersonaTheme>;
+    darkTheme?: DeepPartial<PersonaTheme>;
+    /** Tool call styling for light mode */
+    toolCall?: AgentWidgetToolCallConfig;
+    /** Tool call styling for dark mode (falls back to toolCall if not set) */
+    darkToolCall?: AgentWidgetToolCallConfig;
+    preview: {
+        primary: string;
+        surface: string;
+        accent: string;
+    };
+    darkPreview?: {
+        primary: string;
+        surface: string;
+        accent: string;
+    };
+    /** Tags for filtering/categorization */
+    tags?: string[];
+}
+interface ConfiguratorSnapshot {
+    version: 2;
+    config: Record<string, unknown>;
+    theme: PersonaTheme;
+}
+type ConfigChangeListener = (config: AgentWidgetConfig, theme: PersonaTheme) => void;
+/** Callback for when a control value changes */
+type OnChangeCallback = (path: string, value: unknown) => void;
+
+/** Headless state management for the theme editor (no DOM, no localStorage, no side effects) */
+
+declare class ThemeEditorState {
+    private config;
+    private theme;
+    private listeners;
+    private history;
+    private historyIndex;
+    private suppressHistory;
+    constructor(initialTheme?: Partial<PersonaTheme>, initialConfig?: Partial<AgentWidgetConfig>, options?: {
+        mergeDefaults?: boolean;
+    });
+    /**
+     * Get a value using a dot-path.
+     * - `theme.*` → reads from the PersonaTheme
+     * - `darkTheme.*` → reads from config.darkTheme
+     * - everything else → reads from the AgentWidgetConfig
+     */
+    get(path: string): unknown;
+    getTheme(): PersonaTheme;
+    getConfig(): AgentWidgetConfig;
+    /**
+     * Set a value using a dot-path.
+     * - `theme.*` → writes into the PersonaTheme
+     * - `darkTheme.*` → writes into config.darkTheme
+     * - everything else → writes into AgentWidgetConfig
+     */
+    set(path: string, value: unknown): void;
+    /** Batch-set multiple paths at once */
+    setBatch(updates: Record<string, unknown>): void;
+    /** Replace the entire theme */
+    setTheme(theme: PersonaTheme): void;
+    /** Replace the entire config (for preset loading) */
+    setFullConfig(config: AgentWidgetConfig, theme?: PersonaTheme): void;
+    /** Import a snapshot (v2 or raw theme) */
+    importSnapshot(snapshot: unknown): void;
+    /** Reset to defaults */
+    resetToDefaults(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getHistoryLength(): number;
+    getHistoryIndex(): number;
+    undo(): void;
+    redo(): void;
+    exportSnapshot(): ConfiguratorSnapshot;
+    onChange(listener: ConfigChangeListener): () => void;
+    private syncThemeIntoConfig;
+    private notifyListeners;
+    private recordHistory;
+    private pushHistorySnapshot;
+    private restoreSnapshot;
+}
+
+/** Declarative section/field definitions for the theme editor (pure data — no DOM, no render logic) */
+
+declare const STYLE_SECTIONS: SectionDef[];
+declare const PALETTE_SECTION: SectionDef;
+declare const SEMANTIC_COLORS_SECTION: SectionDef;
+declare const COLORS_SECTIONS: SectionDef[];
+/** Shared shape sections (not scoped to light/dark) */
+declare const COMPONENT_SHAPE_SECTIONS: SectionDef[];
+/** Component color sections (can be scoped for light/dark) */
+declare const COMPONENT_COLOR_SECTIONS: SectionDef[];
+declare const COMPONENTS_SECTIONS: SectionDef[];
+declare const CONFIGURE_SUB_GROUPS: SubGroupDef[];
+declare const CONFIGURE_SECTIONS: SectionDef[];
+/** Section 1: Theme — color mode selection */
+declare const THEME_SECTION: SectionDef;
+/** Section 2: Brand Palette — primary colors + collapsed status colors */
+declare const BRAND_PALETTE_SECTION: SectionDef;
+/** Section 2b: Status palette — collapsed under Brand Palette */
+declare const STATUS_PALETTE_SECTION: SectionDef;
+/** Section 3: Interface Roles — the main theming surface */
+declare const INTERFACE_ROLES_SECTION: SectionDef;
+/** Section 4: Status Colors — feedback semantic tokens */
+declare const STATUS_COLORS_SECTION: SectionDef;
+/** Section 5: Advanced Tokens — entry point for drill-downs (no fields) */
+declare const ADVANCED_TOKENS_SECTION: SectionDef;
+/** V2 Style tab sections — outcome-oriented editor */
+declare const STYLE_SECTIONS_V2: SectionDef[];
+declare const ALL_TABS: TabDef[];
+type ThemeScope = 'theme' | 'darkTheme';
+type ThemeVariant = 'light' | 'dark';
+/** Look up a section by ID from an array of sections */
+declare function findSection(sections: SectionDef[], id: string): SectionDef;
+/** Create a light/dark scoped copy of a section */
+declare function scopeSection(section: SectionDef, scope: ThemeScope, variant: ThemeVariant, collapsed?: boolean | undefined): SectionDef;
+
+/** Theme editor presets — unified collection of built-in presets */
+
+declare const BUILT_IN_PRESETS: ThemeEditorPreset[];
+/** All built-in presets */
+declare const THEME_EDITOR_PRESETS: ThemeEditorPreset[];
+/** Look up a preset by ID */
+declare function getThemeEditorPreset(id: string): ThemeEditorPreset | undefined;
+
+type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error";
+
+/**
+ * Feedback UI components for CSAT and NPS collection
+ */
+type CSATFeedbackOptions = {
+    /** Callback when user submits CSAT feedback */
+    onSubmit: (rating: number, comment?: string) => void | Promise<void>;
+    /** Callback when user dismisses the feedback form */
+    onDismiss?: () => void;
+    /** Title text */
+    title?: string;
+    /** Subtitle/question text */
+    subtitle?: string;
+    /** Placeholder for optional comment field */
+    commentPlaceholder?: string;
+    /** Submit button text */
+    submitText?: string;
+    /** Skip button text */
+    skipText?: string;
+    /** Show comment field */
+    showComment?: boolean;
+    /** Rating labels (5 items for ratings 1-5) */
+    ratingLabels?: [string, string, string, string, string];
+};
+type NPSFeedbackOptions = {
+    /** Callback when user submits NPS feedback */
+    onSubmit: (rating: number, comment?: string) => void | Promise<void>;
+    /** Callback when user dismisses the feedback form */
+    onDismiss?: () => void;
+    /** Title text */
+    title?: string;
+    /** Subtitle/question text */
+    subtitle?: string;
+    /** Placeholder for optional comment field */
+    commentPlaceholder?: string;
+    /** Submit button text */
+    submitText?: string;
+    /** Skip button text */
+    skipText?: string;
+    /** Show comment field */
+    showComment?: boolean;
+    /** Low label (left side) */
+    lowLabel?: string;
+    /** High label (right side) */
+    highLabel?: string;
+};
+
+type Controller = {
+    update: (config: AgentWidgetConfig) => void;
+    destroy: () => void;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    clearChat: () => void;
+    setMessage: (message: string) => boolean;
+    submitMessage: (message?: string) => boolean;
+    startVoiceRecognition: () => boolean;
+    stopVoiceRecognition: () => boolean;
+    /**
+     * Inject a message into the conversation with dual-content support.
+     * Auto-opens the widget if closed and launcher is enabled.
+     */
+    injectMessage: (options: InjectMessageOptions) => AgentWidgetMessage;
+    /**
+     * Convenience method for injecting assistant messages.
+     */
+    injectAssistantMessage: (options: InjectAssistantMessageOptions) => AgentWidgetMessage;
+    /**
+     * Convenience method for injecting user messages.
+     */
+    injectUserMessage: (options: InjectUserMessageOptions) => AgentWidgetMessage;
+    /**
+     * Convenience method for injecting system messages.
+     */
+    injectSystemMessage: (options: InjectSystemMessageOptions) => AgentWidgetMessage;
+    /**
+     * Inject multiple messages in a single batch with one sort and one render pass.
+     */
+    injectMessageBatch: (optionsList: InjectMessageOptions[]) => AgentWidgetMessage[];
+    /**
+     * @deprecated Use injectMessage() instead.
+     */
+    injectTestMessage: (event: AgentWidgetEvent) => void;
+    getMessages: () => AgentWidgetMessage[];
+    getStatus: () => AgentWidgetSessionStatus;
+    getPersistentMetadata: () => Record<string, unknown>;
+    updatePersistentMetadata: (updater: (prev: Record<string, unknown>) => Record<string, unknown>) => void;
+    on: <K extends keyof AgentWidgetControllerEventMap>(event: K, handler: (payload: AgentWidgetControllerEventMap[K]) => void) => () => void;
+    off: <K extends keyof AgentWidgetControllerEventMap>(event: K, handler: (payload: AgentWidgetControllerEventMap[K]) => void) => void;
+    isOpen: () => boolean;
+    isVoiceActive: () => boolean;
+    getState: () => AgentWidgetStateSnapshot;
+    showCSATFeedback: (options?: Partial<CSATFeedbackOptions>) => void;
+    showNPSFeedback: (options?: Partial<NPSFeedbackOptions>) => void;
+    submitCSATFeedback: (rating: number, comment?: string) => Promise<void>;
+    submitNPSFeedback: (rating: number, comment?: string) => Promise<void>;
+    /**
+     * Connect an external SSE stream and process it through the SDK's
+     * native event pipeline (tools, reasoning, streaming text, etc.).
+     */
+    connectStream: (stream: ReadableStream<Uint8Array>, options?: {
+        assistantMessageId?: string;
+    }) => Promise<void>;
+    /** Push a raw event into the event stream buffer (for testing/debugging) */
+    __pushEventStreamEvent: (event: {
+        type: string;
+        payload: unknown;
+    }) => void;
+    /** Opens the event stream panel */
+    showEventStream: () => void;
+    /** Closes the event stream panel */
+    hideEventStream: () => void;
+    /** Returns current visibility state of the event stream panel */
+    isEventStreamVisible: () => boolean;
+    /** Show artifact sidebar (no-op if features.artifacts.enabled is false) */
+    showArtifacts: () => void;
+    /** Hide artifact sidebar */
+    hideArtifacts: () => void;
+    /** Upsert an artifact programmatically */
+    upsertArtifact: (manual: PersonaArtifactManualUpsert) => PersonaArtifactRecord | null;
+    selectArtifact: (id: string) => void;
+    clearArtifacts: () => void;
+    /**
+     * Focus the chat input. Returns true if focus succeeded, false if panel is closed
+     * (launcher mode) or textarea is unavailable.
+     */
+    focusInput: () => boolean;
+    /**
+     * Programmatically resolve a pending approval.
+     * @param approvalId - The approval ID to resolve
+     * @param decision - "approved" or "denied"
+     */
+    resolveApproval: (approvalId: string, decision: 'approved' | 'denied') => Promise<void>;
+};
+type AgentWidgetController = Controller;
+
+/**
+ * Shared preview building blocks for theme editor preview renderers.
+ * Used by both `createThemePreview()` (simple API) and the configurator's
+ * advanced preview system. Separate file for code-splitting.
+ */
+
+declare const DEVICE_DIMENSIONS: Record<string, {
+    w: number;
+    h: number;
+}>;
+declare const ZOOM_MIN = 0.15;
+declare const ZOOM_MAX = 1.5;
+declare const SHELL_STYLE_ID = "persona-preview-shell-theme";
+declare const PREVIEW_STORAGE_ADAPTER: {
+    load: () => null;
+    save: () => void;
+    clear: () => void;
+};
+declare const HOME_SUGGESTION_CHIPS: string[];
+declare function escapeHtml(str: string): string;
+type PreviewShellPalette = {
+    pageBg: string;
+    chromeBg: string;
+    chromeBorder: string;
+    dot: string;
+    skeleton: string;
+    cardBg: string;
+    cardBorder: string;
+};
+declare function getShellPalette(shellMode: 'light' | 'dark'): PreviewShellPalette;
+declare function buildShellCss(shellMode: 'light' | 'dark'): string;
+declare function applyShellTheme(iframe: HTMLIFrameElement, shellMode: 'light' | 'dark'): void;
+/** Browser chrome mock with skeleton content cards */
+declare const MOCK_BROWSER_CONTENT = "\n    <div class=\"preview-iframe-mock\" aria-hidden=\"true\">\n      <div class=\"preview-iframe-chrome\">\n        <span class=\"preview-iframe-dot\"></span>\n        <span class=\"preview-iframe-dot\"></span>\n        <span class=\"preview-iframe-dot\"></span>\n      </div>\n      <div class=\"preview-iframe-copy\">\n        <div class=\"preview-iframe-line hero\"></div>\n        <div class=\"preview-iframe-line body\"></div>\n        <div class=\"preview-iframe-line body\"></div>\n        <div class=\"preview-iframe-grid\">\n          <div class=\"preview-iframe-card\"></div>\n          <div class=\"preview-iframe-card\"></div>\n          <div class=\"preview-iframe-card\"></div>\n        </div>\n        <div class=\"preview-iframe-line body\"></div>\n        <div class=\"preview-iframe-line body\"></div>\n      </div>\n    </div>";
+/** Docked workspace skeleton (cards + rows inside content area) */
+declare const MOCK_WORKSPACE_CONTENT = "\n    <div class=\"preview-workspace-content-shell\" aria-hidden=\"true\">\n      <div class=\"preview-iframe-line hero\"></div>\n      <div class=\"preview-iframe-line body\"></div>\n      <div class=\"preview-workspace-row\">\n        <div class=\"preview-workspace-card\"></div>\n        <div class=\"preview-workspace-card\"></div>\n      </div>\n      <div class=\"preview-workspace-row\">\n        <div class=\"preview-workspace-card short\"></div>\n        <div class=\"preview-workspace-card short\"></div>\n        <div class=\"preview-workspace-card short\"></div>\n      </div>\n    </div>";
+/**
+ * Build a basic iframe srcdoc with mock page chrome and widget mount point.
+ * For advanced use cases (background URLs, embed detection), build custom srcdoc
+ * using the exported templates and shell CSS utilities.
+ */
+declare function buildSrcdoc(mountId: string, shellMode: 'light' | 'dark', docked: boolean, widgetCssPath: string): string;
+type PreviewScene = 'home' | 'conversation' | 'minimized' | 'artifact';
+declare function createPreviewMessages(scene: PreviewScene): AgentWidgetMessage[];
+declare function applySceneConfig(base: AgentWidgetConfig, scene: PreviewScene): AgentWidgetConfig;
+
+interface PreviewConfigOptions {
+    config?: Partial<AgentWidgetConfig>;
+    theme?: DeepPartial<PersonaTheme>;
+    darkTheme?: DeepPartial<PersonaTheme>;
+    scene?: PreviewScene;
+}
+declare function buildPreviewConfig(options: PreviewConfigOptions, shellModeOverride?: 'light' | 'dark'): AgentWidgetConfig;
+
+/**
+ * Imperative preview renderer for the theme editor.
+ * Manages iframe-based widget previews with device frames, zoom, scenes, and compare mode.
+ * No external DOM dependencies — only needs a container element to mount into.
+ *
+ * For advanced preview needs (background URLs, inline editing, contrast checking),
+ * use the lifecycle hooks in `ThemePreviewOptions` and import shared building blocks
+ * from `./preview-utils` directly.
+ */
+
+type PreviewDevice = 'desktop' | 'mobile';
+
+type PreviewShellMode = 'light' | 'dark';
+type CompareMode = 'off' | 'baseline' | 'themes';
+/** Context passed to lifecycle hooks after mounting or updating */
+interface PreviewLifecycleContext {
+    iframes: HTMLIFrameElement[];
+    controllers: AgentWidgetController[];
+}
+interface ThemePreviewOptions {
+    /** Device frame dimensions */
+    device?: PreviewDevice;
+    /** Widget state */
+    scene?: PreviewScene;
+    /** Browser chrome appearance */
+    shellMode?: PreviewShellMode;
+    /** Side-by-side comparison */
+    compareMode?: CompareMode;
+    /** Widget config */
+    config?: Partial<AgentWidgetConfig>;
+    /** Light mode theme */
+    theme?: DeepPartial<PersonaTheme>;
+    /** Dark mode theme */
+    darkTheme?: DeepPartial<PersonaTheme>;
+    /** Zoom level (0.15–1.5), or undefined for auto-fit */
+    zoom?: number;
+    /** Path to widget.css (defaults to looking for /widget-dist/widget.css) */
+    widgetCssPath?: string;
+    /** Config for the baseline side of a baseline comparison */
+    baselineConfig?: Partial<AgentWidgetConfig>;
+    /** Theme for the baseline side of a baseline comparison */
+    baselineTheme?: DeepPartial<PersonaTheme>;
+    /** Dark theme for the baseline side of a baseline comparison */
+    baselineDarkTheme?: DeepPartial<PersonaTheme>;
+    /** Called after all iframes load and widgets mount */
+    onAfterMount?: (ctx: PreviewLifecycleContext) => void;
+    /** Called after fast-path controller updates */
+    onAfterUpdate?: (ctx: PreviewLifecycleContext) => void;
+    /** Called before controllers are destroyed */
+    onBeforeDestroy?: () => void;
+    /** Called whenever the preview scale changes */
+    onScaleChange?: (scale: number) => void;
+    /** Override iframe srcdoc generation (for background URLs, etc.) */
+    buildSrcdoc?: (mountId: string, shellMode: PreviewShellMode, docked: boolean, cssPath: string) => string;
+    /** Override container HTML injection (for Idiomorph, etc.) */
+    morphContainer?: (container: HTMLElement, html: string) => void;
+}
+interface ThemePreviewHandle {
+    /** Update the preview (fast path when possible, full remount when needed) */
+    update(options: Partial<ThemePreviewOptions>): void;
+    /** Destroy preview and clean up */
+    destroy(): void;
+    /** Get live widget controllers */
+    getControllers(): AgentWidgetController[];
+    /** Recalculate auto-fit zoom */
+    fitToContainer(): void;
+    /** Get all preview iframes */
+    getIframes(): HTMLIFrameElement[];
+    /** Get current computed scale */
+    getScale(): number;
+    /** Set explicit zoom (or undefined to auto-fit) */
+    setZoom(zoom: number | undefined): void;
+}
+declare function createThemePreview(container: HTMLElement, initialOptions: ThemePreviewOptions): ThemePreviewHandle;
+
+/**
+ * Interface Role → Token mapping layer.
+ *
+ * Maps high-level editor choices (family + intensity) to concrete palette
+ * token references across multiple component/semantic paths. This is the
+ * core of the "Interface Roles" editor section — one picker writes to
+ * many tokens atomically.
+ *
+ * All functions are pure and headless (no DOM).
+ */
+
+declare const ROLE_INTENSITIES: RoleIntensity[];
+declare const ROLE_FAMILIES: readonly ["primary", "secondary", "accent", "gray"];
+type RoleFamily = (typeof ROLE_FAMILIES)[number];
+/** Display labels for palette families in the editor */
+declare const ROLE_FAMILY_LABELS: Record<RoleFamily, string>;
+declare const ROLE_SURFACES: RoleAssignmentOptions;
+declare const ROLE_HEADER: RoleAssignmentOptions;
+declare const ROLE_USER_MESSAGES: RoleAssignmentOptions;
+declare const ROLE_ASSISTANT_MESSAGES: RoleAssignmentOptions;
+declare const ROLE_PRIMARY_ACTIONS: RoleAssignmentOptions;
+declare const ROLE_SCROLL_TO_BOTTOM: RoleAssignmentOptions;
+declare const ROLE_INPUT: RoleAssignmentOptions;
+declare const ROLE_LINKS_FOCUS: RoleAssignmentOptions;
+declare const ROLE_BORDERS: RoleAssignmentOptions;
+/** All interface role definitions in display order */
+declare const ALL_ROLES: RoleAssignmentOptions[];
+/**
+ * Resolve a role assignment (family + intensity) into concrete token writes.
+ *
+ * Returns a map of `{ "theme.{path}": "palette.colors.{family}.{shade}" }`.
+ * The `theme.` prefix is added so callers can pass the result directly to
+ * `state.setBatch()`.
+ */
+declare function resolveRoleAssignment(family: string, intensity: string, role: RoleAssignmentOptions): Record<string, string>;
+/** Result of detecting a role assignment from current state */
+interface DetectedRoleAssignment {
+    family: RoleFamily;
+    intensity: string;
+}
+/**
+ * Detect the current role assignment by reading token values and matching
+ * against known palette reference patterns.
+ *
+ * @param getValue - Function to read a theme token value (e.g., `(p) => state.get('theme.' + p)`)
+ * @param role - The role definition to detect against
+ * @returns Detected assignment or null if tokens don't match a known pattern
+ */
+declare function detectRoleAssignment(getValue: (path: string) => unknown, role: RoleAssignmentOptions): DetectedRoleAssignment | null;
+
+/** Color parsing, normalization, and scale generation utilities (pure functions — no DOM) */
+
+interface ParsedCssValue {
+    value: number;
+    unit: 'px' | 'rem';
+}
+declare function parseCssValue(cssValue: string): ParsedCssValue;
+declare function formatCssValue(value: number, unit: 'px' | 'rem'): string;
+declare function convertToPx(value: number, unit: 'px' | 'rem'): number;
+declare function convertFromPx(pxValue: number, unit: 'px' | 'rem'): number;
+declare function normalizeColorValue(value: string): string;
+declare function isValidHex(value: string): boolean;
+/**
+ * Compute WCAG 2.x contrast ratio between two hex colors.
+ * Returns a number ≥ 1 (e.g. 4.5 for AA normal text).
+ */
+declare function wcagContrastRatio(hex1: string, hex2: string): number;
+declare function hexToHsl(hex: string): {
+    h: number;
+    s: number;
+    l: number;
+};
+declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * Generate a full color scale (50-950) from a base color (shade 500).
+ * Uses HSL-based lightness interpolation for natural-looking scales.
+ */
+declare function generateColorScale(baseHex: string): ColorShade;
+declare const SHADE_KEYS: readonly ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"];
+declare const COLOR_FAMILIES: readonly ["primary", "secondary", "accent", "gray", "success", "warning", "error", "info"];
+declare function paletteColorPath(family: string, shade: string): string;
+/**
+ * Resolve a theme dot-path to a concrete CSS color string.
+ * Follows token references recursively (palette.*, semantic.*, components.*).
+ */
+declare function resolveThemeColorPath(get: (path: string) => unknown, path: string, depth?: number): string;
+declare function tokenRefDisplayName(path: string): string;
+
+export { ADVANCED_TOKENS_SECTION, ALL_ROLES, ALL_TABS, BRAND_PALETTE_SECTION, BUILT_IN_PRESETS, COLORS_SECTIONS, COLOR_FAMILIES, COMPONENTS_SECTIONS, COMPONENT_COLOR_SECTIONS, COMPONENT_SHAPE_SECTIONS, CONFIGURE_SECTIONS, CONFIGURE_SUB_GROUPS, type ColorScaleOptions, type CompareMode, type ConfigChangeListener, type ConfiguratorSnapshot, DEVICE_DIMENSIONS, type DetectedRoleAssignment, type FieldDef, type FieldType, HOME_SUGGESTION_CHIPS, INTERFACE_ROLES_SECTION, MOCK_BROWSER_CONTENT, MOCK_WORKSPACE_CONTENT, type OnChangeCallback, PALETTE_SECTION, PREVIEW_STORAGE_ADAPTER, type PreviewConfigOptions, type PreviewDevice, type PreviewLifecycleContext, type PreviewScene, type PreviewShellMode, type PreviewShellPalette, ROLE_ASSISTANT_MESSAGES, ROLE_BORDERS, ROLE_FAMILIES, ROLE_FAMILY_LABELS, ROLE_HEADER, ROLE_INPUT, ROLE_INTENSITIES, ROLE_LINKS_FOCUS, ROLE_PRIMARY_ACTIONS, ROLE_SCROLL_TO_BOTTOM, ROLE_SURFACES, ROLE_USER_MESSAGES, type RoleAssignmentOptions, type RoleFamily, type RoleIntensity, type RoleTarget, type RoleTargetKind, SEMANTIC_COLORS_SECTION, SHADE_KEYS, SHELL_STYLE_ID, STATUS_COLORS_SECTION, STATUS_PALETTE_SECTION, STYLE_SECTIONS, STYLE_SECTIONS_V2, type SectionDef, type SectionPreset, type SelectOption, type SliderOptions, type SubGroupDef, THEME_EDITOR_PRESETS, THEME_SECTION, type TabDef, type ThemeEditorPreset, ThemeEditorState, type ThemePreviewHandle, type ThemePreviewOptions, type TokenRefOptions, ZOOM_MAX, ZOOM_MIN, applySceneConfig, applyShellTheme, buildPreviewConfig, buildShellCss, buildSrcdoc, convertFromPx, convertToPx, createPreviewMessages, createThemePreview, detectRoleAssignment, escapeHtml, findSection, formatCssValue, generateColorScale, getShellPalette, getThemeEditorPreset, hexToHsl, hslToHex, isValidHex, normalizeColorValue, paletteColorPath, parseCssValue, resolveRoleAssignment, resolveThemeColorPath, scopeSection, tokenRefDisplayName, wcagContrastRatio };