@runtypelabs/persona 4.14.0 → 4.16.0

package/src/plugins/types.ts

@@ -1,3 +1,5 @@
+import type { ResolvedWelcomeConfig } from "../welcome";
+import type { AgentWidgetPluginStorage } from "../utils/plugin-storage";
 import {
   AgentWidgetMessage,
   AgentWidgetConfig,
@@ -8,9 +10,74 @@ import {
   EventStreamViewRenderContext,
   EventStreamRowRenderContext,
   EventStreamToolbarRenderContext,
-  EventStreamPayloadRenderContext
+  EventStreamPayloadRenderContext,
+  AgentWidgetSuggestion,
+  AgentWidgetResolvedSuggestion,
+  AgentWidgetSuggestionSource,
+  AgentWidgetSuggestionSurface,
+  AgentWidgetSuggestionVariant,
+  AgentWidgetWelcomeVariant
 } from "../types";
 
+export 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;
+};
+
+export 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;
+};
+
+export 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;
+};
+
+export type AgentWidgetSuggestionSelectContext = {
+  suggestion: AgentWidgetResolvedSuggestion;
+  surface: AgentWidgetSuggestionSurface;
+  source: AgentWidgetSuggestionSource;
+  variant: AgentWidgetSuggestionVariant;
+  config: AgentWidgetConfig;
+};
+
 /**
  * Plugin interface for customizing widget components
  */
