import { IconNode } from 'lucide';

/**
 * 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 `ask_user_question` tool calls.
     *
     * When a plugin returns an `HTMLElement`, it is inserted into the transcript
     * in place of the default (which is no transcript bubble: the built-in
     * renders a sheet over the composer). The built-in composer-overlay sheet
     * is suppressed so the plugin's UI fully owns the interaction.
     *
     * Return `null` to fall through to the built-in overlay sheet.
     *
     * The context gives you a pre-parsed `payload` (may be partial while the
     * tool call is still streaming: check `complete`) and two callbacks:
     * `resolve(answer)` resumes the paused LOCAL tool with the user's answer,
     * and `dismiss()` cancels with the sentinel `"(dismissed)"`.
     *
     * @example
     * ```typescript
     * renderAskUserQuestion: ({ payload, resolve, dismiss }) => {
     *   const prompt = payload.questions?.[0];
     *   if (!prompt) return null;
     *   const root = document.createElement("div");
     *   root.textContent = prompt.question ?? "";
     *   (prompt.options ?? []).forEach((option) => {
     *     const btn = document.createElement("button");
     *     btn.textContent = option.label;
     *     btn.addEventListener("click", () => resolve(option.label));
     *     root.appendChild(btn);
     *   });
     *   return root;
     * }
     * ```
     */
    renderAskUserQuestion?: (context: {
        message: AgentWidgetMessage;
        /**
         * Parsed `{ questions: [...] }` payload. May be partial while the tool
         * call is still streaming; see `complete`. `null` when no payload has
         * arrived yet.
         */
        payload: Partial<AskUserQuestionPayload> | null;
        /** `true` once the tool-call args have fully streamed in. */
        complete: boolean;
        /**
         * Resume the paused LOCAL tool with the user's answer. Posts to the
         * resume endpoint, pipes the SSE stream back into the session, and
         * appends a user-visible answer bubble to the transcript.
         */
        resolve: (answer: string) => void;
        /**
         * Cancel the question. Resumes with the sentinel `"(dismissed)"` so the
         * server doesn't sit in `waiting_for_local` forever. Idempotent.
         */
        dismiss: () => void;
        config: AgentWidgetConfig;
    }) => HTMLElement | null;
    /**
     * Custom renderer for approval bubbles.
     *
     * Return an `HTMLElement` to fully own the approval UI, `defaultRenderer()`
     * to render (or wrap) the built-in bubble, or `null` to fall through to the
     * default. Unlike the built-in bubble: whose Approve/Deny buttons are wired
     * via delegation: a fully custom element resolves the approval by calling
     * the `approve`/`deny` callbacks. Both route through the same path the
     * built-in buttons use (optimistic update, `onDecision`, in-place anchoring).
     *
     * An approval is a single binary gate, so there are exactly two outcomes.
     * Pass `{ remember: true }` to flag a "remember this" affordance (e.g. an
     * "Always allow" button); the current approval resolves identically, but the
     * flag is forwarded to `config.approval.onDecision` so you can persist a
     * don't-ask-again policy for future approvals.
     *
     * `renderApproval` is called again whenever the approval's status changes, so
     * branch on `message.approval?.status` to render the resolved state (and tear
     * down any global listeners you added while pending).
     *
     * @example
     * ```typescript
     * // An alternative prompt: "Always allow" / "Allow once" / "Deny".
     * renderApproval: ({ message, approve, deny }) => {
     *   const approval = message.approval;
     *   if (!approval || approval.status !== "pending") return null; // default renders resolved state
     *   const root = document.createElement("div");
     *   root.textContent = `${approval.toolName} requires approval`;
     *
     *   const always = document.createElement("button");
     *   always.textContent = "Always allow";
     *   always.addEventListener("click", () => approve({ remember: true }));
     *
     *   const once = document.createElement("button");
     *   once.textContent = "Allow once";
     *   once.addEventListener("click", () => approve());
     *
     *   const no = document.createElement("button");
     *   no.textContent = "Deny";
     *   no.addEventListener("click", () => deny());
     *
     *   root.append(always, once, no);
     *   return root;
     * }
     * ```
     */
    renderApproval?: (context: {
        message: AgentWidgetMessage;
        defaultRenderer: () => HTMLElement;
        config: AgentWidgetConfig;
        /** Resolve this approval as approved. Pass `{ remember: true }` for an "Always allow" affordance. */
        approve: (options?: AgentWidgetApprovalDecisionOptions) => void;
        /** Resolve this approval as denied. Pass `{ remember: true }` for an "Always deny" affordance. */
        deny: (options?: AgentWidgetApprovalDecisionOptions) => void;
    }) => 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;
}

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;
    };
    /** Border color between messages in the thread. */
    border?: TokenReference<'color'>;
}
/**
 * Welcome / intro card rendered above the message list when no messages exist.
 * Set `copy.showWelcomeCard: false` to hide it; use `layout.slots["body-top"]`
 * to replace it wholesale.
 */
interface IntroCardTokens extends ComponentTokenSet {
    background?: TokenReference<'color'>;
    borderRadius?: TokenReference<'radius'>;
    padding?: TokenReference<'spacing'>;
    /** Box-shadow on the intro card (token ref or raw CSS, e.g. `none`). */
    shadow?: string;
}
/** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
interface CollapsibleWidgetTokens {
    /** Background for content areas. */
    container?: TokenReference<'color'>;
    /** Background for code blocks inside collapsible sections. */
    surface?: TokenReference<'color'>;
    /** Border color for collapsible sections. */
    border?: TokenReference<'color'>;
}
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;
        };
    };
    /** Fenced code block styling. */
    codeBlock?: {
        background?: TokenReference<'color'>;
        borderColor?: TokenReference<'color'>;
        textColor?: TokenReference<'color'>;
    };
    /** Table styling. */
    table?: {
        headerBackground?: TokenReference<'color'>;
        borderColor?: TokenReference<'color'>;
    };
    /** Horizontal rule styling. */
    hr?: {
        color?: TokenReference<'color'>;
    };
    /** Blockquote styling. */
    blockquote?: {
        borderColor?: TokenReference<'color'>;
        background?: TokenReference<'color'>;
        textColor?: TokenReference<'color'>;
    };
}
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'>;
        /** Box-shadow for the approval bubble (token ref or raw CSS, e.g. `none`). */
        shadow: string;
    };
    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;
    /** Welcome / intro card shown above the message list. */
    introCard?: IntroCardTokens;
    /** 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;
    };
    /** Collapsible widget chrome (tool/reasoning/approval bubbles). */
    collapsibleWidget?: CollapsibleWidgetTokens;
}
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;
interface ResolvedToken {
    path: string;
    value: string;
    type: TokenType;
}
interface ThemeValidationError {
    path: string;
    message: string;
    severity: 'error' | 'warning';
}
interface ThemeValidationResult {
    valid: boolean;
    errors: ThemeValidationError[];
    warnings: ThemeValidationError[];
}
interface PersonaThemePlugin {
    name: string;
    version: string;
    transform(theme: PersonaTheme): PersonaTheme;
    cssVariables?: Record<string, string>;
    afterResolve?(resolved: Record<string, string>): Record<string, string>;
}
interface CreateThemeOptions {
    plugins?: PersonaThemePlugin[];
    validate?: boolean;
    extend?: PersonaTheme;
}

type RuntypeExecutionStreamEvent = ({
    agentId?: string;
    agentName?: string;
    config?: Record<string, unknown>;
    executionId: string;
    flowId?: string;
    flowName?: string;
    kind: "agent" | "flow";
    maxTurns?: number;
    seq: number;
    source?: string;
    startedAt: string;
    totalSteps?: number;
    type: "execution_start";
}) | ({
    completedAt?: string;
    durationMs?: number;
    executionId: string;
    failedSteps?: number;
    finalOutput?: string;
    iterations?: number;
    kind: "agent" | "flow";
    seq: number;
    stopReason?: string;
    success: boolean;
    successfulSteps?: number;
    totalCost?: number;
    totalSteps?: number;
    totalTokens?: {
        input: number;
        output: number;
    };
    type: "execution_complete";
}) | ({
    code?: string;
    completedAt?: string;
    error: string | {
        code: string;
        details?: Record<string, unknown>;
        message: string;
    };
    executionId: string;
    kind: "agent" | "flow";
    seq: number;
    type: "execution_error";
    upgradeUrl?: string;
}) | ({
    executionId: string;
    id: string;
    iteration?: number;
    role: "user" | "assistant" | "system";
    seq: number;
    turnIndex?: number;
    type: "turn_start";
}) | ({
    completedAt?: string;
    content?: string;
    cost?: number;
    executionId: string;
    fallback?: {
        attempts: Array<{
            attempt: number;
            error?: string;
            model?: string;
            success: boolean;
            type: "retry" | "model" | "message" | "flow";
        }>;
        exhausted: boolean;
        model?: string;
        reason?: string | null;
        used: boolean;
    };
    id: string;
    iteration?: number;
    role: "user" | "assistant" | "system";
    seq: number;
    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
    tokens?: {
        input: number;
        output: number;
    };
    type: "turn_complete";
}) | {
    executionId: string;
    id: string;
    index?: number;
    name?: string;
    outputVariable?: string;
    seq: number;
    startedAt?: string;
    stepType?: string;
    totalSteps?: number;
    type: "step_start";
} | ({
    completedAt?: string;
    durationMs?: number;
    error?: string;
    executionId: string;
    fallback?: {
        attempts: Array<{
            attempt: number;
            error?: string;
            model?: string;
            success: boolean;
            type: "retry" | "model" | "message" | "flow";
        }>;
        exhausted: boolean;
        model?: string;
        reason?: string | null;
        used: boolean;
    };
    id: string;
    name?: string;
    result?: unknown;
    seq: number;
    stepType?: string;
    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
    success?: boolean;
    tokensUsed?: number;
    type: "step_complete";
    unresolvedVariables?: Array<string>;
}) | {
    executionId: string;
    id: string;
    index?: number;
    name?: string;
    seq: number;
    skippedAt?: string;
    stepType?: string;
    totalSteps?: number;
    type: "step_skip";
    when?: string;
} | ({
    executionId: string;
    id: string;
    parentToolCallId?: string;
    role?: "user" | "assistant" | "system";
    seq: number;
    stepId?: string;
    turnId?: string;
    type: "text_start";
}) | {
    delta: string;
    executionId: string;
    id: string;
    seq: number;
    type: "text_delta";
} | {
    executionId: string;
    id: string;
    seq: number;
    text?: string;
    type: "text_complete";
} | ({
    executionId: string;
    id: string;
    parentToolCallId?: string;
    scope?: "turn" | "loop";
    seq: number;
    type: "reasoning_start";
}) | {
    delta: string;
    executionId: string;
    id: string;
    seq: number;
    type: "reasoning_delta";
} | ({
    executionId: string;
    id: string;
    scope?: "turn" | "loop";
    seq: number;
    text?: string;
    type: "reasoning_complete";
}) | ({
    executionId: string;
    id: string;
    mediaType: string;
    role?: "user" | "assistant" | "system";
    seq: number;
    toolCallId?: string;
    type: "media_start";
}) | {
    delta: string;
    executionId: string;
    id: string;
    seq: number;
    type: "media_delta";
} | {
    data?: string;
    executionId: string;
    id: string;
    mediaType?: string;
    seq: number;
    toolCallId?: string;
    type: "media_complete";
    url?: string;
} | ({
    artifactType: "markdown" | "component";
    component?: string;
    executionId?: string;
    id: string;
    seq?: number;
    title?: string;
    type: "artifact_start";
}) | {
    delta: string;
    executionId?: string;
    id: string;
    seq?: number;
    type: "artifact_delta";
} | {
    component: string;
    executionId?: string;
    id: string;
    props: Record<string, unknown>;
    seq?: number;
    type: "artifact_update";
} | {
    executionId?: string;
    id: string;
    seq?: number;
    type: "artifact_complete";
} | {
    executionId: string;
    id?: string;
    seq: number;
    sourceType?: string;
    title?: string;
    type: "source";
    url?: string;
    [key: string]: unknown;
} | ({
    executionId: string;
    hiddenParameterNames?: Array<string>;
    iteration?: number;
    origin?: "webmcp" | "sdk";
    pageOrigin?: string;
    parameters?: Record<string, unknown>;
    seq: number;
    startedAt?: string;
    stepId?: string;
    toolCallId: string;
    toolName: string;
    toolType: string;
    type: "tool_start";
}) | {
    delta: string;
    executionId: string;
    seq: number;
    toolCallId: string;
    type: "tool_input_delta";
} | {
    executionId: string;
    hiddenParameterNames?: Array<string>;
    parameters: Record<string, unknown>;
    seq: number;
    toolCallId: string;
    toolName?: string;
    type: "tool_input_complete";
} | {
    delta: string;
    executionId: string;
    seq: number;
    toolCallId: string;
    type: "tool_output_delta";
} | {
    error?: string;
    executionId: string;
    executionTime?: number;
    iteration?: number;
    result?: unknown;
    seq: number;
    stepId?: string;
    success: boolean;
    toolCallId: string;
    toolName?: string;
    type: "tool_complete";
} | {
    approvalId: string;
    description?: string;
    executionId: string;
    iteration?: number;
    parameters?: Record<string, unknown>;
    reason?: string;
    seq: number;
    startedAt?: string;
    subagent?: {
        agentName?: string;
        toolName: string;
    };
    timeout?: number;
    toolCallId?: string;
    toolName: string;
    toolType?: string;
    type: "approval_start";
} | ({
    approvalId: string;
    completedAt?: string;
    decision: "approved" | "denied" | "timeout";
    executionId: string;
    resolvedBy?: "user" | "system";
    seq: number;
    type: "approval_complete";
}) | ({
    awaitedAt?: string;
    executionId: string;
    origin?: "webmcp" | "sdk";
    pageOrigin?: string;
    parameters?: Record<string, unknown>;
    seq: number;
    toolCallId?: string;
    toolId?: string;
    toolName?: string;
    type: "await";
}) | ({
    error: string | {
        code: string;
        details?: Record<string, unknown>;
        message: string;
    };
    executionId: string;
    recoverable?: boolean;
    seq: number;
    type: "error";
}) | {
    executionId: string;
    seq: number;
    timestamp: string;
    type: "ping";
} | {
    executionId?: string;
    name: string;
    seq?: number;
    type: "custom";
    value?: unknown;
};
type RuntypeFlowSSEEvent = {
    executionContext?: Record<string, unknown>;
    executionId?: string;
    flowId: string;
    flowName?: string;
    input?: unknown;
    seq?: number;
    source?: string;
    startedAt: string;
    toolContext?: {
        executionId: string;
        stepId: string;
        toolId: string;
    };
    totalSteps?: number;
    type: "flow_start";
} | {
    claudeManagedAgentId?: string;
    completedAt?: string;
    completedSteps?: number;
    duration?: number;
    executionContext?: Record<string, unknown>;
    executionId?: string;
    executionTime?: number;
    failedSteps?: number;
    finalOutput?: string;
    flowId?: string;
    flowName?: string;
    output?: unknown;
    seq?: number;
    source?: string;
    success?: boolean;
    successfulSteps?: number;
    toolContext?: {
        executionId: string;
        stepId: string;
        toolId: string;
    };
    totalSteps?: number;
    totalTokensUsed?: number;
    type: "flow_complete";
} | ({
    code?: string;
    error: string | {
        code: string;
        message: string;
        stepId?: string;
        stepType?: string;
    };
    executionId?: string;
    executionTime?: number;
    flowId?: string;
    seq?: number;
    timestamp?: string;
    toolContext?: {
        executionId: string;
        stepId: string;
        toolId: string;
    };
    type: "flow_error";
    upgradeUrl?: string;
}) | ({
    awaitedAt: string;
    executionId?: string;
    flowId: string;
    origin?: "webmcp" | "sdk";
    pageOrigin?: string;
    parameters?: Record<string, unknown>;
    seq?: number;
    toolCallId?: string;
    toolId?: string;
    toolName?: string;
    type: "flow_await";
}) | {
    estimatedTokens?: number;
    executionId?: string;
    id?: string;
    index?: number;
    name?: string;
    outputVariable?: string;
    seq?: number;
    startedAt: string;
    stepId?: string;
    stepName?: string;
    stepType?: string;
    toolContext?: {
        executionId: string;
        stepId: string;
        toolId: string;
    };
    totalSteps?: number;
    type: "step_start";
} | {
    delta?: string;
    executionId?: string;
    id?: string;
    messageId?: string;
    partId?: string;
    seq?: number;
    text?: string;
    toolContext?: {
        executionId: string;
        stepId: string;
        toolId: string;
    };
    toolId?: string;
    type: "step_delta";
} | ({
    completedAt?: string;
    duration?: number;
    durationMs?: number;
    error?: string;
    executionId?: string;
    executionTime?: number;
    id?: string;
    index?: number;
    name?: string;
    output?: unknown;
    result?: unknown;
    seq?: number;
    stepId?: string;
    stepName?: string;
    stepType?: string;
    stopReason?: "end_turn" | "max_tool_calls" | "length" | "content_filter" | "error" | "unknown";
    success?: boolean;
    tokensUsed?: number;
    toolContext?: {
        executionId: string;
        stepId: string;
        toolId: string;
    };
    type: "step_complete";
    unresolvedVariables?: Array<string>;
}) | {
    error: string;
    executionId?: string;
    executionTime?: number;
    id?: string;
    index?: number;
    name?: string;
    seq?: number;
    stepType?: string;
    type: "step_error";
} | {
    error?: string;
    executionId?: string;
    id: string;
    index?: number;
    name?: string;
    seq?: number;
    skippedAt: string;
    stepType: string;
    totalSteps: number;
    type: "step_skip";
    when: string;
} | {
    executionId?: string;
    reason?: string;
    seq?: number;
    type: "step_await";
    [key: string]: unknown;
} | ({
    agentContext?: {
        executionId: string;
        iteration: number;
        seq: number;
    };
    executionId?: string;
    hiddenParameterNames?: Array<string>;
    name?: string;
    parameters?: Record<string, unknown>;
    providerOptions?: Record<string, unknown>;
    seq?: number;
    startedAt?: string;
    stepId?: string;
    toolCallId?: string;
    toolId?: string;
    toolName?: string;
    toolType: "flow" | "mcp" | "builtin" | "custom" | "external" | "advisor" | "subagent" | "local";
    type: "tool_start";
    [key: string]: unknown;
}) | {
    delta?: string;
    executionId?: string;
    seq?: number;
    toolId?: string;
    type: "tool_delta";
    [key: string]: unknown;
} | {
    delta: string;
    executionId?: string;
    seq?: number;
    stepId?: string;
    toolCallId?: string;
    toolId?: string;
    type: "tool_input_delta";
} | {
    executionId?: string;
    hiddenParameterNames?: Array<string>;
    parameters: Record<string, unknown>;
    providerOptions?: Record<string, unknown>;
    seq?: number;
    stepId?: string;
    toolCallId?: string;
    toolId?: string;
    toolName?: string;
    type: "tool_input_complete";
} | {
    agentContext?: {
        executionId: string;
        iteration: number;
        seq: number;
    };
    completedAt?: string;
    error?: string;
    executionId?: string;
    executionTime?: number;
    name?: string;
    result?: unknown;
    seq?: number;
    stepId?: string;
    success: boolean;
    toolCallId?: string;
    toolCost?: number;
    toolId?: string;
    toolName?: string;
    type: "tool_complete";
} | {
    agentContext?: {
        executionId: string;
        iteration: number;
        seq: number;
    };
    error: string;
    executionId?: string;
    executionTime?: number;
    failedAt?: string;
    name: string;
    seq?: number;
    toolId: string;
    type: "tool_error";
} | {
    executionId?: string;
    id: string;
    seq?: number;
    text: string;
    type: "chunk";
} | {
    executionId?: string;
    seq?: number;
    type: "text_start";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "text_end";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "reason_start";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "reason_delta";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "reason_complete";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "source";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "fallback_start";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "fallback_complete";
    [key: string]: unknown;
} | {
    executionId?: string;
    seq?: number;
    type: "fallback_exhausted";
    [key: string]: unknown;
};
type RuntypeStreamEventOf<U, T extends string> = Extract<U, {
    type: T;
}>;
type RuntypeTurnCompleteEvent = RuntypeStreamEventOf<RuntypeExecutionStreamEvent, "turn_complete">;
type RuntypeStepCompleteEvent = RuntypeStreamEventOf<RuntypeFlowSSEEvent, "step_complete">;
type RuntypeStopReasonKind = NonNullable<RuntypeTurnCompleteEvent["stopReason"] | RuntypeStepCompleteEvent["stopReason"]>;
type RuntypeClientInitRequest = {
    flowId?: string;
    sessionId?: string;
    token: string;
};
type RuntypeClientInitResponse = {
    config: {
        placeholder?: string;
        theme?: unknown;
        welcomeMessage?: string | null;
    };
    expiresAt: string;
    flow: {
        description?: string | null;
        id: string;
        name?: string | null;
    };
    sessionId: string;
};
type RuntypeClientChatRequest = {
    assistantMessageId?: string;
    clientTools?: Array<{
        description: string;
        name: string;
        origin?: "webmcp" | "sdk";
        pageOrigin?: string;
        parametersSchema: {
            type: "object";
            [key: string]: unknown;
        };
        untrustedContentHint?: boolean;
    }>;
    clientToolsFingerprint?: string;
    inputs?: Record<string, unknown>;
    messages: Array<{
        content: string | (Array<{
            text: string;
            type: "text";
        } | {
            image: string;
            mimeType?: string;
            type: "image";
        } | {
            data: string;
            filename: string;
            mimeType: string;
            type: "file";
        } | {
            providerOptions?: Record<string, unknown>;
            text: string;
            type: "reasoning";
        }>);
        id?: string;
        role: "user" | "assistant" | "system";
    }>;
    metadata?: Record<string, unknown>;
    sessionId: string;
    submitMode?: "normal" | "interrupt";
    turnId?: string;
};
type RuntypeClientChatStreamEvent = RuntypeExecutionStreamEvent;
type RuntypeClientResumeRequest = {
    executionId: string;
    messages?: Array<{
        content: string | (Array<{
            text: string;
            type: "text";
        } | {
            image: string;
            mimeType?: string;
            type: "image";
        } | {
            data: string;
            filename: string;
            mimeType: string;
            type: "file";
        } | {
            providerOptions?: Record<string, unknown>;
            text: string;
            type: "reasoning";
        }>);
        role: "system" | "user" | "assistant";
    }>;
    sessionId: string;
    streamResponse?: boolean;
    toolOutputs?: Record<string, unknown>;
};
type RuntypeClientResumeStreamEvent = RuntypeExecutionStreamEvent;
type RuntypeClientFeedbackRequest = {
    comment?: string;
    messageId?: string;
    metadata?: Record<string, unknown>;
    rating?: number;
    sessionId: string;
    token: string;
    type: "upvote" | "downvote" | "copy" | "csat" | "nps";
};
type RuntypeClientFeedbackResponse = {
    feedbackId: string;
    message?: string;
    success: true;
};
type RuntypeClientFeedbackType = RuntypeClientFeedbackRequest["type"];

/**
 * Target resolution for the normalized, backend-neutral `target` field.
 *
 * `target` is a single string that selects which backend resource a widget
 * talks to, optimized for a browser widget (always serializable, no live
 * objects). Three shapes are supported:
 *
 *   - Runtype TypeID (no prefix): `"agent_…"` / `"flow_…"` route to the
 *     Runtype agent/flow paths. The TypeID prefix is self-describing, so no
 *     wrapper is needed for the common case.
 *   - Provider-prefixed: `"<provider>:<id>"` is handed to the matching
 *     `targetProviders[provider]` resolver, which returns the dispatch payload
 *     fragment for that backend (e.g. `eve`, `langgraph`). `"runtype:…"` is a
 *     built-in that re-detects a TypeID.
 *   - Bare name: `"support"` requires a `targetProviders.default` resolver,
 *     otherwise it throws (a bare name is ambiguous without one).
 *
 * Resolvers are registered, not passed as the value, which keeps `target`
 * itself a plain string that survives script-tag installs, `data-config`,
 * persisted state, and codegen.
 */
/** Resolver for a provider-prefixed (or default) target id. */
type TargetResolver = (id: string) => {
    payload: Record<string, unknown>;
};
/** Normalized routing produced from a `target` string. */
type ResolvedTarget = {
    kind: "agentId";
    agentId: string;
} | {
    kind: "flowId";
    flowId: string;
} | {
    kind: "payload";
    payload: Record<string, unknown>;
};

/**
 * Text content part for multi-modal messages
 */
type TextContentPart = {
    type: 'text';
    text: string;
};
/**
 * Image content part for multi-modal messages
 * Supports base64 data URIs or URLs
 */
type ImageContentPart = {
    type: 'image';
    image: string;
    mimeType?: string;
    alt?: string;
};
/**
 * File content part for multi-modal messages
 * Supports PDF, TXT, DOCX, and other document types
 */
type FileContentPart = {
    type: 'file';
    data: string;
    mimeType: string;
    filename: string;
};
/**
 * Audio content part for multi-modal messages
 * Supports base64 data URIs or URLs
 */
type AudioContentPart = {
    type: 'audio';
    audio: string;
    mimeType?: string;
};
/**
 * Video content part for multi-modal messages
 * Supports base64 data URIs or URLs
 */
type VideoContentPart = {
    type: 'video';
    video: string;
    mimeType?: string;
};
/**
 * Union type for all content part types
 */
type ContentPart = TextContentPart | ImageContentPart | FileContentPart | AudioContentPart | VideoContentPart;
/**
 * 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;
    agent?: {
        agentId: 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>;
    /**
     * Per-turn page-discovered tools (WebMCP). Sent to Runtype's dispatch so the
     * agent can call them as `webmcp:<name>`. The widget snapshots
     * `document.modelContext.__getRegisteredTools()` each turn and ships only
     * the JSON-serializable surface (no `execute`).
     */
    clientTools?: ClientToolDefinition[];
};
/**
 * 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;
    /** How the model is steered toward tools: let it decide, force a call, or disable */
    toolCallStrategy?: "auto" | "required" | "none";
    /** Per-tool invocation limits / requirements keyed by tool name */
    perToolLimits?: Record<string, {
        maxCalls?: number;
        required?: boolean;
    }>;
    /** 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;
        /** Ask the agent to state its intent alongside approval requests (default: true) */
        requestReason?: boolean;
    };
    /**
     * Enables the synthesized `spawn_subagent` tool: the model can spin up
     * ad-hoc child agents at runtime, restricted to `toolPool` (tool IDs /
     * runtime-tool names already granted to the parent agent).
     */
    subagentConfig?: {
        toolPool: string[];
        defaultMaxTurns?: number;
        maxTurnsLimit?: number;
        maxSpawnsPerRun?: number;
        defaultModel?: string;
        allowNesting?: boolean;
        defaultTimeoutMs?: number;
    };
    /**
     * Enables the synthesized `code_mode` tool: the model writes JS that calls
     * pool tools inside a sandbox instead of issuing individual tool calls.
     */
    codeModeConfig?: {
        toolPool: string[];
        description?: string;
        timeoutMs?: 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;
};
type SavedAgentConfig = {
    /** Persisted Runtype agent ID to execute. */
    agentId: string;
};
/**
 * 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;
};
/**
 * Request payload for agent execution mode.
 */
