@runtypelabs/persona 4.14.0 → 4.16.0

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 = {
@@ -2257,10 +2284,13 @@ export 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;
 };
@@ -2327,11 +2357,12 @@ export 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.
  */
 export type AgentWidgetSuggestRepliesFeature = {
   /**
@@ -2339,14 +2370,18 @@ export 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;
 };
@@ -2421,10 +2456,13 @@ export 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. */
@@ -2904,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 = {
@@ -2913,6 +3003,10 @@ export 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;
@@ -3728,6 +3822,187 @@ export type AgentWidgetSuggestionChipsConfig = {
   paddingY?: string;
 };
 
+/** A suggested next action shown to the user. Strings remain supported as shorthand. */
+export 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";
+    };
+
+export type AgentWidgetSuggestionBehavior = "send" | "fill";
+export type AgentWidgetSuggestionVariant = "chip" | "card" | "list";
+export type AgentWidgetSuggestionSurface = "starter" | "followUp";
+/**
+ * Who produced the rendered suggestions: static config, the agent's
+ * `suggest_replies` tool, or `controller.setFollowUpSuggestions`.
+ */
+export 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.
+ */
+export 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. */
+export 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;
+};
+
+export 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";
+  };
+
+export 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";
+    // No `items`: follow-up items are contextual and come from the agent's
+    // `suggest_replies` tool or `controller.setFollowUpSuggestions`, not static
+    // config. Static lists are `starters`.
+  };
+
+/**
+ * Structured suggestions configuration. The legacy `suggestionChips` and
+ * `suggestionChipsConfig` fields remain supported for backwards compatibility.
+ */
+export 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.
+ */
+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.).
@@ -4020,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. */
@@ -4216,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;
 };
@@ -4976,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;
@@ -4984,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;
@@ -5048,7 +5332,17 @@ export 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;

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.detached-panel.test.ts

@@ -907,7 +907,7 @@ describe("createAgentExperience welded artifact split chrome", () => {
 
     controller.hideArtifacts();
 
-    // Byte-identical to pane-closed: container carries the border, panel does not.
+    // Same as pane-closed: container carries the border, panel does not.
     expect(mount.classList.contains("persona-artifact-welded-split")).toBe(false);
     expect(container?.style.border).toContain("--persona-panel-border");
     expect(panel?.style.border).toBe("");

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();
   });