@runtypelabs/persona 2.3.1 → 3.1.0

package/dist/index.d.ts

@@ -165,6 +165,456 @@ interface AgentWidgetPlugin {
     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;
+    [key: string]: ColorShade;
+}
+interface SpacingScale {
+    0: string;
+    1: string;
+    2: string;
+    3: string;
+    4: string;
+    5: string;
+    6: string;
+    8: string;
+    10: string;
+    12: string;
+    16: string;
+    20: string;
+    24: string;
+    32: string;
+    40: string;
+    48: string;
+    56: string;
+    64: string;
+    [key: string]: string;
+}
+interface ShadowScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+    [key: string]: string;
+}
+interface BorderScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    [key: string]: string;
+}
+interface RadiusScale {
+    none: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    full: string;
+    [key: string]: string;
+}
+interface TypographyScale {
+    fontFamily: {
+        sans: string;
+        serif: string;
+        mono: string;
+    };
+    fontSize: {
+        xs: string;
+        sm: string;
+        base: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        '3xl': string;
+        '4xl': string;
+    };
+    fontWeight: {
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+    };
+    lineHeight: {
+        tight: string;
+        normal: string;
+        relaxed: string;
+    };
+}
+interface SemanticColors {
+    primary: TokenReference<'color'>;
+    secondary: TokenReference<'color'>;
+    accent: TokenReference<'color'>;
+    surface: TokenReference<'color'>;
+    background: TokenReference<'color'>;
+    container: TokenReference<'color'>;
+    text: TokenReference<'color'>;
+    textMuted: TokenReference<'color'>;
+    textInverse: TokenReference<'color'>;
+    border: TokenReference<'color'>;
+    divider: TokenReference<'color'>;
+    interactive: {
+        default: TokenReference<'color'>;
+        hover: TokenReference<'color'>;
+        focus: TokenReference<'color'>;
+        active: TokenReference<'color'>;
+        disabled: TokenReference<'color'>;
+    };
+    feedback: {
+        success: TokenReference<'color'>;
+        warning: TokenReference<'color'>;
+        error: TokenReference<'color'>;
+        info: TokenReference<'color'>;
+    };
+}
+interface SemanticSpacing {
+    xs: TokenReference<'spacing'>;
+    sm: TokenReference<'spacing'>;
+    md: TokenReference<'spacing'>;
+    lg: TokenReference<'spacing'>;
+    xl: TokenReference<'spacing'>;
+    '2xl': TokenReference<'spacing'>;
+}
+interface SemanticTypography {
+    fontFamily: TokenReference<'typography'>;
+    fontSize: TokenReference<'typography'>;
+    fontWeight: TokenReference<'typography'>;
+    lineHeight: TokenReference<'typography'>;
+}
+interface SemanticTokens {
+    colors: SemanticColors;
+    spacing: SemanticSpacing;
+    typography: SemanticTypography;
+}
+interface ComponentTokenSet {
+    background?: TokenReference<'color'>;
+    foreground?: TokenReference<'color'>;
+    border?: TokenReference<'color'>;
+    borderRadius?: TokenReference<'radius'>;
+    padding?: TokenReference<'spacing'>;
+    margin?: TokenReference<'spacing'>;
+    shadow?: TokenReference<'shadow'>;
+    opacity?: number;
+}
+interface ButtonTokens extends ComponentTokenSet {
+    primary: ComponentTokenSet;
+    secondary: ComponentTokenSet;
+    ghost: ComponentTokenSet;
+}
+interface InputTokens extends ComponentTokenSet {
+    background: TokenReference<'color'>;
+    placeholder: TokenReference<'color'>;
+    focus: {
+        border: TokenReference<'color'>;
+        ring: TokenReference<'color'>;
+    };
+}
+interface LauncherTokens extends ComponentTokenSet {
+    size: string;
+    iconSize: string;
+    shadow: TokenReference<'shadow'>;
+}
+interface PanelTokens extends ComponentTokenSet {
+    width: string;
+    maxWidth: string;
+    height: string;
+    maxHeight: string;
+}
+interface HeaderTokens extends ComponentTokenSet {
+    background: TokenReference<'color'>;
+    border: TokenReference<'color'>;
+    borderRadius: TokenReference<'radius'>;
+    /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
+    iconBackground: TokenReference<'color'>;
+    /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
+    iconForeground: TokenReference<'color'>;
+    /** Header title line (next to the icon, or minimal layout title). */
+    titleForeground: TokenReference<'color'>;
+    /** Header subtitle line under the title. */
+    subtitleForeground: TokenReference<'color'>;
+    /** Default color for clear / close icon buttons when launcher overrides are unset. */
+    actionIconForeground: TokenReference<'color'>;
+    /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
+    shadow?: string;
+    /** Override the header bottom border (e.g., `none`). */
+    borderBottom?: string;
+}
+interface MessageTokens {
+    user: {
+        background: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+        borderRadius: TokenReference<'radius'>;
+        /** User bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+        shadow?: string;
+    };
+    assistant: {
+        background: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+        borderRadius: TokenReference<'radius'>;
+        /** Assistant bubble border color (CSS color). */
+        border?: TokenReference<'color'>;
+        /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
+        shadow?: string;
+    };
+}
+interface MarkdownTokens {
+    inlineCode: {
+        background: TokenReference<'color'>;
+        foreground: TokenReference<'color'>;
+    };
+    /** Foreground for `<a>` in rendered markdown (assistant bubbles + artifact pane). */
+    link?: {
+        foreground: TokenReference<'color'>;
+    };
+    /**
+     * Body font for rendered markdown blocks (artifact pane + markdown bubbles).
+     * Use a raw CSS `font-family` value, e.g. `Georgia, serif`.
+     */
+    prose?: {
+        fontFamily?: string;
+    };
+    /** Optional heading scale overrides (raw CSS or resolvable token paths). */
+    heading?: {
+        h1?: {
+            fontSize?: string;
+            fontWeight?: string;
+        };
+        h2?: {
+            fontSize?: string;
+            fontWeight?: string;
+        };
+    };
+}
+interface VoiceTokens {
+    recording: {
+        indicator: TokenReference<'color'>;
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+    };
+    processing: {
+        icon: TokenReference<'color'>;
+        background: TokenReference<'color'>;
+    };
+    speaking: {
+        icon: TokenReference<'color'>;
+    };
+}
+interface ApprovalTokens {
+    requested: {
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+        text: TokenReference<'color'>;
+    };
+    approve: ComponentTokenSet;
+    deny: ComponentTokenSet;
+}
+interface AttachmentTokens {
+    image: {
+        background: TokenReference<'color'>;
+        border: TokenReference<'color'>;
+    };
+}
+/** Tool-call row chrome (collapsible tool bubbles). */
+interface ToolBubbleTokens {
+    /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
+    shadow: string;
+}
+/** Reasoning / “thinking” row chrome. */
+interface ReasoningBubbleTokens {
+    shadow: string;
+}
+/** Composer (message input) chrome. */
+interface ComposerChromeTokens {
+    /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
+    shadow: string;
+}
+/** Artifact toolbar chrome. */
+interface ArtifactToolbarTokens {
+    iconHoverColor?: string;
+    iconHoverBackground?: string;
+    iconPadding?: string;
+    iconBorderRadius?: string;
+    iconBorder?: string;
+    toggleGroupGap?: string;
+    toggleBorderRadius?: string;
+    copyBackground?: string;
+    copyBorder?: string;
+    copyColor?: string;
+    copyBorderRadius?: string;
+    copyPadding?: string;
+    copyMenuBackground?: string;
+    copyMenuBorder?: string;
+    copyMenuShadow?: string;
+    copyMenuBorderRadius?: string;
+    copyMenuItemHoverBackground?: string;
+    /** Base background of icon buttons (defaults to --persona-surface). */
+    iconBackground?: string;
+    /** Border on the toolbar (e.g., `none` to remove the bottom border). */
+    toolbarBorder?: string;
+}
+/** Artifact tab strip chrome. */
+interface ArtifactTabTokens {
+    background?: string;
+    activeBackground?: string;
+    activeBorder?: string;
+    borderRadius?: string;
+    textColor?: string;
+    /** Hover background for inactive tabs. */
+    hoverBackground?: string;
+    /** Tab list container background. */
+    listBackground?: string;
+    /** Tab list container border color. */
+    listBorderColor?: string;
+    /** Tab list container padding (CSS shorthand). */
+    listPadding?: string;
+}
+/** Artifact pane chrome. */
+interface ArtifactPaneTokens {
+    /**
+     * Background for the artifact column (toolbar + content), resolved from the theme.
+     * Defaults to `semantic.colors.container` so the pane matches assistant message surfaces.
+     * `features.artifacts.layout.paneBackground` still wins when set (layout escape hatch).
+     */
+    background?: string;
+    toolbarBackground?: string;
+}
+/** Icon button chrome (used by createIconButton). */
+interface IconButtonTokens {
+    background?: string;
+    border?: string;
+    color?: string;
+    padding?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    hoverColor?: string;
+    /** Background when aria-pressed="true". */
+    activeBackground?: string;
+    /** Border color when aria-pressed="true". */
+    activeBorder?: string;
+}
+/** Label button chrome (used by createLabelButton). */
+interface LabelButtonTokens {
+    background?: string;
+    border?: string;
+    color?: string;
+    padding?: string;
+    borderRadius?: string;
+    hoverBackground?: string;
+    fontSize?: string;
+    gap?: string;
+}
+/** Toggle group chrome (used by createToggleGroup). */
+interface ToggleGroupTokens {
+    /** Gap between toggle buttons. Default: 0 (connected). */
+    gap?: string;
+    /** Border radius for first/last buttons. */
+    borderRadius?: string;
+}
+interface ComponentTokens {
+    button: ButtonTokens;
+    input: InputTokens;
+    launcher: LauncherTokens;
+    panel: PanelTokens;
+    header: HeaderTokens;
+    message: MessageTokens;
+    /** Markdown surfaces (chat + artifact pane). */
+    markdown?: MarkdownTokens;
+    voice: VoiceTokens;
+    approval: ApprovalTokens;
+    attachment: AttachmentTokens;
+    toolBubble: ToolBubbleTokens;
+    reasoningBubble: ReasoningBubbleTokens;
+    composer: ComposerChromeTokens;
+    /** Icon button styling tokens. */
+    iconButton?: IconButtonTokens;
+    /** Label button styling tokens. */
+    labelButton?: LabelButtonTokens;
+    /** Toggle group styling tokens. */
+    toggleGroup?: ToggleGroupTokens;
+    /** Artifact toolbar, tab strip, and pane chrome. */
+    artifact?: {
+        toolbar?: ArtifactToolbarTokens;
+        tab?: ArtifactTabTokens;
+        pane?: ArtifactPaneTokens;
+    };
+}
+interface PaletteExtras {
+    transitions?: Record<string, string>;
+    easings?: Record<string, string>;
+}
+interface PersonaThemeBase {
+    palette: {
+        colors: ColorPalette;
+        spacing: SpacingScale;
+        typography: TypographyScale;
+        shadows: ShadowScale;
+        borders: BorderScale;
+        radius: RadiusScale;
+    } & PaletteExtras;
+}
+interface PersonaThemeSemantic {
+    semantic: SemanticTokens;
+}
+interface PersonaThemeComponents {
+    components: ComponentTokens;
+}
+type PersonaTheme = PersonaThemeBase & PersonaThemeSemantic & PersonaThemeComponents;
+/** Recursive partial for `config.theme` / `config.darkTheme` overrides. */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+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;
+}
+
 /**
  * Text content part for multi-modal messages
  */