type AgentWidgetAgentRequestPayload = {
    agent: AgentConfig | SavedAgentConfig;
    messages: AgentWidgetRequestPayloadMessage[];
    options: AgentRequestOptions;
    context?: Record<string, unknown>;
    metadata?: Record<string, unknown>;
    /**
     * Per-turn page-discovered tools (WebMCP): same shape as
     * `AgentWidgetRequestPayload.clientTools`.
     */
    clientTools?: ClientToolDefinition[];
};
/**
 * Wire shape for a single client-discovered tool sent on `dispatch.clientTools[]`.
 *
 * Mirrors the SDK's `ClientToolDefinition` in `@runtypelabs/sdk`. Only the
 * JSON-serializable surface of a WebMCP tool: the `execute` function stays
 * client-side; the server merges these into the agent's tool catalog under
 * the `webmcp:` namespace.
 */
type ClientToolDefinition = {
    /** Bare tool name; the server prepends `webmcp:` on the wire. */
    name: string;
    description: string;
    /** JSON Schema (per WebMCP spec): passed through as-is. */
    parametersSchema?: object;
    /**
     * `'webmcp'` for tools discovered via the polyfill (server prepends the
     * `webmcp:` wire prefix); `'sdk'` for widget/SDK-provided tools (name stays
     * bare on the wire). Matches the server's accepted enum: any other value
     * fails dispatch validation.
     */
    origin?: 'webmcp' | 'sdk';
    /** Origin of the page that registered the tool: for server-side audit. */
    pageOrigin?: string;
    /**
     * WebMCP `Tool.annotations` (spec). Not used for gating server-side; the
     * widget reads these client-side. Forwarded so traces/dashboards can show
     * `readOnlyHint` / `untrustedContentHint` on tool-call records.
     */
    annotations?: {
        readOnlyHint?: boolean;
        untrustedContentHint?: boolean;
    };
};
/**
 * Information passed to the confirm-bubble handler before a `webmcp:*` tool
 * call executes. Every WebMCP tool routes through this single gate.
 */
type WebMcpConfirmInfo = {
    /** Bare tool name (no `webmcp:` prefix). */
    toolName: string;
    args: unknown;
    description?: string;
    /**
     * Display title the tool declared via the WebMCP spec's
     * `ToolDescriptor.title` (e.g. `"Add to Cart"`). Absent when the tool
     * didn't declare one.
     */
    title?: string;
    annotations?: {
        readOnlyHint?: boolean;
        untrustedContentHint?: boolean;
    };
    /**
     * Why the confirm was requested. Currently always `'gate'`: the default
     * confirm-by-default gate that fires before every `webmcp:*` call. (The
     * `@mcp-b/webmcp-polyfill` owns the spec's `requestUserInteraction` callback
     * internally, so Persona no longer surfaces a nested in-tool confirm.)
     */
    reason: 'gate';
};
/**
 * Resolves to `true` if the user approves the tool call; `false` to decline.
 */
type WebMcpConfirmHandler = (info: WebMcpConfirmInfo) => Promise<boolean>;
/**
 * Persona's normalized tool-result shape sent back to the agent on `/resume`.
 * Mirrors the MCP `CallToolResult` content shape; arbitrary `execute()` return
 * values are wrapped as a single text block at the bridge boundary.
 */
type WebMcpToolResult = {
    content: Array<{
        type: 'text';
        text: string;
    } | {
        type: string;
        [key: string]: unknown;
    }>;
    isError?: boolean;
    /** Pass-through of the tool's `annotations.untrustedContentHint`. */
    annotations?: {
        untrustedContentHint?: boolean;
    };
};
/**
 * Widget-level WebMCP configuration. Set `enabled: true` to opt in. The
 * surface's server-side `webmcp` policy is the source of truth for which
 * tools are accepted: these client-side options are convenience filters.
 */
type AgentWidgetWebMcpConfig = {
    /** Master switch. Default: `false` (widget never installs the polyfill). */
    enabled?: boolean;
    /**
     * Glob-ish name patterns to include client-side. `'*'` matches any chars
     * except `:`. Patterns are matched against the bare tool name (no `webmcp:`
     * prefix). If unset, all registered tools are included.
     */
    allowlist?: string[];
    /**
     * Per-tool gate policy. Called before the confirm gate for every
     * `webmcp:*` call; return `true` to approve immediately and skip the
     * confirmation UI entirely. Use this to auto-allow read-only tools (e.g.
     * a catalog search) while still gating mutating ones. Only consulted on
     * the default-UI path: a custom `onConfirm` takes full control instead.
     */
    autoApprove?: (info: WebMcpConfirmInfo) => boolean;
    /**
     * Confirm gate handler. When omitted, Persona renders its native in-panel
     * approval bubble (the same chrome used for server-driven tool approvals)
     * and resolves on the user's Approve/Deny click. Supply this to override
     * with a custom confirmer (e.g. a route-level modal). The legacy
     * `window.confirm` fallback only applies when no widget UI is attached.
     */
    onConfirm?: WebMcpConfirmHandler;
};
/**
 * Agent execution state tracking.
 */
type AgentExecutionState = {
    executionId: string;
    agentId: string;
    agentName: string;
    status: 'running' | 'complete' | 'error';
    currentIteration: number;
    maxTurns: number;
    startedAt?: number;
    completedAt?: number;
    stopReason?: 'complete' | 'end_turn' | 'max_turns' | 'max_cost' | 'timeout' | 'error';
};
/**
 * Metadata attached to messages created during agent execution.
 */
type AgentMessageMetadata = {
    executionId?: string;
    iteration?: number;
    turnId?: string;
    agentName?: string;
    /**
     * When this message was produced by a step inside a nested flow executed
     * as a tool, identifies the parent tool call id. Enables renderers to
     * visually group or indent nested-flow output under its parent tool.
     */
    parentToolId?: string;
    /**
     * Nested flow step id that produced this message (e.g. a `send-stream`
     * or `prompt` step inside the nested flow). Stable key for that step.
     */
    parentStepId?: string;
    /**
     * Set to `true` on a tool-variant message produced from a `step_await`
     * event (`awaitReason: "local_tool_required"`). Signals to UI code that
     * the tool call is a LOCAL tool and the server is paused waiting for a
     * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
     */
    awaitingLocalTool?: boolean;
    /**
     * The provider per-call id (`toolu_…`) carried on the `step_await` /
     * `flow_await` events for a LOCAL tool (core#3878). Present only when the
     * server emits it. Two PARALLEL calls to the same tool in one turn share a
     * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
     * so this is the key the widget batches a single `/resume` on: preferred
     * over tool name, which collides for same-tool parallel calls. Absent →
     * fall back to the legacy name-keyed resume contract.
     */
    webMcpToolCallId?: string;
    /**
     * Set to `true` once the user has picked / typed / dismissed an answer for
     * an `ask_user_question` tool call, so renderers stop re-mounting the
     * answer-pill sheet for this tool call on subsequent render passes.
     */
    askUserQuestionAnswered?: boolean;
    /**
     * In-progress answers for a multi-question `ask_user_question` payload,
     * keyed by question text. Persisted across refresh so the user lands back
     * where they were if the page reloads mid-flow. Cleared once
     * `askUserQuestionAnswered` flips to `true`.
     */
    askUserQuestionAnswers?: Record<string, string | string[]>;
    /**
     * Current page index for a multi-question `ask_user_question` payload's
     * paginated stepper. Persists alongside `askUserQuestionAnswers`.
     */
    askUserQuestionIndex?: number;
    /**
     * Set to `true` once a `suggest_replies` tool call's fire-and-forget
     * `/resume` has been accepted by the server. Persisted belt-and-suspenders
     * mirror of the in-memory resolved-key dedupe, so hydration/re-emit paths
     * never re-resume the call.
     */
    suggestRepliesResolved?: boolean;
};
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>;
    artifacts?: PersonaArtifactRecord[];
    selectedArtifactId?: string | null;
};
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;
};
/**
 * Fired on every voice `VoiceStatus` transition (listening / processing /
 * speaking / idle / …). Unlike `voice:state` (a coarse active on/off), this
 * exposes the granular status so consumers can render their own per-state UI
 * (e.g. a listening/speaking status dock).
 */
type AgentWidgetVoiceStatusEvent = {
    status: VoiceStatus;
    timestamp: number;
};
type AgentWidgetActionEventPayload = {
    action: AgentWidgetParsedAction;
    message: AgentWidgetMessage;
};
/**
 * Fired on every "Read aloud" (text-to-speech) state transition for a message:
 * `loading` (press) → `playing` → `paused`/`playing` → `idle` (finished or
 * stopped). On the terminal `idle` transition, `messageId`/`message` still
 * identify the message that just stopped.
 */
type AgentWidgetReadAloudEvent = {
    /** The message being read aloud (or that just finished/stopped), if known. */
    messageId: string | null;
    /** The message object, when still present in the thread. */
    message: AgentWidgetMessage | null;
    /** The new playback state for this message. */
    state: ReadAloudState;
    timestamp: number;
};
/**
 * 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;
    /**
     * Show a "Read aloud" button that speaks the assistant message via
     * text-to-speech (play / pause / resume). Uses the browser Web Speech API by
     * default, or a hosted engine supplied via `textToSpeech.createEngine`.
     * Voice, rate and pitch are read from the `textToSpeech` config.
     * @default false
     */
    showReadAloud?: boolean;
    /**
     * Visibility mode: 'always' shows buttons always, 'hover' shows on hover only
     * @default 'hover'
     */
    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;
    "voice:status": AgentWidgetVoiceStatusEvent;
    "action:detected": AgentWidgetActionEventPayload;
    "action:resubmit": AgentWidgetActionEventPayload;
    "widget:opened": AgentWidgetStateEvent;
    "widget:closed": AgentWidgetStateEvent;
    "widget:state": AgentWidgetStateSnapshot;
    "message:feedback": AgentWidgetMessageFeedback;
    "message:copy": AgentWidgetMessage;
    "message:read-aloud": AgentWidgetReadAloudEvent;
    "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;
};
/**
 * How the transcript scrolls while an assistant response streams in.
 *
 * - `"anchor-top"` (default): on send, scroll the user's message near the top
 *   of the viewport and hold it there while the response streams in beneath it
 *   (ChatGPT-style). When a turn has no user send to anchor to (a proactive
 *   greeting, an injected assistant message, a resubmit, or first-load
 *   streaming), it falls back to `"follow"` for that turn so content never
 *   streams in off-screen.
 * - `"follow"`: keep the newest content pinned to the bottom of the viewport,
 *   pausing when the user scrolls up and resuming when they return to the
 *   bottom. This was the default before 4.x.
 * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
 *   way back to the latest content.
 */
type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
/**
 * Where the transcript lands when a *saved* conversation is reopened (restored
 * from the storage adapter / `initialMessages`), as opposed to a fresh send.
 *
 * - `"bottom"` (default): jump to the absolute end of the transcript, matching
 *   the historical behavior.
 * - `"last-user-turn"`: pin the last user message near the top of the viewport
 *   (the last point the reader was actively driving the conversation) so a long
 *   restored thread opens at a readable place rather than at the very bottom.
 */
type AgentWidgetScrollRestorePosition = "bottom" | "last-user-turn";
type AgentWidgetScrollBehaviorFeature = {
    /** Scroll behavior during streamed responses. @default "anchor-top" */
    mode?: AgentWidgetScrollMode;
    /**
     * Gap (px) kept between the anchored user message and the top of the
     * viewport in `"anchor-top"` mode. Also used as the gap for
     * `restorePosition: "last-user-turn"`.
     * @default 16
     */
    anchorTopOffset?: number;
    /**
     * Where to land when a saved conversation reopens. Additive and opt-in: the
     * default preserves the historical "jump to the bottom" behavior.
     * @default "bottom"
     */
    restorePosition?: AgentWidgetScrollRestorePosition;
    /**
     * When true, interactions beyond text selection — keyboard navigation
     * (PageUp/PageDown/Home/End/arrows) inside the transcript and focusing a
     * link or other interactive element within it — also pause auto-follow in
     * `"follow"` mode. Treats "the reader is doing something here" as intent to
     * stay put, not just "the reader dragged a selection". Opt-in; default keeps
     * only the existing wheel/scroll/selection triggers.
     * @default false
     */
    pauseOnInteraction?: boolean;
    /**
     * When true, the scroll-to-bottom affordance also surfaces new-content and
     * still-streaming activity while the reader is pinned away from the latest
     * content in `"anchor-top"` mode. Lets the reader know a response is arriving
     * offscreen below. Defaults on alongside the `"anchor-top"` default; set
     * `false` to keep the count + streaming hint silent while pinned.
     * @default true
     */
    showActivityWhilePinned?: boolean;
    /**
     * When true, Persona maintains a visually-hidden `aria-live="polite"` region
     * that announces important transcript events — a response starting, a
     * response finishing, and "N new messages below" while the reader is scrolled
     * away — at a comfortable cadence (never token-by-token). Opt-in so existing
     * embeds don't suddenly gain screen-reader announcements.
     * @default false
     */
    announce?: boolean;
};
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 AgentWidgetToolCallCollapsedMode = "tool-call" | "tool-name" | "tool-preview";
/**
 * Animation mode applied to tool call header text while the tool is running.
 * Character-by-character modes (`shimmer`, `shimmer-color`, `rainbow`) wrap each
 * character in a span with staggered `animation-delay`. `pulse` applies to the
 * entire text container. Honors `prefers-reduced-motion`.
 */
type AgentWidgetToolCallLoadingAnimation = "none" | "pulse" | "shimmer" | "shimmer-color" | "rainbow";
type AgentWidgetToolCallDisplayFeature = {
    /**
     * Controls what collapsed tool call rows show in their header/summary area.
     * @default "tool-call"
     */
    collapsedMode?: AgentWidgetToolCallCollapsedMode;
    /**
     * When true, active collapsed tool calls can render a lightweight preview block.
     * @default false
     */
    activePreview?: boolean;
    /**
     * Optional CSS min-height applied to active collapsed tool call rows.
     * @default undefined (no min-height)
     * @example "100px"
     */
    activeMinHeight?: string;
    /**
     * Maximum preview lines shown for collapsed active tool calls.
     * @default 3
     */
    previewMaxLines?: number;
    /**
     * When true, consecutive tool call rows can be visually grouped.
     * @default false
     */
    grouped?: boolean;
    /**
     * When false, tool call bubbles show only the collapsed summary with no
     * expand/collapse toggle. Users see tool awareness without full details.
     * @default true
     */
    expandable?: boolean;
    /**
     * Animation mode applied to the tool call header text while the tool is active.
     * - "none": static text, no animation
     * - "pulse": opacity pulse on the entire header text
     * - "shimmer": monochrome opacity sweep per character
     * - "shimmer-color": color gradient sweep per character
     * - "rainbow": rainbow color cycle per character
     * @default "none"
     */
    loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
};
type AgentWidgetReasoningDisplayFeature = {
    /**
     * When true, active collapsed reasoning rows can render a lightweight preview block.
     * @default false
     */
    activePreview?: boolean;
    /**
     * Optional CSS min-height applied to active collapsed reasoning rows.
     */
    activeMinHeight?: string;
    /**
     * Maximum preview lines shown for collapsed active reasoning rows.
     * @default 3
     */
    previewMaxLines?: number;
    /**
     * When false, reasoning bubbles show only the collapsed summary with no
     * expand/collapse toggle. Users see reasoning awareness without full details.
     * @default true
     */
    expandable?: boolean;
    /**
     * Animation mode applied to the reasoning header text while reasoning is active.
     * Reuses the same modes as tool call animations.
     * - "none": static text, no animation
     * - "pulse": opacity pulse on the entire header text
     * - "shimmer": monochrome opacity sweep per character
     * - "shimmer-color": color gradient sweep per character
     * - "rainbow": rainbow color cycle per character
     * @default "none"
     */
    loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
};
/**
 * Reveal animation applied to assistant message text while it is streaming.
 *
 * Built-in types always available:
 * - `none`: text appears as tokens arrive (default).
 * - `typewriter`: characters fade in with a blinking caret.
 * - `pop-bubble`: the bubble scales in; text streams normally afterward.
 * - `letter-rise`: per-char translateY + fade reveal.
 * - `word-fade`: per-word blur + translateY fade-in.
 *
 * Subpath plugins (import from `@runtypelabs/persona/animations/*` to register):
 * - `wipe`, `glyph-cycle`.
 *
 * Custom types are allowed: register a plugin with any string name and
 * reference it by that name in `type`.
 */
type AgentWidgetStreamAnimationBuiltinType = "none" | "typewriter" | "word-fade" | "letter-rise" | "glyph-cycle" | "wipe" | "pop-bubble";
type AgentWidgetStreamAnimationType = AgentWidgetStreamAnimationBuiltinType | (string & {});
/**
 * Placeholder shown inside a streaming assistant bubble before the first token arrives.
 * - `none`: use the default typing-dots indicator (existing behavior).
 * - `skeleton`: shimmer bars, replaced by streaming content once it starts.
 */
type AgentWidgetStreamAnimationPlaceholder = "none" | "skeleton";
/**
 * How much of the accumulated streaming content to display while tokens are
 * still arriving. Trimming to a boundary means in-progress words or lines
 * stay hidden until they complete: useful for animations that benefit from
 * unit-complete reveals (e.g. wipe, glyph-cycle).
 * - `none`: show every character as it arrives (default).
 * - `word`: trim to the last whitespace boundary.
 * - `line`: trim to the last newline boundary.
 */
type AgentWidgetStreamAnimationBuffer = "none" | "word" | "line";
/**
 * Context passed to plugin lifecycle hooks. Carries the live DOM references
 * and resolved animation settings for the currently-streaming message.
 */
type StreamAnimationContext = {
    /** The `.persona-message-content` element owning the streamed text. */
    container: HTMLElement;
    /** The outer message bubble element. */
    bubble: HTMLElement;
    /** ID of the streaming message. */
    messageId: string;
    /** Read-only reference to the message being streamed. */
    message: AgentWidgetMessage;
    /** Effective `speed` from `streamAnimation.speed`. */
    speed: number;
    /** Effective `duration` from `streamAnimation.duration`. */
    duration: number;
};
/**
 * Pluggable stream animation. Third-party packages and inline registrations
 * implement this interface to add custom reveal effects.
 *
 * Lifecycle:
 * - When the widget mounts and detects a plugin (either passed via config or
 *   auto-registered in the IIFE bundle), it injects `styles` once into the
 *   widget's style host.
 * - For each streaming assistant message whose `type` matches `name`, the
 *   widget applies `containerClass` / `bubbleClass`, wraps text per `wrap`,
 *   and, if `useCaret` is true, appends a blinking caret.
 * - Hooks fire after the live DOM is morphed; plugins use stable element IDs
 *   and `data-preserve-animation` to safely mutate per-char or per-word spans
 *   without idiomorph clobbering in-flight work.
 */
type StreamAnimationPlugin = {
    /** Plugin identifier. Matches the `type` field in `streamAnimation`. */
    name: string;
    /** Class added to `.persona-message-content` while streaming. */
    containerClass?: string;
    /** Class added to the bubble element (e.g. a one-shot scale animation). */
    bubbleClass?: string;
    /** Wrap mode applied to text nodes during streaming. @default "none" */
    wrap?: "none" | "char" | "word";
    /**
     * HTML tags whose descendant text is skipped during wrapping. Defaults to
     * `["pre", "code", "a", "script", "style"]`: useful for keeping code
     * blocks legible and link click-targets intact. Plugins that want to
     * animate characters inside inline code (e.g. `glyph-cycle`) can narrow
     * the list.
     */
    skipTags?: string[];
    /** Append a blinking caret after the last rendered char/word. */
    useCaret?: boolean;
    /** CSS string injected into the widget style host on first activation. */
    styles?: string;
    /**
     * Optional custom buffering strategy. Returns the portion of `content`
     * that should be rendered during streaming. Use this for buffering
     * schemes beyond the built-in `word` / `line` strategies.
     */
    bufferContent?: (content: string, message: AgentWidgetMessage) => string;
    /**
     * Fires once when the plugin is first activated inside a widget instance.
     * Use this to set up MutationObservers or other long-lived listeners.
     * Return an optional cleanup function that runs on widget destroy.
     */
    onAttach?: (root: HTMLElement | ShadowRoot) => (() => void) | void;
    /** Fires after each render that reaches the live DOM. */
    onAfterRender?: (ctx: StreamAnimationContext) => void;
    /** Fires when a streamed message's `streaming` flag flips to false. */
    onStreamComplete?: (ctx: StreamAnimationContext) => void;
    /**
     * Report whether the plugin still has in-flight animation work for a
     * message. When `true`, the widget keeps rendering the message in its
     * "streaming-animated" mode even after `message.streaming` flips false:   * preventing the final non-animated render from yanking the rug out from
     * under unfinished per-char cycles or reveals.
     */
    isAnimating?: (message: AgentWidgetMessage) => boolean;
};
type AgentWidgetStreamAnimationFeature = {
    /** Reveal animation to apply while streaming. @default "none" */
    type?: AgentWidgetStreamAnimationType;
    /** Pre-first-token placeholder. @default "none" */
    placeholder?: AgentWidgetStreamAnimationPlaceholder;
    /**
     * Per-unit animation duration (ms) for `typewriter`, `letter-rise`, `word-fade`,
     * and per-unit plugin animations. Each arriving character/word animates from
     * invisible to visible over this duration, independent of its position: the
     * streaming cadence itself provides the visible stagger.
     * @default 120
     */
    speed?: number;
    /**
     * Total duration of container-level animations (`pop-bubble` and custom
     * plugin animations), in milliseconds.
     * @default 1800
     */
    duration?: number;
    /**
     * Trim the accumulated streaming content to a word or line boundary before
     * rendering. Hides in-progress units until they complete.
     * @default "none"
     */
    buffer?: AgentWidgetStreamAnimationBuffer;
    /**
     * Extra animation plugins available to this widget instance. Keys are
     * plugin names; the matching plugin activates when `type` is set to that
     * name. Built-in types (`typewriter`, `pop-bubble`) are always registered.
     */
    plugins?: Record<string, StreamAnimationPlugin>;
};
type AgentWidgetFeatureFlags = {
    showReasoning?: boolean;
    showToolCalls?: boolean;
    showEventStreamToggle?: boolean;
    /**
     * Up/Down arrow navigation through previously sent user messages in the
     * composer, for quick re-entry or editing (shell / Slack style). History is
     * only entered when the caret is at the start of the input, so normal
     * multi-line cursor movement is preserved. Set to `false` to disable.
     * @default true
     */
    composerHistory?: boolean;
    /** Shared transcript + event stream scroll-to-bottom affordance. */
    scrollToBottom?: AgentWidgetScrollToBottomFeature;
    /** Transcript scroll behavior during streamed responses. */
    scrollBehavior?: AgentWidgetScrollBehaviorFeature;
    /** Collapsed transcript behavior for tool call rows. */
    toolCallDisplay?: AgentWidgetToolCallDisplayFeature;
    /** Collapsed transcript behavior for reasoning rows. */
    reasoningDisplay?: AgentWidgetReasoningDisplayFeature;
    /** Configuration for the Event Stream inspector view */
    eventStream?: EventStreamConfig;
    /** Optional artifact sidebar (split pane / mobile drawer) */
    artifacts?: AgentWidgetArtifactsFeature;
    /** Reveal animation for streaming assistant text. */
    streamAnimation?: AgentWidgetStreamAnimationFeature;
    /**
     * Built-in interactive answer-pill sheet shown when the assistant invokes
     * the `ask_user_question` tool. Slides up over the composer with tappable
     * pills + optional free-text input.
     */
    askUserQuestion?: AgentWidgetAskUserQuestionFeature;
    /**
     * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
     * the tool, the widget shows the suggestions as tappable chips above the
     * composer (reusing the suggestion-chips surface) and immediately resumes
     * the execution: fire-and-forget, no user input awaited.
     */
    suggestReplies?: AgentWidgetSuggestRepliesFeature;
};
/**
 * Feature config for the built-in `suggest_replies` quick-reply chips.
 * Chips render in the existing suggestions slot above the composer and are
 * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
 * verbatim as the user's next message; chips clear once any user message
 * follows them.
 */
type AgentWidgetSuggestRepliesFeature = {
    /**
     * Enable the feature. Defaults to true. When false, `suggest_replies`
     * renders as a regular tool bubble and is NOT auto-resumed: only set this
     * with no server-side `suggest_replies` declaration, or the execution
     * parks awaiting a resume that never comes.
     */
    enabled?: boolean;
    /**
     * Advertise the built-in `suggest_replies` tool to the agent on every
     * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
     * needed. Defaults to `false`: flows that already declare the tool via
     * `runtimeTools` would otherwise present it to the model twice. Ignored
     * when `enabled` is `false`.
     */
    expose?: boolean;
};
/**
 * Single selectable option in an `ask_user_question` prompt.
 * Mirrors Anthropic's AskUserQuestion schema.
 */
type AskUserQuestionOption = {
    /** Pill label (required). */
    label: string;
    /** Optional long-form description (shown as a subtitle on tap-hover). */
    description?: string;
    /** Optional rich preview: reserved for future rendering; ignored in v1. */
    preview?: string;
};
/**
 * A single question in an `ask_user_question` tool call.
 * The tool may carry 1–8 prompts. When more than one is supplied, the built-in
 * renderer paginates them as a "Question N of M" stepper with Back / Next /
 * Submit-all controls; single-question payloads render without stepper chrome.
 */
type AskUserQuestionPrompt = {
    /** The question text shown to the user. */
    question: string;
    /** Optional short header label (≤12 chars) used as a compact group title. */
    header?: string;
    /** 2–4 selectable options. */
    options: AskUserQuestionOption[];
    /** When true, the user can pick multiple options and submit together. Default false. */
    multiSelect?: boolean;
    /** When true, a free-text "Other…" pill expands to an input. Default true. */
    allowFreeText?: boolean;
};
/** Parsed payload of an `ask_user_question` tool call. */
type AskUserQuestionPayload = {
    /** 1–8 questions. Anything beyond the renderer's cap is truncated with a console warning. */
    questions: AskUserQuestionPrompt[];
};
/**
 * Style overrides for the answer-pill sheet. All values are raw CSS strings
 * and are plumbed through as CSS custom properties on the sheet root.
 */
