@runtypelabs/persona 4.15.0 → 4.17.0

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.
@@ -34,6 +34,9 @@ export interface WidgetTranscriptRefs {
   transcriptSuggestions: HTMLElement;
   /** Absolute slot above the composer where interactive sheets mount. */
   composerOverlay: HTMLElement;
+  welcomeHost: HTMLElement;
+  welcomeIconHolder: HTMLElement;
+  greetingHost: HTMLElement;
   introTitle: HTMLElement;
   introSubtitle: HTMLElement;
 }
@@ -124,6 +127,9 @@ export const createWidgetView = ({
     starterSuggestions: panelElements.starterSuggestions,
     transcriptSuggestions: panelElements.transcriptSuggestions,
     composerOverlay: panelElements.composerOverlay,
+    welcomeHost: panelElements.welcomeHost,
+    welcomeIconHolder: panelElements.welcomeIconHolder,
+    greetingHost: panelElements.greetingHost,
     introTitle: panelElements.introTitle,
     introSubtitle: panelElements.introSubtitle,
   };
@@ -199,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;
 }
 
@@ -213,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,
@@ -233,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",
   },

package/src/index-core.ts

@@ -31,6 +31,7 @@ export type {
   AgentWidgetInitOptions,
   AgentWidgetMessage,
   AgentWidgetLauncherConfig,
+  AgentWidgetLauncherTeaserConfig,
   AgentWidgetDockConfig,
   AgentWidgetEvent,
   AgentWidgetStreamParser,
@@ -151,7 +152,11 @@ export type {
   AgentWidgetSuggestionSurfaceConfig,
   AgentWidgetStarterSuggestionsConfig,
   AgentWidgetFollowUpSuggestionsConfig,
-  AgentWidgetSuggestionsConfig
+  AgentWidgetSuggestionsConfig,
+  AgentWidgetWelcomeConfig,
+  AgentWidgetWelcomeIcon,
+  AgentWidgetWelcomeVariant,
+  AgentWidgetWelcomeDismiss
 } from "./types";
 
 export {
@@ -341,8 +346,13 @@ 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
@@ -447,6 +457,7 @@ export type {
   SemanticSpacing,
   SemanticTypography,
   ComponentTokens,
+  TextStyleTokens,
   ArtifactToolbarTokens,
   ArtifactTabTokens,
   ArtifactPaneTokens,

package/src/install.test.ts

@@ -404,12 +404,46 @@ describe("install.ts: CDN base derivation", () => {
     expect(cssHref).toBe("https://cdn.jsdelivr.net/npm/@runtypelabs/persona@latest/dist/widget.css");
   });
 
-  it("an explicit `version` opts back into npm-CDN URLs even when the src is derivable", async () => {
+  it("an explicit `version` on the first-party CDN stays first-party (versioned path)", async () => {
     setCurrentScript("https://cdn.runtype.com/persona/latest/install.global.js");
+    const { cssHref, scripts } = await installedUrls({ version: "1.2.3" });
+    expect(cssHref).toBe("https://cdn.runtype.com/persona/1.2.3/widget.css");
+    expect(scripts).toContain("https://cdn.runtype.com/persona/1.2.3/launcher.global.js");
+  });
+
+  it("an explicit `version` on a non-first-party src opts into npm-CDN URLs", async () => {
+    setCurrentScript("https://assets.example.com/vendor/persona/install.global.js");
     const { cssHref } = await installedUrls({ version: "1.2.3" });
     expect(cssHref).toBe("https://cdn.jsdelivr.net/npm/@runtypelabs/persona@1.2.3/dist/widget.css");
   });
 
+  it("warns when resolved assets leave the installer's origin (silent-CSP guard)", async () => {
+    setCurrentScript("https://cdn.runtype.com/persona/latest/install.global.js");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await installedUrls({ cdn: "jsdelivr" });
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("strict CSP may silently block"));
+    warn.mockRestore();
+  });
+
+  it("does not warn when assets resolve to the installer's own origin", async () => {
+    setCurrentScript("https://cdn.runtype.com/persona/latest/install.global.js");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await installedUrls({ version: "1.2.3" });
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("does not warn for explicit cssUrl + jsUrl overrides on another origin", async () => {
+    setCurrentScript("https://cdn.runtype.com/persona/latest/install.global.js");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await installedUrls({
+      cssUrl: "https://assets.example.com/persona/widget.css",
+      jsUrl: "https://assets.example.com/persona/index.global.js",
+    });
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
   it("an explicit `cdn` opts back into npm-CDN URLs even when the src is derivable", async () => {
     setCurrentScript("https://cdn.runtype.com/persona/latest/install.global.js");
     const { cssHref } = await installedUrls({ cdn: "unpkg" });

package/src/install.ts

@@ -7,9 +7,12 @@
 export {};
 
 interface SiteAgentInstallConfig {
-  // Setting `version` or `cdn` explicitly opts into npm-CDN asset URLs
-  // (jsDelivr/unpkg). When neither is set, assets load from the directory the
-  // installer script itself was served from — see getCdnBase().
+  // Setting `cdn` explicitly opts into npm-CDN asset URLs (jsDelivr/unpkg),
+  // and `version` pins the asset version. When neither is set, assets load
+  // from the directory the installer script itself was served from. On the
+  // first-party CDN (cdn.runtype.com) a `version` stays first-party
+  // (…/persona/<version>/); elsewhere it opts into npm-CDN URLs. Prefer
+  // pinning via the installer script URL itself — see getCdnBase().
   version?: string;
   cdn?: "unpkg" | "jsdelivr";
   cssUrl?: string;
@@ -239,16 +242,30 @@ declare global {
 
     // Default: load assets from wherever the installer was served, so a page
     // whose CSP allows only its own CDN (e.g. cdn.runtype.com) never has
-    // sibling requests fan out to a third-party host. An explicit `cdn` or
-    // `version` keeps the documented npm-CDN behavior.
-    if (!config.cdn && !config.version) {
+    // sibling requests fan out to a third-party host. An explicit `cdn`
+    // keeps the documented npm-CDN behavior.
+    if (!config.cdn) {
       const selfBase = getInstallerBase();
       if (selfBase) {
-        return {
-          cssUrl: `${selfBase}/widget.css`,
-          jsUrl: `${selfBase}/index.global.js`,
-          launcherUrl: `${selfBase}/launcher.global.js` as string | null,
-        };
+        if (!config.version) {
+          return {
+            cssUrl: `${selfBase}/widget.css`,
+            jsUrl: `${selfBase}/index.global.js`,
+            launcherUrl: `${selfBase}/launcher.global.js` as string | null,
+          };
+        }
+        // A `version` on the first-party CDN stays first-party: the bucket
+        // mirrors every release at /persona/<version>/, and rerouting to a
+        // npm CDN would be blocked by the CSP that allowed the installer.
+        const selfOrigin = new URL(selfBase).origin;
+        if (selfOrigin === "https://cdn.runtype.com") {
+          const base = `${selfOrigin}/persona/${config.version}`;
+          return {
+            cssUrl: `${base}/widget.css`,
+            jsUrl: `${base}/index.global.js`,
+            launcherUrl: `${base}/launcher.global.js` as string | null,
+          };
+        }
       }
     }
 
@@ -268,6 +285,25 @@ declare global {
 
   const { cssUrl, jsUrl, launcherUrl } = getCdnBase();
 
+  // Surface silent CSP breakage: when `cdn`/`version` reroutes assets to a
+  // different origin than the one that served the installer, a strict CSP
+  // (e.g. Runtype-hosted apps) blocks them with no visible error. Explicit
+  // cssUrl/jsUrl overrides are a deliberate choice, so they don't warn.
+  if (!(config.cssUrl && config.jsUrl)) {
+    const selfBase = getInstallerBase();
+    try {
+      if (selfBase && new URL(selfBase).origin !== new URL(jsUrl, document.baseURI).origin) {
+        console.warn(
+          `[persona] Widget assets resolve to ${new URL(jsUrl, document.baseURI).origin}, but the installer loaded from ${new URL(selfBase).origin}. ` +
+          "A strict CSP may silently block them. To pin a version, put it in the installer script URL " +
+          "(e.g. https://cdn.runtype.com/persona/<version>/install.global.js) instead of the `version`/`cdn` config keys.",
+        );
+      }
+    } catch {
+      // URL parsing is best-effort; never let diagnostics break installation.
+    }
+  }
+
   // Check if CSS is already loaded
   const isCssLoaded = () => {
     return !!document.head.querySelector('link[data-persona]') ||

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