@runtypelabs/persona 4.15.0 → 4.17.0

package/dist/theme-editor-preview.d.cts

@@ -1,5 +1,26 @@
 import { IconNode } from 'lucide';
 
+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:
@@ -27,6 +48,27 @@ type AgentWidgetRenderSuggestionContext = {
      */
     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;
@@ -83,6 +125,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
@@ -127,6 +197,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
@@ -507,6 +586,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'>;
@@ -515,10 +603,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). */
@@ -548,7 +640,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 {
@@ -557,6 +649,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 {
@@ -599,6 +697,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?: {
@@ -656,10 +756,19 @@ 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" */
@@ -819,7 +928,10 @@ interface ScrollToBottomTokens extends ComponentTokenSet {
 }
 /** 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;
@@ -861,6 +973,8 @@ 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. */
@@ -2559,6 +2673,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`).
@@ -3187,6 +3308,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;
@@ -3231,6 +3364,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 = {
     /**
@@ -4131,6 +4271,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;
@@ -4883,7 +5074,10 @@ type AgentWidgetSuggestion = string | {
     label: string;
     /** Text placed in the composer or sent. Defaults to `label`. */
     prompt?: string;
-    /** Optional supporting copy, most useful with the `card` variant. */
+    /**
+     * 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;
@@ -4927,9 +5121,10 @@ type AgentWidgetSuggestionSurfaceConfig = {
     /** Default click behavior, overridable per item. Defaults to `send`. */
     behavior?: AgentWidgetSuggestionBehavior;
     /**
-     * Layout for items past the surface width. Defaults to `wrap` for starters
-     * and `scroll` for follow-ups. Applies to the `chip` variant only; the
-     * `card` and `list` layouts manage their own stacking.
+     * 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. */
@@ -4978,6 +5173,70 @@ 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.).
@@ -5159,7 +5418,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. */
@@ -5339,7 +5600,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;
 };
@@ -6087,7 +6352,9 @@ type AgentWidgetConfig = {
      */
     getHeaders?: AgentWidgetHeadersFunction;
     copy?: {
+        /** @deprecated Use `welcome.title`. */
         welcomeTitle?: string;
+        /** @deprecated Use `welcome.subtitle`. */
         welcomeSubtitle?: string;
         inputPlaceholder?: string;
         sendButtonLabel?: string;
@@ -6095,6 +6362,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;
@@ -6161,6 +6429,12 @@ type AgentWidgetConfig = {
     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`. */