type AgentWidgetAskUserQuestionStyles = {
    sheetBackground?: string;
    sheetBorder?: string;
    sheetShadow?: string;
    pillBackground?: string;
    pillBackgroundSelected?: string;
    pillTextColor?: string;
    pillTextColorSelected?: string;
    pillBorderRadius?: string;
    customInputBackground?: string;
};
/**
 * Feature config for the built-in `ask_user_question` answer-pill sheet.
 * When a tool call with the name `ask_user_question` arrives, the widget
 * renders an interactive sheet over the composer in place of the generic
 * tool bubble.
 */
type AgentWidgetAskUserQuestionFeature = {
    /** Enable the feature. Defaults to true. When false, `ask_user_question` renders as a regular tool bubble. */
    enabled?: boolean;
    /**
     * Advertise the built-in `ask_user_question` tool to the agent on every
     * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
     * needed. The tool ships with a model-facing description and JSON schema
     * matching {@link AskUserQuestionPayload}; when the model calls it, the
     * existing answer-pill sheet renders and the answer resumes the execution.
     *
     * Defaults to `false`: flows that already declare `ask_user_question` via
     * `runtimeTools` would otherwise present the tool to the model twice.
     * Ignored when `enabled` is `false`: never offer the agent a question
     * tool the widget can't render an answer UI for.
     */
    expose?: boolean;
    /** Slide-in animation duration in ms. Defaults to 180. */
    slideInMs?: number;
    /** Label for the free-text pill. Defaults to "Other…". */
    freeTextLabel?: string;
    /** Placeholder text in the free-text input. Defaults to "Type your answer…". */
    freeTextPlaceholder?: string;
    /** Button label for submitting multi-select / free-text answers. Defaults to "Send". */
    submitLabel?: string;
    /** Button label advancing to the next question in grouped (paginated) payloads. Defaults to "Next". */
    nextLabel?: string;
    /** Button label moving back to the previous question in grouped payloads. Defaults to "Back". */
    backLabel?: string;
    /** Button label submitting all answers from the final page of a grouped payload. Defaults to "Submit all". */
    submitAllLabel?: string;
    /**
     * In grouped (multi-question) mode, auto-advance to the next page after a
     * single-select pill pick or free-text submit on intermediate pages.
     * Defaults to `true`. The final page never auto-submits: users always
     * confirm with an explicit "Submit all" click. Multi-select pages always
     * require an explicit Next regardless of this setting.
     */
    groupedAutoAdvance?: boolean;
    /**
     * Visual layout for the option list.
     * - `"rows"` (default): full-width stacked rows with always-visible
     *   descriptions, right-edge number badges (single-select) or checkboxes
     *   (multi-select), and an always-visible inline "Other" input.
     * - `"pills"`: legacy compact pill list with horizontal wrap; description
     *   surfaces as a tooltip and the "Other…" pill expands on click.
     */
    layout?: "rows" | "pills";
    /**
     * Button label for skipping the current question in grouped payloads.
     * Defaults to "Skip". On intermediate pages Skip advances without recording
     * an answer; on the final page Skip submits the partial answer record
     * (skipped questions absent from the resolved object). For single-question
     * payloads Skip behaves like dismiss.
     */
    skipLabel?: string;
    /** Style overrides for the sheet and pills. */
    styles?: AgentWidgetAskUserQuestionStyles;
};
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";
    /**
     * Maximum height of the dock panel, applied as a viewport-overflow guard.
     *
     * The docked shell sizes itself with `height: 100%`, which only resolves when
     * an ancestor (usually `html, body { height: 100% }`) provides a definite
     * height. Without one, the dock column would otherwise grow with the
     * conversation and scroll off the page. This cap clamps the panel to the
     * viewport (and keeps the `resize`/`emerge` reveals pinned with
     * `position: sticky`; `push`/`overlay` get the cap only, since their
     * transform/absolute contexts defeat sticky) so a missing height chain
     * degrades gracefully instead of breaking the chat.
     *
     * - Set a CSS length (e.g. `"600px"`, `"80vh"`) to override the cap.
     * - Set `false` to disable the guard entirely (the panel then sizes purely
     *   from the surrounding layout: make sure your page provides a definite
     *   height all the way down to the dock target's parent).
     *
     * @default "100dvh"
     */
    maxHeight?: string | false;
};
/**
 * Layout configuration for `mountMode: "composer-bar"`. Controls how the
 * collapsed pill is positioned and sized, and how the panel expands when
 * the user opens it.
 */
type AgentWidgetComposerBarConfig = {
    /**
     * Max-width of the collapsed pill composer at the bottom of the viewport.
     * @default "720px"
     */
    collapsedMaxWidth?: string;
    /**
     * Bottom offset (CSS length) from the viewport edge in the collapsed state.
     * @default "16px"
     */
    bottomOffset?: string;
    /**
     * Auto-expand the panel when the user submits a message while the composer
     * is collapsed. When false, the message still sends but the panel remains
     * collapsed (the host can drive expansion programmatically).
     * @default true
     */
    expandOnSubmit?: boolean;
    /**
     * Size of the expanded chat panel.
     * - `"anchored"` (default): the pill stays at the bottom of the viewport
     *   and the chat history grows upward into a centered column above it.
     *   Width is driven by `expandedMaxWidth`; the panel's top edge sits at
     *   `expandedTopOffset` from the viewport top.
     * - `"fullscreen"`: covers the entire viewport (mobile-app style). Inner
     *   content is centered horizontally via `contentMaxWidth`.
     * - `"modal"`: centered sheet with margins; size driven by
     *   `modalMaxWidth` / `modalMaxHeight`.
     * @default "anchored"
     */
    expandedSize?: "anchored" | "fullscreen" | "modal";
    /**
     * When `expandedSize === "anchored"`, max-width of the expanded panel
     * column. Capped at `calc(100vw - 32px)` on narrow viewports.
     * @default "880px"
     */
    expandedMaxWidth?: string;
    /**
     * When `expandedSize === "anchored"`, distance from the viewport top to
     * the panel's top edge. Accepts any CSS length.
     * @default "5vh"
     */
    expandedTopOffset?: string;
    /**
     * Max-width applied to messages, composer form, suggestions, and
     * attachment previews so they center horizontally inside the expanded
     * panel. Falls back to `layout.contentMaxWidth` when set; otherwise
     * defaults to this value.
     * @default "720px"
     */
    contentMaxWidth?: string;
    /**
     * When `expandedSize === "modal"`, max-width of the expanded sheet.
     * @default "880px"
     */
    modalMaxWidth?: string;
    /**
     * When `expandedSize === "modal"`, max-height of the expanded sheet.
     * @default "min(90vh, 800px)"
     */
    modalMaxHeight?: string;
    /**
     * Configuration for the "peek" banner: the chrome-less row above the
     * collapsed pill that previews the most recent assistant message.
     */
    peek?: AgentWidgetComposerBarPeekConfig;
};
/**
 * Configuration for the composer-bar peek banner. Reuses the same
 * `streamAnimation` shape developers already configure for the main message
 * stream, so the surface for animations is identical across both contexts.
 *
 * Resolution order:
 * - If `peek.streamAnimation` is set, those values apply to the peek.
 * - Otherwise the peek inherits from `features.streamAnimation`.
 *
 * Per-surface carve-outs:
 * - `bubbleClass` from a plugin (used by `pop-bubble`) is ignored: the peek
 *   has no bubble analog.
 * - `containerClass`, `wrap` ("char" | "word"), `useCaret`, `placeholder`
 *   ("skeleton"), `buffer` ("word" | "line"), `speed`, `duration`, and
 *   custom plugins all apply unchanged.
 */
type AgentWidgetComposerBarPeekConfig = {
    /**
     * Reveal animation for the peek's trailing-message preview. Same shape as
     * `features.streamAnimation`. Omit to inherit from the main stream config.
     */
    streamAnimation?: AgentWidgetStreamAnimationFeature;
};
type AgentWidgetLauncherConfig = {
    enabled?: boolean;
    title?: string;
    subtitle?: string;
    textHidden?: boolean;
    iconUrl?: string;
    agentIconText?: string;
    agentIconName?: string;
    agentIconHidden?: boolean;
    /**
     * Background color for the agent icon circle in the launcher button. Accepts
     * any CSS color value. When set, overrides the default primary-color
     * background (the `persona-bg-persona-primary` utility).
     */
    agentIconBackgroundColor?: string;
    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
    /**
     * Controls how the launcher panel is mounted relative to the host page.
     * - "floating": default floating launcher / panel behavior
     * - "docked": wraps the target container and renders as a sibling dock
     * - "composer-bar": persistent rounded-pill composer fixed to the bottom of
     *   the viewport that morphs into a fullscreen (or modal) chat panel on
     *   submit and minimizes back to the pill on close.
     *
     * @default "floating"
     */
    mountMode?: "floating" | "docked" | "composer-bar";
    /**
     * Layout configuration for docked mode.
     */
    dock?: AgentWidgetDockConfig;
    /**
     * Layout configuration for composer-bar mode.
     * Only applies when `mountMode === "composer-bar"`.
     */
    composerBar?: AgentWidgetComposerBarConfig;
    autoExpand?: boolean;
    width?: string;
    /**
     * When true, the widget panel will fill the full height of its container.
     * Useful for sidebar layouts where the chat should take up the entire viewport height.
     * The widget will use flex layout to ensure header stays at top, messages scroll in middle,
     * and composer stays fixed at bottom.
     *
     * @default false
     */
    fullHeight?: boolean;
    /**
     * When true, the widget panel will be positioned as a sidebar flush with the viewport edges.
     * The panel will have:
     * - No border-radius (square corners)
     * - No margins (flush with top, left/right, and bottom edges)
     * - Full viewport height
     * - Subtle shadow on the edge facing the content
     * - No border between footer and messages
     *
     * Use with `position` to control which side ('bottom-left' for left sidebar, 'bottom-right' for right sidebar).
     * Automatically enables fullHeight when true.
     *
     * @default false
     */
    sidebarMode?: boolean;
    /**
     * Width of the sidebar panel when sidebarMode is true.
     * @default "420px"
     */
    sidebarWidth?: string;
    /**
     * Offset (in pixels) to subtract from the calculated panel height.
     * Useful for adjusting the panel height when there are other fixed elements on the page.
     * Only applies when not in fullHeight or sidebarMode.
     *
     * @default 0
     */
    heightOffset?: number;
    /**
     * When true, the widget panel expands to fill the full viewport on mobile devices.
     * Removes border-radius, margins, and shadows for a native app-like experience.
     * Applies when viewport width is at or below `mobileBreakpoint`.
     *
     * @default true
     */
    mobileFullscreen?: boolean;
    /**
     * Viewport width (in pixels) at or below which the widget enters mobile fullscreen mode.
     * Only applies when `mobileFullscreen` is true.
     *
     * @default 640
     */
    mobileBreakpoint?: number;
    /**
     * CSS z-index applied to the widget wrapper and launcher button in all
     * positioned modes (floating panel, mobile fullscreen, sidebar, docked
     * mobile fullscreen). Increase this value if other elements on the host
     * page appear on top of the widget.
     *
     * In viewport-covering modes (sidebar, mobile fullscreen), the widget
     * also elevates the host element's stacking context and locks
     * document scroll to prevent background scrolling.
     *
     * @default 100000
     */
    zIndex?: number;
    callToActionIconText?: string;
    callToActionIconName?: string;
    callToActionIconColor?: string;
    callToActionIconBackgroundColor?: string;
    callToActionIconHidden?: boolean;
    callToActionIconPadding?: string;
    agentIconSize?: string;
    callToActionIconSize?: string;
    headerIconSize?: string;
    headerIconName?: string;
    headerIconHidden?: boolean;
    closeButtonSize?: string;
    closeButtonColor?: string;
    closeButtonBackgroundColor?: string;
    closeButtonBorderWidth?: string;
    closeButtonBorderColor?: string;
    closeButtonBorderRadius?: string;
    closeButtonPaddingX?: string;
    closeButtonPaddingY?: string;
    closeButtonPlacement?: "inline" | "top-right";
    closeButtonIconName?: string;
    closeButtonIconText?: string;
    closeButtonTooltipText?: string;
    closeButtonShowTooltip?: boolean;
    clearChat?: AgentWidgetClearChatConfig;
    /**
     * Border style for the launcher button.
     * @example "1px solid #e5e7eb" | "2px solid #3b82f6" | "none"
     * @default "1px solid #e5e7eb"
     */
    border?: string;
    /**
     * Box shadow for the launcher button.
     * @example "0 10px 15px -3px rgba(0,0,0,0.1)" | "none"
     * @default "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)"
     */
    shadow?: string;
    /**
     * CSS `max-width` for the floating launcher button when the panel is closed.
     * Title and subtitle each truncate with an ellipsis when space is tight; full strings are available via the native `title` tooltip. Does not affect the open chat panel (`width` / `launcherWidth`).
     *
     * @example "min(380px, calc(100vw - 48px))"
     */
    collapsedMaxWidth?: string;
};
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;
    /** Lucide icon name shown while a response is streaming. Clicking the button in this state aborts the stream. Default: "square". */
    stopIconName?: string;
    /** Tooltip text shown while streaming. Default: "Stop generating". */
    stopTooltipText?: 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";
    /**
     * Called with per-turn latency metrics on the realtime (`runtype`) voice path.
     * Fires once per turn after the reply completes.
     */
    onMetrics?: (metrics: VoiceMetrics) => void;
    provider?: {
        type: 'browser' | 'runtype' | 'custom';
        browser?: {
            language?: string;
            continuous?: boolean;
        };
        runtype?: {
            agentId: string;
            /** Defaults to the widget's `clientToken` when omitted. */
            clientToken?: string;
            /** Defaults to the widget's `apiUrl` when omitted. */
            host?: string;
            voiceId?: string;
            /**
             * Optional custom streaming playback engine. Defaults to the built-in
             * `AudioPlaybackManager`. Import `createWorkletPlaybackEngine` from
             * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
             */
            createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
            /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
            pauseDuration?: number;
            /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
            silenceThreshold?: number;
        };
        /**
         * Bring-your-own voice provider. Set `type: 'custom'` and pass either a
         * ready {@link VoiceProvider} instance or a `() => VoiceProvider` factory
         * (the factory defers construction until voice is set up). STT-style
         * providers deliver a final transcript via `onResult` (sent as a user
         * message); full-duplex providers can drive `onTranscript`/`onMetrics` like
         * the realtime `runtype` provider.
         */
        custom?: VoiceProvider | (() => VoiceProvider);
    };
};
/**
 * 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'`: Use Runtype-hosted TTS. The realtime voice path speaks
     *   replies during a voice call, and the per-message "Read aloud" button (and
     *   auto-speak of text-typed replies) stream from Runtype's
     *   `POST {host}/v1/agents/:agentId/speak` endpoint via the built-in
     *   {@link SpeechEngine}. `host`/`agentId`/`clientToken` are derived from the
     *   widget config (see `agentId`/`host` below); unless `browserFallback` is
     *   `false`, a missing endpoint or transient failure falls back to the browser
     *   voice so the button is never broken.
     */
    provider?: 'browser' | 'runtype';
    /**
     * When `provider` is `'runtype'`:
     * - Read-aloud / auto-speak: acts as a safety net — if Runtype TTS is
     *   unreachable (no endpoint yet, network/auth failure) or the Runtype config
     *   is incomplete, speech falls back to the browser Web Speech API instead of
     *   erroring. Set to `false` to surface Runtype errors instead. **Defaults to
     *   on for this path.**
     * - Auto-speak of text-typed replies also requires this to be truthy (the
     *   realtime voice path already speaks voice-call replies).
     *
     * Has no effect when provider is `'browser'` (browser TTS is always used).
     */
    browserFallback?: boolean;
    /**
     * When `provider` is `'runtype'`, the agent whose configured voice synthesizes
     * read-aloud / auto-speak audio. Falls back to
     * `voiceRecognition.provider.runtype.agentId` when omitted. Required (here or
     * there) for Runtype TTS to activate; without it the browser voice is used.
     */
    agentId?: string;
    /**
     * When `provider` is `'runtype'`, the Runtype API host (e.g.
     * `https://api.runtype.com`). Defaults to the widget's `apiUrl`.
     */
    host?: string;
    /**
     * When `provider` is `'runtype'`, audio (ms) the streaming player buffers
     * before the first sample and after an underrun. Lower = snappier start;
     * higher = rides out delivery hiccups. Default 200. Applies to the default
     * in-bundle player; a custom `createPlaybackEngine` manages its own prebuffer.
     */
    prebufferMs?: number;
    /**
     * When `provider` is `'runtype'`, an optional factory for the streaming PCM
     * player that synthesizes read-aloud / auto-speak audio. Defaults to the
     * in-bundle, main-thread `AudioPlaybackManager` (smooth for steady Runtype
     * streams, no AudioWorklet — keeps the widget bundle lean).
     *
     * For the higher-quality, jitter-buffered AudioWorklet player, import
     * `createPcmStreamPlayer` from `@runtypelabs/persona/voice-worklet-player` and
     * pass it here — it then ships in your bundle, not Persona's:
     *
     * @example
     * import { createPcmStreamPlayer } from '@runtypelabs/persona/voice-worklet-player'
     * textToSpeech: {
     *   enabled: true,
     *   provider: 'runtype',
     *   createPlaybackEngine: () => createPcmStreamPlayer({ prebufferMs: 400 }),
     * }
     */
    createPlaybackEngine?: () => PcmStreamPlayer | Promise<PcmStreamPlayer>;
    /** Voice name to use for browser TTS (e.g., 'Google US English'). If not found, uses auto-detect. */
    voice?: string;
    /**
     * 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;
    /**
     * Factory for a custom {@link SpeechEngine}, used by both the auto-speak path
     * and the per-message "Read aloud" action. When omitted, the browser Web
     * Speech API engine is used. Return a hosted engine here to use server-side
     * TTS (e.g. Runtype) — such an engine can stream audio through the realtime
     * voice {@link VoicePlaybackEngine}. May be async (it is resolved on first
     * playback, inside the user gesture).
     */
    createEngine?: () => SpeechEngine | Promise<SpeechEngine>;
};
/**
 * Playback state of the per-message "Read aloud" action.
 * - `idle`: not reading this message.
 * - `loading`: the engine is preparing audio (e.g. a hosted TTS fetch). Browser
 *   engines pass through this state almost instantly.
 * - `playing`: audio is playing.
 * - `paused`: playback is paused and resumable.
 */
type ReadAloudState = "idle" | "loading" | "playing" | "paused";
/** A unit of speech handed to a {@link SpeechEngine}. */
interface SpeechRequest {
    /** Plain text to speak. The widget strips Markdown before calling the engine. */
    text: string;
    /** Preferred voice identifier (engine-specific; browser = voice name). */
    voice?: string;
    /** Speech rate (engine-specific range; browser: 0.1–10, default 1). */
    rate?: number;
    /** Speech pitch (engine-specific range; browser: 0–2, default 1). */
    pitch?: number;
}
/** Lifecycle callbacks a {@link SpeechEngine} invokes during playback. */
interface SpeechCallbacks {
    /** Audio has started playing. */
    onStart?: () => void;
    /** Playback finished naturally (or was canceled). */
    onEnd?: () => void;
    /** Playback failed. */
    onError?: (error: Error) => void;
}
/**
 * Pluggable text-to-speech engine behind the "Read aloud" message action.
 *
 * The widget ships a browser Web Speech API engine by default. Provide a hosted
 * engine (Runtype TTS, ElevenLabs, a server proxy, …) by implementing this
 * interface and returning it from {@link TextToSpeechConfig.createEngine}; a
 * server engine can stream audio into the realtime voice
 * {@link VoicePlaybackEngine}.
 */
interface SpeechEngine {
    /** Stable identifier, e.g. `"browser"`, `"runtype"`, or a custom id. */
    readonly id: string;
    /**
     * Whether {@link pause}/{@link resume} are supported. When `false`, the UI
     * offers play/stop only (tapping a playing message stops it).
     */
    readonly supportsPause: boolean;
    /** Begin speaking. Drives the lifecycle through `callbacks`. */
    speak(request: SpeechRequest, callbacks: SpeechCallbacks): void;
    /** Pause playback (no-op if unsupported). */
    pause(): void;
    /** Resume paused playback (no-op if unsupported). */
    resume(): void;
    /** Stop playback and discard any queued audio. */
    stop(): void;
    /** Optional teardown of engine resources. */
    destroy?(): void;
}
/**
 * Voice recognition result with transcript and optional audio
 */
type VoiceResult = {
    text: string;
    transcript?: string;
    audio?: {
        base64: string;
        format: 'wav' | 'mp3' | 'ogg' | 'webm';
        sampleRate: number;
        duration: number;
    };
    confidence?: number;
    provider: 'runtype' | 'browser' | 'custom';
};
/**
 * Voice provider status states
 */
type VoiceStatus = 'disconnected' | 'connected' | 'listening' | 'processing' | 'speaking' | 'error' | 'idle';
/**
 * Per-turn latency metrics emitted by the realtime voice path.
 * The wire frame is snake_case (`metrics`); decoded to camelCase at the
 * provider boundary before being surfaced through `onMetrics`.
 */
type VoiceMetrics = {
    /** LLM generation time (ms). */
    llmMs?: number;
    /** Text-to-speech synthesis time (ms). */
    ttsMs?: number;
    /** Time to first audio frame (ms). */
    firstAudioMs?: number;
    /** Total turn time (ms). */
    totalMs?: number;
};
/**
 * Streaming PCM playback engine used by the realtime voice provider.
 *
 * The provider feeds raw PCM16 LE mono @ 24kHz (WAV header already stripped)
 * via `enqueue`, signals end-of-reply with `markStreamEnd`, and learns when
 * playback has fully drained via `onFinished`. The default implementation is
 * `AudioPlaybackManager`; an optional jitter-buffered AudioWorklet engine ships
 * from `@runtypelabs/persona/voice-worklet-player` and can be injected via the
 * `runtype.createPlaybackEngine` config hook.
 */
interface VoicePlaybackEngine {
    /** Enqueue a raw PCM16 LE mono @ 24kHz chunk (no WAV header). */
    enqueue(pcm: Uint8Array): void;
    /** Signal that no more chunks will arrive for the current reply. */
    markStreamEnd(): void;
    /** Immediately stop playback and discard queued audio. */
    flush(): void;
    /** Register a callback fired once all queued audio has finished playing. */
    onFinished(callback: () => void): void;
    /** Release all audio resources. */
    destroy(): Promise<void> | void;
}
/**
 * A {@link VoicePlaybackEngine} that also supports pause/resume. Returned by
 * `createPcmStreamPlayer` (`@runtypelabs/persona/voice-worklet-player`): a
 * jitter-buffered AudioWorklet player for raw PCM16 / 24 kHz / mono streams.
 * Reuse it inside a hosted {@link SpeechEngine} to get gapless playback with a
 * configurable prebuffer and graceful underrun handling — feed each streamed
 * chunk to {@link VoicePlaybackEngine.enqueue} and the worklet does the rest.
 */
interface PcmStreamPlayer extends VoicePlaybackEngine {
    /** Pause playback; the audio clock suspends and {@link resume} continues in place. */
    pause(): void;
    /** Resume playback after {@link pause}. */
    resume(): void;
    /**
     * Register a callback fired once audible playback actually begins — i.e. the
     * prebuffer waterline filled and the first sample reached the output. Use this
     * (rather than "first chunk enqueued") to flip a UI from loading to playing, so
     * the spinner holds through the prebuffer. Fires once per playback session
     * (cleared by {@link VoicePlaybackEngine.flush}); a mid-reply underrun re-buffer
     * does not re-fire it.
     */
    onStarted(callback: () => void): void;
}
/**
 * Voice provider configuration
 * Determines which voice provider to use and its specific settings
 */
type VoiceConfig = {
    type: 'browser' | 'runtype' | 'custom';
    browser?: {
        language?: string;
        continuous?: boolean;
    };
    runtype?: {
        agentId: string;
        /** Defaults to the widget's `clientToken` when omitted. */
        clientToken?: string;
        /** Defaults to the widget's `apiUrl` (as a ws(s):// base) when omitted. */
        host?: string;
        voiceId?: string;
        /**
         * Optional custom streaming playback engine. Defaults to the built-in
         * `AudioPlaybackManager`. Import `createWorkletPlaybackEngine` from
         * `@runtypelabs/persona/voice-worklet-player` for a jitter-buffered engine.
         */
        createPlaybackEngine?: () => VoicePlaybackEngine | Promise<VoicePlaybackEngine>;
        /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
        pauseDuration?: number;
        /** @deprecated No-op on the realtime path: the server's STT owns turn-taking. */
        silenceThreshold?: number;
    };
    /**
     * Bring-your-own voice provider for `type: 'custom'`: either a ready
     * {@link VoiceProvider} instance or a `() => VoiceProvider` factory. The
     * factory form defers construction (WebSocket/AudioContext/etc.) until
     * `createVoiceProvider` runs.
     */
    custom?: VoiceProvider | (() => VoiceProvider);
};
/**
 * Voice provider interface
 * Abstract interface for all voice providers in the Persona SDK
 */
interface VoiceProvider {
    type: 'browser' | 'runtype' | 'custom';
    connect(): Promise<void>;
    disconnect(): Promise<void>;
    startListening(): Promise<void>;
    stopListening(): Promise<void>;
    onResult(callback: (result: VoiceResult) => void): void;
    onError(callback: (error: Error) => void): void;
    onStatusChange(callback: (status: VoiceStatus) => void): void;
    /** Register a callback fired when recording stops and audio is about to be sent */
    onProcessingStart?(callback: () => void): void;
    /**
     * Register a callback for incremental transcript updates during a voice turn.
     * `isFinal=false` is a live interim update (user partials, or assistant deltas
     * on providers that stream them); `isFinal=true` finalizes that role's text.
     * On the realtime `runtype` path, interim updates fire for the `user` only and
     * the `assistant` arrives as a single final.
     */
    onTranscript?(callback: (role: 'user' | 'assistant', text: string, isFinal: boolean) => void): void;
    /** Register a callback for per-turn latency metrics (realtime path). */
    onMetrics?(callback: (metrics: VoiceMetrics) => void): void;
    /** Returns the current interruption mode (only meaningful for Runtype provider) */
    getInterruptionMode?(): "none" | "cancel" | "barge-in";
    /** Returns true if the barge-in mic stream is alive (hot mic between turns) */
    isBargeInActive?(): boolean;
    /** Tear down the barge-in mic pipeline: "hang up" the always-on mic */
    deactivateBargeIn?(): Promise<void>;
    /** Stop playback / cancel in-flight request without starting recording */
    stopPlayback?(): void;
}
/**
 * Extra context for an approval decision, surfaced to `onDecision` and to the
 * `approve`/`deny` callbacks passed to the `renderApproval` plugin hook.
 */
