@runtypelabs/persona 4.15.0 → 4.16.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/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();
     },
   };

package/src/plugins/types.ts

@@ -1,3 +1,5 @@
+import type { ResolvedWelcomeConfig } from "../welcome";
+import type { AgentWidgetPluginStorage } from "../utils/plugin-storage";
 import {
   AgentWidgetMessage,
   AgentWidgetConfig,
@@ -13,7 +15,8 @@ import {
   AgentWidgetResolvedSuggestion,
   AgentWidgetSuggestionSource,
   AgentWidgetSuggestionSurface,
-  AgentWidgetSuggestionVariant
+  AgentWidgetSuggestionVariant,
+  AgentWidgetWelcomeVariant
 } from "../types";
 
 export type AgentWidgetTransformSuggestionsContext = {
@@ -45,6 +48,28 @@ export type AgentWidgetRenderSuggestionContext = {
   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;
@@ -115,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
@@ -157,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;
 
   /**