@@ -25,6 +92,34 @@ export interface AgentWidgetPlugin {
    */
   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
@@ -45,6 +140,37 @@ export interface AgentWidgetPlugin {
     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
@@ -87,6 +213,15 @@ export 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;
 
   /**
@@ -298,5 +433,3 @@ export interface AgentWidgetPlugin {
 
 
 
-
-

package/src/presets.ts

@@ -75,9 +75,9 @@ export const PRESET_SHOP: WidgetPreset = {
       sendButtonLabel: "Send",
     },
     suggestionChips: [
-      "What can you help me with?",
-      "Tell me about your features",
-      "How does this work?",
+      "Show me what you can help with",
+      "Walk me through getting started",
+      "Answer a question about this page",
     ],
   },
 };

package/src/session.ts

@@ -2,6 +2,7 @@ import { AgentWidgetClient, type SSEEventCallback } from "./client";
 import { isWebMcpToolName } from "./webmcp-bridge";
 import {
   SUGGEST_REPLIES_TOOL_NAME,
+  resolveFollowUpsFeature,
   suggestRepliesToolResult,
 } from "./suggest-replies-tool";
 import {
@@ -77,10 +78,11 @@ export type AgentWidgetSessionStatus =
  * request. When NONE of these change, `updateConfig` can refresh the live
  * client in place (preserving the WebMCP bridge and any in-flight stream/resume)
  * instead of swapping in a fresh client and tearing down WebMCP state. Fields
- * outside this list (theme, copy, layout, suggestionChips, iterationDisplay,
- * postprocessMessage, feature display toggles, …) are display-only and safe to
- * apply mid-turn: which is what a self-styling widget needs when a `webmcp:*`
- * theme tool re-renders the widget while the agent's turn is still streaming.
+ * outside this list (theme, copy, layout, suggestions, suggestionChips,
+ * iterationDisplay, postprocessMessage, feature display toggles, …) are
+ * display-only and safe to apply mid-turn: which is what a self-styling widget
+ * needs when a `webmcp:*` theme tool re-renders the widget while the agent's
+ * turn is still streaming.
  *
  * Compared by identity (`!==`): primitives by value, functions/objects by
  * reference. A consumer that rebuilds these objects on every render simply
@@ -2983,15 +2985,15 @@ export class AgentWidgetSession {
       // indefinitely: `resolveWebMcpToolCall` translates the missing-bridge
       // case into an isError result that resumes the flow cleanly.
       // `suggest_replies`, by contrast, is gated on its feature flag: when
-      // `features.suggestReplies.enabled === false` the widget neither
-      // renders chips nor resumes: the same parked-execution posture as a
-      // server-declared ask_user_question with its sheet disabled.
+      // the resolved `enabled` is false the widget neither renders chips nor
+      // resumes: the same parked-execution posture as a server-declared
+      // ask_user_question with its sheet disabled.
       const tc = event.message.toolCall;
       const autoResolvable =
         !!tc?.name &&
         (isWebMcpToolName(tc.name) ||
           (tc.name === SUGGEST_REPLIES_TOOL_NAME &&
-            this.config.features?.suggestReplies?.enabled !== false));
+            resolveFollowUpsFeature(this.config).enabled));
       if (
         event.message.agentMetadata?.awaitingLocalTool === true &&
         autoResolvable

package/src/styles/widget-styles.test.ts

@@ -0,0 +1,382 @@
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+const widgetCss = readFileSync(
+  new URL("./widget.css", import.meta.url),
+  "utf8",
+);
+
+describe("suggestion interaction styles", () => {
+  it("keeps suggestion surfaces from collapsing inside constrained transcripts", () => {
+    const selector = ".persona-suggestions {";
+    const start = widgetCss.indexOf(selector);
+    const end = widgetCss.indexOf("\n}", start);
+    const surfaceRule = widgetCss.slice(start, end);
+
+    expect(start).toBeGreaterThan(-1);
+    expect(surfaceRule).toContain("flex-shrink: 0");
+  });
+
+  it("keeps the primary emphasis a quiet accent rather than a solid fill", () => {
+    const selector = '.persona-suggestion[data-emphasis="primary"] {';
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("border-color: var(--persona-primary)");
+    // Plain declaration first so engines without color-mix stay transparent.
+    expect(rule).toContain("background: transparent");
+    expect(rule).toContain(
+      "background: color-mix(in srgb, var(--persona-primary) 6%, transparent)",
+    );
+    expect(rule).not.toContain("--persona-text-inverse");
+  });
+
+  it("strengthens the primary wash on hover instead of filling it", () => {
+    const selector =
+      '.persona-suggestion[data-emphasis="primary"]:hover {';
+    const start = widgetCss.indexOf(selector);
+    const hoverRule = widgetCss.slice(start, widgetCss.indexOf("\n  }", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(hoverRule).toContain("border-color: var(--persona-primary)");
+    expect(hoverRule).toContain(
+      "color-mix(in srgb, var(--persona-primary) 12%, transparent)",
+    );
+    expect(hoverRule).not.toContain("filter: brightness");
+  });
+
+  it("rests cards flat and reserves the shadow plus lift for hover", () => {
+    const restStart = widgetCss.indexOf(".persona-suggestion--card {");
+    const restRule = widgetCss.slice(
+      restStart,
+      widgetCss.indexOf("\n}", restStart),
+    );
+
+    expect(restStart).toBeGreaterThan(-1);
+    expect(restRule).toContain(
+      "box-shadow: var(--persona-components-suggestion-card-shadow, none)",
+    );
+
+    const hoverStart = widgetCss.indexOf(".persona-suggestion--card:hover {");
+    const hoverRule = widgetCss.slice(
+      hoverStart,
+      widgetCss.indexOf("\n  }", hoverStart),
+    );
+
+    expect(hoverStart).toBeGreaterThan(-1);
+    expect(hoverRule).toContain("box-shadow: var(--persona-shadow-sm)");
+    expect(hoverRule).toContain("transform: translateY(-1px)");
+  });
+
+  it("reveals the suggestion arrow only on hover and keyboard focus", () => {
+    // Searched past `__copy`: the bare selector also appears in the shared
+    // `flex: 0 0 auto` group above it and the coarse-pointer override below.
+    const restStart = widgetCss.indexOf(
+      ".persona-suggestion__arrow {",
+      widgetCss.indexOf(".persona-suggestion__copy {"),
+    );
+    const restRule = widgetCss.slice(
+      restStart,
+      widgetCss.indexOf("\n}", restStart),
+    );
+
+    expect(restStart).toBeGreaterThan(-1);
+    expect(restRule).toContain("opacity: 0;");
+    expect(restRule).toContain("transition: opacity");
+    expect(widgetCss).toContain(
+      ".persona-suggestion:focus-visible .persona-suggestion__arrow",
+    );
+    expect(widgetCss).toContain(
+      ".persona-suggestion:hover .persona-suggestion__arrow",
+    );
+  });
+
+  it("caps the starter card grid so wide panels get two columns", () => {
+    expect(widgetCss).toContain(
+      "grid-template-columns: repeat(auto-fit, minmax(min(100%, 240px), 1fr))",
+    );
+    const selector =
+      '.persona-suggestions[data-variant="card"][data-persona-suggestion-surface="starter"] {';
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("max-width: 600px");
+  });
+
+  it("centers label-only items and top-aligns only description cards", () => {
+    const cardStart = widgetCss.indexOf(".persona-suggestion--card {");
+    const cardRule = widgetCss.slice(
+      cardStart,
+      widgetCss.indexOf("\n}", cardStart),
+    );
+    expect(cardRule).toContain("align-items: center");
+
+    const listStart = widgetCss.indexOf(".persona-suggestion--list {");
+    const listRule = widgetCss.slice(
+      listStart,
+      widgetCss.indexOf("\n}", listStart),
+    );
+    expect(listRule).toContain("align-items: center");
+
+    // Only content that actually wraps to two lines earns the top alignment.
+    const hasStart = widgetCss.indexOf(
+      ".persona-suggestion--card:has(.persona-suggestion__description)",
+    );
+    const hasRule = widgetCss.slice(
+      hasStart,
+      widgetCss.indexOf("\n}", hasStart),
+    );
+    expect(hasStart).toBeGreaterThan(-1);
+    expect(hasRule).toContain(
+      ".persona-suggestion--list:has(.persona-suggestion__description)",
+    );
+    expect(hasRule).toContain("align-items: flex-start");
+  });
+
+  it("masks only the scrollable chip edges that still contain content", () => {
+    expect(widgetCss).toContain(
+      '[data-overflow="scroll"][data-scroll-right]:not(',
+    );
+    expect(widgetCss).toContain(
+      '[data-overflow="scroll"][data-scroll-left]:not(',
+    );
+    expect(widgetCss).toContain(
+      '[data-overflow="scroll"][data-scroll-left][data-scroll-right]',
+    );
+    expect(widgetCss).toContain(
+      "--persona-suggestion-scroll-fade-size: 32px",
+    );
+  });
+
+  it("centers the chip row on the composer surface only", () => {
+    const selector =
+      '[data-persona-composer-suggestions].persona-suggestions[data-variant="chip"] {';
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    // fit-content + auto margins center a single row while wrapped rows keep
+    // a shared left edge; per-row justify-content would rag them.
+    expect(rule).toContain("width: fit-content");
+    expect(rule).toContain("max-width: 100%");
+    expect(rule).toContain("margin-inline: auto");
+    expect(rule).not.toContain("justify-content");
+
+    // Transcript follow-ups and welcome rows keep the default left alignment.
+    const sharedStart = widgetCss.indexOf(
+      '.persona-suggestions[data-variant="chip"] {',
+    );
+    const sharedRule = widgetCss.slice(
+      sharedStart,
+      widgetCss.indexOf("\n}", sharedStart),
+    );
+    expect(sharedStart).toBeGreaterThan(-1);
+    expect(sharedRule).not.toContain("justify-content");
+  });
+
+  it("only pulls follow-ups up against the roomy welcome-visible body gap", () => {
+    // Unscoped, the -12px offset would zero out the tightened 12px gap that
+    // applies when the welcome host is hidden, gluing follow-ups to the answer.
+    expect(widgetCss).toContain(
+      '.persona-gap-6 > [data-persona-suggestions="follow-up"] {',
+    );
+    expect(widgetCss).not.toMatch(
+      /\n\[data-persona-suggestions="follow-up"\] \{/,
+    );
+  });
+});
+
+describe("composer spacing styles", () => {
+  it("themes the composer form padding and gap with utility-matching fallbacks", () => {
+    const selector =
+      "[data-persona-root] .persona-widget-composer:not(.persona-pill-composer) {";
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    // Fallbacks reproduce `persona-px-4 persona-py-3` and `persona-gap-2`.
+    expect(rule).toContain(
+      "padding: var(--persona-composer-padding, 0.75rem 1rem)",
+    );
+    expect(rule).toContain("gap: var(--persona-composer-gap, 0.5rem)");
+  });
+
+  it("themes the composer textarea type with text-sm fallbacks", () => {
+    const selector = "[data-persona-root] .persona-composer-textarea {";
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain(
+      "font-size: var(--persona-composer-font-size, 0.875rem)",
+    );
+    expect(rule).toContain(
+      "line-height: var(--persona-composer-line-height, 1.25rem)",
+    );
+  });
+
+  it("leaves the pill composer on its own single-row geometry", () => {
+    const start = widgetCss.indexOf(".persona-pill-composer {");
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("padding: 6px 14px");
+    expect(rule).toContain("gap: 8px");
+  });
+});
+
+describe("transcript layout styles", () => {
+  it("drops the empty messages wrapper from the flex flow", () => {
+    // A zero-height flex child still triggers the body's gap, so an empty
+    // transcript added phantom scrollable space below the welcome (and a
+    // scroll-to-bottom arrow with nothing to scroll to).
+    expect(widgetCss).toContain(
+      ".persona-widget-messages:empty {\n  display: none;\n}",
+    );
+  });
+});
+
+describe("launcher teaser styles", () => {
+  it("keeps the [hidden] dismiss control hidden despite its own display: grid", () => {
+    // dismissible: false sets the hidden property; without this companion
+    // rule the block's display: grid outranks the UA [hidden] stylesheet.
+    expect(widgetCss).toContain(
+      ".persona-launcher-teaser-dismiss[hidden] {\n  display: none;\n}",
+    );
+  });
+});
+
+describe("plugin welcome styles", () => {
+  it("hides the default welcome content while a plugin element owns the host", () => {
+    const selector =
+      '.persona-welcome[data-persona-welcome-content="plugin"]\n  > :not([data-persona-welcome-plugin]) {';
+    const start = widgetCss.indexOf(selector);
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("display: none !important");
+  });
+
+  it("centers the welcome column at wide widths but never the overlay", () => {
+    const start = widgetCss.indexOf(
+      ".persona-welcome:not([data-persona-welcome-overlay]) {",
+    );
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    // The card variant shares the transcript column so its left-aligned
+    // text lines up with messages and composer.
+    expect(rule).toContain("max-width: var(--persona-content-max-width, 768px)");
+    expect(rule).toContain("margin-inline: auto");
+    // The var is published on the root so plugin content can consume it.
+    expect(widgetCss).toContain("--persona-welcome-max-width: 640px");
+  });
+
+  it("keeps the narrower centered column for the hero variant only", () => {
+    const start = widgetCss.indexOf(
+      '.persona-welcome[data-persona-welcome-variant="hero"]:not(',
+    );
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("max-width: var(--persona-welcome-max-width, 640px)");
+  });
+
+  it("aligns the greeting bubble to the transcript column", () => {
+    const start = widgetCss.indexOf(".persona-welcome-greeting {");
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("max-width: var(--persona-content-max-width, 768px)");
+    expect(rule).toContain("margin-inline: auto");
+  });
+
+  it("pads the welcome host from the intro-card alias, full padding on overlays", () => {
+    // Flat default resolves the alias to `1.5rem 0` (tokens.ts), aligning
+    // the text with the content column; overlays are opaque surfaces and
+    // keep a fixed symmetric inset.
+    const start = widgetCss.indexOf(".persona-welcome {");
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("padding: var(--persona-intro-card-padding, 1.5rem)");
+
+    const overlayStart = widgetCss.indexOf(
+      ".persona-welcome[data-persona-welcome-overlay] {",
+    );
+    const overlayRule = widgetCss.slice(
+      overlayStart,
+      widgetCss.indexOf("\n}", overlayStart),
+    );
+    expect(overlayRule).toContain("padding: 1.5rem");
+  });
+
+  it("overlays the messages area while plugin content is active", () => {
+    const start = widgetCss.indexOf(
+      ".persona-welcome[data-persona-welcome-overlay] {",
+    );
+    const rule = widgetCss.slice(start, widgetCss.indexOf("\n}", start));
+
+    expect(start).toBeGreaterThan(-1);
+    expect(rule).toContain("position: absolute");
+    expect(rule).toContain("inset: 0");
+    // !important: only way to beat the host's inline intro-card background
+    // (default transparent), which otherwise lets the transcript bleed
+    // through the overlay.
+    expect(rule).toMatch(/background:[\s\S]*!important/);
+    // Two classes so it outranks the body's own overflow utility.
+    expect(widgetCss).toContain(
+      ".persona-widget-body.persona-welcome-overlay-active {\n  overflow: hidden;\n}",
+    );
+  });
+});
+
+describe("scrollbar policy styles", () => {
+  it("themes every scroller from the shared tokens", () => {
+    // scrollbar-color inherits from the root; scrollbar-width does not, so
+    // the width needs the descendant star.
+    expect(widgetCss).toMatch(
+      /\[data-persona-root\] \{\n {2}scrollbar-color: var\(\n\s+--persona-scrollbar-thumb,/,
+    );
+    expect(widgetCss).toContain("var(--persona-scrollbar-track, transparent)");
+    expect(widgetCss).toContain(
+      "[data-persona-root],\n[data-persona-root] * {\n  scrollbar-width: thin;\n}",
+    );
+    // The artifact tab strip keeps its own token as an alias layered on the
+    // shared thumb token.
+    expect(widgetCss).toContain(
+      "--persona-artifact-tab-list-scrollbar,\n    var(--persona-scrollbar-thumb, var(--persona-border, #e5e7eb))",
+    );
+  });
+
+  it("hides the transcript bar at rest under the on-scroll policy without reflow", () => {
+    // Rest state keys off the ui.ts-owned attributes; the reveal attribute
+    // must appear as a :not() so flipping it shows the bar again.
+    expect(widgetCss).toContain(
+      '[data-persona-scrollbar="on-scroll"]\n  .persona-widget-body:not([data-persona-scrollbar-visible]),\n[data-persona-scrollbar="hidden"] .persona-widget-body {\n  scrollbar-width: none;\n}',
+    );
+    // Old-Safari fallback: webkit hiding agrees with the standard property.
+    expect(widgetCss).toContain(
+      '[data-persona-scrollbar="hidden"] .persona-widget-body::-webkit-scrollbar {\n  display: none;\n}',
+    );
+    // Classic-scrollbar platforms must not reflow the transcript on toggle.
+    expect(widgetCss).toContain(
+      '[data-persona-scrollbar="on-scroll"] .persona-widget-body {\n  scrollbar-gutter: stable;\n}',
+    );
+  });
+
+  it("hover-reveals inner scroller bars under the on-scroll policy", () => {
+    expect(widgetCss).toContain(
+      '[data-persona-scrollbar="on-scroll"] .persona-artifact-list:not(:hover)',
+    );
+    expect(widgetCss).toContain(
+      '[data-persona-scrollbar="on-scroll"]\n  .persona-suggestions[data-overflow="scroll"]:not(:hover)',
+    );
+    expect(widgetCss).toContain(
+      '[data-persona-scrollbar="hidden"] .persona-artifact-list,',
+    );
+  });
+});