type AgentWidgetApprovalDecisionOptions = {
    /**
     * The user chose a "remember this" affordance (e.g. an "Always allow"
     * button) rather than a one-time decision. The widget resolves the *current*
     * approval identically whether or not this is set: an approval bubble is a
     * single binary gate (`approved`/`denied`). Persisting a don't-ask-again
     * policy for *future* approvals (auto-resolving them, or not surfacing them)
     * is the integrator's responsibility, typically inside `onDecision`.
     * Defaults to absent/`false`.
     */
    remember?: boolean;
};
/**
 * 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;
    /** Box-shadow for the approval bubble; pass `"none"` to remove it. Overrides the default `persona-shadow-sm`. */
    shadow?: 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;
    /**
     * Color for the agent-authored reason line (the agent's per-call
     * justification, shown attributed below the summary when present).
     */
    reasonColor?: string;
    /**
     * Label prefix for the agent-authored reason line.
     * Defaults to "Agent's stated reason:".
     */
    reasonLabel?: string;
    /**
     * How the technical details (the tool's agent-facing description and the
     * raw parameters JSON) are presented:
     * - `"collapsed"` (default): hidden behind a "Show details" toggle
     * - `"expanded"`: visible, with the toggle available to hide them
     * - `"hidden"`: never rendered
     */
    detailsDisplay?: "collapsed" | "expanded" | "hidden";
    /** Label for the toggle that reveals the technical details */
    showDetailsLabel?: string;
    /** Label for the toggle that hides the technical details */
    hideDetailsLabel?: string;
    /**
     * Offer an "Always allow" affordance in the default approval bubble.
     *
     * Default `false`. When `false`, the bubble shows a single "Allow" (allow
     * once) plus "Deny". When `true`, the primary action becomes a split control:
     * "Always allow" (resolves with `{ remember: true }`) with a dropdown for
     * "Allow once", plus "Deny", and keyboard shortcuts (Enter = Always allow,
     * Cmd/Ctrl+Enter = Allow once, Esc = Deny).
     *
     * Keep this off unless your backend actually persists the don't-ask-again
     * policy: "Always allow" only resolves the *current* approval — honoring it
     * for *future* calls is up to your `onDecision` handler (which receives
     * `options.remember`). Showing it without that wiring would mislead users.
     */
    enableAlwaysAllow?: boolean;
    /**
     * Build the user-facing summary line for an approval request. Overrides the
     * default "The assistant wants to use “Tool name”." copy. Return a falsy
     * value to fall back to the default for that approval. `displayTitle` is
     * the display name the tool declared via the WebMCP spec's
     * `ToolDescriptor.title`, when one exists.
     */
    formatDescription?: (approval: {
        toolName: string;
        toolType?: string;
        description: string;
        parameters?: unknown;
        displayTitle?: string;
        /**
         * Agent-authored justification for this specific call, when the agent
         * provided one. It is the agent's own claim: if you fold it into the
         * summary, keep it attributed to the agent.
         */
        reason?: string;
    }) => string | undefined;
    /**
     * Custom handler for approval decisions.
     * Return void to let the SDK auto-resolve via the API,
     * or return a Response/ReadableStream for custom handling.
     *
     * `options.remember` is `true` when the decision came from a "remember this"
     * affordance (e.g. an "Always allow" button in a custom `renderApproval`
     * plugin). Use it to persist a don't-ask-again policy for future approvals;
     * the current approval resolves the same way regardless.
     */
    onDecision?: (data: {
        approvalId: string;
        executionId: string;
        agentId: string;
        toolName: string;
    }, decision: 'approved' | 'denied', options?: AgentWidgetApprovalDecisionOptions) => Promise<Response | ReadableStream<Uint8Array> | void>;
};
type AgentWidgetToolCallConfig = {
    /** Box-shadow for tool-call bubbles; pass `"none"` to remove it. Overrides the `components.toolBubble.shadow` token / `--persona-tool-bubble-shadow`. */
    shadow?: string;
    /** Background color of the tool call bubble container. */
    backgroundColor?: string;
    /** Border color of the tool call bubble container. */
    borderColor?: string;
    /** Border width of the tool call bubble container (CSS value, e.g. `"1px"`). */
    borderWidth?: string;
    /** Border radius of the tool call bubble container (CSS value, e.g. `"12px"`). */
    borderRadius?: string;
    /** Background color of the collapsed header row. */
    headerBackgroundColor?: string;
    /** Text color of the collapsed header row (tool name / summary). */
    headerTextColor?: string;
    /** Horizontal padding of the collapsed header row (CSS value). */
    headerPaddingX?: string;
    /** Vertical padding of the collapsed header row (CSS value). */
    headerPaddingY?: string;
    /** Background color of the expanded content area. */
    contentBackgroundColor?: string;
    /** Text color of the expanded content area. */
    contentTextColor?: string;
    /** Horizontal padding of the expanded content area (CSS value). */
    contentPaddingX?: string;
    /** Vertical padding of the expanded content area (CSS value). */
    contentPaddingY?: string;
    /** Background color of code blocks (arguments / result) in the expanded area. */
    codeBlockBackgroundColor?: string;
    /** Border color of code blocks in the expanded area. */
    codeBlockBorderColor?: string;
    /** Text color of code blocks in the expanded area. */
    codeBlockTextColor?: string;
    /** Color of the expand/collapse toggle icon. */
    toggleTextColor?: string;
    /** Color of section labels ("Arguments", "Result", "Activity") in the expanded area. */
    labelTextColor?: string;
    /**
     * Override the collapsed summary row content for a tool call bubble.
     * Return `null` to fall back to the built-in summary for the active display mode.
     */
    renderCollapsedSummary?: (context: {
        message: AgentWidgetMessage;
        toolCall: AgentWidgetToolCall;
        defaultSummary: string;
        previewText: string;
        collapsedMode: AgentWidgetToolCallCollapsedMode;
        isActive: boolean;
        config: AgentWidgetConfig;
        /** Static elapsed time snapshot, e.g. "2.6s". */
        elapsed: string;
        /**
         * Returns a `<span>` whose text content is automatically updated every
         * 100ms by the widget's global timer. Place it anywhere in your returned
         * HTMLElement to get a live-ticking duration display.
         */
        createElapsedElement: () => HTMLElement;
    }) => HTMLElement | string | null;
    /**
     * Override the lightweight collapsed preview content shown for active tool rows.
     * Return `null` to fall back to the built-in preview text.
     */
    renderCollapsedPreview?: (context: {
        message: AgentWidgetMessage;
        toolCall: AgentWidgetToolCall;
        defaultPreview: string;
        isActive: boolean;
        config: AgentWidgetConfig;
    }) => HTMLElement | string | null;
    /**
     * Override the summary content for grouped consecutive tool-call containers.
     * Return `null` to fall back to the built-in `Called [x] tools` summary.
     */
    renderGroupedSummary?: (context: {
        messages: AgentWidgetMessage[];
        toolCalls: AgentWidgetToolCall[];
        defaultSummary: string;
        config: AgentWidgetConfig;
    }) => HTMLElement | string | null;
    /**
     * Template string for the header text while a tool call is active (running).
     *
     * **Placeholders:** `{toolName}` (tool name), `{duration}` (live-updating elapsed time).
     *
     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: parsed at render time and
     * applied as styled `<span>` elements. Works with all animation modes.
     *
     * When not set, falls back to the current `collapsedMode` behavior.
     * @example "Calling {toolName}... ~{duration}~"
     * @example "**Searching** *{toolName}*..."
     */
    activeTextTemplate?: string;
    /**
     * Template string for the header text when a tool call is complete.
     *
     * **Placeholders:** `{toolName}` (tool name), `{duration}` (final elapsed time).
     *
     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: same syntax as `activeTextTemplate`.
     *
     * When not set, falls back to the existing "Used tool for X seconds" text.
     * @example "Finished {toolName} ~{duration}~"
     */
    completeTextTemplate?: string;
    /**
     * Primary color for shimmer-color animation mode.
     * Defaults to the current text color.
     */
    loadingAnimationColor?: string;
    /**
     * Secondary/end color for shimmer-color animation mode.
     * Creates a gradient sweep between `loadingAnimationColor` and this color.
     * @default "#3b82f6"
     */
    loadingAnimationSecondaryColor?: string;
    /**
     * Duration of one full animation cycle in milliseconds.
     * Applies to pulse, shimmer, shimmer-color, and rainbow modes.
     * @default 2000
     */
    loadingAnimationDuration?: number;
};
type AgentWidgetReasoningConfig = {
    /**
     * Override the collapsed summary row content for a reasoning bubble.
     * Return `null` to fall back to the built-in summary.
     */
    renderCollapsedSummary?: (context: {
        message: AgentWidgetMessage;
        reasoning: AgentWidgetReasoning;
        defaultSummary: string;
        previewText: string;
        isActive: boolean;
        config: AgentWidgetConfig;
        /** Static elapsed time snapshot, e.g. "2.6s". */
        elapsed: string;
        /**
         * Returns a `<span>` whose text content is automatically updated every
         * 100ms by the widget's global timer. Place it anywhere in your returned
         * HTMLElement to get a live-ticking duration display.
         */
        createElapsedElement: () => HTMLElement;
    }) => HTMLElement | string | null;
    /**
     * Override the lightweight collapsed preview content shown for active reasoning rows.
     * Return `null` to fall back to the built-in preview text.
     */
    renderCollapsedPreview?: (context: {
        message: AgentWidgetMessage;
        reasoning: AgentWidgetReasoning;
        defaultPreview: string;
        isActive: boolean;
        config: AgentWidgetConfig;
    }) => HTMLElement | string | null;
    /**
     * Template string for the header text while reasoning is active (streaming).
     *
     * **Placeholders:** `{duration}` (live-updating elapsed time).
     *
     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: parsed at render time.
     *
     * When not set, falls back to the default "Thinking..." text.
     * @example "Thinking... ~{duration}~"
     */
    activeTextTemplate?: string;
    /**
     * Template string for the header text when reasoning is complete.
     *
     * **Placeholders:** `{duration}` (final elapsed time).
     *
     * **Inline formatting:** `~dim~`, `*italic*`, `**bold**`: same syntax as `activeTextTemplate`.
     *
     * When not set, falls back to the default "Thought for X seconds" text.
     * @example "Thought for ~{duration}~"
     */
    completeTextTemplate?: string;
    /**
     * Primary color for shimmer-color animation mode.
     * Defaults to the current text color.
     */
    loadingAnimationColor?: string;
    /**
     * Secondary/end color for shimmer-color animation mode.
     * Creates a gradient sweep between `loadingAnimationColor` and this color.
     * @default "#3b82f6"
     */
    loadingAnimationSecondaryColor?: string;
    /**
     * Duration of one full animation cycle in milliseconds.
     * Applies to pulse, shimmer, shimmer-color, and rainbow modes.
     * @default 2000
     */
    loadingAnimationDuration?: number;
};
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;
    };
};
/**
 * Raw API response from /v1/client/init endpoint
 */
type ClientInitResponse = {
    sessionId: string;
    expiresAt: string;
    flow: {
        id: string;
        name: string;
        description: string | null;
    };
    config: {
        welcomeMessage: string | null;
        placeholder: string;
        theme: Record<string, unknown> | null;
    };
};
/**
 * Request payload for /v1/client/chat endpoint
 */
type ClientChatRequest = {
    sessionId: string;
    messages: Array<{
        id?: string;
        role: 'user' | 'assistant' | 'system';
        content: MessageContent;
    }>;
    /** ID for the expected assistant response message */
    assistantMessageId?: string;
    metadata?: Record<string, unknown>;
    /** Per-turn inputs for Runtype prompt templates (e.g. {{page_url}}). */
    inputs?: Record<string, unknown>;
    context?: Record<string, unknown>;
    /** WebMCP page-discovered tools: same shape as `dispatch.clientTools[]`. */
    clientTools?: ClientToolDefinition[];
    /**
     * Diff-only / send-once: order-independent fingerprint of the client tool set.
     * When the set is unchanged from the previous turn the widget sends this
     * WITHOUT `clientTools` and the server reuses its stored set. On a cache miss
     * the server replies `409 { error: 'client_tools_resend_required' }` and the
     * widget retries once with the full `clientTools[]`.
     */
    clientToolsFingerprint?: string;
    /** Stable client-owned turn ID for stale stream suppression (from Core public OpenAPI). */
    turnId?: RuntypeClientChatRequest['turnId'];
    /** Whether this turn should interrupt a prior in-flight response (from Core public OpenAPI). */
    submitMode?: RuntypeClientChatRequest['submitMode'];
};
/**
 * Feedback types supported by the API
 */
type ClientFeedbackType = RuntypeClientFeedbackRequest['type'];
/**
 * Request payload for /v1/client/feedback endpoint
 */
type ClientFeedbackRequest = {
    sessionId: string;
    /** Required for upvote, downvote, copy feedback types */
    messageId?: string;
    type: ClientFeedbackType;
    /** Required for csat (1-5) and nps (0-10) feedback types */
    rating?: number;
    /** Optional comment for any feedback type */
    comment?: string;
};
/** 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;
    /**
     * Customize the drag-and-drop overlay that appears when files are dragged over the widget.
     */
    dropOverlay?: {
        /** Background color/value of the overlay. @default 'rgba(59, 130, 246, 0.08)' */
        background?: string;
        /** Backdrop blur applied behind the overlay (CSS value). @default '8px' */
        backdropBlur?: string;
        /** Border style shown during drag. @default '2px dashed rgba(59, 130, 246, 0.4)' */
        border?: string;
        /** Border radius of the overlay. @default 'inherit' */
        borderRadius?: string;
        /** Inset/margin pulling the overlay away from the container edges (CSS value). @default '0' */
        inset?: string;
        /** Lucide icon name displayed in the center. @default 'upload' */
        iconName?: string;
        /** Icon size (CSS value). @default '48px' */
        iconSize?: string;
        /** Icon stroke color. @default 'rgba(59, 130, 246, 0.6)' */
        iconColor?: string;
        /** Icon stroke width. @default 0.5 */
        iconStrokeWidth?: number;
        /** Optional label text shown below the icon. */
        label?: string;
        /** Label font size. @default '0.875rem' */
        labelSize?: string;
        /** Label color. @default 'rgba(59, 130, 246, 0.8)' */
        labelColor?: string;
    };
};
/**
 * 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;
    /**
     * Persisted Runtype agent ID to execute.
     *
     * This is the primary Runtype entry point for simple agent-backed widgets.
     * It is mutually exclusive with `flowId` and with inline `agent` configs.
     * Voice and Runtype TTS providers inherit this value unless they specify their
     * own feature-scoped agent ID.
     */
    agentId?: string;
    /**
     * Normalized, backend-neutral routing target. A single string that selects
     * the backend resource to talk to, optimized for portability across
     * frameworks (it is always serializable: no live objects).
     *
     * Shapes:
     * - Runtype TypeID (no prefix): `"agent_…"` / `"flow_…"` route to the
     *   Runtype agent/flow paths (the prefix is self-describing).
     * - Provider-prefixed: `"<provider>:<id>"` is resolved by
     *   `targetProviders[provider]` (e.g. `"eve:support"`). `"runtype:…"` is a
     *   built-in that re-detects a TypeID.
     * - Bare name: `"support"` requires a `targetProviders.default` resolver.
     *
     * Mutually exclusive with `agentId`, `flowId`, and inline `agent`. Prefer
     * `target` for backend-agnostic apps; use `agentId`/`flowId` for the explicit
     * Runtype path.
     *
     * @example
     * ```typescript
     * config: { target: "agent_01k..." }            // Runtype agent
     * config: { target: "flow_01k..." }             // Runtype flow
     * config: {                                       // custom backend
     *   apiUrl: "/api/chat",
     *   target: "eve:support",
     *   targetProviders: { eve: (id) => ({ payload: { assistant: id } }) },
     * }
     * ```
     */
    target?: string;
    /**
     * Prefix-keyed resolvers for `target` strings of the form
     * `"<provider>:<id>"`. Each resolver maps the id to the dispatch-payload
     * fragment its backend expects. Register a `default` resolver to also accept
     * bare (unprefixed, non-TypeID) target names. The built-in `runtype` provider
     * is always available and does not need to be registered.
     */
    targetProviders?: Record<string, TargetResolver>;
    /**
     * Override the assistant-bubble copy shown when a dispatch fails before any
     * response streams back (connection refused, CORS, 4xx/5xx, malformed
     * stream). Provide a static string, or a function of the error so you can
     * tailor the message per failure and decide whether to surface the raw
     * reason. When omitted, a default message is shown that includes the
     * underlying error detail.
     *
     * Returning an empty string suppresses the fallback bubble entirely (the
     * `onError` callback still fires).
     *
     * @example
     * ```typescript
     * config: {
     *   // Static
     *   errorMessage: "We're having trouble connecting. Please try again."
     *   // Or dynamic
     *   errorMessage: (error) =>
     *     error.message.includes("Failed to fetch")
     *       ? "You appear to be offline."
     *       : "Something went wrong. Please try again."
     * }
     * ```
     */
    errorMessage?: string | ((error: Error) => string);
    /**
     * Agent configuration for agent execution mode.
     * When provided, the widget uses agent loop execution instead of flow dispatch.
     * Mutually exclusive with `flowId`.
     *
     * Note: `@runtypelabs/persona-proxy` rejects a client-supplied `agent` (it was
     * an open relay). This option is only for endpoints authorized to accept a
     * client agent — your own backend, or token-scoped direct-to-Runtype dispatch.
     * For the proxy, pin the agent server-side with `agentConfig`/`agentId`.
     *
     * @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;
        /** Button label shown in text mode while a response is streaming. Default: "Stop". */
        stopButtonLabel?: string;
        /**
         * When false, the welcome / intro card is not shown above the message list.
         * @default true
         */
        showWelcomeCard?: boolean;
        /**
         * Per-stop-reason copy for the inline notice rendered on assistant
         * bubbles when the runtime reports a non-natural stop (e.g. the agent
         * loop hit `max_tool_calls` and was cut off mid-loop). Each key is
         * optional: keys you omit fall back to the built-in defaults. Set a
         * key to an empty string to suppress the notice for that reason.
         */
        stopReasonNotice?: Partial<Record<StopReasonKind, string>>;
    };
    /**
     * 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[];
    /**
     * Artifacts to hydrate into the pane at init. Typically populated from
     * `storageAdapter.load()` alongside `initialMessages` so the artifact pane
     * survives a page refresh.
     */
    initialArtifacts?: PersonaArtifactRecord[];
    /**
     * Which artifact id (if any) should be selected in the pane at init. Paired
     * with `initialArtifacts`.
     */
    initialSelectedArtifactId?: string | null;
    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;
    reasoning?: AgentWidgetReasoningConfig;
    /**
     * 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;
    /**
     * WebMCP: consume page-registered tools (`document.modelContext.registerTool`).
     * When `enabled`, the widget installs `@mcp-b/webmcp-polyfill`, snapshots the
     * registry on every dispatch, ships it as `clientTools[]`, and executes
     * returned `webmcp:*` tool calls with confirm-by-default gating.
     *
     * Server-side policy on the chat surface is the source of truth: these
     * fields layer on top.
     *
     * @example
     * ```typescript
     * config: {
     *   webmcp: {
     *     enabled: true,
     *     allowlist: ['search_*', 'list_*'],
     *   }
     * }
     * ```
     */
    webmcp?: AgentWidgetWebMcpConfig;
    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;
    /**
     * Called for every parsed SSE frame (after JSON parse), before native handling.
     * Use for lightweight side effects (e.g. telemetry). Does not replace native
     * streaming; pair with {@link parseSSEEvent} only when you need to override text mapping.
     *
     * When the event stream inspector is enabled, this runs in the same order as
     * events are appended to the inspector buffer.
     */
    onSSEEvent?: (eventType: string, payload: unknown) => void;
    /**
     * 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.
     *
     * Setting this to `false` is the explicit kill-switch: it disables UI-state
     * persistence **and** message-history persistence. When `false`, any
     * `storageAdapter` you configure is ignored and the default localStorage
     * adapter is not created: no chat history is read or written. Pass `true`
     * (or omit) to keep the default behavior of persisting messages via the
     * configured `storageAdapter` (or the built-in localStorage adapter).
     *
     * @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
     *     }
     *   }
     * }
     * ```
     *
     * @example
     * ```typescript
     * // Ephemeral widget: no message history written anywhere
     * config: {
     *   persistState: false
     * }
     * ```
     */
    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[];
    /**
     * Reasoning channel scope (wire spec). `"turn"` is ordinary per-turn
     * thinking; `"loop"` is a cross-iteration agent reflection (the fold that
     * replaced the legacy `agent_reflection` event). Absent for legacy streams.
     */
    scope?: "turn" | "loop";
    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;
    /**
     * Agent-authored justification for this specific call (the agent's own
     * claim about its intent, extracted server-side from the reserved
     * `_approvalReason` parameter). Render it attributed to the agent and as
     * plain text: it is approver context, not a system statement.
     */
    reason?: string;
    parameters?: unknown;
    resolvedAt?: number;
};
type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "approval";
/**
 * Per-turn / per-step stop reason emitted by the runtime on
 * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
 * owned by the upstream Runtype API: do not extend without coordination.
 *
 * - `end_turn`: natural completion (no affordance needed)
 * - `max_tool_calls`: agent loop tripped the configured tool-call ceiling
 * - `length`: provider hit max output tokens
 * - `content_filter`: provider content filter intervened
 * - `error`: provider/runtime error (prefer existing error rendering)
 * - `unknown`: explicitly reported but uninformative
 *
 * Absent (`undefined`) means "not reported": distinct from `'unknown'`.
 */
type StopReasonKind = RuntypeStopReasonKind;
/**
 * Represents a message in the chat conversation.
 *
 * @property id - Unique message identifier
 * @property role - Message role: "user", "assistant", or "system"
 * @property content - Message text content (for display)
 * @property contentParts - Original multi-modal content parts (for API requests)
 * @property createdAt - ISO timestamp when message was created
 * @property streaming - Whether message is still streaming (for assistant messages)
 * @property variant - Message variant for assistant messages: "assistant", "reasoning", or "tool"
 * @property sequence - Message ordering number
 * @property reasoning - Reasoning data for assistant reasoning messages
 * @property toolCall - Tool call data for assistant tool messages
 * @property tools - Array of tool calls
 * @property viaVoice - Set to `true` when a user message is sent via voice recognition.
 *                      Useful for implementing voice-specific behaviors like auto-reactivation.
 */
type AgentWidgetMessage = {
    id: string;
    role: AgentWidgetMessageRole;
    content: string;
    createdAt: string;
    /**
     * Original multi-modal content parts for this message.
     * When present, this is sent to the API instead of `content`.
     * The `content` field contains the text-only representation for display.
     */
    contentParts?: ContentPart[];
    streaming?: boolean;
    variant?: AgentWidgetMessageVariant;
    sequence?: number;
    reasoning?: AgentWidgetReasoning;
    toolCall?: AgentWidgetToolCall;
    tools?: AgentWidgetToolCall[];
    /** Approval data for messages with variant "approval" */
    approval?: AgentWidgetApproval;
    viaVoice?: boolean;
    /**
     * Set to `true` on placeholder messages injected during Runtype voice processing.
     * Use this in `messageTransform` to detect and customize voice processing placeholders.
     *
     * @example
     * messageTransform: ({ text, message }) => {
     *   if (message.voiceProcessing && message.role === 'user') {
     *     return '<div class="my-voice-spinner">Transcribing...</div>';
     *   }
     *   return text;
     * }
     */
    voiceProcessing?: boolean;
    /**
     * Raw structured payload for this message (e.g., JSON action response).
     * Populated automatically when structured parsers run.
     */
    rawContent?: string;
    /**
     * LLM-specific content for API requests.
     * When present, this is sent to the LLM instead of `content`.
     *
     * Priority for API payload:
     * 1. `contentParts` (if present, used as-is for multi-modal)
     * 2. `llmContent` (if present, sent as string)
     * 3. `rawContent` (backward compatibility with structured parsers)
     * 4. `content` (fallback - display content)
     *
     * The `content` field is always used for UI display.
     *
     * @example
     * // Show full details to user, send summary to LLM
     * {
     *   content: "**Product:** iPhone 15 Pro\n**Price:** $1,199\n**SKU:** IP15P-256",
     *   llmContent: "[Product search: iPhone 15 Pro, $1199]"
     * }
     */
    llmContent?: string;
    /**
     * Text segment identity for chronological ordering.
     * When present, identifies which text segment this message represents
     * (e.g., "text_0", "text_1") for messages split at tool boundaries.
     */
    partId?: string;
    /**
     * Metadata for messages created during agent loop execution.
     * Contains execution context like iteration number and turn ID.
     */
    agentMetadata?: AgentMessageMetadata;
    /**
     * Per-turn stop reason reported by the runtime on `agent_turn_complete`
     * (agent-loop path) or the last `step_complete` for a prompt step
     * (dispatch / flow path). Absent when the API did not report a value.
     *
     * When set to a non-natural value (`max_tool_calls`, `length`,
     * `content_filter`, `error`), the widget renders an inline notice on
     * the assistant bubble. See `config.copy.stopReasonNotice` to override
     * the default copy.
     */
    stopReason?: StopReasonKind;
};
/**
 * 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;
    /**
     * Raw structured payload (typically a JSON string) representing the
     * full directive that produced this message: e.g. `{ "text": "...",
     * "component": "Foo", "props": {...} }`.
     *
     * Mirrors the field populated by stream parsers during normal LLM
     * responses. Set this when injecting a message that should render as a
     * component directive (`hasComponentDirective` /
     * `extractComponentDirectiveFromMessage` look at `rawContent` first).
     *
     * Priority for the API payload remains:
     * `contentParts > llmContent > rawContent > content`. Pass `llmContent`
     * alongside `rawContent` if the LLM should see something other than the
     * raw directive.
     */
    rawContent?: string;
};
/**
 * 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">;
/**
 * Options for injecting an assistant message that renders as a component
 * directive: sugar over `injectAssistantMessage` for the common case of
 * "render this registered component, same as if the LLM had emitted it".
 *
 * Equivalent to calling `injectAssistantMessage({ content: text, rawContent:
 * JSON.stringify({ text, component, props }), llmContent })`.
 *
 * @example
 * widget.injectComponentDirective({
 *   component: "DynamicForm",
 *   props: { title: "Book a demo", fields: [...] },
 *   text: "Share your details to book a demo.",
 *   llmContent: "[Showed booking form]"
 * });
 */
