@runtypelabs/persona 4.14.0 → 4.16.0

package/dist/smart-dom-reader.d.cts

@@ -269,6 +269,82 @@ interface SmartDomAdapterOptions {
  */
 declare function smartDomResultToEnriched(result: SmartDOMResult, opts?: SmartDomAdapterOptions): EnrichedPageElement[];
 
+interface ResolvedWelcomeConfig {
+    title: string;
+    subtitle: string;
+    icon?: AgentWidgetWelcomeIcon;
+    variant: AgentWidgetWelcomeVariant;
+    dismiss: AgentWidgetWelcomeDismiss;
+    /** Undefined under `variant: "hero"`, which suppresses the greeting. */
+    message?: string;
+}
+
+/**
+ * Synchronous key-value store handed to plugin render hooks. Backed by
+ * `localStorage`, namespaced per plugin id. The async `storageAdapter` cannot
+ * back a synchronous API and `persistState` is not a general key-value surface.
+ */
+interface AgentWidgetPluginStorage {
+    get: (key: string) => string | null;
+    set: (key: string, value: string) => void;
+    remove: (key: string) => void;
+}
+
+type AgentWidgetTransformSuggestionsContext = {
+    /**
+     * Fresh copy of the suggestions entering this plugin, already normalized:
+     * shorthand strings expanded and the effective send/fill behavior resolved.
+     */
+    suggestions: AgentWidgetResolvedSuggestion[];
+    surface: AgentWidgetSuggestionSurface;
+    source: AgentWidgetSuggestionSource;
+    config: AgentWidgetConfig;
+};
+type AgentWidgetRenderSuggestionContext = {
+    /** Fully normalized suggestion, including the effective send/fill behavior. */
+    suggestion: AgentWidgetResolvedSuggestion;
+    index: number;
+    surface: AgentWidgetSuggestionSurface;
+    source: AgentWidgetSuggestionSource;
+    variant: AgentWidgetSuggestionVariant;
+    streaming: boolean;
+    config: AgentWidgetConfig;
+    /** Build Persona's standard chip, card, or list item. */
+    defaultRenderer: () => HTMLElement;
+    /**
+     * Run the normal selection pipeline: DOM event, plugin selection hooks, then
+     * send or fill. Custom renderers should call this instead of sending directly.
+     */
+    select: () => void;
+};
+type AgentWidgetRenderWelcomeContext = {
+    /** Alias-resolved welcome config; never the raw `copy.welcome*` shape. */
+    config: ResolvedWelcomeConfig;
+    variant: AgentWidgetWelcomeVariant;
+    /** Derived visibility for this render; governs the default renderer only. */
+    visible: boolean;
+    /** The core-owned welcome card, live-updated by `controller.update()`. */
+    defaultRenderer: () => HTMLElement;
+    sendMessage: (text: string) => void;
+    /** Re-run welcome arbitration: cleanups run, previous content is removed. */
+    requestRender: () => void;
+    /**
+     * Persona's starter renderer, wired through the full select pipeline:
+     * `onSuggestionSelect`, cancelable `persona:suggestion:*` events, send/fill.
+     */
+    renderStarter: (suggestion: AgentWidgetSuggestion) => HTMLElement;
+    /** Sync store namespaced by `persistState.keyPrefix` plus the plugin id. */
+    storage: AgentWidgetPluginStorage;
+    /** Teardown for this render; runs before the next one and on destroy. */
+    onCleanup: (fn: () => void) => void;
+};
+type AgentWidgetSuggestionSelectContext = {
+    suggestion: AgentWidgetResolvedSuggestion;
+    surface: AgentWidgetSuggestionSurface;
+    source: AgentWidgetSuggestionSource;
+    variant: AgentWidgetSuggestionVariant;
+    config: AgentWidgetConfig;
+};
 /**
  * Plugin interface for customizing widget components
  */
@@ -281,6 +357,25 @@ interface AgentWidgetPlugin {
      * Optional priority (higher = runs first). Default: 0
      */
     priority?: number;
+    /**
+     * Transform, filter, enrich, or reorder suggestions. Hooks receive normalized
+     * items and compose in plugin priority order; the return value may use the
+     * loose shape (string shorthand included) and is re-normalized before the next
+     * hook. A per-item `behavior` set here survives. `maxItems` caps the list
+     * after the full chain. Return an empty array to hide the surface.
+     */
+    transformSuggestions?: (context: AgentWidgetTransformSuggestionsContext) => AgentWidgetSuggestion[];
+    /**
+     * Render one starter or follow-up suggestion. Return null to use Persona's
+     * default chip/card/list renderer. Call `select()` from custom interaction
+     * controls to preserve events, selection hooks, and send/fill behavior.
+     */
+    renderSuggestion?: (context: AgentWidgetRenderSuggestionContext) => HTMLElement | null;
+    /**
+     * Observe or intercept a suggestion selection. Return false to cancel the
+     * built-in send/fill action. Hooks run in plugin priority order.
+     */
+    onSuggestionSelect?: (context: AgentWidgetSuggestionSelectContext) => void | boolean;
     /**
      * Custom renderer for message bubbles
      * Return null to use default renderer
@@ -299,6 +394,34 @@ interface AgentWidgetPlugin {
         defaultRenderer: () => HTMLElement;
         onToggle: () => void;
     }) => HTMLElement | null;
+    /**
+     * Custom renderer for the welcome surface (card, hero, greeting stack).
+     * First plugin returning an element wins; null falls through to the default,
+     * same contract as `renderSuggestion`.
+     *
+     * The core owns the welcome host: it stays mounted for the panel's lifetime
+     * and content is swapped inside it. A plugin element renders regardless of
+     * `ctx.visible` (derived visibility governs the default renderer only) and
+     * the host overlays the transcript while that element is active, so a home
+     * screen can return over an existing conversation. Return null again to
+     * clear the overlay.
+     *
+     * The ctx carries no controller: plugins are host-instantiated, so close a
+     * factory over the init handle (`plugin.attach(controller)`).
+     *
+     * @example
+     * ```typescript
+     * renderWelcome: ({ config, renderStarter, requestRender, onCleanup }) => {
+     *   const root = document.createElement("div");
+     *   root.textContent = config.title;
+     *   root.appendChild(renderStarter({ label: "Track my order" }));
+     *   const timer = setInterval(requestRender, 60_000);
+     *   onCleanup(() => clearInterval(timer));
+     *   return root;
+     * }
+     * ```
+     */
+    renderWelcome?: (context: AgentWidgetRenderWelcomeContext) => HTMLElement | null;
     /**
      * Custom renderer for panel header
      * Return null to use default renderer
@@ -343,6 +466,15 @@ interface AgentWidgetPlugin {
          * Omitted when `config.voiceRecognition.enabled` is not true.
          */
         onVoiceToggle?: () => void;
+        /**
+         * Re-run composer arbitration and swap the footer in place. The hook runs
+         * once at panel construction, so this is how a composer plugin unlocks
+         * (returns null) or re-renders later. Pending attachments, the mention
+         * affordances, and the composer listener registry are re-wired by the core.
+         */
+        requestRender: () => void;
+        /** Same sync store as the `renderWelcome` ctx, namespaced per plugin id. */
+        storage: AgentWidgetPluginStorage;
     }) => HTMLElement | null;
     /**
      * Custom renderer for reasoning bubbles
@@ -723,6 +855,15 @@ interface PanelTokens extends ComponentTokenSet {
     /** Background of the region revealed behind a detached panel. */
     canvasBackground?: string;
 }
