@runtypelabs/persona 4.14.0 → 4.16.0

package/src/components/welcome.test.ts

@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  animateWelcomeOut,
+  applyWelcomeConfig,
+  applyWelcomeVisibility,
+  buildGreetingHost,
+  buildWelcomeHost,
+  renderWelcomeGreeting,
+} from "./welcome";
+import { resolveWelcomeConfig } from "../welcome";
+import type { AgentWidgetConfig } from "../types";
+
+const makeHost = () => {
+  const starters = document.createElement("div");
+  return buildWelcomeHost(undefined, starters);
+};
+
+describe("welcome host", () => {
+  it("carries the permanent host attributes", () => {
+    const { host } = makeHost();
+    expect(host.hasAttribute("data-persona-welcome")).toBe(true);
+    expect(host.hasAttribute("data-persona-intro-card")).toBe(true);
+  });
+
+  it("gives the title and subtitle their tokenized typography classes", () => {
+    const { title, subtitle } = makeHost();
+    expect(title.tagName).toBe("H2");
+    expect(title.className).toBe("persona-welcome-title");
+    expect(subtitle.tagName).toBe("P");
+    expect(subtitle.className).toBe("persona-welcome-subtitle");
+  });
+
+  it("applies resolved config in place", () => {
+    const elements = makeHost();
+    applyWelcomeConfig(
+      elements,
+      resolveWelcomeConfig({
+        welcome: { title: "Hi", subtitle: "Scope", variant: "hero" },
+      } as AgentWidgetConfig)
+    );
+    expect(elements.title.textContent).toBe("Hi");
+    expect(elements.subtitle.textContent).toBe("Scope");
+    expect(elements.host.getAttribute("data-persona-welcome-variant")).toBe(
+      "hero"
+    );
+    expect(elements.host.getAttribute("data-persona-welcome-dismiss")).toBe(
+      "on-first-message"
+    );
+  });
+
+  it("tightens the body gap when the surface is hidden", () => {
+    const { host } = makeHost();
+    const body = document.createElement("div");
+    body.className = "persona-gap-6";
+    applyWelcomeVisibility(body, host, false);
+    expect(body.classList.contains("persona-gap-3")).toBe(true);
+    expect(body.classList.contains("persona-gap-6")).toBe(false);
+    applyWelcomeVisibility(body, host, true);
+    expect(body.classList.contains("persona-gap-6")).toBe(true);
+    expect(host.hidden).toBe(false);
+  });
+});
+
+describe("greeting bubble", () => {
+  it("renders the greeting as plain text, never markup", () => {
+    const host = buildGreetingHost();
+    renderWelcomeGreeting(host, "<b>bold</b> & fine", undefined);
+    expect(host.querySelector("b")).toBeNull();
+    expect(host.textContent).toBe("<b>bold</b> & fine");
+  });
+
+  it("clears and hides when the greeting is removed", () => {
+    const host = buildGreetingHost();
+    renderWelcomeGreeting(host, "Hi", undefined);
+    expect(host.hidden).toBe(false);
+    renderWelcomeGreeting(host, undefined, undefined);
+    expect(host.hidden).toBe(true);
+    expect(host.childElementCount).toBe(0);
+  });
+});
+
+describe("hero dismiss animation", () => {
+  it("runs on the Web Animations API and settles after it finishes", async () => {
+    const { host } = makeHost();
+    document.body.appendChild(host);
+    let resolveFinished: () => void = () => {};
+    const finished = new Promise<void>((resolve) => {
+      resolveFinished = resolve;
+    });
+    const animate = vi.fn(
+      (_keyframes: unknown, _options?: { fill?: string }) =>
+        ({ finished }) as unknown as Animation
+    );
+    (host as unknown as { animate: typeof animate }).animate = animate;
+
+    const onFinished = vi.fn();
+    const animation = animateWelcomeOut(host, onFinished);
+    expect(animate).toHaveBeenCalledTimes(1);
+    // `forwards`: `backwards` only fills the delay phase, so the element would
+    // flash back to opacity 1 after the keyframes end.
+    expect(animate.mock.calls[0]![1]?.fill).toBe("forwards");
+    expect(animation).toBeTruthy();
+    expect(onFinished).not.toHaveBeenCalled();
+
+    resolveFinished();
+    await finished;
+    await Promise.resolve();
+    expect(onFinished).toHaveBeenCalledWith(animation);
+    host.remove();
+  });
+
+  it("settles immediately without Web Animations support", () => {
+    const { host } = makeHost();
+    const onFinished = vi.fn();
+    expect(animateWelcomeOut(host, onFinished)).toBeNull();
+    expect(onFinished).toHaveBeenCalledWith(null);
+  });
+});