type InjectComponentDirectiveOptions = {
    /**
     * Name of a renderer registered via `componentRegistry.register(...)`.
     */
    component: string;
    /**
     * Props passed to the component renderer.
     */
    props?: Record<string, unknown>;
    /**
     * Bubble copy displayed above (or with) the rendered component.
     * Mirrors the `text` field in a streamed JSON directive.
     * @default ""
     */
    text?: string;
    /**
     * Content sent to the LLM in API requests. When omitted, the raw
     * directive JSON is what the LLM would see (per the standard
     * priority chain). Provide a redacted/short version to avoid sending
     * the full directive in subsequent turns.
     */
    llmContent?: string;
    /**
     * Optional message ID. If omitted, an assistant id is auto-generated.
     */
    id?: string;
    /**
     * Optional creation timestamp (ISO string). If omitted, uses current time.
     */
    createdAt?: string;
    /**
     * Optional sequence number for ordering.
     */
    sequence?: number;
};
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;
};
type AgentWidgetInitOptions = {
    target: string | HTMLElement;
    config?: AgentWidgetConfig;
    useShadowDom?: boolean;
    /** Fired when the widget controller is mounted and its API is callable. */
    onChatReady?: () => void;
    windowKey?: string;
    debugTools?: boolean;
};

type DispatchOptions = {
    messages: AgentWidgetMessage[];
    signal?: AbortSignal;
    /** Pre-generated ID for the expected assistant response (for feedback tracking) */
    assistantMessageId?: string;
};
type SSEHandler = (event: AgentWidgetEvent) => void;
type SSEEventCallback = (eventType: string, payload: unknown) => void;
declare class AgentWidgetClient {
    private config;
    private readonly apiUrl;
    private readonly headers;
    private readonly debug;
    private readonly createStreamParser;
    private readonly contextProviders;
    private readonly requestMiddleware?;
    private readonly customFetch?;
    private readonly parseSSEEvent?;
    private readonly getHeaders?;
    private onSSEEvent?;
    private clientSession;
    private sessionInitPromise;
    private lastSentClientToolsFingerprint;
    private clientToolsFingerprintSessionId;
    private readonly webMcpBridge;
    constructor(config?: AgentWidgetConfig);
    /**
     * Refresh config in place WITHOUT tearing down the live connection or the
     * WebMCP bridge. `AgentWidgetSession.updateConfig` calls this when only
     * connection-irrelevant fields changed (theme, copy, layout, suggestions, …),
     * so a UI update that lands mid-turn: e.g. a `webmcp:*` tool restyling the
     * widget while the agent's turn is still streaming: doesn't abandon the
     * in-flight stream/resume. Connection or request-shaping changes (apiUrl,
     * clientToken, webmcp, headers, parser, …) take the full client rebuild path
     * in the session instead, which is the only place the bridge is recreated.
     *
     * Only the live-read `config` is refreshed (e.g. `iterationDisplay`); the
     * constructor-derived request-shaping fields (apiUrl, headers, parser,
     * contextProviders, middleware, …) are left untouched because the session
     * routes any change to those down the full-rebuild path instead, so they are
     * guaranteed unchanged here. The `webMcpBridge` instance and its
     * installed-polyfill memo are deliberately preserved, which keeps any
     * in-flight resolve alive.
     */
    updateConfig(next: AgentWidgetConfig): void;
    /**
     * Set callback for capturing raw SSE events
     */
    setSSEEventCallback(callback: SSEEventCallback): void;
    /**
     * WebMCP: wire (or replace) the confirm-bubble handler. Called from
     * `ui.ts` once the widget panel is built and the approval-bubble
     * chrome is ready to render.
     */
    setWebMcpConfirmHandler(handler: WebMcpConfirmHandler | null): void;
    /**
     * WebMCP: `true` when the bridge installed the polyfill and can both
     * snapshot the page registry and execute returned `webmcp:*` tool calls.
     * `false` for any guard miss (no `document.modelContext`, polyfill not yet
     * installed, or `config.webmcp.enabled` not set).
     */
    isWebMcpOperational(): boolean;
    /**
     * WebMCP: execute a returned `webmcp:<name>` tool call against the page's
     * registry and return the normalized MCP-shaped result for `/resume`. The
     * bridge handles confirm-bubble gating, the 30s timeout, error
     * normalization, and `signal`-driven abort: callers never see throws.
     *
     * Returns `null` when WebMCP is not enabled on this client (signal to the
     * session that it should fall back to the legacy local-tool resume path,
     * if any).
     */
    executeWebMcpToolCall(wireToolName: string, args: unknown, signal?: AbortSignal): Promise<WebMcpToolResult> | null;
    /**
     * Get the current SSE event callback (used to preserve across client recreation)
     */
    getSSEEventCallback(): SSEEventCallback | undefined;
    /**
     * Check if running in client token mode
     */
    isClientTokenMode(): boolean;
    /**
     * Resolve the effective backend routing for the current config. Combines the
     * explicit `agentId`/`flowId` fields with the normalized `target` string
     * (resolved via `resolveTarget`). Computed on demand so it stays correct
     * across `update()`; the `target`/explicit-field conflict is rejected in the
     * constructor, so at most one source is set here.
     */
    private routing;
    /**
     * Check if operating in agent execution mode
     */
    isAgentMode(): boolean;
    /**
     * Get the appropriate API URL based on mode
     */
    private getClientApiUrl;
    /**
     * Get the current client session (if any)
     */
    getClientSession(): ClientSession | null;
    /**
     * Initialize session for client token mode.
     * Called automatically on first message if not already initialized.
     */
    initSession(): Promise<ClientSession>;
    private _doInitSession;
    /**
     * Clear the current client session
     */
    clearClientSession(): void;
    /**
     * Forget the diff-only WebMCP tool fingerprint so the next client-token turn
     * resends the full `clientTools[]`. Called when the session is cleared and
     * when the conversation is reset (`WidgetSession.clearMessages`).
     */
    resetClientToolsFingerprint(): void;
    /**
     * Get the feedback API URL
     */
    private getFeedbackApiUrl;
    /**
     * Send feedback for a message (client token mode only).
     * Supports upvote, downvote, copy, csat, and nps feedback types.
     *
     * @param feedback - The feedback request payload
     * @returns Promise that resolves when feedback is sent successfully
     * @throws Error if not in client token mode or if session is invalid
     *
     * @example
     * ```typescript
     * // Message feedback (upvote/downvote/copy)
     * await client.sendFeedback({
     *   sessionId: sessionId,
     *   messageId: messageId,
     *   type: 'upvote'
     * });
     *
     * // CSAT feedback (1-5 rating)
     * await client.sendFeedback({
     *   sessionId: sessionId,
     *   type: 'csat',
     *   rating: 5,
     *   comment: 'Great experience!'
     * });
     *
     * // NPS feedback (0-10 rating)
     * await client.sendFeedback({
     *   sessionId: sessionId,
     *   type: 'nps',
     *   rating: 9
     * });
     * ```
     */
    sendFeedback(feedback: ClientFeedbackRequest): Promise<void>;
    /**
     * Submit message feedback (upvote, downvote, or copy).
     * Convenience method for sendFeedback with message-level feedback.
     *
     * @param messageId - The ID of the message to provide feedback for
     * @param type - The feedback type: 'upvote', 'downvote', or 'copy'
     */
    submitMessageFeedback(messageId: string, type: 'upvote' | 'downvote' | 'copy'): Promise<void>;
    /**
     * Submit CSAT (Customer Satisfaction) feedback.
     * Convenience method for sendFeedback with CSAT feedback.
     *
     * @param rating - Rating from 1 to 5
     * @param comment - Optional comment
     */
    submitCSATFeedback(rating: number, comment?: string): Promise<void>;
    /**
     * Submit NPS (Net Promoter Score) feedback.
     * Convenience method for sendFeedback with NPS feedback.
     *
     * @param rating - Rating from 0 to 10
     * @param comment - Optional comment
     */
    submitNPSFeedback(rating: number, comment?: string): Promise<void>;
    /**
     * Send a message - handles both proxy and client token modes
     */
    dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
    /**
     * Client token mode dispatch
     */
    private dispatchClientToken;
    /**
     * Proxy mode dispatch (original implementation)
     */
    private dispatchProxy;
    /**
     * Agent mode dispatch
     */
    private dispatchAgent;
    /**
     * Process an external SSE stream through the SDK's event pipeline.
     * This allows piping responses from endpoints like agent approval
     * through the same message/tool/reasoning handling as dispatch().
     */
    processStream(body: ReadableStream<Uint8Array>, onEvent: SSEHandler, assistantMessageId?: string): Promise<void>;
    /**
     * Send an approval decision to the API and return the response
     * for streaming continuation.
     */
    resolveApproval(approval: {
        agentId: string;
        executionId: string;
        approvalId: string;
    }, decision: 'approved' | 'denied'): Promise<Response>;
    /**
     * Resume a paused flow execution by supplying outputs for LOCAL
     * (client-executed) tools. Used by the built-in `ask_user_question`
     * answer-pill sheet, but generic enough for any LOCAL tool.
     *
     * Routes by mode:
     *  - **client-token mode**: POST `${apiBase}/v1/client/resume` (the
     *    session-authenticated sibling of `/v1/client/chat`; runtypelabs/core#3889),
     *    with the active `sessionId` in the body and no Bearer key: a browser
     *    client-token page holds no secret. `clientTools` are already persisted
     *    server-side from the dispatch turn, so only `toolOutputs` is re-sent.
     *  - **dispatch / proxy mode**: POST `${apiUrl}/resume`: Runtype mounts
     *    resume as a child of `/v1/dispatch`, so the URL is `${apiUrl}/resume`,
     *    and proxies follow the same shape (`/api/chat/dispatch/resume`).
     *
     * Returns the raw Response so the caller can pipe its SSE body through
     * `connectStream()`.
     *
     * @param executionId - The paused execution id carried on `step_await`.
     * @param toolOutputs - Map keyed by per-call `toolCallId` (core#3878),
     *   falling back to tool name for legacy servers → the tool's result value.
     */
    resumeFlow(executionId: string, toolOutputs: Record<string, unknown>, options?: {
        streamResponse?: boolean;
        signal?: AbortSignal;
    }): Promise<Response>;
    private buildAgentPayload;
    private buildPayload;
    /**
     * Handle custom SSE event parsing via parseSSEEvent callback
     * Returns true if event was handled, false otherwise
     */
    private handleCustomSSEEvent;
    private streamResponse;
}

declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;

/**
 * Pick the best available English voice from the browser's voice list.
 * Prefers high-quality remote/natural voices, then enhanced local voices,
 * then standard local voices, then any English voice, then the first voice.
 */
declare function pickBestVoice(voices: SpeechSynthesisVoice[]): SpeechSynthesisVoice;
interface BrowserSpeechEngineOptions {
    /** Custom voice picker, used when no exact `voice` name is requested. */
    pickVoice?: (voices: SpeechSynthesisVoice[]) => SpeechSynthesisVoice;
}
/** Default `SpeechEngine` backed by the browser Web Speech API. */
declare class BrowserSpeechEngine implements SpeechEngine {
    private options;
    readonly id = "browser";
    readonly supportsPause = true;
    constructor(options?: BrowserSpeechEngineOptions);
    /** Whether the Web Speech API is available in this environment. */
    static isSupported(): boolean;
    speak(request: SpeechRequest, callbacks: SpeechCallbacks): void;
    pause(): void;
    resume(): void;
    stop(): void;
}

interface FallbackSpeechEngineOptions {
    /**
     * Called once when the primary engine fails before audio starts and the
     * fallback takes over — so a silent downgrade is still observable in dev/
     * telemetry even though the user keeps hearing speech.
     */
    onFallback?: (error: Error) => void;
}

type ReadAloudListener = (activeId: string | null, state: ReadAloudState) => void;
declare class ReadAloudController {
    private resolveEngine;
    private engine;
    private activeId;
    private state;
    private listeners;
    private generation;
    constructor(resolveEngine: () => SpeechEngine | Promise<SpeechEngine> | null);
    /** Whether the active engine supports pause/resume (vs. stop-only). */
    get supportsPause(): boolean;
    /** Playback state for a message id (`idle` unless it's the active message). */
    stateFor(id: string): ReadAloudState;
    /** The message currently being read aloud, if any. */
    activeMessageId(): string | null;
    /** Subscribe to state changes. Returns an unsubscribe function. */
    onChange(listener: ReadAloudListener): () => void;
    /**
     * Primary entry point for the button: cycle this message through
     * play → pause → resume (or play → stop when the engine can't pause), and
     * start fresh when a different message is requested.
     */
    toggle(id: string, request: SpeechRequest): void;
    /** Start (or restart) playback for a message, stopping any current playback. */
    play(id: string, request: SpeechRequest): Promise<void>;
    /** Stop playback and return to idle. */
    stop(): void;
    /** Drop the controller and its engine (called on widget teardown). */
    destroy(): void;
    private set;
}

type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error";
type SessionCallbacks = {
    onMessagesChanged: (messages: AgentWidgetMessage[]) => void;
    onStatusChanged: (status: AgentWidgetSessionStatus) => void;
    onStreamingChanged: (streaming: boolean) => void;
    onError?: (error: Error) => void;
    onVoiceStatusChanged?: (status: VoiceStatus) => void;
    onArtifactsState?: (state: {
        artifacts: PersonaArtifactRecord[];
        selectedId: string | null;
    }) => void;
};
declare class AgentWidgetSession {
    private config;
    private callbacks;
    private client;
    private messages;
    private status;
    private streaming;
    private abortController;
    private sequenceCounter;
    private clientSession;
    private agentExecution;
    private artifacts;
    private selectedArtifactId;
    private webMcpInflightKeys;
    private webMcpResolvedKeys;
    private webMcpResolveControllers;
    private webMcpEpoch;
    private webMcpApprovalResolvers;
    private webMcpApprovalSeq;
    private webMcpAwaitBatches;
    private voiceProvider;
    private voiceActive;
    private voiceStatus;
    constructor(config: AgentWidgetConfig | undefined, callbacks: SessionCallbacks);
    /**
     * Warm the deferred Runtype TTS engine chunk at init so it's resolved before
     * the first "Read aloud" click. Module fetch only — no AudioContext (that
     * still waits for the user gesture on first playback). In the IIFE/CDN build
     * this fetches the standalone `runtype-tts.js`; in bundler builds the module
     * is already inlined, so this is a cheap no-op. Errors are swallowed: a failed
     * prefetch just means the chunk loads on first click instead (or, on a hard
     * failure, the browser-voice fallback kicks in).
     */
    private prefetchRuntypeTts;
    /**
     * Set callback for capturing raw SSE events (forwards to client)
     */
    setSSEEventCallback(callback: SSEEventCallback): void;
    /**
     * Check if running in client token mode
     */
    isClientTokenMode(): boolean;
    /**
     * Check if running in agent execution mode
     */
    isAgentMode(): boolean;
    /**
     * Get current agent execution state (if in agent mode)
     */
    getAgentExecution(): AgentExecutionState | null;
    /**
     * Check if an agent execution is currently running
     */
    isAgentExecuting(): boolean;
    /**
     * Check if voice is supported
     */
    isVoiceSupported(): boolean;
    /**
     * Check if voice is currently active
     */
    isVoiceActive(): boolean;
    /**
     * Get current voice status
     */
    getVoiceStatus(): VoiceStatus;
    /**
     * Get the voice interruption mode from the provider (none/cancel/barge-in)
     */
    getVoiceInterruptionMode(): "none" | "cancel" | "barge-in";
    /**
     * Stop voice playback / cancel in-flight request without starting recording.
     * Returns to idle state.
     */
    stopVoicePlayback(): void;
    /** Returns true if the barge-in mic stream is alive (hot mic between turns) */
    isBargeInActive(): boolean;
    /** Tear down the barge-in mic pipeline: "hang up" the always-on mic */
    deactivateBargeIn(): Promise<void>;
    private pendingVoiceUserMessageId;
    private pendingVoiceAssistantMessageId;
    private ttsSpokenMessageIds;
    private readAloud;
    /**
     * Resolve the speech engine behind read-aloud (and auto-speak):
     *   1. An explicit `textToSpeech.createEngine` always wins (full BYO control).
     *   2. `provider: 'runtype'` builds the hosted {@link RuntypeSpeechEngine}
     *      from the widget config (host = `apiUrl`, `agentId`, `clientToken`),
     *      wrapped in a browser {@link FallbackSpeechEngine} unless
     *      `browserFallback: false` — so a missing endpoint or transient failure
     *      degrades to the browser voice instead of erroring, and auto-upgrades to
     *      Runtype voices the day the endpoint ships.
     *   3. Otherwise the browser Web Speech API engine.
     */
    private createSpeechEngine;
    /**
     * Setup voice recognition with the given configuration
     */
    setupVoice(config?: VoiceConfig): void;
    /**
     * Toggle voice recognition on/off
     */
    toggleVoice(): Promise<void>;
    /**
     * Cleanup voice resources
     */
    cleanupVoice(): void;
    /**
     * Extract voice configuration from widget config
     */
    private getVoiceConfigFromConfig;
    /**
     * Initialize the client session (for client token mode).
     * This is called automatically on first message, but can be called
     * explicitly to pre-initialize the session and get config from server.
     */
    initClientSession(): Promise<ClientSession | null>;
    /**
     * Set the client session after initialization
     */
    setClientSession(session: ClientSession): void;
    /**
     * Get current client session
     */
    getClientSession(): ClientSession | null;
    /**
     * Check if session is valid and not expired
     */
    isSessionValid(): boolean;
    /**
     * Clear session (on expiry or error)
     */
    clearClientSession(): void;
    /**
     * Get the underlying client instance (for advanced use cases like feedback)
     */
    getClient(): AgentWidgetClient;
    /**
     * Submit message feedback (upvote, downvote, or copy) to the API.
     * Only available in client token mode.
     *
     * @param messageId - The ID of the message to provide feedback for
     * @param type - The feedback type: 'upvote', 'downvote', or 'copy'
     */
    submitMessageFeedback(messageId: string, type: 'upvote' | 'downvote' | 'copy'): Promise<void>;
    /**
     * Submit CSAT (Customer Satisfaction) feedback to the API.
     * Only available in client token mode.
     *
     * @param rating - Rating from 1 to 5
     * @param comment - Optional comment
     */
    submitCSATFeedback(rating: number, comment?: string): Promise<void>;
    /**
     * Submit NPS (Net Promoter Score) feedback to the API.
     * Only available in client token mode.
     *
     * @param rating - Rating from 0 to 10
     * @param comment - Optional comment
     */
    submitNPSFeedback(rating: number, comment?: string): Promise<void>;
    updateConfig(next: AgentWidgetConfig): void;
    getMessages(): AgentWidgetMessage[];
    getStatus(): AgentWidgetSessionStatus;
    isStreaming(): boolean;
    /**
     * @deprecated Use injectMessage() instead.
     * Injects a raw event into the session event handler.
     */
    injectTestEvent(event: AgentWidgetEvent): void;
    /**
     * Inject a message into the conversation.
     * This is the primary API for adding messages programmatically.
     *
     * Supports dual-content where the displayed content differs from what the LLM receives.
     *
     * @param options - Message injection options including dual-content support
     * @returns The created message object
     *
     * @example
     * // Same content for user and LLM
     * session.injectMessage({
     *   role: 'assistant',
     *   content: 'Here are the search results...'
     * });
     *
     * @example
     * // Different content for user and LLM (redaction)
     * session.injectMessage({
     *   role: 'assistant',
     *   content: '**Found 3 products:**\n- iPhone 15 Pro ($1,199)\n- iPhone 15 ($999)',
     *   llmContent: '[Search results: 3 iPhone products, $799-$1199]'
     * });
     */
    injectMessage(options: InjectMessageOptions): AgentWidgetMessage;
    /**
     * Convenience method for injecting assistant messages.
     * Role defaults to 'assistant'.
     *
     * @example
     * // Simple assistant message
     * session.injectAssistantMessage({
     *   content: 'Here are your search results...'
     * });
     *
     * @example
     * // With redacted LLM content
     * session.injectAssistantMessage({
     *   content: 'Full product details for the user...',
     *   llmContent: '[Product details summary]'
     * });
     */
    injectAssistantMessage(options: InjectAssistantMessageOptions): AgentWidgetMessage;
    /**
     * Convenience method for injecting user messages.
     * Role defaults to 'user'.
     *
     * @example
     * session.injectUserMessage({
     *   content: 'Add iPhone 15 Pro to my cart'
     * });
     */
    injectUserMessage(options: InjectUserMessageOptions): AgentWidgetMessage;
    /**
     * Convenience method for injecting system messages.
     * Role defaults to 'system'.
     *
     * @example
     * // Inject context that guides LLM behavior
     * session.injectSystemMessage({
     *   content: '[Context updated]',  // Minimal display
     *   llmContent: 'User is viewing iPhone 15 Pro. Cart has 2 items.'
     * });
     */
    injectSystemMessage(options: InjectSystemMessageOptions): AgentWidgetMessage;
    /**
     * Inject multiple messages in a single batch with one sort and one render pass.
     */
    injectMessageBatch(optionsList: InjectMessageOptions[]): AgentWidgetMessage[];
    /**
     * Convenience method for injecting a registered component directive as
     * an assistant message: the same shape Persona produces from a streamed
     * `{ "text": "...", "component": "...", "props": {...} }` payload.
     *
     * Sets `content` to `text`, `rawContent` to the JSON directive (so
     * `extractComponentDirectiveFromMessage` can find it), and forwards
     * `llmContent` / `id` / `createdAt` / `sequence`.
     *
     * @example
     * session.injectComponentDirective({
     *   component: "DynamicForm",
     *   props: { title: "Book a demo", fields: [...] },
     *   text: "Share your details to book a demo.",
     *   llmContent: "[Showed booking form]"
     * });
     */
    injectComponentDirective(options: InjectComponentDirectiveOptions): AgentWidgetMessage;
    sendMessage(rawInput: string, options?: {
        viaVoice?: boolean;
        /** Multi-modal content parts (e.g., images) to include with the message */
        contentParts?: ContentPart[];
    }): Promise<void>;
    /**
     * Continue the conversation without adding a new user message.
     * Triggers the model to respond based on the current conversation state.
     *
     * Use this for automatic continuation after action handlers inject data
     * (e.g., search results) that the model should analyze.
     *
     * @example
     * // After injecting search results, trigger model to analyze them
     * session.injectAssistantMessage({ content: 'Found 5 products...' });
     * session.continueConversation();
     */
    continueConversation(): Promise<void>;
    /**
     * Connect an external SSE stream (e.g. from an approval endpoint) and
     * process it through the SDK's native event pipeline.
     */
    connectStream(stream: ReadableStream<Uint8Array>, options?: {
        assistantMessageId?: string;
        allowReentry?: boolean;
    }): Promise<void>;
    /**
     * Install the native approval-bubble confirm handler on the WebMCP bridge
     * when the integrator hasn't supplied a custom `webmcp.onConfirm`. Without
     * this, the bridge falls back to a blunt `window.confirm`. Safe to call
     * repeatedly (e.g. after the client is re-created in `updateConfig`).
     */
    private wireDefaultWebMcpConfirm;
    /**
     * Default WebMCP confirm gate: render Persona's native in-panel approval
     * bubble and resolve when the user clicks Approve/Deny. Returns immediately
     * with `true` when `webmcp.autoApprove(info)` opts the tool out of the gate
     * (e.g. a read-only catalog search), so no bubble is shown. The bridge
     * awaits this Promise before executing the page tool.
     */
    requestWebMcpApproval(info: WebMcpConfirmInfo): Promise<boolean>;
    /**
     * Resolve a pending WebMCP approval bubble (from the Approve/Deny click in
     * `ui.ts`). Updates the bubble to its resolved state and unblocks the
     * bridge Promise parked in `requestWebMcpApproval`. No-op if already
     * resolved (double-click, re-render).
     */
    resolveWebMcpApproval(approvalMessageId: string, decision: "approved" | "denied"): void;
    /**
     * Resolve a tool approval request (approve or deny).
     * Updates the approval message status, calls the API (or custom onDecision),
     * and pipes the response stream through connectStream().
     */
    resolveApproval(approval: AgentWidgetApproval, decision: 'approved' | 'denied', options?: AgentWidgetApprovalDecisionOptions): Promise<void>;
    /**
     * Resolve a paused `ask_user_question` LOCAL tool call.
     *
     * When the server emits `step_await` for `ask_user_question`, the widget
     * renders the answer-pill sheet and calls this method once the user
     * picks. Steps:
     *   1. POST the answer to `/resume` via `client.resumeFlow`.
     *   2. Pipe the resulting SSE stream through `connectStream()` so the
     *      paused agent execution continues.
     *   3. Append a user-visible bubble with the answer text so the
     *      transcript reads naturally.
     */
    /**
     * Persist in-progress answers and the current page index for a multi-question
     * `ask_user_question` payload, so a refresh resumes on the same page with
     * prior answers intact. Called by ui.ts on every Back/Next/pick interaction.
     */
    persistAskUserQuestionProgress(toolMessage: AgentWidgetMessage, progress: {
        answers: Record<string, string | string[]>;
        currentIndex: number;
    }): void;
    /**
     * Flip an `ask_user_question` tool message from awaiting → answered so
     * render passes stop re-mounting its answer-pill sheet. Idempotent.
     * When `answers` is provided, persists the full structured answer Record
     * atomically with the answered flag: guarding against later events that
     * could re-emit the tool message and clobber the per-pick persisted
     * answers via top-level merge.
     */
    markAskUserQuestionResolved(toolMessage: AgentWidgetMessage, answers?: Record<string, string | string[]>): void;
    resolveAskUserQuestion(toolMessage: AgentWidgetMessage, answer: string | Record<string, string | string[]>): Promise<void>;
    /**
     * Collect an auto-resolving LOCAL-tool `step_await` (`webmcp:*` page tools
     * and the built-in `suggest_replies`) into a per-executionId batch
     * and schedule a single deferred flush. Parallel calls (core#3878) emit
     * several `step_await`s for ONE paused execution within the same stream tick;
     * buffering them and flushing once lets us post ONE `/resume` keyed by the
     * per-call `webMcpToolCallId` rather than racing N name-keyed resumes on the
     * same execution (which 404'd on the second and hung the turn).
     *
     * Deferred via `queueMicrotask` (epoch-guarded) for the same reason the old
     * direct resolve was: handleEvent must return first so the dispatch's
     * `connectStream` sees end-of-stream and releases the shared abortController
     * before a resolve grabs it.
     *
     * Awaits without an `executionId` or `toolCall.id` can't be batched (no key)
     *: route them straight to the single-call path, which surfaces the malformed
     * wire shape via `onError` / an `isError` resume.
     */
    private enqueueWebMcpAwait;
    /**
     * Flush every buffered local-tool await batch, one `/resume` per executionId.
     * Called once a stream ends (`status: idle` / `error`): by then all parallel
     * `step_await`s the stream carried have been collected, even if split across
     * SSE chunks. Deferred via `queueMicrotask` (epoch-guarded) so the idle
     * handler returns first and the stream's end-of-stream teardown (streaming /
     * abortController) settles before a resolve grabs them: the same ordering the
     * single-call resolve always relied on.
     */
    private scheduleWebMcpBatchFlush;
    /**
     * Run a buffered batch of local-tool awaits for one executionId. Size 1
     * (single call, or distinct-tool turns that happened to arrive alone) takes
     * the original single-call path; size >1 (parallel calls) takes the batched
     * path that posts ONE `/resume`. The batch is removed from the map up front
     * so any later sibling re-emit (e.g. from a re-pause) forms a fresh batch
     * rather than mutating one already in flight.
     */
    private flushWebMcpAwaitBatch;
    private resolveWebMcpToolStartedAt;
    /**
     * Persisted-resolution guard for `suggest_replies`. The in-memory dedupe
     * sets (`webMcpInflightKeys` / `webMcpResolvedKeys`) are cleared by
     * hydrateMessages/clearMessages/cancel, but `suggestRepliesResolved`
     * survives on the stored message, so a stale `step_await` re-emit after a
     * hydration must not re-POST `/resume` for an already-resolved call (the
     * historical double-resume failure mode the batching work exists to avoid).
     * Checks the LIVE message first; the handleEvent snapshot is a fresh wire
     * skeleton whose metadata never carries the flag.
     */
    private isSuggestRepliesAlreadyResolved;
    private markWebMcpToolRunning;
    private markWebMcpToolComplete;
    /**
     * Resolve TWO OR MORE parallel local-tool awaits sharing one paused
     * executionId with a SINGLE `/resume` (core#3878). Each call is executed
     * against the page registry concurrently: every gated call renders its own
     * native approval bubble, and a sibling's confirm Promise never blocks
     * another's execution. Outputs are keyed by per-call `webMcpToolCallId`
     * (server prefers it over tool name; name-keying remains the fallback for
     * legacy single/distinct-tool turns), so two calls to the SAME tool no longer
     * collide. The server is tolerant: any call we omit (declined-after-abort,
     * dedupe, exec failure) simply re-pauses and is retried on its re-emit.
     *
     * Mirrors `resolveWebMcpToolCall`'s dedupe / abort / streaming machinery, but
     * shares one resume POST and marks every resolved key on that POST's HTTP OK.
     */
    private resolveWebMcpToolCallBatch;
    /**
     * Resolve a paused auto-resolving LOCAL tool call and post the result to
     * `/resume`: `webmcp:*` calls execute against the host page's tool
     * registry; the built-in `suggest_replies` skips execution entirely and
     * resumes with a canned "shown" result (the chips render from the message
     * list, not from this resolve).
     *
     * Triggered automatically from `handleEvent` when a `step_await`-derived
     * message arrives for such a tool: the user does not click a pill; the
     * bridge's confirm-bubble gate (WebMCP only) is the only interactive
     * surface.
     *
     * Idempotent on the message's `toolCall.id`: re-emits of the same step_await
     * (e.g. from message coalescing) won't double-fire `tool.execute`. Failure
     * modes, declined, timed out, throw, unknown tool, all resolve into a
     * `{ isError: true, content: [...] }` payload that resumes the dispatch
     * cleanly so the agent can recover.
     */
    resolveWebMcpToolCall(toolMessage: AgentWidgetMessage): Promise<void>;
    /**
     * POST `/resume` with a SINGLE tool's output and pipe the resulting SSE
     * stream back through `connectStream`. Shared by every single-call local-tool
     * resolve path (ask_user_question and single WebMCP calls). Parallel WebMCP
     * calls use `resolveWebMcpToolCallBatch`, which posts one resume for many.
     *
     * `resumeKey` is the `toolOutputs` map key: the per-call `webMcpToolCallId`
     * for WebMCP (core#3878), or the tool name for ask_user_question / legacy
     * servers. `onHttpOk` runs synchronously between the HTTP-status check and the
     * stream pipe; it lets the WebMCP resolve path commit the dedupe flag at
     * "server accepted the answer" rather than "stream finished cleanly".
     */
    private resumeWithToolOutput;
    /**
     * Tear down every in-flight WebMCP resolve and advance the epoch. Each
     * resolve owns a dedicated AbortController (chained/parallel resolves don't
     * share one), so we abort them individually; the aborts propagate into the
     * bridge's execute race and into each `/resume` fetch signal. Bumping
     * `webMcpEpoch` strands any resolve still deferred in a queued microtask:   * it captured the prior epoch and bails before installing a fresh
     * controller, so it can't escape this teardown. Called from every stop /
     * new-turn boundary (cancel, clearMessages, hydrateMessages, sendMessage).
     */
    private abortWebMcpResolves;
    cancel(): void;
    clearMessages(): void;
    getArtifacts(): PersonaArtifactRecord[];
    getArtifactById(id: string): PersonaArtifactRecord | undefined;
    getSelectedArtifactId(): string | null;
    selectArtifact(id: string | null): void;
    clearArtifacts(): void;
    upsertArtifact(manual: PersonaArtifactManualUpsert): PersonaArtifactRecord;
    private clearArtifactState;
    private emitArtifactsState;
    private applyArtifactStreamEvent;
    hydrateMessages(messages: AgentWidgetMessage[]): void;
    hydrateArtifacts(artifacts: PersonaArtifactRecord[], selectedId?: string | null): void;
    private handleEvent;
    private setStatus;
    private setStreaming;
    /**
     * Speak the latest assistant message using the Web Speech API
     * if text-to-speech is enabled in the config.
     */
    private speakLatestAssistantMessage;
    /**
     * Pick the best available English voice from a list of SpeechSynthesisVoices.
     * Prefers high-quality remote/natural voices, then enhanced local voices,
     * then standard local voices. Retained for backwards compatibility; delegates
     * to the browser speech engine's picker.
     */
    static pickBestVoice(voices: SpeechSynthesisVoice[]): SpeechSynthesisVoice;
    /**
     * Toggle the per-message "Read aloud" action: play → pause → resume (or
     * play → stop when the engine can't pause). Speaks the assistant message's
     * text via the configured speech engine (browser Web Speech API by default,
     * or a hosted engine from `textToSpeech.createEngine`).
     */
    toggleReadAloud(messageId: string): void;
    /** Current read-aloud playback state for a message (`idle` unless active). */
    getReadAloudState(messageId: string): ReadAloudState;
    /** Subscribe to read-aloud state changes. Returns an unsubscribe function. */
    onReadAloudChange(listener: ReadAloudListener): () => void;
    /**
     * Stop any in-progress text-to-speech / read-aloud playback.
     */
    stopSpeaking(): void;
    private appendMessage;
    private upsertMessage;
    private ensureSequence;
    private nextSequence;
    private sortMessages;
}

