@runtypelabs/persona 4.15.0 → 4.17.0

package/src/types/theme.ts

@@ -202,6 +202,16 @@ export interface PanelTokens extends ComponentTokenSet {
   canvasBackground?: string;
 }
 
+/** Per-element text styling shared by themable text surfaces. */
+export interface TextStyleTokens {
+  fontFamily?: string;
+  fontSize?: string;
+  fontWeight?: string;
+  lineHeight?: string;
+  letterSpacing?: string;
+  color?: TokenReference<'color'>;
+}
+
 export interface HeaderTokens extends ComponentTokenSet {
   background: TokenReference<'color'>;
   border: TokenReference<'color'>;
@@ -210,10 +220,14 @@ export 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). */
@@ -245,7 +259,7 @@ export 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.
  */
 export interface IntroCardTokens extends ComponentTokenSet {
@@ -254,6 +268,12 @@ export 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). */
@@ -298,6 +318,8 @@ export 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?: {
@@ -361,10 +383,20 @@ export interface ReasoningBubbleTokens {
   shadow: string;
 }
 
+/** Scrollbar appearance shared by every scroller in the widget. */
+export interface ScrollbarTokens {
+  /** Thumb color. @default semantic.colors.border */
+  thumb?: TokenReference<'color'>;
+  /** Track color. @default "transparent" */
+  track?: TokenReference<'color'>;
+}
+
 /** Composer (message input) chrome. */
 export 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" */
@@ -534,7 +566,10 @@ export interface ScrollToBottomTokens extends ComponentTokenSet {
 
 /** Visual tokens shared by one suggestion presentation variant. */
 export 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;
@@ -579,6 +614,8 @@ export 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. */

package/src/types.ts

@@ -1251,6 +1251,13 @@ export 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`).
@@ -1894,6 +1901,19 @@ export type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
  */
 export 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.
+ */
+export type AgentWidgetScrollbarPolicy = "on-scroll" | "auto" | "hidden";
+
 export type AgentWidgetScrollBehaviorFeature = {
   /** Scroll behavior during streamed responses. @default "anchor-top" */
   mode?: AgentWidgetScrollMode;
@@ -1938,6 +1958,13 @@ export 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;
 };
 
 export type AgentWidgetScrollToBottomFeature = {
@@ -2915,6 +2942,58 @@ export 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 }
+ * }
+ * ```
+ */
+export 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;
 };
 
 export type AgentWidgetSendButtonConfig = {
@@ -3753,7 +3832,10 @@ export type AgentWidgetSuggestion =
       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;
@@ -3800,9 +3882,10 @@ export 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. */
@@ -3860,6 +3943,66 @@ export type AgentWidgetSuggestionsConfig = {
   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.
+ */
+export 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.
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.).
@@ -4152,7 +4295,9 @@ export 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. */
@@ -4348,7 +4493,11 @@ export 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;
 };
@@ -5108,7 +5257,9 @@ export type AgentWidgetConfig = {
    */
   getHeaders?: AgentWidgetHeadersFunction;
   copy?: {
+    /** @deprecated Use `welcome.title`. */
     welcomeTitle?: string;
+    /** @deprecated Use `welcome.subtitle`. */
     welcomeSubtitle?: string;
     inputPlaceholder?: string;
     sendButtonLabel?: string;
@@ -5116,6 +5267,7 @@ export 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;
@@ -5182,6 +5334,12 @@ export 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`. */

package/src/ui.body-top-slot.test.ts

@@ -0,0 +1,95 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+describe("layout.slots['body-top']", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("resolves defaultContent() to the intro card (regression: queried stale utility classes)", () => {
+    window.scrollTo = vi.fn();
+    const mount = createMount();
+    let resolved: HTMLElement | null | undefined;
+
+    createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      layout: {
+        slots: {
+          "body-top": ({ defaultContent }) => {
+            resolved = defaultContent();
+            return null;
+          },
+        },
+      },
+    });
+
+    expect(resolved).not.toBeNull();
+    expect(resolved!.hasAttribute("data-persona-intro-card")).toBe(true);
+  });
+
+  it("replaces the intro card with the slot element instead of prepending beside it", () => {
+    window.scrollTo = vi.fn();
+    const mount = createMount();
+
+    createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      layout: {
+        slots: {
+          "body-top": () => {
+            const custom = document.createElement("div");
+            custom.setAttribute("data-test-slot", "body-top");
+            return custom;
+          },
+        },
+      },
+    });
+
+    const body = mount.querySelector("#persona-scroll-container")!;
+    expect(body.querySelector("[data-test-slot='body-top']")).not.toBeNull();
+    expect(body.querySelector("[data-persona-intro-card]")).toBeNull();
+    expect(
+      (body.firstElementChild as HTMLElement).getAttribute("data-test-slot")
+    ).toBe("body-top");
+  });
+
+  it("supports composing around the default intro card", () => {
+    window.scrollTo = vi.fn();
+    const mount = createMount();
+
+    createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: { enabled: false },
+      layout: {
+        slots: {
+          "body-top": ({ defaultContent }) => {
+            const wrapper = document.createElement("div");
+            wrapper.setAttribute("data-test-slot", "wrapper");
+            const banner = document.createElement("p");
+            banner.textContent = "Welcome back";
+            wrapper.appendChild(banner);
+            const card = defaultContent();
+            if (card) wrapper.appendChild(card);
+            return wrapper;
+          },
+        },
+      },
+    });
+
+    const body = mount.querySelector("#persona-scroll-container")!;
+    const wrapper = body.querySelector("[data-test-slot='wrapper']");
+    expect(wrapper).not.toBeNull();
+    expect(wrapper!.querySelector("[data-persona-intro-card]")).not.toBeNull();
+  });
+});

package/src/ui.content-width.test.ts

@@ -0,0 +1,91 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const mounts: HTMLElement[] = [];
+const controllers: ReturnType<typeof createAgentExperience>[] = [];
+
+const makeController = (config: Record<string, unknown> = {}) => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  mounts.push(mount);
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    persistState: false,
+    suggestionChips: [],
+    ...config,
+  } as unknown as Parameters<typeof createAgentExperience>[1]);
+  controllers.push(controller);
+  return { mount, controller };
+};
+
+const wrapper = (mount: HTMLElement) =>
+  mount.querySelector<HTMLElement>("#persona-scroll-container > .persona-widget-messages")!;
+
+describe("default content column", () => {
+  afterEach(() => {
+    controllers.splice(0).forEach((controller) => controller.destroy());
+    mounts.splice(0).forEach((mount) => mount.remove());
+    document.body.innerHTML = "";
+  });
+
+  it("keeps the transcript wrapper :empty pre-conversation so CSS drops it from the flex flow", () => {
+    // The stylesheet's .persona-widget-messages:empty { display: none } only
+    // works if nothing seeds the wrapper with placeholder nodes.
+    const { mount, controller } = makeController();
+    const messagesWrapper = wrapper(mount);
+    expect(messagesWrapper.matches(":empty")).toBe(true);
+
+    controller.injectUserMessage({ content: "hi" });
+    expect(messagesWrapper.matches(":empty")).toBe(false);
+  });
+
+  it("caps and centers the transcript at 768px by default", () => {
+    const { mount } = makeController();
+    const messagesWrapper = wrapper(mount);
+    expect(messagesWrapper.style.maxWidth).toBe("768px");
+    expect(messagesWrapper.style.marginLeft).toBe("auto");
+    expect(messagesWrapper.style.marginRight).toBe("auto");
+    expect(messagesWrapper.style.width).toBe("100%");
+  });
+
+  it("honors an explicit layout.contentMaxWidth", () => {
+    const { mount } = makeController({ layout: { contentMaxWidth: "90ch" } });
+    expect(wrapper(mount).style.maxWidth).toBe("90ch");
+  });
+
+  it("opts out with \"none\" for a full-width column", () => {
+    const { mount } = makeController({ layout: { contentMaxWidth: "none" } });
+    expect(wrapper(mount).style.maxWidth).toBe("none");
+  });
+
+  it("caps the composer status text to the same column as the composer form", () => {
+    const { mount, controller } = makeController();
+    const statusText = mount.querySelector<HTMLElement>("[data-persona-composer-status]")!;
+    expect(statusText.style.maxWidth).toBe("768px");
+    expect(statusText.style.marginLeft).toBe("auto");
+    expect(statusText.style.marginRight).toBe("auto");
+
+    controller.update({ layout: { contentMaxWidth: "90ch" } });
+    expect(statusText.style.maxWidth).toBe("90ch");
+
+    controller.update({ layout: { contentMaxWidth: "" } });
+    expect(statusText.style.maxWidth).toBe("");
+    expect(statusText.style.marginLeft).toBe("");
+  });
+
+  it("publishes the resolved column as a CSS var for plugin content", () => {
+    const { mount, controller } = makeController();
+    expect(
+      mount.style.getPropertyValue("--persona-content-max-width")
+    ).toBe("768px");
+
+    controller.update({ layout: { contentMaxWidth: "90ch" } });
+    expect(
+      mount.style.getPropertyValue("--persona-content-max-width")
+    ).toBe("90ch");
+  });
+});

package/src/ui.docked.test.ts

@@ -27,24 +27,27 @@ describe("createAgentExperience docked mode", () => {
     });
 
     const wrapper = mount.firstElementChild as HTMLElement | null;
-    const launcherButton = mount.lastElementChild as HTMLButtonElement | null;
+    // The launcher mounts inside its surface wrapper; visibility is driven on
+    // the wrapper so a teaser bubble hides with the button.
+    const launcherSurface = mount.lastElementChild as HTMLElement | null;
+    const launcherButton = launcherSurface?.querySelector("button") ?? null;
 
     expect(wrapper).not.toBeNull();
     expect(wrapper?.style.display).toBe("flex");
     expect(launcherButton).not.toBeNull();
     expect(launcherButton?.tagName).toBe("BUTTON");
-    expect(launcherButton?.style.display).toBe("none");
+    expect(launcherSurface?.style.display).toBe("none");
     expect(launcherButton?.className).toContain("persona-mt-4");
 
     controller.close();
 
     expect(wrapper?.style.display).toBe("none");
-    expect(launcherButton?.style.display).toBe("none");
+    expect(launcherSurface?.style.display).toBe("none");
 
     controller.open();
 
     expect(wrapper?.style.display).toBe("flex");
-    expect(launcherButton?.style.display).toBe("none");
+    expect(launcherSurface?.style.display).toBe("none");
 
     controller.destroy();
   });