package/src/components/welcome.ts

@@ -0,0 +1,305 @@
+import { createElement, createNode } from "../utils/dom";
+import { renderLucideIcon } from "../utils/icons";
+import { getBubbleClasses } from "./message-bubble";
+import type {
+  AgentWidgetConfig,
+  AgentWidgetWelcomeIcon,
+} from "../types";
+import type { ResolvedWelcomeConfig } from "../welcome";
+
+/**
+ * Welcome surface DOM. The host is permanent: it mounts once with the panel
+ * and every variant/visibility change is applied to it in place, so live
+ * `controller.update()` never rebuilds it.
+ */
+
+export interface WelcomeHostElements {
+  /** Permanent host; also carries `data-persona-intro-card` for slot parity. */
+  host: HTMLElement;
+  iconHolder: HTMLElement;
+  title: HTMLElement;
+  subtitle: HTMLElement;
+  starterSuggestions: HTMLElement;
+}
+
+const WELCOME_ICON_SIZE = 40;
+
+/** Replaces the holder's content; hides it when no icon is configured. */
+export const applyWelcomeIcon = (
+  holder: HTMLElement,
+  icon: AgentWidgetWelcomeIcon | undefined
+): void => {
+  holder.replaceChildren();
+  if (!icon) {
+    holder.hidden = true;
+    return;
+  }
+
+  if (typeof icon === "function") {
+    let custom: HTMLElement | SVGElement | null = null;
+    try {
+      custom = icon();
+    } catch (error) {
+      console.warn("[persona] welcome.icon renderer threw", error);
+    }
+    if (!custom) {
+      holder.hidden = true;
+      return;
+    }
+    holder.appendChild(custom);
+    holder.hidden = false;
+    return;
+  }
+
+  if (icon.type === "lucide") {
+    const svg = renderLucideIcon(icon.name, WELCOME_ICON_SIZE);
+    if (!svg) {
+      holder.hidden = true;
+      return;
+    }
+    holder.appendChild(svg);
+  } else if (icon.type === "image") {
+    holder.appendChild(
+      createNode("img", {
+        className: "persona-welcome-icon-image",
+        attrs: { src: icon.url, alt: icon.alt },
+      })
+    );
+  } else {
+    holder.appendChild(
+      createNode("span", {
+        className: "persona-welcome-icon-text",
+        text: icon.text,
+      })
+    );
+  }
+  holder.hidden = false;
+};
+
+/**
+ * Build the welcome host. `starterSuggestions` is created by the caller so the
+ * suggestion surface keeps its existing wiring.
+ */
+export const buildWelcomeHost = (
+  config: AgentWidgetConfig | undefined,
+  starterSuggestions: HTMLElement,
+  options: { flatShadow?: boolean } = {}
+): WelcomeHostElements => {
+  const iconHolder = createNode("div", {
+    className: "persona-welcome-icon",
+    attrs: { "data-persona-welcome-icon": "" },
+  });
+  iconHolder.hidden = true;
+
+  // Typography flows through `components.introCard.title` / `.subtitle`;
+  // the CSS fallbacks reproduce the utility classes these replaced.
+  const title = createElement("h2", "persona-welcome-title");
+  const subtitle = createElement("p", "persona-welcome-subtitle");
+
+  // Background and box-shadow flow through the themable `components.introCard`
+  // tokens; both default to flat. Docked mode always stays flat. Padding comes
+  // from `--persona-intro-card-padding` (see widget.css), which zeroes its
+  // horizontal component when the card resolves flat so the text shares the
+  // content column's left edge instead of carrying a phantom card inset.
+  const host = createNode(
+    "div",
+    {
+      className: "persona-welcome persona-rounded-2xl",
+      attrs: {
+        "data-persona-welcome": "",
+        "data-persona-intro-card": "",
+        "data-persona-welcome-variant": "card",
+      },
+      style: {
+        background: "var(--persona-intro-card-bg, transparent)",
+        boxShadow: options.flatShadow
+          ? "none"
+          : "var(--persona-intro-card-shadow, none)",
+        border: "var(--persona-intro-card-border, none)",
+      },
+    },
+    iconHolder,
+    title,
+    subtitle,
+    starterSuggestions
+  );
+
+  return { host, iconHolder, title, subtitle, starterSuggestions };
+};
+
+/**
+ * Show/hide the permanent host. The body gap tightens when nothing renders
+ * there so a hidden welcome leaves no phantom section spacing.
+ */
+export const applyWelcomeVisibility = (
+  body: HTMLElement,
+  host: HTMLElement,
+  visible: boolean
+): void => {
+  host.hidden = !visible;
+  host.style.display = visible ? "" : "none";
+  body.classList.toggle("persona-gap-6", visible);
+  body.classList.toggle("persona-gap-3", !visible);
+};
+
+/**
+ * Apply resolved config to the permanent host. Every field is set on every
+ * call so `controller.update()` can drop a field and see it revert.
+ */
+export const applyWelcomeConfig = (
+  elements: WelcomeHostElements,
+  resolved: ResolvedWelcomeConfig
+): void => {
+  elements.title.textContent = resolved.title;
+  elements.subtitle.textContent = resolved.subtitle;
+  // An empty subtitle omits the paragraph entirely, margin included.
+  elements.subtitle.hidden = resolved.subtitle === "";
+  applyWelcomeIcon(elements.iconHolder, resolved.icon);
+  elements.host.setAttribute("data-persona-welcome-variant", resolved.variant);
+  elements.host.setAttribute("data-persona-welcome-dismiss", resolved.dismiss);
+};
+
+/** Marks the element a `renderWelcome` plugin returned. */
+export const WELCOME_PLUGIN_CONTENT_ATTR = "data-persona-welcome-plugin";
+const WELCOME_OVERLAY_ATTR = "data-persona-welcome-overlay";
+const WELCOME_OVERLAY_BODY_CLASS = "persona-welcome-overlay-active";
+
+// An absolute child of a scrolled scroller sits at the content origin, not
+// the visible viewport, and overflow: hidden freezes scrollTop rather than
+// resetting it. Zero the scroll while the overlay is up, restore on clear.
+const overlayScrollTop = new WeakMap<HTMLElement, number>();
+
+/**
+ * Mount plugin content inside the permanent host. The default children are
+ * hidden by CSS while the content attribute is set, so nothing about their
+ * own hidden state has to be saved and restored.
+ */
+export const mountWelcomePluginContent = (
+  body: HTMLElement,
+  host: HTMLElement,
+  element: HTMLElement
+): void => {
+  element.setAttribute(WELCOME_PLUGIN_CONTENT_ATTR, "");
+  host.appendChild(element);
+  host.setAttribute("data-persona-welcome-content", "plugin");
+  // Plugin content renders regardless of derived visibility and overlays the
+  // transcript, which is what makes "return to home" over a conversation work.
+  host.setAttribute(WELCOME_OVERLAY_ATTR, "");
+  if (!body.classList.contains(WELCOME_OVERLAY_BODY_CLASS)) {
+    overlayScrollTop.set(body, body.scrollTop);
+    body.classList.add(WELCOME_OVERLAY_BODY_CLASS);
+    body.scrollTop = 0;
+  }
+};
+
+/** Remove plugin content and hand the host back to the default renderer. */
+export const clearWelcomePluginContent = (
+  body: HTMLElement,
+  host: HTMLElement,
+  element: HTMLElement | null
+): void => {
+  if (element && element !== host) element.remove();
+  host.removeAttribute("data-persona-welcome-content");
+  host.removeAttribute(WELCOME_OVERLAY_ATTR);
+  if (body.classList.contains(WELCOME_OVERLAY_BODY_CLASS)) {
+    body.classList.remove(WELCOME_OVERLAY_BODY_CLASS);
+    body.scrollTop = overlayScrollTop.get(body) ?? body.scrollTop;
+    overlayScrollTop.delete(body);
+  }
+};
+
+/**
+ * Greeting host: a sibling above `messagesWrapper`, so it is pinned at
+ * transcript position zero without ever entering the morph target.
+ */
+export const buildGreetingHost = (): HTMLElement => {
+  const host = createNode("div", {
+    className: "persona-welcome-greeting persona-flex persona-flex-col",
+    attrs: { "data-persona-welcome-greeting": "" },
+  });
+  host.hidden = true;
+  return host;
+};
+
+/**
+ * Render the display-only greeting bubble. Plain text by contract: no
+ * markdown pipeline, no action affordances, no message id, never a session
+ * message.
+ */
+export const renderWelcomeGreeting = (
+  host: HTMLElement,
+  text: string | undefined,
+  config: AgentWidgetConfig | undefined
+): void => {
+  host.replaceChildren();
+  if (!text) {
+    host.hidden = true;
+    return;
+  }
+
+  const layout = config?.layout?.messages?.layout ?? "bubble";
+  const bubble = createNode("div", {
+    className: getBubbleClasses("assistant", layout).join(" "),
+    attrs: { "data-persona-theme-zone": "assistant-message" },
+    text,
+    style:
+      layout === "flat"
+        ? {
+            backgroundColor: "transparent",
+            color: "var(--persona-message-assistant-text, var(--persona-text))",
+          }
+        : {
+            backgroundColor:
+              "var(--persona-message-assistant-bg, var(--persona-container))",
+            color: "var(--persona-message-assistant-text, var(--persona-text))",
+          },
+  });
+
+  host.appendChild(createNode("div", { className: "persona-flex" }, bubble));
+  host.hidden = false;
+};
+
+const prefersReducedMotion = (): boolean =>
+  typeof window !== "undefined" &&
+  typeof window.matchMedia === "function" &&
+  window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+/**
+ * Hero dismiss. WAAPI, not a CSS transition: morph re-renders strip
+ * post-render CSS state and cancel transitions mid-stream. Shares the
+ * starters' entrance motion spec so the two read as one system.
+ *
+ * Returns the animation so the caller can hold the host visible while it runs
+ * and cancel it on a re-show. `onFinished` receives it, or null when the motion
+ * was skipped and the callback ran synchronously.
+ */
+export const animateWelcomeOut = (
+  host: HTMLElement,
+  onFinished: (animation: Animation | null) => void
+): Animation | null => {
+  if (
+    prefersReducedMotion() ||
+    typeof host.animate !== "function" ||
+    !host.isConnected
+  ) {
+    onFinished(null);
+    return null;
+  }
+  // `forwards`, not `backwards`: backwards only fills the delay phase, so the
+  // element snaps back to opacity 1 for a frame after the keyframes end.
+  const animation = host.animate(
+    [
+      { opacity: "1", transform: "none" },
+      { opacity: "0", transform: "translateY(-4px)" },
+    ],
+    { duration: 180, easing: "ease-out", fill: "forwards" }
+  );
+  let settled = false;
+  const settle = () => {
+    if (settled) return;
+    settled = true;
+    onFinished(animation);
+  };
+  animation.finished.then(settle).catch(settle);
+  return animation;
+};