type LoadingIndicatorRenderer = (context: LoadingIndicatorRenderContext) => HTMLElement | null;
type MessageTransform = (context: {
    text: string;
    message: AgentWidgetMessage;
    streaming: boolean;
    raw?: string;
}) => string;
type MessageActionCallbacks = {
    onCopy?: (message: AgentWidgetMessage) => void;
    onFeedback?: (feedback: AgentWidgetMessageFeedback) => void;
};
declare const createTypingIndicator: () => HTMLElement;
/**
 * Render loading indicator with fallback chain:
 * 1. Custom renderer (if provided and returns non-null)
 * 2. Default typing indicator
 */
declare const renderLoadingIndicatorWithFallback: (location: "inline" | "standalone", customRenderer?: LoadingIndicatorRenderer, widgetConfig?: AgentWidgetConfig) => HTMLElement | null;
/**
 * Create message action buttons (copy, upvote, downvote)
 *
 * This is a pure rendering function. It creates button elements with the
 * correct `data-action` attributes, icons, and CSS classes. All click
 * handling, vote state management, clipboard logic, and callback dispatch
 * is handled via event delegation in `ui.ts` so that handlers survive
 * idiomorph DOM morphing.
 */
declare const createMessageActions: (message: AgentWidgetMessage, actionsConfig: AgentWidgetMessageActionsConfig, _callbacks?: MessageActionCallbacks) => HTMLElement;
/**
 * Options for creating a standard message bubble
 */
type CreateStandardBubbleOptions = {
    /**
     * Custom loading indicator renderer for inline location
     */
    loadingIndicatorRenderer?: LoadingIndicatorRenderer;
    /**
     * Full widget config (needed for loading indicator context)
     */
    widgetConfig?: AgentWidgetConfig;
};
/**
 * Create standard message bubble
 * Supports layout configuration for avatars, timestamps, and visual presets
 */
declare const createStandardBubble: (message: AgentWidgetMessage, transform: MessageTransform, layoutConfig?: AgentWidgetMessageLayoutConfig, actionsConfig?: AgentWidgetMessageActionsConfig, actionCallbacks?: MessageActionCallbacks, options?: CreateStandardBubbleOptions) => HTMLElement;
/**
 * Create bubble with custom renderer support
 * Uses custom renderer if provided in layout config, otherwise falls back to standard bubble
 */
declare const createBubbleWithLayout: (message: AgentWidgetMessage, transform: MessageTransform, layoutConfig?: AgentWidgetMessageLayoutConfig, actionsConfig?: AgentWidgetMessageActionsConfig, actionCallbacks?: MessageActionCallbacks, options?: CreateStandardBubbleOptions) => HTMLElement;

type ActionManagerProcessContext = {
    text: string;
    message: AgentWidgetMessage;
    streaming: boolean;
    raw?: string;
};
type ActionManagerOptions = {
    parsers: AgentWidgetActionParser[];
    handlers: AgentWidgetActionHandler[];
    getSessionMetadata: () => Record<string, unknown>;
    updateSessionMetadata: (updater: (prev: Record<string, unknown>) => Record<string, unknown>) => void;
    emit: <K extends keyof AgentWidgetControllerEventMap>(event: K, payload: AgentWidgetControllerEventMap[K]) => void;
    documentRef: Document | null;
};
declare const defaultJsonActionParser: AgentWidgetActionParser;
declare const defaultActionHandlers: Record<string, AgentWidgetActionHandler>;
declare const createActionManager: (options: ActionManagerOptions) => {
    process: (context: ActionManagerProcessContext) => {
        text: string;
        persist: boolean;
        resubmit?: boolean;
    } | null;
    syncFromMetadata: () => void;
};

/**
 * 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;
};
/**
 * Create a CSAT (Customer Satisfaction) feedback form
 * Rating scale: 1-5
 */
declare function createCSATFeedback(options: CSATFeedbackOptions): HTMLElement;
/**
 * Create an NPS (Net Promoter Score) feedback form
 * Rating scale: 0-10
 */
declare function createNPSFeedback(options: NPSFeedbackOptions): HTMLElement;

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[];
    /**
     * Convenience method for injecting an assistant message that renders as a
     * registered component: same shape Persona produces from a streamed
     * `{ "text": "...", "component": "...", "props": {...} }` payload.
     */
    injectComponentDirective: (options: InjectComponentDirectiveOptions) => 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;
    toggleReadAloud: (messageId: string) => void;
    stopReadAloud: () => void;
    getReadAloudState: (messageId: string) => ReadAloudState;
    onReadAloudChange: (listener: (activeId: string | null, state: ReadAloudState) => void) => () => void;
    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;
    /** Read current artifacts (useful on init to rebuild host-side tab state after hydration). */
    getArtifacts: () => PersonaArtifactRecord[];
    /** Read the currently selected artifact id (paired with `getArtifacts`). */
    getSelectedArtifactId: () => string | null;
    /**
     * 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"
     * @param options - Optional decision context (e.g. `{ remember: true }`),
     *   forwarded to `config.approval.onDecision`.
     */
    resolveApproval: (approvalId: string, decision: 'approved' | 'denied', options?: AgentWidgetApprovalDecisionOptions) => Promise<void>;
};
declare const createAgentExperience: (mount: HTMLElement, initialConfig?: AgentWidgetConfig, runtimeOptions?: {
    debugTools?: boolean;
}) => Controller;
type AgentWidgetController = Controller;

type AgentWidgetInitHandle = AgentWidgetController & {
    host: HTMLElement;
};
declare const initAgentWidget: (options: AgentWidgetInitOptions) => AgentWidgetInitHandle;

declare const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
declare const isAskUserQuestionMessage: (message: AgentWidgetMessage) => boolean;
/**
 * Parse an `ask_user_question` tool-variant message into a partial payload.
 * Safe to call mid-stream: will walk the tool call's `chunks` via
 * `partial-json` and return `{ payload: null, complete: false }` when there
 * isn't enough data yet. `complete` flips to `true` once the tool call
 * reports status `"complete"`.
 *
 * Exported for plugin authors implementing `renderAskUserQuestion`.
 */
declare const parseAskUserQuestionPayload: (message: AgentWidgetMessage) => {
    payload: Partial<AskUserQuestionPayload> | null;
    complete: boolean;
};
/**
 * Create the small in-transcript stub for an `ask_user_question` tool call.
 * The stub is passive: the interactive sheet is mounted separately into
 * the composer overlay via `ensureAskUserQuestionSheet`.
 */
declare const createAskUserQuestionBubble: (message: AgentWidgetMessage, config?: AgentWidgetConfig) => HTMLElement;
/**
 * Mount or update the interactive answer-pill sheet for a given message.
 * Idempotent: if a sheet already exists for the tool-call id, it is hydrated
 * in-place instead of remounted, so streaming updates don't flicker.
 */
declare const ensureAskUserQuestionSheet: (message: AgentWidgetMessage, config: AgentWidgetConfig | undefined, overlay: HTMLElement | null | undefined) => void;
/**
 * Remove the sheet for a specific tool-call id, or all sheets if omitted.
 * Runs a slide-out transition before removing.
 */
declare const removeAskUserQuestionSheet: (overlay: HTMLElement | null | undefined, toolCallId?: string) => void;

/**
 * Built-in `ask_user_question` client tool.
 *
 * The widget can advertise this tool to the agent on every dispatch via
 * `clientTools[]` (set `features.askUserQuestion.expose: true`): the same
 * wire surface WebMCP page tools ride. The server registers it as a LOCAL
 * tool under its bare name (`origin: 'sdk'` tools are not `webmcp:`-prefixed),
 * so when the model calls it the execution pauses with a `step_await`
 * (`awaitReason: "local_tool_required"`), the widget's answer-pill sheet
 * renders, and `session.resolveAskUserQuestion()` resumes the execution with
 * the structured answers.
 *
 * This replaces the previous integrator burden of hand-declaring the tool in
 * a flow's `runtimeTools` and keeping that schema in sync with the renderer.
 * Flows that already declare `ask_user_question` server-side should leave
 * `expose` off: the model would otherwise see the tool twice.
 */

/**
 * JSON Schema for the tool's parameters. Mirrors {@link AskUserQuestionPayload}
 *, the shape `parseAskUserQuestionPayload` hydrates the answer sheet from,  * so the schema the model is held to and the schema the renderer expects can
 * never drift.
 */
declare const ASK_USER_QUESTION_PARAMETERS_SCHEMA: {
    readonly type: "object";
    readonly properties: {
        readonly questions: {
            readonly type: "array";
            readonly minItems: 1;
            readonly maxItems: 8;
            readonly description: "Questions to ask the user. Prefer a single question.";
            readonly items: {
                readonly type: "object";
                readonly properties: {
                    readonly question: {
                        readonly type: "string";
                        readonly description: "The complete question, ending with a question mark.";
                    };
                    readonly header: {
                        readonly type: "string";
                        readonly maxLength: 12;
                        readonly description: "Short topic label, e.g. \"Auth method\".";
                    };
                    readonly options: {
                        readonly type: "array";
                        readonly minItems: 2;
                        readonly maxItems: 4;
                        readonly description: "2-4 distinct choices. Do NOT add an \"Other\" option: free text is automatic.";
                        readonly items: {
                            readonly type: "object";
                            readonly properties: {
                                readonly label: {
                                    readonly type: "string";
                                    readonly description: "Concise choice text (1-5 words).";
                                };
                                readonly description: {
                                    readonly type: "string";
                                    readonly description: "What the option means or implies.";
                                };
                            };
                            readonly required: readonly ["label"];
                            readonly additionalProperties: false;
                        };
                    };
                    readonly multiSelect: {
                        readonly type: "boolean";
                        readonly description: "Allow selecting multiple options. Default false.";
                    };
                    readonly allowFreeText: {
                        readonly type: "boolean";
                        readonly description: "Show a free-text input. Default true.";
                    };
                };
                readonly required: readonly ["question", "options"];
                readonly additionalProperties: false;
            };
        };
    };
    readonly required: readonly ["questions"];
    readonly additionalProperties: false;
};
/**
 * The `ClientToolDefinition` shipped on `dispatch.clientTools[]` when
 * `features.askUserQuestion.expose` is on. Exported so integrators who prefer
 * declaring the tool server-side (a flow's `runtimeTools`) can reuse the same
 * description and schema instead of hand-writing them.
 */
declare const ASK_USER_QUESTION_CLIENT_TOOL: ClientToolDefinition;
/**
 * Built-in client tools to append to a dispatch's `clientTools[]` for the
 * given widget config: `ask_user_question` and `suggest_replies`; future
 * built-in local tools join here.
 *
 * Each tool is gated on BOTH of its feature flags: `expose` opts the tool
 * into the agent's catalog, and `enabled !== false` guarantees the widget can
 * actually render UI (and, for fire-and-forget tools, auto-resume) for it: * exposing a tool with its feature disabled would park the execution on a
 * generic tool bubble with no way to advance.
 */
declare const builtInClientToolsForDispatch: (config: AgentWidgetConfig | undefined) => ClientToolDefinition[];

/**
 * Built-in `suggest_replies` client tool.
 *
 * The widget can advertise this tool to the agent on every dispatch via
 * `clientTools[]` (set `features.suggestReplies.expose: true`): the same
 * wire surface as `ask_user_question` and WebMCP page tools. When the model
 * calls it, the execution pauses with a `step_await`
 * (`awaitReason: "local_tool_required"`); unlike `ask_user_question`, the
 * widget resolves it FIRE-AND-FORGET: it renders the suggestions as tappable
 * chips above the composer and immediately resumes the execution with a
 * canned "shown" result, so the agent's turn completes without waiting on the
 * user. Tapping a chip sends its text verbatim as the user's next message.
 *
 * Chip visibility is DERIVED state, not imperative show/hide: the chips of
 * the last `suggest_replies` tool message with no user message after it are
 * shown (see {@link latestAgentSuggestions}). That single rule covers
 * soft-dismiss on any user message (typed, voice, or chip click), restore on
 * reload/hydration, and latest-wins when a turn carries multiple calls.
 */

declare const SUGGEST_REPLIES_TOOL_NAME = "suggest_replies";
/**
 * JSON Schema for the tool's parameters. Mirrors what
 * {@link parseSuggestRepliesPayload} hydrates the chips from, so the schema
 * the model is held to and the shape the renderer expects can never drift.
 */
declare const SUGGEST_REPLIES_PARAMETERS_SCHEMA: {
    readonly type: "object";
    readonly properties: {
        readonly suggestions: {
            readonly type: "array";
            readonly minItems: 1;
            readonly maxItems: 4;
            readonly description: "1-4 short, distinct follow-up replies, phrased in the user's voice.";
            readonly items: {
                readonly type: "string";
                readonly minLength: 1;
                readonly maxLength: 60;
            };
        };
    };
    readonly required: readonly ["suggestions"];
    readonly additionalProperties: false;
};
/**
 * The `ClientToolDefinition` shipped on `dispatch.clientTools[]` when
 * `features.suggestReplies.expose` is on. Exported so integrators who prefer
 * declaring the tool server-side (a flow's `runtimeTools`) can reuse the same
 * description and schema instead of hand-writing them.
 */
declare const SUGGEST_REPLIES_CLIENT_TOOL: ClientToolDefinition;
/** A tool-variant message produced by a `suggest_replies` call. */
declare const isSuggestRepliesMessage: (message: AgentWidgetMessage) => boolean;
/**
 * Tolerant parse of a `suggest_replies` tool call's args into chip labels:
 * accepts a JSON string or object, coerces items to trimmed strings, drops
 * empties, and truncates past the renderer cap with a console warning.
 */
declare const parseSuggestRepliesPayload: (args: unknown) => string[];
/**
 * The chips to show right now: those of the LAST `suggest_replies` tool
 * message with NO user message after it, or `null` when none apply. All
 * calls in a turn still get resumed (the server awaits each); only the
 * latest renders.
 */
declare const latestAgentSuggestions: (messages: AgentWidgetMessage[]) => string[] | null;

type WidgetHostLayoutMode = "direct" | "docked";
type WidgetHostLayout = {
    mode: WidgetHostLayoutMode;
    host: HTMLElement;
    shell: HTMLElement | null;
    syncWidgetState: (state: Pick<AgentWidgetStateSnapshot, "open" | "launcherEnabled">) => void;
    updateConfig: (config?: AgentWidgetConfig) => void;
    destroy: () => void;
};
declare const createWidgetHostLayout: (target: HTMLElement, config?: AgentWidgetConfig) => WidgetHostLayout;

/**
 * WebMCP consumption bridge.
 *
 * Owns the per-widget lifecycle of `@mcp-b/webmcp-polyfill`:
 *   - installs the polyfill (lazily, only when enabled) so `document.modelContext`
 *     is present;
 *   - snapshots the host page's tool registry per dispatch turn for
 *     `dispatch.clientTools[]`;
 *   - executes `webmcp:*` tool calls returned by the agent, mediating a single
 *     confirm-bubble gate before invoking the page's `execute()`.
 *
 * Spec reference: WebMCP (https://webmachinelearning.github.io/webmcp/).
 * Wire-level merging, namespace prefixing, and server-side allowlist
 * enforcement live on the Runtype API; this bridge mirrors those checks
 * client-side as a usability convenience, not a security boundary.
 *
 * About `@mcp-b/webmcp-polyfill`: it polyfills the *strict standard surface*
 * only (`registerTool` / `getTools` / `executeTool` on `document.modelContext`),
 * with no MCP-B-only extensions. The spec standardizes the *producer* side;
 * Persona is an in-page *consumer*, so it reads the registry via the
 * producer-facing preview API:
 *   - `getTools()`: async; returns `{ name, description, inputSchema }` where
 *     `inputSchema` is a JSON *string*. Annotations are not exposed here.
 *   - `executeTool(toolInfo, inputArgsJson, { signal })`: async; validates args
 *     against the tool's schema, runs `execute()`, and returns the raw result as
 *     a JSON *string* (or `null` for `undefined`). Honors `signal` for abort.
 *
 * The polyfill auto-installs `document.modelContext` at module-evaluation time,
 * so it is imported *dynamically* and only when `config.webmcp.enabled === true`
 *: a static import would install the global for every widget consumer,
 * including those that never opted into WebMCP.
 *
 * Confirm model: every `webmcp:*` call goes through one confirm gate before
 * `execute()` runs, regardless of `annotations.readOnlyHint`. (The polyfill owns
 * the spec's `client.requestUserInteraction` callback internally; Persona cannot
 * inject a nested confirm there, so the single outer gate is the whole story.)
 */

/** Server-applied wire prefix; strip when looking up registry entries. */
declare const WEBMCP_TOOL_PREFIX = "webmcp:";
declare class WebMcpBridge {
    private readonly config;
    private confirmHandler;
    private readonly timeoutMs;
    /** `true` once the polyfill has been (idempotently) installed. */
    private installed;
    /** Memoizes the one-shot async install so concurrent callers share it. */
    private readyPromise;
    /**
     * Warn-once latch for a present-but-incompatible `document.modelContext`
     * (some other / older WebMCP polyfill squatting the global). `getModelContext`
     * is hit on every snapshot + execute, so we log the diagnostic only once.
     */
    private incompatibleContextWarned;
    constructor(config: AgentWidgetWebMcpConfig);
    /**
     * Override the confirm handler post-construction. Used by `ui.ts` to wire
     * the in-panel approval bubble after the client has been built (the widget
     * lifecycle constructs the client before the panel renders).
     */
    setConfirmHandler(handler: WebMcpConfirmHandler | null): void;
    /**
     * `true` when the bridge can both snapshot the registry AND execute returned
     * tool calls: i.e. the polyfill is installed and `document.modelContext`
     * exposes the consumer surface (`getTools` / `executeTool`). Native browsers
     * that ship `document.modelContext` satisfy this too.
     *
     * Synchronous and best-effort: returns `false` until the lazy install has
     * resolved (see `ensureReady`). The snapshot/execute paths await readiness
     * themselves, so this is purely an advisory check for callers.
     */
    isOperational(): boolean;
    /**
     * Per-turn snapshot for `dispatch.clientTools[]`. Returns the JSON-only
     * surface: `execute` stays client-side, reached later via `executeToolCall`.
     *
     * Async because the strict polyfill's `getTools()` is async. Both payload
     * builders in `client.ts` already `await`, so this adds no new ceremony.
     */
    snapshotForDispatch(): Promise<ClientToolDefinition[]>;
    /**
     * Execute a `webmcp:<name>` tool call returned by the agent and return the
     * normalized MCP-shaped result for `/resume`.
     *
     * Failure modes: all return `{ isError: true, content: [...] }` rather than
     * throwing, so the dispatch can resume cleanly:
     *   - bridge not operational
     *   - tool not in registry (e.g. unmounted between snapshot and call)
     *   - tool excluded by the client allowlist
     *   - user declined the confirm gate
     *   - `execute()` threw or failed schema validation
     *   - `execute()` exceeded the 30s timeout
     *   - `signal` fired (session-level `cancel()`)
     *
     * When `signal` is provided, abort is honored at three points: before the
     * confirm bubble renders, after the user approves but before `execute()`
     * runs, and (via a combined `AbortController`) during `execute()` itself.
     * Honoring abort BEFORE the confirm prevents a late approval after `cancel()`
     * from firing a host-page side effect with no matching `/resume`.
     */
    executeToolCall(wireToolName: string, args: unknown, signal?: AbortSignal): Promise<WebMcpToolResult>;
    /**
     * Lazily install `@mcp-b/webmcp-polyfill` the first time the bridge needs the
     * registry. Idempotent and memoized. Dynamic import keeps the polyfill out of
     * the main bundle and prevents it from installing `document.modelContext` for
     * widget consumers that never enable WebMCP.
     *
     * Producer pages should still install the polyfill themselves (or import it)
     * before registering tools: Persona's install is a fallback, and a page that
     * registers tools at load before Persona's first dispatch needs the global to
     * already exist.
     */
    private ensureReady;
    private install;
    /**
     * Read the consumer surface off `document.modelContext`, returning `null`
     * when it is absent or doesn't expose the producer-preview API we rely on.
     */
    private getModelContext;
    private requestConfirm;
    private passesClientAllowlist;
}
/**
 * Strip the server-applied `webmcp:` prefix from a wire-format tool name.
 * Exported for tests; widget code should always go through the bridge.
 */