+/** Per-element text styling shared by themable text surfaces. */
+interface TextStyleTokens {
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: string;
+    lineHeight?: string;
+    letterSpacing?: string;
+    color?: TokenReference<'color'>;
+}
 interface HeaderTokens extends ComponentTokenSet {
     background: TokenReference<'color'>;
     border: TokenReference<'color'>;
@@ -731,10 +872,14 @@ interface HeaderTokens extends ComponentTokenSet {
     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). */
+    /** Legacy alias of `title.color`; `title.color` wins when both are set. */
     titleForeground: TokenReference<'color'>;
-    /** Header subtitle line under the title. */
+    /** Legacy alias of `subtitle.color`; `subtitle.color` wins when both are set. */
     subtitleForeground: TokenReference<'color'>;
+    /** Header title typography (next to the icon, or minimal layout title). */
+    title?: TextStyleTokens;
+    /** Header subtitle typography, for the line under the title. */
+    subtitle?: TextStyleTokens;
     /** 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). */
@@ -764,7 +909,7 @@ interface MessageTokens {
 }
 /**
  * Welcome / intro card rendered above the message list when no messages exist.
- * Set `copy.showWelcomeCard: false` to hide it; use `layout.slots["body-top"]`
+ * Set `welcome.variant: "none"` to hide it; use `layout.slots["body-top"]`
  * to replace it wholesale.
  */
 interface IntroCardTokens extends ComponentTokenSet {
@@ -773,6 +918,12 @@ interface IntroCardTokens extends ComponentTokenSet {
     padding?: TokenReference<'spacing'>;
     /** Box-shadow on the intro card (token ref or raw CSS, e.g. `none`). */
     shadow?: string;
+    /** Full border shorthand on the intro card (raw CSS, e.g. `"1px solid rgba(0,0,0,0.1)"`). @default "none" */
+    border?: string;
+    /** Welcome title typography. */
+    title?: TextStyleTokens;
+    /** Welcome subtitle typography. */
+    subtitle?: TextStyleTokens;
 }
 /** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
 interface CollapsibleWidgetTokens {
@@ -815,6 +966,8 @@ interface MarkdownTokens {
         background?: TokenReference<'color'>;
         borderColor?: TokenReference<'color'>;
         textColor?: TokenReference<'color'>;
+        /** Corner radius; follows `palette.radius.md` by default so square-corner themes get square code blocks. */
+        borderRadius?: TokenReference<'radius'>;
     };
     /** Table styling. */
     table?: {
@@ -872,10 +1025,27 @@ interface ToolBubbleTokens {
 interface ReasoningBubbleTokens {
     shadow: string;
 }
+/** Scrollbar appearance shared by every scroller in the widget. */
+interface ScrollbarTokens {
+    /** Thumb color. @default semantic.colors.border */
+    thumb?: TokenReference<'color'>;
+    /** Track color. @default "transparent" */
+    track?: TokenReference<'color'>;
+}
 /** Composer (message input) chrome. */
 interface ComposerChromeTokens {
     /** Box-shadow on the composer form (raw CSS, e.g. `none`). */
     shadow: string;
+    /** Border color of the composer form. @default semantic.colors.border */
+    borderColor?: TokenReference<'color'>;
+    /** Inner padding of the composer form (raw CSS shorthand). @default "0.75rem 1rem" */
+    padding?: string;
+    /** Gap between the textarea row and the actions row. @default "0.5rem" */
+    gap?: string;
+    /** Composer textarea font-size. @default "0.875rem" */
+    fontSize?: string;
+    /** Composer textarea line-height. @default "1.25rem" */
+    lineHeight?: string;
 }
 /** Artifact toolbar chrome. */
 interface ArtifactToolbarTokens {
@@ -1025,6 +1195,29 @@ interface ScrollToBottomTokens extends ComponentTokenSet {
     fontSize?: string;
     iconSize?: string;
 }
+/** Visual tokens shared by one suggestion presentation variant. */
+interface SuggestionVariantTokens extends ComponentTokenSet {
+    /** Space inside one item, between its icon and its copy. */
+    gap?: string;
+    /** Space between suggestion items in the container. */
+    itemGap?: string;
+    minHeight?: string;
+    fontSize?: string;
+    lineHeight?: string;
+    iconSize?: string;
+    hoverBackground?: TokenReference<'color'>;
+    hoverForeground?: TokenReference<'color'>;
+    hoverBorder?: TokenReference<'color'>;
+    pressedBackground?: TokenReference<'color'>;
+    focusRing?: TokenReference<'color'>;
+    disabledOpacity?: string;
+}
+/** Starter and follow-up suggestion chrome. */
+interface SuggestionTokens {
+    chip: SuggestionVariantTokens;
+    card: SuggestionVariantTokens;
+    list: SuggestionVariantTokens;
+}
 /** Toggle group chrome (used by createToggleGroup). */
 interface ToggleGroupTokens {
     /** Gap between toggle buttons. Default: 0 (connected). */
@@ -1049,12 +1242,16 @@ interface ComponentTokens {
     toolBubble: ToolBubbleTokens;
     reasoningBubble: ReasoningBubbleTokens;
     composer: ComposerChromeTokens;
+    /** Scrollbar appearance for every scroller in the widget. */
+    scrollbar?: ScrollbarTokens;
     /** Icon button styling tokens. */
     iconButton?: IconButtonTokens;
     /** Label button styling tokens. */
     labelButton?: LabelButtonTokens;
     /** Scroll-to-bottom indicator styling tokens. */
     scrollToBottom?: ScrollToBottomTokens;
+    /** Starter prompt and follow-up suggestion styling tokens. */
+    suggestion?: SuggestionTokens;
     /** Toggle group styling tokens. */
     toggleGroup?: ToggleGroupTokens;
     /** Artifact toolbar, tab strip, and pane chrome. */
@@ -1349,7 +1546,24 @@ type RuntypeExecutionStreamEvent = ({
     type: "source";
     url?: string;
     [key: string]: unknown;
+} | {
+    executionId: string;
+    iteration?: number;
+    seq: number;
+    state: Record<string, unknown>;
+    type: "state_snapshot";
 } | ({
+    executionId: string;
+    iteration?: number;
+    patch: Array<{
+        from?: string;
+        op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+        path: string;
+        value?: unknown;
+    }>;
+    seq: number;
+    type: "state_delta";
+}) | ({
     executionId: string;
     hiddenParameterNames?: Array<string>;
     iteration?: number;
@@ -1591,6 +1805,7 @@ declare const LUCIDE_ICONS: {
     readonly plus: IconNode;
     readonly minus: IconNode;
     readonly pencil: IconNode;
+    readonly "pen-line": IconNode;
     readonly trash: IconNode;
     readonly "trash-2": IconNode;
     readonly save: IconNode;
@@ -1633,11 +1848,13 @@ declare const LUCIDE_ICONS: {
     readonly folder: IconNode;
     readonly "folder-open": IconNode;
     readonly files: IconNode;
+    readonly "chart-column": IconNode;
     readonly sparkles: IconNode;
     readonly zap: IconNode;
     readonly sun: IconNode;
     readonly moon: IconNode;
     readonly flag: IconNode;
+    readonly lightbulb: IconNode;
     readonly monitor: IconNode;
     readonly smartphone: IconNode;
 };
@@ -2635,6 +2852,13 @@ type AgentWidgetArtifactsLayoutConfig = {
      * @default 520
      */
     narrowHostMaxWidth?: number;
+    /**
+     * Width of the slide-over artifact drawer (the narrow-host and mobile
+     * presentations; `paneWidth`/`paneMaxWidth` only size the desktop split).
+     * CSS length; `"100%"` makes the drawer cover the whole panel.
+     * @default min(calc(100% - 1rem), 22rem)
+     */
+    drawerWidth?: string;
     /**
      * When true (default), widen the launcher panel while artifacts are visible and not user-dismissed.
      * No-op for inline embed (`launcher.enabled === false`).
@@ -3263,6 +3487,18 @@ type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
  *   restored thread opens at a readable place rather than at the very bottom.
  */
 type AgentWidgetScrollRestorePosition = "bottom" | "last-user-turn";
+/**
+ * Scrollbar visibility policy for every scroll surface in the widget.
+ *
+ * - `"on-scroll"` hides bars at rest and reveals them on genuine reader
+ *   input, keeping them visible while the reader is away from the resting
+ *   position: overlay-scrollbar semantics on every platform.
+ * - `"auto"` keeps the themed bar under native visibility semantics: overlay
+ *   platforms still auto-hide, classic-scrollbar platforms (Windows,
+ *   always-show macOS) show it persistently.
+ * - `"hidden"` never shows an indicator. Scrolling itself is unaffected.
+ */
+type AgentWidgetScrollbarPolicy = "on-scroll" | "auto" | "hidden";
 type AgentWidgetScrollBehaviorFeature = {
     /** Scroll behavior during streamed responses. @default "anchor-top" */
     mode?: AgentWidgetScrollMode;
@@ -3307,6 +3543,13 @@ type AgentWidgetScrollBehaviorFeature = {
      * @default false
      */
     announce?: boolean;
+    /**
+     * Scrollbar visibility policy, applied to the transcript and every inner
+     * scroller through one root attribute. Themable via
+     * `--persona-scrollbar-thumb` and `--persona-scrollbar-track`.
+     * @default "on-scroll"
+     */
+    scrollbar?: AgentWidgetScrollbarPolicy;
 };
 type AgentWidgetScrollToBottomFeature = {
     /**
@@ -3596,10 +3839,13 @@ type AgentWidgetFeatureFlags = {
      */
     askUserQuestion?: AgentWidgetAskUserQuestionFeature;
     /**
-     * Built-in `suggest_replies` quick-reply chips. When the assistant invokes
-     * the tool, the widget shows the suggestions as tappable chips above the
-     * composer (reusing the suggestion-chips surface) and immediately resumes
-     * the execution: fire-and-forget, no user input awaited.
+     * Built-in `suggest_replies` follow-ups. When the assistant invokes the
+     * tool, the widget shows the suggestions using `suggestions.followUps` and
+     * immediately resumes the execution: fire-and-forget, no user input awaited.
+     *
+     * @deprecated Both keys moved to `suggestions.followUps`: use
+     * `suggestions.followUps.enabled` and `suggestions.followUps.expose`. This
+     * alias keeps working per key, with `suggestions.followUps` winning.
      */
     suggestReplies?: AgentWidgetSuggestRepliesFeature;
 };
@@ -3639,11 +3885,12 @@ type WidgetPreferenceSlice = {
     };
 };
 /**
- * Feature config for the built-in `suggest_replies` quick-reply chips.
- * Chips render in the existing suggestions slot above the composer and are
- * styled by the widget-level `suggestionChipsConfig`. A tapped chip is sent
- * verbatim as the user's next message; chips clear once any user message
- * follows them.
+ * Feature config for the built-in `suggest_replies` follow-ups.
+ *
+ * @deprecated Both keys moved to `suggestions.followUps`
+ * (`suggestions.followUps.enabled` / `suggestions.followUps.expose`), which
+ * also owns presentation, placement, and send/fill behavior. Resolution is
+ * per key with `suggestions.followUps` winning; removal waits for 5.0.
  */
 type AgentWidgetSuggestRepliesFeature = {
     /**
@@ -3651,14 +3898,18 @@ type AgentWidgetSuggestRepliesFeature = {
      * renders as a regular tool bubble and is NOT auto-resumed: only set this
      * with no server-side `suggest_replies` declaration, or the execution
      * parks awaiting a resume that never comes.
+     * @deprecated Use `suggestions.followUps.enabled`.
      */
     enabled?: boolean;
     /**
      * Advertise the built-in `suggest_replies` tool to the agent on every
      * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
-     * needed. Defaults to `false`: flows that already declare the tool via
-     * `runtimeTools` would otherwise present it to the model twice. Ignored
-     * when `enabled` is `false`.
+     * needed. Defaults to `false`. Declare the tool in one place: the API
+     * dedupes a double declaration by name with `clientTools[]` winning, so the
+     * model still sees exactly one tool, but the widget's description and schema
+     * win and the effective tool type becomes `local` (the execution pauses and
+     * the widget auto-resumes it). Ignored when `enabled` is `false`.
+     * @deprecated Use `suggestions.followUps.expose`.
      */
     expose?: boolean;
 };
@@ -3728,10 +3979,13 @@ type AgentWidgetAskUserQuestionFeature = {
      * matching {@link AskUserQuestionPayload}; when the model calls it, the
      * existing answer-pill sheet renders and the answer resumes the execution.
      *
-     * Defaults to `false`: flows that already declare `ask_user_question` via
-     * `runtimeTools` would otherwise present the tool to the model twice.
-     * Ignored when `enabled` is `false`: never offer the agent a question
-     * tool the widget can't render an answer UI for.
+     * Defaults to `false`. Declare the tool in one place: the API dedupes a
+     * double declaration by name with `clientTools[]` winning, so the model
+     * still sees exactly one tool, but the widget's description and schema win
+     * and the effective tool type becomes `local` (the execution pauses and the
+     * widget resumes it with the user's answer). Ignored when `enabled` is
+     * `false`: never offer the agent a question tool the widget can't render an
+     * answer UI for.
      */
     expose?: boolean;
     /** Slide-in animation duration in ms. Defaults to 180. */
@@ -4196,6 +4450,57 @@ type AgentWidgetLauncherConfig = {
      * @example "min(380px, calc(100vw - 48px))"
      */
     collapsedMaxWidth?: string;
+    /**
+     * Proactive nudge bubble anchored above the collapsed floating launcher.
+     * Omit it (the default) and no teaser renders.
+     */
+    teaser?: AgentWidgetLauncherTeaserConfig;
+};
+/**
+ * Launcher teaser: a small bubble above the collapsed launcher. Clicking it
+ * opens the panel and consumes the teaser exactly like an explicit dismissal.
+ * Within a single page load the teaser appears at most once under either
+ * frequency.
+ *
+ * @example
+ * ```typescript
+ * launcher: {
+ *   teaser: { text: "Need a hand picking a plan?", delayMs: 3000 }
+ * }
+ * ```
+ */
+type AgentWidgetLauncherTeaserConfig = {
+    /** Bubble copy. An empty string renders no teaser. */
+    text: string;
+    /**
+     * Delay before the bubble appears, in milliseconds.
+     * @default 0
+     */
+    delayMs?: number;
+    /**
+     * How often the teaser may return.
+     *
+     * `"once"`: a dismissal or a click-through is remembered in `localStorage`
+     * under `` `${persistState.keyPrefix ?? "persona-"}teaser-dismissed` `` and
+     * the teaser never returns on that browser. `"always"`: shows on every page
+     * load, tracked in memory only. `persistState: false` downgrades `"once"` to
+     * in-memory too, so the teaser reappears each load.
+     *
+     * Custom `storageAdapter` implementations do not participate in teaser state.
+     *
+     * @default "once"
+     */
+    frequency?: "once" | "always";
+    /**
+     * Render an x affordance that dismisses the teaser without opening the panel.
+     * @default true
+     */
+    dismissible?: boolean;
+    /**
+     * Accessible label for the dismiss affordance.
+     * @default "Dismiss message"
+     */
+    dismissLabel?: string;
 };
 type AgentWidgetSendButtonConfig = {
     borderWidth?: string;
@@ -4204,6 +4509,10 @@ type AgentWidgetSendButtonConfig = {
     paddingY?: string;
     iconText?: string;
     iconName?: string;
+    /** Icon glyph box in icon mode, e.g. "20px". Defaults to half of `size`. */
+    iconSize?: string;
+    /** Stroke width for the icon glyph, in viewBox units. Default 2. */
+    iconStrokeWidth?: number;
     useIcon?: boolean;
     tooltipText?: string;
     showTooltip?: boolean;
@@ -4927,6 +5236,177 @@ type AgentWidgetSuggestionChipsConfig = {
     paddingX?: string;
     paddingY?: string;
 };
+/** A suggested next action shown to the user. Strings remain supported as shorthand. */
+type AgentWidgetSuggestion = string | {
+    /** Stable analytics / DOM identity. Falls back to the prompt or label. */
+    id?: string;
+    /** Concise visible action label. */
+    label: string;
+    /** Text placed in the composer or sent. Defaults to `label`. */
+    prompt?: string;
+    /**
+     * Optional supporting copy, most useful with the `card` variant. The
+     * `chip` variant ignores it and renders the label alone.
+     */
+    description?: string;
+    /** Optional icon from Persona's bundled Lucide registry. */
+    icon?: IconName;
+    /**
+     * CSS color for this item's glyph. Tints the icon only: label, border,
+     * and background stay neutral. Ignored without an `icon`.
+     */
+    iconColor?: string;
+    /** Override the surface's click behavior for this item. */
+    behavior?: AgentWidgetSuggestionBehavior;
+    /** Visually promote one high-confidence action. */
+    emphasis?: "default" | "primary";
+};
+type AgentWidgetSuggestionBehavior = "send" | "fill";
+type AgentWidgetSuggestionVariant = "chip" | "card" | "list";
+type AgentWidgetSuggestionSurface = "starter" | "followUp";
+/**
+ * Who produced the rendered suggestions: static config, the agent's
+ * `suggest_replies` tool, or `controller.setFollowUpSuggestions`.
+ */
+type AgentWidgetSuggestionSource = "config" | "agent" | "host";
+/**
+ * A suggestion after Persona has normalized shorthand strings and resolved the
+ * effective click behavior. Plugin hooks receive this stable shape.
+ */
+type AgentWidgetResolvedSuggestion = {
+    id: string;
+    label: string;
+    prompt: string;
+    description?: string;
+    icon?: IconName;
+    /** CSS color for the glyph only; never the label, border, or background. */
+    iconColor?: string;
+    behavior: AgentWidgetSuggestionBehavior;
+    emphasis: "default" | "primary";
+};
+/** Presentation keys shared by every suggestion surface. */
+type AgentWidgetSuggestionSurfaceConfig = {
+    /** Item density. Defaults to `card` for starters and `chip` for follow-ups. */
+    variant?: AgentWidgetSuggestionVariant;
+    /** Default click behavior, overridable per item. Defaults to `send`. */
+    behavior?: AgentWidgetSuggestionBehavior;
+    /**
+     * Layout for items past the surface width. Defaults to `wrap` on every
+     * surface; `scroll` opts into a horizontal strip for large sets. Applies
+     * to the `chip` variant only; the `card` and `list` layouts manage their
+     * own stacking.
+     */
+    overflow?: "scroll" | "wrap";
+    /** Maximum visible items. Defaults to 4. */
+    maxItems?: number;
+};
+type AgentWidgetStarterSuggestionsConfig = AgentWidgetSuggestionSurfaceConfig & {
+    /** Suggestions shown before the first user message. */
+    items?: AgentWidgetSuggestion[];
+    /**
+     * `auto` uses the welcome surface when the welcome card renders and the
+     * composer otherwise. Explicit values are literal: `welcome` renders
+     * nothing when the welcome card is hidden. Defaults to `auto`.
+     */
+    placement?: "auto" | "welcome" | "composer";
+};
+type AgentWidgetFollowUpSuggestionsConfig = AgentWidgetSuggestionSurfaceConfig & {
+    /**
+     * Enable the built-in `suggest_replies` follow-ups. Defaults to true. When
+     * false, `suggest_replies` renders as a regular tool bubble and is NOT
+     * auto-resumed: only set this with no server-side `suggest_replies`
+     * declaration, or the execution parks awaiting a resume that never comes.
+     */
+    enabled?: boolean;
+    /**
+     * Advertise the built-in `suggest_replies` tool to the agent on every
+     * dispatch via `clientTools[]`: no server-side `runtimeTools` declaration
+     * needed. Defaults to `false`. Declare the tool in one place: the API
+     * dedupes a double declaration by name with `clientTools[]` winning, so
+     * the model still sees exactly one tool, but the widget's description and
+     * schema win and the effective tool type becomes `local` (the execution
+     * pauses and the widget auto-resumes it). Ignored when `enabled` is
+     * `false`.
+     */
+    expose?: boolean;
+    /**
+     * `auto` places follow-ups after the transcript in regular panels and above
+     * the composer in composer-bar mode. Defaults to `auto`.
+     */
+    placement?: "auto" | "after-message" | "composer";
+};
+/**
+ * Structured suggestions configuration. The legacy `suggestionChips` and
+ * `suggestionChipsConfig` fields remain supported for backwards compatibility.
+ */
+type AgentWidgetSuggestionsConfig = {
+    starters?: AgentWidgetStarterSuggestionsConfig;
+    followUps?: AgentWidgetFollowUpSuggestionsConfig;
+};
+/**
+ * Which welcome surface renders.
+ * `"card"` is the top-of-scroll intro card (default, back-compatible),
+ * `"hero"` centers it in the empty conversation, `"none"` renders no surface.
+ */
+type AgentWidgetWelcomeVariant = "card" | "hero" | "none";
+/**
+ * When the welcome surface goes away. `"never"` is the default for `"card"`;
+ * `"on-first-message"` is the default for `"hero"` and cannot be overridden
+ * there.
+ */
+type AgentWidgetWelcomeDismiss = "never" | "on-first-message";
+/**
+ * Avatar or logo shown above the welcome title. Discriminated union; the
+ * function form is the escape hatch for custom markup. There is deliberately
+ * no raw HTML string variant (sanitization surface plus accessibility hole).
+ */
+type AgentWidgetWelcomeIcon = {
+    type: "lucide";
+    name: IconName;
+}
+/** `alt` is required, and may be `""` for a decorative logo. */
+ | {
+    type: "image";
+    url: string;
+    alt: string;
+}
+/** Emoji or short text glyph. */
+ | {
+    type: "text";
+    text: string;
+} | (() => HTMLElement | SVGElement);
+/**
+ * First-open welcome surface. Consolidates the deprecated
+ * `copy.welcomeTitle` / `copy.welcomeSubtitle` / `copy.showWelcomeCard`
+ * options; a field present here wins over its legacy alias.
+ *
+ * All defaults live in the resolver (`resolveWelcomeConfig`), never in
+ * `DEFAULT_WIDGET_CONFIG`: presence on this object is what distinguishes a
+ * host-set value from a filled-in default.
+ */
+interface AgentWidgetWelcomeConfig {
+    /** Card or hero title. Defaults to "Hello 👋". */
+    title?: string;
+    /** Scope statement in the assistant's voice. Empty string omits it. */
+    subtitle?: string;
+    /** Avatar or logo shown above the title. */
+    icon?: AgentWidgetWelcomeIcon;
+    /** @default "card" */
+    variant?: AgentWidgetWelcomeVariant;
+    /** @default "never" for `card`, always `"on-first-message"` for `hero`. */
+    dismiss?: AgentWidgetWelcomeDismiss;
+    /**
+     * Display-only greeting bubble pinned at transcript position zero. It is UI
+     * chrome derived from config, never a session message: it does not appear in
+     * `getMessages()`, is never persisted or sent to the model, `onMessage` does
+     * not fire for it, and it survives `clearChat()`. Use an assistant
+     * `initialMessages` entry instead when the model should see the greeting.
+     *
+     * Ignored (with a debug-mode warning) when `variant` is `"hero"`: the hero
+     * is the greeting.
+     */
+    message?: string;
+}
 /**
  * Interface for pluggable stream parsers that extract text from streaming responses.
  * Parsers handle incremental parsing to extract text values from structured formats (JSON, XML, etc.).
@@ -5108,7 +5588,9 @@ type AgentWidgetHeaderLayoutConfig = {
      */
     render?: (context: HeaderRenderContext) => HTMLElement;
     /**
-     * Shown after the title in `minimal` header layout (e.g. chevron menu affordance).
+     * Icon action buttons at the trailing edge of the `minimal` header layout,
+     * clustered with the close button and sharing its chrome. For a menu
+     * affordance next to the title, use `titleMenu` instead.
      */
     trailingActions?: AgentWidgetHeaderTrailingAction[];
     /** Called when a `trailingActions` button is clicked. */
@@ -5288,7 +5770,11 @@ type AgentWidgetLayoutConfig = {
     /**
      * Max width for the content area (messages + composer).
      * Applied with `margin: 0 auto` for centering.
-     * Accepts any CSS width value (e.g. "90ch", "720px", "80%").
+     * Accepts any CSS width value (e.g. "90ch", "720px", "80%"), or "none"
+     * for a full-width column. Only engages on panels wider than the cap,
+     * so launcher-width panels are unaffected.
+     * @default "768px" ("720px" in composer-bar mode via
+     * `launcher.composerBar.contentMaxWidth`)
      */
     contentMaxWidth?: string;
 };
@@ -6036,7 +6522,9 @@ type AgentWidgetConfig = {
      */
     getHeaders?: AgentWidgetHeadersFunction;
     copy?: {
+        /** @deprecated Use `welcome.title`. */
         welcomeTitle?: string;
+        /** @deprecated Use `welcome.subtitle`. */
         welcomeSubtitle?: string;
         inputPlaceholder?: string;
         sendButtonLabel?: string;
@@ -6044,6 +6532,7 @@ type AgentWidgetConfig = {
         stopButtonLabel?: string;
         /**
          * When false, the welcome / intro card is not shown above the message list.
+         * @deprecated Use `welcome.variant: "none"`.
          * @default true
          */
         showWelcomeCard?: boolean;
@@ -6108,7 +6597,17 @@ type AgentWidgetConfig = {
      * with `initialArtifacts`.
      */
     initialSelectedArtifactId?: string | null;
+    /** Rich starter and follow-up suggestion surfaces. */
+    suggestions?: AgentWidgetSuggestionsConfig;
+    /**
+     * First-open welcome surface (card, hero, or none) plus the optional
+     * display-only greeting bubble. Supersedes `copy.welcomeTitle`,
+     * `copy.welcomeSubtitle`, and `copy.showWelcomeCard`.
+     */
+    welcome?: AgentWidgetWelcomeConfig;
+    /** @deprecated Prefer `suggestions.starters.items`. */
     suggestionChips?: string[];
+    /** @deprecated Prefer semantic tokens under `theme.components.suggestion`. */
     suggestionChipsConfig?: AgentWidgetSuggestionChipsConfig;
     debug?: boolean;
     formEndpoint?: string;