package/src/components/widget-view.test.ts

@@ -129,15 +129,17 @@ describe("createWidgetView: replacement helpers", () => {
 describe("resolveLauncher", () => {
   const config: AgentWidgetConfig = { apiUrl: "/api" };
 
-  it("builds the default launcher controller and wires onToggle", () => {
+  it("builds the default launcher surface and wires onToggle", () => {
     const onToggle = vi.fn();
     const { instance, element } = resolveLauncher({ config, plugins: [], onToggle });
 
     expect(instance).not.toBeNull();
     expect(element).toBe(instance?.element);
-    expect(element.tagName).toBe("BUTTON");
+    // The mounted element is the surface wrapper; the button is inside it.
+    expect(element.tagName).toBe("DIV");
+    expect(instance?.launcher.element.tagName).toBe("BUTTON");
 
-    element.dispatchEvent(new Event("click"));
+    instance!.launcher.element.dispatchEvent(new Event("click"));
     expect(onToggle).toHaveBeenCalledTimes(1);
   });
 

package/src/components/widget-view.ts

@@ -2,7 +2,7 @@ import { AgentWidgetConfig } from "../types";
 import { AgentWidgetPlugin } from "../plugins/types";
 import { createWrapper, buildPanel, PanelElements } from "./panel";
 import { HeaderElements } from "./header-builder";
-import { createLauncherButton, LauncherButton } from "./launcher";
+import { createLauncherButton, createLauncherSurface, LauncherSurface } from "./launcher";
 
 /**
  * Widget view assembly layer.
@@ -30,8 +30,13 @@ export interface WidgetTranscriptRefs {
   container: HTMLElement;
   body: HTMLElement;
   messagesWrapper: HTMLElement;
+  starterSuggestions: HTMLElement;
+  transcriptSuggestions: HTMLElement;
   /** Absolute slot above the composer where interactive sheets mount. */
   composerOverlay: HTMLElement;
+  welcomeHost: HTMLElement;
+  welcomeIconHolder: HTMLElement;
+  greetingHost: HTMLElement;
   introTitle: HTMLElement;
   introSubtitle: HTMLElement;
 }
@@ -119,7 +124,12 @@ export const createWidgetView = ({
     container: panelElements.container,
     body: panelElements.body,
     messagesWrapper: panelElements.messagesWrapper,
+    starterSuggestions: panelElements.starterSuggestions,
+    transcriptSuggestions: panelElements.transcriptSuggestions,
     composerOverlay: panelElements.composerOverlay,
+    welcomeHost: panelElements.welcomeHost,
+    welcomeIconHolder: panelElements.welcomeIconHolder,
+    greetingHost: panelElements.greetingHost,
     introTitle: panelElements.introTitle,
     introSubtitle: panelElements.introSubtitle,
   };
@@ -195,11 +205,11 @@ export interface ResolveLauncherOptions {
 
 export interface ResolvedLauncher {
   /**
-   * The default launcher controller (with `update`/`destroy`), or null when a
+   * The default launcher surface (with `update`/`destroy`), or null when a
    * plugin supplied a custom launcher element.
    */
-  instance: LauncherButton | null;
-  /** The element to mount: either the default button or the plugin's element. */
+  instance: LauncherSurface | null;
+  /** The element to mount: either the default surface or the plugin's element. */
   element: HTMLElement;
 }
 
@@ -209,8 +219,9 @@ export interface ResolvedLauncher {
  * both the initial-build and re-enable call sites in ui.ts.
  *
  * When a plugin returns a custom element, `instance` is null (the plugin owns
- * its own updates); otherwise the default `LauncherButton` controller is
- * returned so the caller can drive `update()`/`destroy()`.
+ * its own updates, including any teaser); otherwise the default
+ * `LauncherSurface` controller is returned so the caller can drive
+ * `update()`/`destroy()`.
  */
 export const resolveLauncher = ({
   config,
@@ -229,6 +240,6 @@ export const resolveLauncher = ({
     }
   }
 
-  const instance = createLauncherButton(config, onToggle);
+  const instance = createLauncherSurface(config, onToggle);
   return { instance, element: instance.element };
 };

package/src/defaults.ts

@@ -79,8 +79,8 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
   colorScheme: "light",
   launcher: DEFAULT_LAUNCHER_CONFIG,
   copy: {
-    welcomeTitle: "Hello 👋",
-    welcomeSubtitle: "Ask anything about your account or products.",
+    // No welcomeTitle / welcomeSubtitle here on purpose: `resolveWelcomeConfig`
+    // owns those defaults so presence still means "the host set this".
     inputPlaceholder: "How can I help...",
     sendButtonLabel: "Send",
   },
@@ -169,10 +169,12 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       submitLabel: "Send",
     },
   },
+  // Placeholder copy that models the right shape: verb-first, user-voice,
+  // one line. Integrators should swap in domain prompts.
   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",
   ],
   suggestionChipsConfig: {
     fontFamily: "sans-serif",

package/src/generated/runtype-openapi-contract.ts

@@ -260,7 +260,24 @@ export type RuntypeExecutionStreamEvent = ({
   type: "source";
   url?: string;
   [key: string]: unknown;
+} | {
+  executionId: string;
+  iteration?: number;
+  seq: number;
+  state: Record<string, unknown>;
+  type: "state_snapshot";
 } | ({
+  executionId: string;
+  iteration?: number;
+  patch: Array<{
+  from?: string;
+  op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+  path: string;
+  value?: unknown;
+}>;
+  seq: number;
+  type: "state_delta";
+}) | ({
   executionId: string;
   hiddenParameterNames?: Array<string>;
   iteration?: number;

package/src/index-core.ts

@@ -31,6 +31,7 @@ export type {
   AgentWidgetInitOptions,
   AgentWidgetMessage,
   AgentWidgetLauncherConfig,
+  AgentWidgetLauncherTeaserConfig,
   AgentWidgetDockConfig,
   AgentWidgetEvent,
   AgentWidgetStreamParser,
@@ -140,7 +141,22 @@ export type {
   AskUserQuestionPrompt,
   AskUserQuestionOption,
   AgentWidgetAskUserQuestionFeature,
-  AgentWidgetAskUserQuestionStyles
+  AgentWidgetAskUserQuestionStyles,
+  AgentWidgetSuggestion,
+  AgentWidgetSuggestionChipsConfig,
+  AgentWidgetResolvedSuggestion,
+  AgentWidgetSuggestionBehavior,
+  AgentWidgetSuggestionVariant,
+  AgentWidgetSuggestionSurface,
+  AgentWidgetSuggestionSource,
+  AgentWidgetSuggestionSurfaceConfig,
+  AgentWidgetStarterSuggestionsConfig,
+  AgentWidgetFollowUpSuggestionsConfig,
+  AgentWidgetSuggestionsConfig,
+  AgentWidgetWelcomeConfig,
+  AgentWidgetWelcomeIcon,
+  AgentWidgetWelcomeVariant,
+  AgentWidgetWelcomeDismiss
 } from "./types";
 
 export {
@@ -326,7 +342,17 @@ export { VERSION } from "./version";
 export type { AgentWidgetInitHandle };
 
 // Plugin system exports
-export type { AgentWidgetPlugin } from "./plugins/types";
+export type {
+  AgentWidgetPlugin,
+  AgentWidgetTransformSuggestionsContext,
+  AgentWidgetRenderSuggestionContext,
+  AgentWidgetRenderWelcomeContext,
+  AgentWidgetSuggestionSelectContext
+} from "./plugins/types";
+// Welcome resolver: `renderWelcome` receives the resolved shape.
+export { resolveWelcomeConfig, isWelcomeVisible } from "./welcome";
+export type { ResolvedWelcomeConfig } from "./welcome";
+export type { AgentWidgetPluginStorage } from "./utils/plugin-storage";
 export { pluginRegistry } from "./plugins/registry";
 
 // Stream animation plugin API: lets consumers register custom animations
@@ -431,6 +457,7 @@ export type {
   SemanticSpacing,
   SemanticTypography,
   ComponentTokens,
+  TextStyleTokens,
   ArtifactToolbarTokens,
   ArtifactTabTokens,
   ArtifactPaneTokens,

package/src/launcher-global.ts

@@ -1,7 +1,8 @@
 /**
  * Critical-path launcher entry: built to `launcher.global.js` (IIFE).
  *
- * Ships ONLY the real collapsed launcher (`createLauncherButton`) plus the
+ * Ships ONLY the real collapsed launcher surface (`createLauncherSurface`,
+ * which carries the optional launcher teaser) plus the
  * theme application path, so the launcher paints pixel-identically to the full
  * widget from a tiny bundle. The heavy conversation panel is deferred until
  * first open by the installer (Phase 2).
@@ -16,7 +17,7 @@
  *   window.AgentWidgetLauncher.mount({ target, config, onOpen })
  *     → { root, element, update, destroy }
  */
-import { createLauncherButton } from "./components/launcher";
+import { createLauncherSurface } from "./components/launcher";
 import { applyThemeVariables } from "./utils/theme";
 import { DEFAULT_LAUNCHER_CONFIG } from "./defaults";
 import type { AgentWidgetConfig } from "./types";
@@ -76,7 +77,7 @@ const mergeCriticalLauncherConfig = (
  * Mirrors the full widget's DOM exactly (`runtime/init.ts` + `ui.ts`): a
  * `[data-persona-root]` wrapper carries the theme CSS variables and the launcher
  * button is its child. Keeping the theme vars on the wrapper (not the button)
- * leaves the button's own inline style byte-identical to the full widget's, so
+ * leaves the button's own inline style matching the full widget's, so
  * the eventual mount-then-remove handoff is invisible.
  */
 export const mount = (
@@ -100,20 +101,22 @@ export const mount = (
   root.setAttribute(CRITICAL_LAUNCHER_ATTR, "true");
   applyThemeVariables(root, config);
 
-  const launcher = createLauncherButton(config, onOpen);
-  root.appendChild(launcher.element);
+  const surface = createLauncherSurface(config, onOpen);
+  root.appendChild(surface.element);
   target.appendChild(root);
 
   return {
     root,
-    element: launcher.element,
+    element: surface.launcher.element,
     update: (next: AgentWidgetConfig) => {
       const merged = mergeCriticalLauncherConfig(next);
       applyThemeVariables(root, merged);
-      launcher.update(merged);
+      surface.update(merged);
     },
+    // Handoff destroys the whole surface, so a pending teaser timer cannot
+    // outlive the critical launcher.
     destroy: () => {
-      launcher.destroy();
+      surface.destroy();
       root.remove();
     },
   };