declare const stripWebMcpPrefix: (name: string) => string;
/**
 * `true` when `wireToolName` carries the `webmcp:` prefix. Used by `client.ts`
 * to route `step_await` events.
 */
declare const isWebMcpToolName: (name: string) => boolean;

declare const createLocalStorageAdapter: (key?: string) => AgentWidgetStorageAdapter;

/**
 * Options for creating a markdown processor
 */
type MarkdownProcessorOptions = {
    /** Marked parsing options */
    markedOptions?: AgentWidgetMarkdownOptions;
    /** Custom renderer overrides */
    renderer?: AgentWidgetMarkdownRendererOverrides;
};
/**
 * Creates a configured markdown processor with custom options and renderers.
 *
 * @param options - Configuration options for the markdown processor
 * @returns A function that converts markdown text to HTML
 *
 * @example
 * ```typescript
 * // Basic usage with defaults
 * const processor = createMarkdownProcessor();
 * const html = processor("# Hello World");
 *
 * // With custom options
 * const processor = createMarkdownProcessor({
 *   markedOptions: { gfm: true, breaks: true },
 *   renderer: {
 *     link(token) {
 *       return `<a href="${token.href}" target="_blank">${token.text}</a>`;
 *     }
 *   }
 * });
 * ```
 */
declare const createMarkdownProcessor: (options?: MarkdownProcessorOptions) => (text: string) => string;
/**
 * Creates a markdown processor from AgentWidgetMarkdownConfig.
 * This is a convenience function that maps the widget config to processor options.
 *
 * @param config - The markdown configuration from widget config
 * @returns A function that converts markdown text to HTML
 */
declare const createMarkdownProcessorFromConfig: (config?: AgentWidgetMarkdownConfig) => (text: string) => string;
/**
 * Basic markdown renderer using default settings.
 * Remember to sanitize the returned HTML if you render untrusted content in your host page.
 *
 * For custom configuration, use `createMarkdownProcessor()` or `createMarkdownProcessorFromConfig()`.
 */
declare const markdownPostprocessor: (text: string) => string;
/**
 * Escapes HTML entities. Used as the default safe renderer.
 */
declare const escapeHtml: (text: string) => string;
/**
 * Creates a directive postprocessor with custom markdown configuration.
 * Converts special directives (either `<Form type="init" />` or
 * `<Directive>{"component":"form","type":"init"}</Directive>`) into placeholder
 * elements that the widget upgrades after render. Remaining text is rendered as
 * Markdown with the provided configuration.
 *
 * @param markdownConfig - Optional markdown configuration
 * @returns A function that processes text with directives and markdown
 */
declare const createDirectivePostprocessor: (markdownConfig?: AgentWidgetMarkdownConfig) => (text: string) => string;
/**
 * Converts special directives (either `<Form type="init" />` or
 * `<Directive>{"component":"form","type":"init"}</Directive>`) into placeholder
 * elements that the widget upgrades after render. Remaining text is rendered as
 * Markdown using default settings.
 *
 * For custom markdown configuration, use `createDirectivePostprocessor()`.
 */
declare const directivePostprocessor: (text: string) => string;

/**
 * A function that sanitizes an HTML string, returning safe HTML.
 */
type SanitizeFunction = (html: string) => string;
/**
 * Creates the default DOMPurify-based sanitizer.
 * Uses the global window when available (browser).
 */
declare const createDefaultSanitizer: () => SanitizeFunction;
/**
 * Resolves a `sanitize` config value into a concrete function or null.
 *
 * - `undefined` / `true` → built-in DOMPurify sanitizer
 * - `false` → `null` (no sanitization)
 * - custom function → returned as-is
 */
declare const resolveSanitizer: (option: boolean | SanitizeFunction | undefined) => SanitizeFunction | null;

/**
 * Plain text parser - passes through text as-is without any parsing.
 * This is the default parser.
 */
declare const createPlainTextParser: () => AgentWidgetStreamParser;
/**
 * JSON parser using regex-based extraction.
 * Extracts the 'text' field from JSON responses using regex patterns.
 * This is a simpler regex-based alternative to createJsonStreamParser.
 * Less robust for complex/malformed JSON but has no external dependencies.
 */
declare const createRegexJsonParser: () => AgentWidgetStreamParser;
/**
 * JSON stream parser using partial-json library.
 * Extracts the 'text' field from JSON responses using the partial-json library,
 * which is specifically designed for parsing incomplete JSON from LLMs.
 * This is the recommended parser as it's more robust than regex.
 *
 * Library: https://github.com/promplate/partial-json-parser-js
 */
declare const createJsonStreamParser: () => AgentWidgetStreamParser;
/**
 * Flexible JSON stream parser that can extract text from various field names.
 * This parser looks for display text in multiple possible fields, making it
 * compatible with different JSON response formats.
 *
 * @param textExtractor Optional function to extract display text from parsed JSON.
 *                      If not provided, looks for common text fields.
 */
declare const createFlexibleJsonStreamParser: (textExtractor?: (parsed: any) => string | null) => AgentWidgetStreamParser;
/**
 * XML stream parser.
 * Extracts text from <text>...</text> tags in XML responses.
 */
declare const createXmlParser: () => AgentWidgetStreamParser;

/**
 * Content Utilities
 *
 * Helper functions for working with multi-modal message content.
 */

/**
 * Normalize content to ContentPart[] format.
 * Converts string content to a single text content part.
 */
declare function normalizeContent(content: MessageContent): ContentPart[];
/**
 * Extract display text from content parts.
 * Concatenates all text parts into a single string.
 */
declare function getDisplayText(content: MessageContent): string;
/**
 * Check if content contains any images.
 */
declare function hasImages(content: MessageContent): boolean;
/**
 * Get all image parts from content.
 */
declare function getImageParts(content: MessageContent): ImageContentPart[];
/**
 * Create a text-only content part.
 */
declare function createTextPart(text: string): TextContentPart;
/**
 * Create an image content part from a base64 data URI or URL.
 *
 * @param image - Base64 data URI (data:image/...) or URL
 * @param options - Optional mimeType and alt text
 */
declare function createImagePart(image: string, options?: {
    mimeType?: string;
    alt?: string;
}): ImageContentPart;
/**
 * Convert a File object to an image content part.
 * Reads the file and converts it to a base64 data URI.
 */
declare function fileToImagePart(file: File): Promise<ImageContentPart>;
/**
 * Validate that a file is an acceptable image type.
 *
 * @param file - The file to validate
 * @param acceptedTypes - Array of accepted MIME types (default: common image types)
 * @param maxSizeBytes - Maximum file size in bytes (default: 10MB)
 */
declare function validateImageFile(file: File, acceptedTypes?: string[], maxSizeBytes?: number): {
    valid: boolean;
    error?: string;
};

/**
 * Enriched DOM context collection for providing richer page information to AI.
 *
 * Captures interactive elements, stable CSS selectors, ARIA roles, data attributes,
 * and visibility state: giving the LLM much better context than basic className/innerText.
 *
 * ## Modes
 *
 * - **structured** (default): collects candidates, scores them with optional {@link ParseRule}
 *   hooks, then applies `maxElements`. Rich containers (e.g. product cards) can surface
 *   before unrelated static noise.
 * - **simple**: legacy behavior: cap during traversal, interactive-first ordering, no rule
 *   scoring or {@link EnrichedPageElement.formattedSummary}.
 */
interface EnrichedPageElement {
    /** Stable CSS selector the LLM can use directly */
    selector: string;
    /** Lowercase tag name */
    tagName: string;
    /** Visible text content, trimmed */
    text: string;
    /** ARIA role or null */
    role: string | null;
    /** Interactivity classification */
    interactivity: "clickable" | "input" | "navigable" | "static";
    /** Relevant attributes: id, data-*, href, aria-label, type, value, name */
    attributes: Record<string, string>;
    /**
     * When set (structured mode + matching rule), {@link formatEnrichedContext} prefers this
     * markdown-like line instead of raw `text`.
     */
    formattedSummary?: string;
}
/** How DOM context is collected and formatted. */
type DomContextMode = "simple" | "structured";
/**
 * Options that control collection limits, visibility, and mode.
 * Prefer nesting these under {@link DomContextOptions.options}; top-level fields remain
 * supported for backward compatibility.
 */
interface ParseOptionsConfig {
    /**
     * `structured` (default): score candidates with rules, then apply `maxElements`.
     * `simple`: legacy traversal cap and ordering only: rules are ignored (with a warning
     * if `rules` was passed on {@link DomContextOptions}).
     */
    mode?: DomContextMode;
    /** Maximum number of elements to return. Default: 80 */
    maxElements?: number;
    /** CSS selector for elements to exclude (e.g. the widget host). Default: '.persona-host' */
    excludeSelector?: string;
    /** Maximum text length per element. Default: 200 */
    maxTextLength?: number;
    /** Only include visible elements. Default: true */
    visibleOnly?: boolean;
    /** Root element to walk. Default: document.body */
    root?: HTMLElement;
    /**
     * Maximum candidates gathered before scoring (structured mode only).
     * Default: `max(500, maxElements * 10)`.
     */
    maxCandidates?: number;
}
interface RuleScoringContext {
    doc: Document;
    maxTextLength: number;
}
/**
 * Extensible rule for structured DOM context: scoring, descendant suppression, and
 * optional formatted output.
 */
interface ParseRule {
    /** Stable id for debugging and tests */
    id: string;
    /**
     * Score bonus when this rule applies to the element (0 when it does not).
     * Higher scores are kept first when applying `maxElements`.
     */
    scoreElement(el: HTMLElement, enriched: EnrichedPageElement, ctx: RuleScoringContext): number;
    /**
     * When `owner` is kept in the final set and matched this rule for formatting,
     * return true to drop `descendant` (redundant price text, CTAs summarized on the card, etc.).
     */
    shouldSuppressDescendant?(owner: HTMLElement, descendant: HTMLElement, descendantEnriched: EnrichedPageElement): boolean;
    /**
     * Markdown-like summary for the LLM. Only used when `scoreElement` &gt; 0 for this rule.
     */
    formatSummary?(el: HTMLElement, enriched: EnrichedPageElement, ctx: RuleScoringContext): string | null;
}
interface DomContextOptions {
    /** Nested parse options (mode, limits, root). Merged with legacy top-level fields. */
    options?: ParseOptionsConfig;
    /** Custom rules for structured mode. Default: {@link defaultParseRules} */
    rules?: ParseRule[];
    /** @inheritdoc ParseOptionsConfig.maxElements */
    maxElements?: number;
    /** @inheritdoc ParseOptionsConfig.excludeSelector */
    excludeSelector?: string;
    /** @inheritdoc ParseOptionsConfig.maxTextLength */
    maxTextLength?: number;
    /** @inheritdoc ParseOptionsConfig.visibleOnly */
    visibleOnly?: boolean;
    /** @inheritdoc ParseOptionsConfig.root */
    root?: HTMLElement;
}
interface FormatEnrichedContextOptions {
    /** When `simple`, ignore {@link EnrichedPageElement.formattedSummary}. Default: structured */
    mode?: DomContextMode;
}
/** Default structured rules: commerce-style cards and generic search/result rows. */
declare const defaultParseRules: ParseRule[];
/**
 * Generate a stable, unique CSS selector for an element.
 * Priority: #id → [data-testid]/[data-product] → tag.classes with :nth-of-type()
 */
declare function generateStableSelector(el: HTMLElement): string;
/**
 * Collect enriched page context from the DOM.
 *
 * - **Default (structured):** walks up to `maxCandidates` nodes, scores with
 *   {@link defaultParseRules} (or `rules`), suppresses redundant descendants when a
 *   formatting rule matches, then keeps the top `maxElements` by score (DOM order tie-break).
 * - **simple:** legacy path: stops once `maxElements` nodes are collected during traversal
 *   and sorts interactive before static.
 *
 * Pass `options: { mode: "simple" }` to disable rules. If `mode` is `simple` and `rules` is
 * non-empty, rules are ignored and a console warning is emitted.
 */
declare function collectEnrichedPageContext(options?: DomContextOptions): EnrichedPageElement[];
/**
 * Format enriched page elements as a structured string for LLM consumption.
 * When `mode` is structured (default) and elements include {@link EnrichedPageElement.formattedSummary},
 * those render under **Structured summaries** before the usual interactivity groups.
 */
declare function formatEnrichedContext(elements: EnrichedPageElement[], options?: FormatEnrichedContextOptions): string;

/**
 * Attachment Manager
 *
 * Handles file selection, validation, preview generation, and content part creation
 * for the composer attachment feature. Supports both images and documents.
 */

/**
 * Pending attachment with preview
 */
interface PendingAttachment {
    id: string;
    file: File;
    previewUrl: string | null;
    contentPart: ImageContentPart | FileContentPart;
}
/**
 * Attachment manager configuration
 */
interface AttachmentManagerConfig {
    allowedTypes?: string[];
    maxFileSize?: number;
    maxFiles?: number;
    onFileRejected?: (file: File, reason: "type" | "size" | "count") => void;
    onAttachmentsChange?: (attachments: PendingAttachment[]) => void;
}
/**
 * Creates and manages attachments for the composer
 */
declare class AttachmentManager {
    private attachments;
    private config;
    private previewsContainer;
    constructor(config?: AttachmentManagerConfig);
    /**
     * Set the previews container element
     */
    setPreviewsContainer(container: HTMLElement | null): void;
    /**
     * Update the configuration (e.g., when allowed types change)
     */
    updateConfig(config: Partial<AttachmentManagerConfig>): void;
    /**
     * Get current attachments
     */
    getAttachments(): PendingAttachment[];
    /**
     * Get content parts for all attachments
     */
    getContentParts(): ContentPart[];
    /**
     * Check if there are any attachments
     */
    hasAttachments(): boolean;
    /**
     * Get the number of attachments
     */
    count(): number;
    /**
     * Handle file input change event
     */
    handleFileSelect(files: FileList | null): Promise<void>;
    /**
     * Handle an array of files (e.g., clipboard image paste)
     */
    handleFiles(files: readonly File[]): Promise<void>;
    /**
     * Remove an attachment by ID
     */
    removeAttachment(id: string): void;
    /**
     * Clear all attachments
     */
    clearAttachments(): void;
    /**
     * Render a preview for an attachment (image thumbnail or file icon)
     */
    private renderPreview;
    /**
     * Update the visibility of the previews container
     */
    private updatePreviewsVisibility;
    /**
     * Create an AttachmentManager from widget config
     */
    static fromConfig(config?: AgentWidgetAttachmentsConfig, onAttachmentsChange?: (attachments: PendingAttachment[]) => void): AttachmentManager;
}

/**
 * Message ID utilities for client-side message tracking
 * Used for feedback integration with the Runtype API
 */
/**
 * Generate a unique message ID for tracking
 * Format: msg_{timestamp_base36}_{random_8chars}
 */
declare function generateMessageId(): string;
/**
 * Generate a unique user message ID
 * Format: usr_{timestamp_base36}_{random_8chars}
 */
declare function generateUserMessageId(): string;
/**
 * Generate a unique assistant message ID
 * Format: ast_{timestamp_base36}_{random_8chars}
 */
declare function generateAssistantMessageId(): string;

declare const isDockedMountMode: (config?: AgentWidgetConfig) => boolean;
/**
 * Resolved dock layout. For `reveal: "resize"`, when the panel is closed the dock column is `0px`.
 * For `reveal: "overlay"`, the panel overlays with `transform`. For `reveal: "push"`, a sliding track
 * moves content and panel together without width animation on the main column. For `emerge`,
 * the dock column still animates like `resize` but the widget stays `dock.width` wide inside the slot.
 * Unknown keys on `launcher.dock` (e.g. legacy `collapsedWidth`) are ignored.
 */
declare const resolveDockConfig: (config?: AgentWidgetConfig) => Required<AgentWidgetDockConfig>;

/**
 * The current version of the @runtypelabs/persona package.
 * This is automatically derived from package.json.
 */
declare const VERSION: string;

declare class PluginRegistry {
    private plugins;
    /**
     * Register a plugin
     */
    register(plugin: AgentWidgetPlugin): void;
    /**
     * Unregister a plugin
     */
    unregister(pluginId: string): void;
    /**
     * Get all plugins sorted by priority
     */
    getAll(): AgentWidgetPlugin[];
    /**
     * Get plugins for a specific instance (from config)
     * Merges instance plugins with globally registered plugins
     */
    getForInstance(instancePlugins?: AgentWidgetPlugin[]): AgentWidgetPlugin[];
    /**
     * Clear all plugins
     */
    clear(): void;
}
declare const pluginRegistry: PluginRegistry;

/**
 * Register a custom stream animation plugin globally. Subsequent widget
 * instances can reference the plugin by `name` in `features.streamAnimation.type`.
 * Per-widget plugin overrides via `features.streamAnimation.plugins` take
 * precedence over the global registry.
 */
declare const registerStreamAnimationPlugin: (plugin: StreamAnimationPlugin) => void;
declare const unregisterStreamAnimationPlugin: (name: string) => void;
declare const listRegisteredStreamAnimations: () => string[];

interface DropdownMenuItem {
    id: string;
    label: string;
    /** Lucide icon name to show before the label. */
    icon?: string;
    /** When true, item text is styled in a destructive/danger color. */
    destructive?: boolean;
    /** When true, a visual divider is inserted before this item. */
    dividerBefore?: boolean;
}
interface CreateDropdownOptions {
    /** Menu items to render. */
    items: DropdownMenuItem[];
    /** Called when a menu item is selected. */
    onSelect: (id: string) => void;
    /** Anchor element used for positioning. When `portal` is not set the menu is appended inside this element (which must have position: relative). */
    anchor: HTMLElement;
    /** Alignment of the menu relative to the anchor. Default: 'bottom-left'. */
    position?: 'bottom-left' | 'bottom-right';
    /**
     * Portal target element. When set, the menu is appended to this element
     * and uses fixed positioning calculated from the anchor's bounding rect.
     * Use this to escape `overflow: hidden` containers.
     */
    portal?: HTMLElement;
}
interface DropdownMenuHandle {
    /** The menu DOM element. */
    element: HTMLElement;
    /** Show the menu. */
    show: () => void;
    /** Hide the menu. */
    hide: () => void;
    /** Toggle visibility. */
    toggle: () => void;
    /** Remove the menu and clean up all listeners. */
    destroy: () => void;
}
/**
 * Create a dropdown menu attached to an anchor element.
 *
 * The menu is styled via `.persona-dropdown-menu` CSS rules and themed
 * through `--persona-dropdown-*` CSS variables with semantic fallbacks.
 *
 * ```ts
 * import { createDropdownMenu } from "@runtypelabs/persona";
 *
 * const dropdown = createDropdownMenu({
 *   items: [
 *     { id: "edit", label: "Edit", icon: "pencil" },
 *     { id: "delete", label: "Delete", icon: "trash-2", destructive: true, dividerBefore: true },
 *   ],
 *   onSelect: (id) => console.log("selected", id),
 *   anchor: buttonElement,
 * });
 * anchor.appendChild(dropdown.element);
 * button.addEventListener("click", () => dropdown.toggle());
 * ```
 */
declare function createDropdownMenu(options: CreateDropdownOptions): DropdownMenuHandle;

/**
 * Curated registry of lucide icons available to `renderLucideIcon`.
 *
 * The widget used to do `import * as icons from "lucide"` and look up
 * icons dynamically by string. That defeated tree-shaking, so the IIFE
 * (CDN/script-tag) bundle shipped all 1640 lucide icons (~400KB of icon
 * data) regardless of which we actually used. This explicit registry
 * lets the bundler drop any icon not listed here.
 *
 * Trade-off: `renderLucideIcon(name)` is now a *closed set*. Names not
 * in this map return `null` and log a warning, exactly as a typo did
 * before. The registry is intentionally generous (~110 icons) so that
 * custom `ComponentRenderer` authors rarely hit a missing-icon dead end.
 *
 * To add icons: add a named import above and a row in `LUCIDE_ICONS`,
 * keyed by the lucide kebab-case name (matches their filename and
 * https://lucide.dev/icons).
 *
 * See `packages/widget/docs/icon-registry-shortlist.md` for the full
 * curation rationale and which icons were considered but excluded.
 */
declare const LUCIDE_ICONS: {
    readonly activity: IconNode;
    readonly "arrow-down": IconNode;
    readonly "arrow-up": IconNode;
    readonly "arrow-up-right": IconNode;
    readonly bot: IconNode;
    readonly "chevron-down": IconNode;
    readonly "chevron-up": IconNode;
    readonly "chevron-right": IconNode;
    readonly "chevron-left": IconNode;
    readonly check: IconNode;
    readonly clipboard: IconNode;
    readonly "clipboard-copy": IconNode;
    readonly copy: IconNode;
    readonly file: IconNode;
    readonly "file-code": IconNode;
    readonly "file-spreadsheet": IconNode;
    readonly "file-text": IconNode;
    readonly "image-plus": IconNode;
    readonly loader: IconNode;
    readonly "loader-circle": IconNode;
    readonly mic: IconNode;
    readonly paperclip: IconNode;
    readonly "refresh-cw": IconNode;
    readonly search: IconNode;
    readonly send: IconNode;
    readonly "shield-alert": IconNode;
    readonly "shield-check": IconNode;
    readonly "shield-x": IconNode;
    readonly square: IconNode;
    readonly "thumbs-down": IconNode;
    readonly "thumbs-up": IconNode;
    readonly upload: IconNode;
    readonly "volume-2": IconNode;
    readonly x: IconNode;
    readonly user: IconNode;
    readonly mail: IconNode;
    readonly phone: IconNode;
    readonly calendar: IconNode;
    readonly clock: IconNode;
    readonly building: IconNode;
    readonly "map-pin": IconNode;
    readonly lock: IconNode;
    readonly key: IconNode;
    readonly "credit-card": IconNode;
    readonly "at-sign": IconNode;
    readonly hash: IconNode;
    readonly globe: IconNode;
    readonly link: IconNode;
    readonly "circle-check": IconNode;
    readonly "circle-x": IconNode;
    readonly "triangle-alert": IconNode;
    readonly info: IconNode;
    readonly ban: IconNode;
    readonly shield: IconNode;
    readonly "arrow-left": IconNode;
    readonly "arrow-right": IconNode;
    readonly "external-link": IconNode;
    readonly ellipsis: IconNode;
    readonly "ellipsis-vertical": IconNode;
    readonly menu: IconNode;
    readonly house: IconNode;
    readonly plus: IconNode;
    readonly minus: IconNode;
    readonly pencil: IconNode;
    readonly trash: IconNode;
    readonly "trash-2": IconNode;
    readonly save: IconNode;
    readonly download: IconNode;
    readonly share: IconNode;
    readonly funnel: IconNode;
    readonly settings: IconNode;
    readonly "rotate-cw": IconNode;
    readonly maximize: IconNode;
    readonly minimize: IconNode;
    readonly "shopping-cart": IconNode;
    readonly "shopping-bag": IconNode;
    readonly package: IconNode;
    readonly truck: IconNode;
    readonly tag: IconNode;
    readonly gift: IconNode;
    readonly receipt: IconNode;
    readonly wallet: IconNode;
    readonly store: IconNode;
    readonly "dollar-sign": IconNode;
    readonly percent: IconNode;
    readonly play: IconNode;
    readonly pause: IconNode;
    readonly "volume-x": IconNode;
    readonly camera: IconNode;
    readonly image: IconNode;
    readonly film: IconNode;
    readonly headphones: IconNode;
    readonly "message-circle": IconNode;
    readonly "message-square": IconNode;
    readonly bell: IconNode;
    readonly heart: IconNode;
    readonly star: IconNode;
    readonly eye: IconNode;
    readonly "eye-off": IconNode;
    readonly bookmark: IconNode;
    readonly "calendar-days": IconNode;
    readonly history: IconNode;
    readonly timer: IconNode;
    readonly folder: IconNode;
    readonly "folder-open": IconNode;
    readonly files: IconNode;
    readonly sparkles: IconNode;
    readonly zap: IconNode;
    readonly sun: IconNode;
    readonly moon: IconNode;
    readonly flag: IconNode;
    readonly monitor: IconNode;
    readonly smartphone: IconNode;
};
/**
 * Names of lucide icons that ship with the widget. Names not in this
 * union return `null` from `renderLucideIcon` (with a console warning).
 */
type IconName = keyof typeof LUCIDE_ICONS;
/**
 * Renders a lucide icon as an inline SVG element. Works inside Shadow
 * DOM and requires no CSS.
 *
 * @param iconName - A lucide kebab-case name from the registry. See
 *   `IconName` for the full list, or `docs/icon-registry-shortlist.md`
 *   for rationale.
 * @param size - The size in pixels (number) or any CSS length string.
 * @param color - Stroke color (default: "currentColor").
 * @param strokeWidth - Stroke width (default: 2).
 * @returns SVGElement, or null if the name is not in the registry.
 */
declare const renderLucideIcon: (iconName: IconName | (string & {}), size?: number | string, color?: string, strokeWidth?: number) => SVGElement | null;

/** Options for {@link createIconButton}. */
interface CreateIconButtonOptions {
    /** Lucide icon name (kebab-case, e.g. "eye", "chevron-down"). */
    icon: string;
    /** Accessible label (used for aria-label and title). */
    label: string;
    /** Icon size in pixels. Default: 16. */
    size?: number;
    /** Icon stroke width. Default: 2. */
    strokeWidth?: number;
    /** Extra CSS class(es) appended after "persona-icon-btn". */
    className?: string;
    /** Click handler. */
    onClick?: (e: MouseEvent) => void;
    /** Additional ARIA attributes (e.g. { "aria-haspopup": "true" }). */
    aria?: Record<string, string>;
}
/**
 * Creates a minimal icon-only button with accessible labelling.
 *
 * The button receives the base class `persona-icon-btn` and renders a single
 * Lucide icon inside it.
 */