@@ -580,7 +1030,9 @@ type AgentWidgetArtifactsLayoutConfig = {
      */
     unifiedSplitOuterRadius?: string;
     /**
-     * Background color for the artifact column (CSS color). Sets `--persona-artifact-pane-bg` on the widget root.
+     * 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;
     /**
@@ -646,6 +1098,20 @@ type AgentWidgetArtifactsFeature = {
         type: 'open' | 'download';
         artifactId: string;
     }) => boolean | void;
+    /**
+     * Custom renderer for artifact reference cards shown in the message thread.
+     * Return an HTMLElement to replace the default card, or `null` to use the default.
+     */
+    renderCard?: (context: {
+        artifact: {
+            artifactId: string;
+            title: string;
+            artifactType: string;
+            status: string;
+        };
+        config: AgentWidgetConfig;
+        defaultRenderer: () => HTMLElement;
+    }) => HTMLElement | null;
 };
 type AgentWidgetFeatureFlags = {
     showReasoning?: boolean;
@@ -767,84 +1233,6 @@ type EventStreamPayloadRenderContext = {
     defaultRenderer: () => HTMLElement;
     parsedPayload: unknown;
 };
-type AgentWidgetTheme = {
-    primary?: string;
-    secondary?: string;
-    surface?: string;
-    muted?: string;
-    accent?: string;
-    container?: string;
-    border?: string;
-    divider?: string;
-    messageBorder?: string;
-    inputBackground?: string;
-    callToAction?: string;
-    callToActionBackground?: string;
-    sendButtonBackgroundColor?: string;
-    sendButtonTextColor?: string;
-    sendButtonBorderColor?: string;
-    closeButtonColor?: string;
-    closeButtonBackgroundColor?: string;
-    closeButtonBorderColor?: string;
-    clearChatIconColor?: string;
-    clearChatBackgroundColor?: string;
-    clearChatBorderColor?: string;
-    tooltipBackground?: string;
-    tooltipForeground?: string;
-    micIconColor?: string;
-    micBackgroundColor?: string;
-    micBorderColor?: string;
-    recordingIconColor?: string;
-    recordingBackgroundColor?: string;
-    recordingBorderColor?: string;
-    inputFontFamily?: "sans-serif" | "serif" | "mono";
-    inputFontWeight?: string;
-    radiusSm?: string;
-    radiusMd?: string;
-    radiusLg?: string;
-    launcherRadius?: string;
-    buttonRadius?: string;
-    /**
-     * Border style for the chat panel container.
-     * @example "1px solid #e5e7eb" | "none"
-     * @default "1px solid var(--persona-border)"
-     */
-    panelBorder?: string;
-    /**
-     * Box shadow for the chat panel container.
-     * @example "0 25px 50px -12px rgba(0,0,0,0.25)" | "none"
-     * @default "0 25px 50px -12px rgba(0,0,0,0.25)"
-     */
-    panelShadow?: string;
-    /**
-     * Border radius for the chat panel container.
-     * @example "16px" | "0"
-     * @default "16px"
-     */
-    panelBorderRadius?: string;
-    /**
-     * Box-shadow for user message bubbles (bubble message layout).
-     * @example "none" | "0 1px 2px rgba(0,0,0,0.05)"
-     */
-    messageUserShadow?: string;
-    /**
-     * Box-shadow for assistant message bubbles (bubble message layout).
-     * Overrides the default subtle assistant shadow when set.
-     */
-    messageAssistantShadow?: string;
-    /**
-     * Box-shadow for tool-call / function-call rows.
-     */
-    toolBubbleShadow?: string;
-    /**
-     * Box-shadow for reasoning (“thinking”) rows.
-     */
-    reasoningBubbleShadow?: string;
-    /**
-     * Box-shadow on the composer (input) container.
-     */
-    composerShadow?: string;
-};
 type AgentWidgetDockConfig = {
     /**
      * Side of the wrapped container where the docked panel should render.
@@ -857,10 +1245,22 @@ type AgentWidgetDockConfig = {
      */
     width?: string;
     /**
-     * Width of the collapsed launcher rail when the docked panel is closed.
-     * @default "72px"
+     * 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.
      */
-    collapsedWidth?: string;
+    reveal?: "resize" | "overlay" | "push" | "emerge";
 };
 type AgentWidgetLauncherConfig = {
     enabled?: boolean;
@@ -1428,6 +1828,17 @@ type AgentWidgetHeaderTrailingAction = {
     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
@@ -1494,6 +1905,41 @@ type AgentWidgetHeaderLayoutConfig = {
      * 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
@@ -2257,22 +2703,15 @@ type AgentWidgetConfig = {
          */
         showWelcomeCard?: boolean;
     };
-    theme?: AgentWidgetTheme;
     /**
-     * Theme colors for dark mode. Applied when dark mode is detected
-     * (when colorScheme is 'dark' or 'auto' with dark mode active).
-     * If not provided, falls back to `theme` colors.
-     *
-     * @example
-     * ```typescript
-     * config: {
-     *   theme: { primary: '#111827', surface: '#ffffff' },
-     *   darkTheme: { primary: '#f9fafb', surface: '#1f2937' },
-     *   colorScheme: 'auto'
-     * }
-     * ```
+     * 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?: AgentWidgetTheme;
+    darkTheme?: DeepPartial<PersonaTheme>;
     /**
      * Color scheme mode for the widget.
      * - 'light': Always use light theme (default)
@@ -4013,6 +4452,13 @@ declare function generateUserMessageId(): string;
 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>;
 
 type CodeFormat = "esm" | "script-installer" | "script-manual" | "script-advanced" | "react-component" | "react-advanced";
@@ -4084,480 +4530,313 @@ type CodeGeneratorHooks = {
     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;
-};
-declare function generateCodeSnippet(config: any, format?: CodeFormat, options?: CodeGeneratorOptions): string;
-
-/**
- * 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;
+    }) => unknown);
     /**
-     * Unregister a plugin
+     * Custom action handlers array.
+     * Array of handler functions.
+     *
+     * @example
+     * ```typescript
+     * [
+     *   (action, context) => {
+     *     if (action.type === 'custom') {
+     *       return { handled: true };
+     *     }
+     *   }
+     * ]
+     * ```
      */
-    unregister(pluginId: string): void;
+    actionHandlers?: string | Array<(action: unknown, context: unknown) => unknown>;
     /**
-     * Get all plugins sorted by priority
+     * Custom action parsers array.
+     * Array of parser functions.
      */
-    getAll(): AgentWidgetPlugin[];
+    actionParsers?: string | Array<(context: unknown) => unknown>;
     /**
-     * Get plugins for a specific instance (from config)
-     * Merges instance plugins with globally registered plugins
+     * Custom postprocessMessage function.
+     * Receives { text, message, streaming, raw } context.
+     * Will override the default markdownPostprocessor.
+     *
+     * @example
+     * ```typescript
+     * ({ text }) => customMarkdownProcessor(text)
+     * ```
      */
-    getForInstance(instancePlugins?: AgentWidgetPlugin[]): AgentWidgetPlugin[];
+    postprocessMessage?: string | ((context: {
+        text: string;
+        message?: unknown;
+        streaming?: boolean;
+        raw?: string;
+    }) => string);
     /**
-     * Clear all plugins
-     */
-    clear(): void;
-}
-declare const pluginRegistry: PluginRegistry;
-
-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;
-    [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'>;
-}
-interface MessageTokens {
-    user: {
-        background: TokenReference<'color'>;
-        text: TokenReference<'color'>;
-        borderRadius: TokenReference<'radius'>;
-        /** User bubble box-shadow (token ref or raw CSS, e.g. `none`). */
-        shadow?: string;
-    };
-    assistant: {
-        background: TokenReference<'color'>;
-        text: TokenReference<'color'>;
-        borderRadius: TokenReference<'radius'>;
-        /** Assistant bubble border color (CSS color). */
-        border?: TokenReference<'color'>;
-        /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
-        shadow?: string;
-    };
-}
-interface MarkdownTokens {
-    inlineCode: {
-        background: TokenReference<'color'>;
-        foreground: TokenReference<'color'>;
-    };
-    /** Foreground for `<a>` in rendered markdown (assistant bubbles + artifact pane). */
-    link?: {
-        foreground: TokenReference<'color'>;
-    };
+     * Custom context providers array.
+     * Array of provider functions.
+     */
+    contextProviders?: string | Array<() => unknown>;
     /**
-     * Body font for rendered markdown blocks (artifact pane + markdown bubbles).
-     * Use a raw CSS `font-family` value, e.g. `Georgia, serif`.
+     * Custom stream parser factory.
+     * Should be a function that returns a StreamParser.
      */
-    prose?: {
-        fontFamily?: string;
-    };
-    /** Optional heading scale overrides (raw CSS or resolvable token paths). */
-    heading?: {
-        h1?: {
-            fontSize?: string;
-            fontWeight?: string;
-        };
-        h2?: {
-            fontSize?: string;
-            fontWeight?: string;
-        };
-    };
-}
-interface VoiceTokens {
-    recording: {
-        indicator: TokenReference<'color'>;
-        background: TokenReference<'color'>;
-        border: TokenReference<'color'>;
-    };
-    processing: {
-        icon: TokenReference<'color'>;
-        background: TokenReference<'color'>;
-    };
-    speaking: {
-        icon: TokenReference<'color'>;
-    };
+    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;
+};
+declare function generateCodeSnippet(config: any, format?: CodeFormat, options?: CodeGeneratorOptions): string;
+
+/**
+ * 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;
 }
-interface ApprovalTokens {
-    requested: {
-        background: TokenReference<'color'>;
-        border: TokenReference<'color'>;
-        text: TokenReference<'color'>;
-    };
-    approve: ComponentTokenSet;
-    deny: ComponentTokenSet;
+declare const pluginRegistry: PluginRegistry;
+
+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 AttachmentTokens {
-    image: {
-        background: TokenReference<'color'>;
-        border: TokenReference<'color'>;
-    };
+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;
 }
-/** Tool-call row chrome (collapsible tool bubbles). */
-interface ToolBubbleTokens {
-    /** Box-shadow for tool bubbles (token ref or raw CSS, e.g. `none`). */
-    shadow: string;
+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;
 }
-/** Reasoning / “thinking” row chrome. */
-interface ReasoningBubbleTokens {
-    shadow: string;
+/**
+ * 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;
+
+/** 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>;
 }
-/** Composer (message input) chrome. */
-interface ComposerChromeTokens {
-    /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
-    shadow: 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>;
 }
-/** 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;
+/**
+ * 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;
 }
-/** Artifact tab strip chrome. */
-interface ArtifactTabTokens {
-    background?: string;
-    activeBackground?: string;
-    activeBorder?: string;
-    borderRadius?: string;
-    textColor?: 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;
 }
-/** Artifact pane chrome. */
-interface ArtifactPaneTokens {
-    toolbarBackground?: 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;
 }
-interface ComponentTokens {
-    button: ButtonTokens;
-    input: InputTokens;
-    launcher: LauncherTokens;
-    panel: PanelTokens;
-    header: HeaderTokens;
-    message: MessageTokens;
-    /** Markdown surfaces (chat + artifact pane). */
-    markdown?: MarkdownTokens;
-    voice: VoiceTokens;
-    approval: ApprovalTokens;
-    attachment: AttachmentTokens;
-    toolBubble: ToolBubbleTokens;
-    reasoningBubble: ReasoningBubbleTokens;
-    composer: ComposerChromeTokens;
-    /** Artifact toolbar, tab strip, and pane chrome. */
-    artifact?: {
-        toolbar?: ArtifactToolbarTokens;
-        tab?: ArtifactTabTokens;
-        pane?: ArtifactPaneTokens;
+/**
+ * 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;
     };
 }
-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;
-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;
+/** 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: {
@@ -4726,7 +5005,7 @@ 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?: Partial<PersonaTheme>, options?: CreateThemeOptions): PersonaTheme;
+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.
@@ -4747,8 +5026,8 @@ type ThemeZone = keyof typeof THEME_ZONES;
 
 type ColorScheme = 'light' | 'dark' | 'auto';
 interface PersonaWidgetConfig {
-    theme?: Partial<PersonaTheme>;
-    darkTheme?: Partial<PersonaTheme>;
+    theme?: DeepPartial<PersonaTheme>;
+    darkTheme?: DeepPartial<PersonaTheme>;
     colorScheme?: ColorScheme;
 }
 type WidgetConfig = PersonaWidgetConfig | AgentWidgetConfig;
@@ -4778,16 +5057,6 @@ declare function createPlugin(config: {
     afterResolve?: (resolved: Record<string, string>) => Record<string, string>;
 }): PersonaThemePlugin;
 
-interface V1ToV2MigrationOptions {
-    warn?: boolean;
-    colorScheme?: 'light' | 'dark' | 'auto';
-}
-declare function migrateV1Theme(v1Theme: AgentWidgetTheme | undefined, options?: V1ToV2MigrationOptions): Partial<PersonaTheme>;
-declare function validateV1Theme(v1Theme: unknown): {
-    valid: boolean;
-    warnings: string[];
-};
-
 /**
  * Context provided to component renderers
  */
@@ -4965,14 +5234,6 @@ declare function hasComponentDirective(message: AgentWidgetMessage): boolean;
  */
 declare function extractComponentDirectiveFromMessage(message: AgentWidgetMessage): ComponentDirective | null;
 
-/**
- * Default light theme colors
- */
-declare const DEFAULT_LIGHT_THEME: AgentWidgetTheme;
-/**
- * Default dark theme colors
- */
-declare const DEFAULT_DARK_THEME: AgentWidgetTheme;
 /**
  * Default widget configuration
  * Single source of truth for all default values
@@ -5104,4 +5365,4 @@ declare function createVoiceProvider(config: VoiceConfig): VoiceProvider;
 declare function createBestAvailableVoiceProvider(config?: Partial<VoiceConfig>): VoiceProvider;
 declare function isVoiceSupported(config?: Partial<VoiceConfig>): boolean;
 
-export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, 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 AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type CodeGeneratorHooks, type CodeGeneratorOptions, type ColorPalette, type ColorShade, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComponentTokens, type ComposerBuildContext, type ComposerElements, type ContentPart, type CreateStandardBubbleOptions, type CreateThemeOptions, DEFAULT_COMPONENTS, DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, DEFAULT_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DomContextMode, type DomContextOptions, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, type InjectMessageOptions, type InjectSystemMessageOptions, type InjectUserMessageOptions, 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 PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, createDirectivePostprocessor, createFlexibleJsonStreamParser, createImagePart, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createPlugin, createRegexJsonParser, createStandardBubble, createTextPart, createTheme, createThemeObserver, createTypingIndicator, createVoiceProvider, createWidgetHostLayout, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, defaultParseRules, detectColorScheme, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, markdownPostprocessor, mergeWithDefaults, migrateV1Theme, normalizeContent, pluginRegistry, reducedMotionPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, validateImageFile, validateTheme, validateV1Theme };
+export { type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAttachmentsConfig, type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetComposerConfig, type AgentWidgetConfig, 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 AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, AttachmentManager, type AttachmentManagerConfig, type BorderScale, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, 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_PALETTE, DEFAULT_SEMANTIC, DEFAULT_WIDGET_CONFIG, type DeepPartial, type DomContextMode, type DomContextOptions, type DropdownMenuHandle, type DropdownMenuItem, type EnrichedPageElement, type EventStreamBadgeColor, type EventStreamConfig, type EventStreamPayloadRenderContext, type EventStreamRowRenderContext, type EventStreamToolbarRenderContext, type EventStreamViewRenderContext, type FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IdleIndicatorRenderContext, type ImageContentPart, type InjectAssistantMessageOptions, 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 PendingAttachment, type PersonaArtifactKind, type PersonaArtifactManualUpsert, type PersonaArtifactRecord, type PersonaTheme, type PersonaThemePlugin, type RadiusScale, type RuleScoringContext, type SSEEventCallback, type SSEEventRecord, type SanitizeFunction, type SemanticColors, type SemanticSpacing, type SemanticTypography, type ShadowScale, type SlotRenderContext, type SlotRenderer, type SpacingScale, THEME_ZONES, type TextContentPart, type ThemeValidationError, type ThemeValidationResult, type ThemeZone, type ToggleGroupHandle, type ToggleGroupItem, type ToggleGroupTokens, type TokenReference, type TypographyScale, VERSION, type VoiceConfig, type VoiceProvider, type VoiceResult, type VoiceStatus, type WidgetHostLayout, type WidgetHostLayoutMode, type WidgetLayoutSlot, type WidgetPreset, accessibilityPlugin, animationsPlugin, applyThemeVariables, attachHeaderToContainer, brandPlugin, buildComposer, buildDefaultHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, collectEnrichedPageContext, componentRegistry, createActionManager, createAgentExperience, createBestAvailableVoiceProvider, createBubbleWithLayout, createCSATFeedback, createComboButton, createComponentMiddleware, createComponentStreamParser, createDefaultSanitizer, 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, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, markdownPostprocessor, mergeWithDefaults, normalizeContent, pluginRegistry, reducedMotionPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, validateImageFile, validateTheme };