@runtypelabs/persona 3.17.0 → 3.19.0

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { IconNode } from 'lucide';
+
 /**
  * Plugin interface for customizing widget components
  */
@@ -91,6 +93,61 @@ interface AgentWidgetPlugin {
         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 null to use default renderer
@@ -384,6 +441,18 @@ interface MessageTokens {
     /** 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. */
@@ -581,6 +650,8 @@ interface ComponentTokens {
     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;
@@ -829,6 +900,31 @@ type AgentMessageMetadata = {
      * 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;
+    /**
+     * 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;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -876,6 +972,8 @@ type AgentWidgetActionHandler = (action: AgentWidgetParsedAction, context: Agent
 type AgentWidgetStoredState = {
     messages?: AgentWidgetMessage[];
     metadata?: Record<string, unknown>;
+    artifacts?: PersonaArtifactRecord[];
+    selectedArtifactId?: string | null;
 };
 interface AgentWidgetStorageAdapter {
     load?: () => AgentWidgetStoredState | null | Promise<AgentWidgetStoredState | null>;
@@ -1433,6 +1531,113 @@ type AgentWidgetFeatureFlags = {
     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;
+};
+/**
+ * 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;
+    /** 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;
@@ -1574,6 +1779,101 @@ type AgentWidgetDockConfig = {
      */
     reveal?: "resize" | "overlay" | "push" | "emerge";
 };
+/**
+ * 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;
@@ -1588,14 +1888,22 @@ type AgentWidgetLauncherConfig = {
      * 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";
+    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;
     /**
@@ -3288,6 +3596,17 @@ type AgentWidgetConfig = {
     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;
@@ -3668,6 +3987,13 @@ type AgentWidgetConfig = {
      * 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
@@ -3690,6 +4016,14 @@ type AgentWidgetConfig = {
      *   }
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Ephemeral widget — no message history written anywhere
+     * config: {
+     *   persistState: false
+     * }
+     * ```
      */
     persistState?: boolean | AgentWidgetPersistStateConfig;
     /**
@@ -4157,6 +4491,22 @@ declare class AgentWidgetClient {
         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.
+     *
+     * Posts to the upstream `/resume` endpoint (the dispatch URL with
+     * `/dispatch` replaced by `/resume` — works for both direct-to-Runtype
+     * and the persona proxy) and 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 tool name → the tool's result value.
+     */
+    resumeFlow(executionId: string, toolOutputs: Record<string, unknown>, options?: {
+        streamResponse?: boolean;
+    }): Promise<Response>;
     private buildAgentPayload;
     private buildPayload;
     /**
@@ -4419,6 +4769,37 @@ declare class AgentWidgetSession {
      * and pipes the response stream through connectStream().
      */
     resolveApproval(approval: AgentWidgetApproval, decision: 'approved' | 'denied'): 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>;
     cancel(): void;
     clearMessages(): void;
     getArtifacts(): PersonaArtifactRecord[];
@@ -4431,6 +4812,7 @@ declare class AgentWidgetSession {
     private emitArtifactsState;
     private applyArtifactStreamEvent;
     hydrateMessages(messages: AgentWidgetMessage[]): void;
+    hydrateArtifacts(artifacts: PersonaArtifactRecord[], selectedId?: string | null): void;
     private handleEvent;
     private setStatus;
     private setStreaming;
@@ -4592,6 +4974,10 @@ type Controller = {
     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.
@@ -4614,6 +5000,39 @@ type AgentWidgetInitHandle = AgentWidgetController & {
 };
 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;
+
 type WidgetHostLayoutMode = "direct" | "docked";
 type WidgetHostLayout = {
     mode: WidgetHostLayoutMode;
@@ -5333,6 +5752,161 @@ interface DropdownMenuHandle {
  */
 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"). */
@@ -6044,8 +6618,10 @@ interface ComposerBuildContext {
     disabled?: boolean;
 }
 /**
- * Build the composer/footer section of the panel.
- * Extracted for reuse and plugin override support.
+ * 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;
 
@@ -6084,4 +6660,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 AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, 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_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 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, type StreamAnimationContext, type StreamAnimationPlugin, 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, 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, escapeHtml, extractComponentDirectiveFromMessage, fileToImagePart, formatEnrichedContext, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateStableSelector, generateUserMessageId, getActiveTheme, getColorScheme, getDisplayText, getHeaderLayout, getImageParts, getPreset, hasComponentDirective, hasImages, headerLayouts, highContrastPlugin, initAgentWidget, isComponentDirectiveType, isDockedMountMode, isVoiceSupported, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, renderComponentDirective, renderLoadingIndicatorWithFallback, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };
+export { ASK_USER_QUESTION_TOOL_NAME, type AgentConfig, type AgentExecutionState, type AgentLoopConfig, type AgentMessageMetadata, type AgentRequestOptions, type AgentToolsConfig, type AgentWidgetAgentRequestPayload, type AgentWidgetApproval, type AgentWidgetApprovalConfig, type AgentWidgetArtifactsFeature, type AgentWidgetArtifactsLayoutConfig, type AgentWidgetAskUserQuestionFeature, type AgentWidgetAskUserQuestionStyles, 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 AgentWidgetStreamAnimationBuffer, type AgentWidgetStreamAnimationBuiltinType, type AgentWidgetStreamAnimationFeature, type AgentWidgetStreamAnimationPlaceholder, type AgentWidgetStreamAnimationType, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTimestampConfig, type ArtifactConfigPayload, type ArtifactPaneTokens, type ArtifactTabTokens, type ArtifactToolbarTokens, type AskUserQuestionOption, type AskUserQuestionPayload, type AskUserQuestionPrompt, 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_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 FormatEnrichedContextOptions, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type IconButtonTokens, type IconName, 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, type StreamAnimationContext, type StreamAnimationPlugin, 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, 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, isVoiceSupported, listRegisteredStreamAnimations, markdownPostprocessor, mergeWithDefaults, normalizeContent, parseAskUserQuestionPayload, pluginRegistry, reducedMotionPlugin, registerStreamAnimationPlugin, removeAskUserQuestionSheet, renderComponentDirective, renderLoadingIndicatorWithFallback, renderLucideIcon, resolveDockConfig, resolveSanitizer, resolveTokens, themeToCssVariables, unregisterStreamAnimationPlugin, validateImageFile, validateTheme };