declare function createIconButton(options: CreateIconButtonOptions): HTMLButtonElement;
/** Options for {@link createLabelButton}. */
interface CreateLabelButtonOptions {
    /** Optional Lucide icon name shown before the label. */
    icon?: string;
    /** Button text label (also used for aria-label). */
    label: string;
    /** Visual variant. Default: "default". */
    variant?: "default" | "primary" | "destructive" | "ghost";
    /** Size preset. Default: "sm". */
    size?: "sm" | "md";
    /** Icon size in pixels. Default: 14. */
    iconSize?: number;
    /** Extra CSS class(es). */
    className?: string;
    /** Click handler. */
    onClick?: (e: MouseEvent) => void;
    /** Additional ARIA attributes. */
    aria?: Record<string, string>;
}
/**
 * Creates a button with an optional leading icon and a text label.
 *
 * CSS classes follow the BEM-like pattern:
 * `persona-label-btn persona-label-btn--{variant} persona-label-btn--{size}`
 */
declare function createLabelButton(options: CreateLabelButtonOptions): HTMLButtonElement;
/** Describes a single item inside a toggle group. */
interface ToggleGroupItem {
    id: string;
    /** Lucide icon name. If omitted, uses label as text. */
    icon?: string;
    /** Accessible label for the button. */
    label: string;
}
/** Options for {@link createToggleGroup}. */
interface CreateToggleGroupOptions {
    /** Toggle items. */
    items: ToggleGroupItem[];
    /** Initially selected item id. */
    selectedId: string;
    /** Called when selection changes. */
    onSelect: (id: string) => void;
    /** Extra CSS class(es) on the wrapper. */
    className?: string;
}
/** Handle returned by {@link createToggleGroup}. */
interface ToggleGroupHandle {
    /** The wrapper element containing toggle buttons. */
    element: HTMLElement;
    /** Programmatically change the selected item. */
    setSelected: (id: string) => void;
}
/**
 * Creates a group of mutually-exclusive toggle buttons.
 *
 * Each button uses `aria-pressed` to communicate its state. Only one button
 * can be active at a time.
 */
declare function createToggleGroup(options: CreateToggleGroupOptions): ToggleGroupHandle;
/** Options for {@link createComboButton}. */
interface CreateComboButtonOptions {
    /** Button text label. */
    label: string;
    /** Lucide icon name for the dropdown indicator (default: "chevron-down"). */
    icon?: string;
    /** Dropdown menu items. */
    menuItems: DropdownMenuItem[];
    /** Called when a menu item is selected. */
    onSelect: (id: string) => void;
    /** Where to align the dropdown. Default: "bottom-left". */
    position?: "bottom-left" | "bottom-right";
    /**
     * Portal target for the dropdown menu. When set, the menu escapes
     * overflow containers by rendering inside this element with fixed positioning.
     */
    portal?: HTMLElement;
    /** Extra CSS class(es) on the wrapper element. */
    className?: string;
    /** Hover style for the pill effect. */
    hover?: {
        background?: string;
        border?: string;
        borderRadius?: string;
        padding?: string;
    };
}
/** Handle returned by {@link createComboButton}. */
interface ComboButtonHandle {
    /** The wrapper element (label + chevron + dropdown). */
    element: HTMLElement;
    /** Update the displayed label text. */
    setLabel: (text: string) => void;
    /** Open the dropdown. */
    open: () => void;
    /** Close the dropdown. */
    close: () => void;
    /** Toggle the dropdown. */
    toggle: () => void;
    /** Remove from DOM and clean up listeners. */
    destroy: () => void;
}
/**
 * Creates a combo button: a clickable label with a chevron that opens a dropdown menu.
 *
 * The entire label + chevron area acts as a single interactive unit with an optional
 * hover pill effect. Clicking anywhere on it toggles the dropdown.
 *
 * ```ts
 * import { createComboButton } from "@runtypelabs/persona";
 *
 * const combo = createComboButton({
 *   label: "Chat Assistant",
 *   menuItems: [
 *     { id: "star", label: "Star", icon: "star" },
 *     { id: "rename", label: "Rename", icon: "pencil" },
 *     { id: "delete", label: "Delete", icon: "trash-2", destructive: true, dividerBefore: true },
 *   ],
 *   onSelect: (id) => console.log("Selected:", id),
 * });
 * header.appendChild(combo.element);
 * ```
 */
declare function createComboButton(options: CreateComboButtonOptions): ComboButtonHandle;

declare const DEFAULT_PALETTE: {
    colors: {
        primary: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
            950: string;
        };
        secondary: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
            950: string;
        };
        accent: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
            950: string;
        };
        gray: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
            950: string;
        };
        success: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
        };
        warning: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
        };
        error: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
        };
        info: {
            50: string;
            100: string;
            200: string;
            300: string;
            400: string;
            500: string;
            600: string;
            700: string;
            800: string;
            900: string;
            950: string;
        };
    };
    spacing: {
        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;
    };
    typography: {
        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;
        };
    };
    shadows: {
        none: string;
        sm: string;
        md: string;
        lg: string;
        xl: string;
        '2xl': string;
    };
    borders: {
        none: string;
        sm: string;
        md: string;
        lg: string;
    };
    radius: {
        none: string;
        sm: string;
        md: string;
        lg: string;
        xl: string;
        '2xl': string;
        full: string;
    };
};
declare const DEFAULT_SEMANTIC: SemanticTokens;
declare const DEFAULT_COMPONENTS: ComponentTokens;
declare function resolveTokens(theme: PersonaTheme): Record<string, ResolvedToken>;
declare function validateTheme(theme: Partial<PersonaTheme>): ThemeValidationResult;
declare function createTheme(userConfig?: DeepPartial<PersonaTheme>, options?: CreateThemeOptions): PersonaTheme;
declare function themeToCssVariables(theme: PersonaTheme): Record<string, string>;
/**
 * Stable `data-persona-theme-zone` values applied to key widget regions.
 * Visual editors should use `[data-persona-theme-zone="header"]` selectors
 * rather than internal class names.
 */
declare const THEME_ZONES: {
    readonly header: "Widget header bar";
    readonly messages: "Message list area";
    readonly 'user-message': "User message bubble";
    readonly 'assistant-message': "Assistant message bubble";
    readonly composer: "Footer / composer area";
    readonly container: "Main widget container";
    readonly 'artifact-pane': "Artifact sidebar";
    readonly 'artifact-toolbar': "Artifact toolbar";
};
type ThemeZone = keyof typeof THEME_ZONES;

type ColorScheme = 'light' | 'dark' | 'auto';
interface PersonaWidgetConfig {
    theme?: DeepPartial<PersonaTheme>;
    darkTheme?: DeepPartial<PersonaTheme>;
    colorScheme?: ColorScheme;
}
type WidgetConfig = PersonaWidgetConfig | AgentWidgetConfig;
declare const detectColorScheme: () => "light" | "dark";
declare const getColorScheme: (config?: WidgetConfig) => "light" | "dark";
declare const getActiveTheme: (config?: WidgetConfig) => PersonaTheme;
declare const applyThemeVariables: (element: HTMLElement, config?: WidgetConfig) => void;
declare const createThemeObserver: (callback: (scheme: "light" | "dark") => void) => (() => void);

declare function accessibilityPlugin(): PersonaThemePlugin;
declare function animationsPlugin(): PersonaThemePlugin;
declare function brandPlugin(brandConfig: {
    colors?: {
        primary?: string;
        secondary?: string;
        accent?: string;
    };
    logo?: string;
}): PersonaThemePlugin;
declare function reducedMotionPlugin(): PersonaThemePlugin;
declare function highContrastPlugin(): PersonaThemePlugin;
declare function createPlugin(config: {
    name: string;
    version: string;
    transform?: (theme: PersonaTheme) => PersonaTheme;
    cssVariables?: Record<string, string>;
    afterResolve?: (resolved: Record<string, string>) => Record<string, string>;
}): PersonaThemePlugin;

/**
 * Context provided to component renderers
 */
interface ComponentContext {
    message: AgentWidgetMessage;
    config: AgentWidgetConfig;
    /**
     * Update component props during streaming
     */
    updateProps: (newProps: Record<string, unknown>) => void;
}
/**
 * Component renderer function signature
 */
type ComponentRenderer = (props: Record<string, unknown>, context: ComponentContext) => HTMLElement;
/**
 * Component registry for managing custom components
 */
declare class ComponentRegistry {
    private components;
    /**
     * Register a custom component
     */
    register(name: string, renderer: ComponentRenderer): void;
    /**
     * Unregister a component
     */
    unregister(name: string): void;
    /**
     * Get a component renderer by name
     */
    get(name: string): ComponentRenderer | undefined;
    /**
     * Check if a component is registered
     */
    has(name: string): boolean;
    /**
     * Get all registered component names
     */
    getAllNames(): string[];
    /**
     * Clear all registered components
     */
    clear(): void;
    /**
     * Register multiple components at once
     */
    registerAll(components: Record<string, ComponentRenderer>): void;
}
/**
 * Global component registry instance
 */
declare const componentRegistry: ComponentRegistry;

/**
 * Represents a component directive extracted from JSON
 */
interface ComponentDirective {
    component: string;
    props: Record<string, unknown>;
    raw: string;
}
/**
 * Creates a parser that extracts component directives from JSON streams
 * This parser looks for objects with a "component" field and extracts
 * the component name and props incrementally as they stream in.
 */
declare function createComponentStreamParser(): {
    /**
     * Get the currently extracted component directive
     */
    getExtractedDirective: () => ComponentDirective | null;
    /**
     * Process a chunk of JSON and extract component directive if present
     */
    processChunk: (accumulatedContent: string) => ComponentDirective | null;
    /**
     * Reset the parser state
     */
    reset: () => void;
};
/**
 * Type guard to check if an object is a component directive
 */
declare function isComponentDirectiveType(obj: unknown): obj is ComponentDirective;

/**
 * Options for component middleware
 */
interface ComponentMiddlewareOptions {
    config: AgentWidgetConfig;
    message: AgentWidgetMessage;
    transform: MessageTransform;
    onPropsUpdate?: (props: Record<string, unknown>) => void;
}
/**
 * Renders a component directive into an HTMLElement
 */
declare function renderComponentDirective(directive: ComponentDirective, options: ComponentMiddlewareOptions): HTMLElement | null;
/**
 * Creates middleware that processes component directives from streamed JSON
 */
declare function createComponentMiddleware(): {
    /**
     * Process accumulated content and extract component directive
     */
    processChunk: (accumulatedContent: string) => ComponentDirective | null;
    /**
     * Get the currently extracted directive
     */
    getDirective: () => ComponentDirective | null;
    /**
     * Reset the parser state
     */
    reset: () => void;
};
/**
 * Checks if a message contains a component directive.
 *
 * Looks at `rawContent` first (the field set by stream parsers); falls back
 * to `content` when it looks like JSON, so injected messages that pass the
 * directive via `content` (or have no `rawContent`) are still recognized.
 */
declare function hasComponentDirective(message: AgentWidgetMessage): boolean;
/**
 * Extracts component directive from a complete message.
 *
 * Looks at `rawContent` first (the field set by stream parsers); falls back
 * to `content` when it looks like JSON, so injected messages that pass the
 * directive via `content` (or have no `rawContent`) render the same as
 * streamed ones.
 */
declare function extractComponentDirectiveFromMessage(message: AgentWidgetMessage): ComponentDirective | null;

/**
 * Default width for the floating launcher panel (when not overridden).
 * Benchmarks: many chat products use ~300–400px; 400px is a frequent “standard” default.
 * We use 440px to better fit code/JSON and structured replies while staying responsive via `min(..., 100vw)`.
 */
declare const DEFAULT_FLOATING_LAUNCHER_WIDTH = "min(440px, calc(100vw - 24px))";
/** Max width cap paired with {@link DEFAULT_FLOATING_LAUNCHER_WIDTH} for theme defaults. */
declare const DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH = "440px";
/**
 * Default widget configuration
 * Single source of truth for all default values
 */
declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
/**
 * Helper to deep merge user config with defaults
 * This ensures all default values are present while allowing selective overrides
 */
declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;

/**
 * A named preset containing partial widget configuration.
 * Apply with: `createAgentExperience(el, { ...PRESET_SHOP.config, apiUrl: '...' })`
 * or via IIFE: `{ ...AgentWidget.PRESETS.shop.config, apiUrl: '...' }`
 */
interface WidgetPreset {
    id: string;
    label: string;
    config: Partial<AgentWidgetConfig>;
}
/**
 * Shopping / e-commerce preset.
 * Dark header, rounded launchers, shopping-oriented copy.
 */
declare const PRESET_SHOP: WidgetPreset;
/**
 * Minimal preset.
 * Stripped-down header, no launcher button, suitable for inline embeds.
 */
declare const PRESET_MINIMAL: WidgetPreset;
/**
 * Fullscreen assistant preset.
 * No launcher, content-max-width constrained, minimal header.
 */
declare const PRESET_FULLSCREEN: WidgetPreset;
/** All named presets keyed by ID. */
declare const PRESETS: Record<string, WidgetPreset>;
/** Look up a preset by ID. */
declare function getPreset(id: string): WidgetPreset | undefined;

interface HeaderElements {
    header: HTMLElement;
    iconHolder: HTMLElement;
    headerTitle: HTMLElement;
    headerSubtitle: HTMLElement;
    closeButton: HTMLButtonElement;
    closeButtonWrapper: HTMLElement;
    clearChatButton: HTMLButtonElement | null;
    clearChatButtonWrapper: HTMLElement | null;
}
interface HeaderBuildContext {
    config?: AgentWidgetConfig;
    showClose?: boolean;
    onClose?: () => void;
    onClearChat?: () => void;
}
/**
 * Build the header section of the panel.
 * Extracted for reuse and plugin override support.
 */
declare const buildHeader: (context: HeaderBuildContext) => HeaderElements;
/**
 * Attach header elements to the container, handling placement modes.
 */
declare const attachHeaderToContainer: (container: HTMLElement, headerElements: HeaderElements, config?: AgentWidgetConfig) => void;

interface ComposerElements {
    footer: HTMLElement;
    suggestions: HTMLElement;
    composerForm: HTMLFormElement;
    textarea: HTMLTextAreaElement;
    sendButton: HTMLButtonElement;
    sendButtonWrapper: HTMLElement;
    micButton: HTMLButtonElement | null;
    micButtonWrapper: HTMLElement | null;
    statusText: HTMLElement;
    attachmentButton: HTMLButtonElement | null;
    attachmentButtonWrapper: HTMLElement | null;
    attachmentInput: HTMLInputElement | null;
    attachmentPreviewsContainer: HTMLElement | null;
    actionsRow: HTMLElement;
    leftActions: HTMLElement;
    rightActions: HTMLElement;
    /**
     * Swap the send button between its idle ("send") appearance and its
     * streaming ("stop") appearance. In icon mode this swaps the SVG; in text
     * mode it swaps the button label. Tooltip text is updated when a tooltip
     * element is present.
     */
    setSendButtonMode: (mode: "send" | "stop") => void;
}
interface ComposerBuildContext {
    config?: AgentWidgetConfig;
    onSubmit?: (text: string) => void;
    disabled?: boolean;
}
/**
 * Build the full footer + composer form (column-stacked card layout) for
 * the floating, docked, and inline-embed launcher modes. The pill variant
 * for `mountMode: "composer-bar"` lives in `pill-composer-builder.ts` and
 * shares the same low-level part factories from `composer-parts.ts`.
 */
declare const buildComposer: (context: ComposerBuildContext) => ComposerElements;

interface HeaderLayoutContext {
    config: AgentWidgetConfig;
    showClose?: boolean;
    onClose?: () => void;
    onClearChat?: () => void;
    /** Passed from `buildHeaderWithLayout` for minimal/default chrome extensions */
    layoutHeaderConfig?: AgentWidgetHeaderLayoutConfig;
    onHeaderAction?: (actionId: string) => void;
}
type HeaderLayoutRenderer = (context: HeaderLayoutContext) => HeaderElements;
/**
 * Build default header layout
 * Full header with icon, title, subtitle, clear chat, and close button
 */
declare const buildDefaultHeader: HeaderLayoutRenderer;
declare const buildMinimalHeader: HeaderLayoutRenderer;
/**
 * Header layout registry
 * Maps layout names to their renderer functions
 */
declare const headerLayouts: Record<string, HeaderLayoutRenderer>;
/**
 * Get header layout renderer by name
 */
declare const getHeaderLayout: (layoutName: string) => HeaderLayoutRenderer;
/**
 * Build header based on layout configuration
 * Applies layout config settings to determine which layout to use
 */
declare const buildHeaderWithLayout: (config: AgentWidgetConfig, layoutConfig?: AgentWidgetHeaderLayoutConfig, context?: Partial<HeaderLayoutContext>) => HeaderElements;

type CodeFormat = "esm" | "script-installer" | "script-manual" | "script-advanced" | "react-component" | "react-advanced";
/**
 * Hook code templates for code generation.
 * Each hook can be provided as a string (code template) OR as an actual function.
 * Functions are automatically serialized via `.toString()`.
 *
 * IMPORTANT: When providing functions:
 * - Functions must be self-contained (no external variables/closures)
 * - External variables will be undefined when the generated code runs
 * - Use arrow functions or regular function expressions
 *
 * @example
 * ```typescript
 * // Both of these work:
 *
 * // As string:
 * { getHeaders: "async () => ({ 'Authorization': 'Bearer token' })" }
 *
 * // As function (recommended - better IDE support):
 * { getHeaders: async () => ({ 'Authorization': 'Bearer token' }) }
 * ```
 */
type CodeGeneratorHooks = {
    /**
     * Custom getHeaders function.
     * Should return an object with header key-value pairs.
     *
     * @example
     * ```typescript
     * async () => ({ 'Authorization': `Bearer ${await getAuthToken()}` })
     * ```
     */
    getHeaders?: string | (() => Record<string, string> | Promise<Record<string, string>>);
    /**
     * Custom onFeedback callback for message actions.
     * Receives a feedback object with type, messageId, and message.
     *
     * @example
     * ```typescript
     * (feedback) => { console.log('Feedback:', feedback.type); }
     * ```
     */
    onFeedback?: string | ((feedback: {
        type: string;
        messageId: string;
        message: unknown;
    }) => void);
    /**
     * Custom onCopy callback for message actions.
     * Receives the message that was copied.
     *
     * @example
     * ```typescript
     * (message) => { analytics.track('message_copied', { id: message.id }); }
     * ```
     */
    onCopy?: string | ((message: unknown) => void);
    /**
     * Custom requestMiddleware function.
     * Receives { payload, config } context.
     *
     * @example
     * ```typescript
     * ({ payload }) => ({ ...payload, metadata: { pageUrl: window.location.href } })
     * ```
     */
    requestMiddleware?: string | ((context: {
        payload: unknown;
        config: unknown;
    }) => unknown);
    /**
     * Custom action handlers array.
     * Array of handler functions.
     *
     * @example
     * ```typescript
     * [
     *   (action, context) => {
     *     if (action.type === 'custom') {
     *       return { handled: true };
     *     }
     *   }
     * ]
     * ```
     */
    actionHandlers?: string | Array<(action: unknown, context: unknown) => unknown>;
    /**
     * Custom action parsers array.
     * Array of parser functions.
     */
    actionParsers?: string | Array<(context: unknown) => unknown>;
    /**
     * Custom postprocessMessage function.
     * Receives { text, message, streaming, raw } context.
     * Will override the default markdownPostprocessor.
     *
     * @example
     * ```typescript
     * ({ text }) => customMarkdownProcessor(text)
     * ```
     */
    postprocessMessage?: string | ((context: {
        text: string;
        message?: unknown;
        streaming?: boolean;
        raw?: string;
    }) => string);
    /**
     * Custom context providers array.
     * Array of provider functions.
     */
    contextProviders?: string | Array<() => unknown>;
    /**
     * Custom stream parser factory.
     * Should be a function that returns a StreamParser.
     */
    streamParser?: string | (() => unknown);
};
/**
 * Options for code generation beyond format selection.
 */
type CodeGeneratorOptions = {
    /**
     * Custom hook code to inject into the generated snippet.
     * Hooks are JavaScript/TypeScript code strings that will be
     * inserted at appropriate locations in the output.
     */
    hooks?: CodeGeneratorHooks;
    /**
     * Whether to include comments explaining each hook.
     * @default true
     */
    includeHookComments?: boolean;
    /**
     * If provided, emits `windowKey` in the generated `initAgentWidget()` call
     * so the widget handle is stored on `window[windowKey]`.
     * Only affects script formats (script-installer, script-manual, script-advanced).
     */
    windowKey?: string;
    /**
     * CSS selector for the mount target. When omitted, the widget mounts on
     * `body` (the existing default). When provided, the generated snippet mounts
     * into that element: ESM / React / manual / advanced formats emit it as the
     * `target` argument to `initAgentWidget()`, and `script-installer` serializes
     * it into `data-config` (the installer reads `config.target`).
     * @default "body"
     */
    target?: string;
};
declare function generateCodeSnippet(config: any, format?: CodeFormat, options?: CodeGeneratorOptions): string;

interface DemoCarouselItem {
    /** URL to load in the iframe (relative or absolute). */
    url: string;
    /** Display title shown in the toolbar. */
    title: string;
    /** Optional subtitle/description. */
    description?: string;
}
interface DemoCarouselOptions {
    /** Demo pages to cycle through. */
    items: DemoCarouselItem[];
    /** Initial item index. Default: 0. */
    initialIndex?: number;
    /** Initial device viewport. Default: 'desktop'. */
    initialDevice?: "desktop" | "mobile";
    /** Initial color scheme for the iframe wrapper. Default: 'light'. */
    initialColorScheme?: "light" | "dark";
    /** Show zoom +/- controls. Default: true. */
    showZoomControls?: boolean;
    /** Show desktop/mobile toggle. Default: true. */
    showDeviceToggle?: boolean;
    /** Show light/dark scheme toggle. Default: true. */
    showColorSchemeToggle?: boolean;
    /** Called when the active demo changes. */
    onChange?: (index: number, item: DemoCarouselItem) => void;
}
interface DemoCarouselHandle {
    /** Root element (already appended to the container). */
    element: HTMLElement;
    /** Navigate to a demo by index. */
    goTo(index: number): void;
    /** Go to the next demo. */
    next(): void;
    /** Go to the previous demo. */
    prev(): void;
    /** Current demo index. */
    getIndex(): number;
    /** Change the device viewport. */
    setDevice(device: "desktop" | "mobile"): void;
    /** Change the wrapper color scheme. */
    setColorScheme(scheme: "light" | "dark"): void;
    /** Override zoom level (null = auto-fit). */
    setZoom(zoom: number | null): void;
    /** Tear down listeners, observer, and DOM. */
    destroy(): void;
}
declare function createDemoCarousel(container: HTMLElement, options: DemoCarouselOptions): DemoCarouselHandle;

export { ASK_USER_QUESTION_CLIENT_TOOL, ASK_USER_QUESTION_PARAMETERS_SCHEMA, ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetActionContext, type AgentWidgetActionEventPayload, type AgentWidgetActionHandler, type AgentWidgetActionHandlerResult, type AgentWidgetActionParser, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetApprovalDecisionOptions, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComponentRenderer, type AgentWidgetComposerConfig, type AgentWidgetConfig, type AgentWidgetContextProvider, type AgentWidgetContextProviderContext, type AgentWidgetController, type AgentWidgetControllerEventMap, type AgentWidgetCustomFetch, type AgentWidgetDockConfig, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetLoadingIndicatorConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetParsedAction, type AgentWidgetPlugin, type AgentWidgetReadAloudEvent, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, type AgentWidgetScrollBehaviorFeature, type AgentWidgetScrollMode, type AgentWidgetScrollRestorePosition, type AgentWidgetScrollToBottomFeature, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type AgentWidgetVoiceStatusEvent, type AgentWidgetWebMcpConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, type AskUserQuestionOption, type AskUserQuestionPayload, type AskUserQuestionPrompt, AttachmentManager, type AttachmentManagerConfig, type BorderScale, BrowserSpeechEngine, type BrowserSpeechEngineOptions, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type ClientToolDefinition, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComboButtonHandle, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateComboButtonOptions, type CreateDropdownOptions, type CreateIconButtonOptions, type CreateLabelButtonOptions, type CreateStandardBubbleOptions, type CreateThemeOptions, type CreateToggleGroupOptions, DEFAULT_COMPONENTS, DEFAULT_FLOATING_LAUNCHER_MAX_WIDTH, DEFAULT_FLOATING_LAUNCHER_WIDTH, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DemoCarouselHandle, type DemoCarouselItem, type DemoCarouselOptions, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FallbackSpeechEngineOptions, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IconName, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectComponentDirectiveOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, type LabelButtonTokens, type LoadingIndicatorRenderContext, type LoadingIndicatorRenderer, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageContent, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, PRESETS, PRESET_FULLSCREEN, PRESET_MINIMAL, PRESET_SHOP, type ParseOptionsConfig, type ParseRule, type PcmStreamPlayer, type PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, ReadAloudController, type ReadAloudListener, type ReadAloudState, type ResolvedTarget, type RuleScoringContext, type RuntypeClientChatRequest, type RuntypeClientChatStreamEvent, type RuntypeClientFeedbackRequest, type RuntypeClientFeedbackResponse, type RuntypeClientFeedbackType, type RuntypeClientInitRequest, type RuntypeClientInitResponse, type RuntypeClientResumeRequest, type RuntypeClientResumeStreamEvent, type RuntypeExecutionStreamEvent, type RuntypeFlowSSEEvent, type RuntypeStepCompleteEvent, type RuntypeStopReasonKind, type RuntypeStreamEventOf, type RuntypeTurnCompleteEvent, type SSEEventCallback, type SSEEventRecord, SUGGEST_REPLIES_CLIENT_TOOL, SUGGEST_REPLIES_PARAMETERS_SCHEMA, SUGGEST_REPLIES_TOOL_NAME, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, type SpeechCallbacks, type SpeechEngine, type SpeechRequest, type StreamAnimationContext, type StreamAnimationPlugin, THEME_ZONES, type TargetResolver, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceMetrics, type VoicePlaybackEngine, type VoiceProvider, type VoiceResult, type VoiceStatus, WEBMCP_TOOL_PREFIX, WebMcpBridge, type WebMcpConfirmHandler, type WebMcpConfirmInfo, type WebMcpToolResult, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, builtInClientToolsForDispatch, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createAskUserQuestionBubble, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDemoCarousel, createDirectivePostprocessor, createDropdownMenu, createFlexibleJsonStreamParser, createIconButton, createImagePart, createJsonStreamParser, createLabelButton, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createToggleGroup, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, ensureAskUserQuestionSheet, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isAskUserQuestionMessage, isComponentDirectiveType, isDockedMountMode, isSuggestRepliesMessage, isVoiceSupported, isWebMcpToolName, latestAgentSuggestions, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, parseSuggestRepliesPayload, pickBestVoice, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, renderLucideIcon, resolveDockConfig, resolveSanitizer, resolveTokens, stripWebMcpPrefix, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };