@runtypelabs/persona 3.25.0 → 3.27.0

package/src/install.ts

@@ -24,14 +24,42 @@ interface SiteAgentInstallConfig {
   useShadowDom?: boolean;
   // Expose the widget handle on window[windowKey] for programmatic access
   windowKey?: string;
-  // Called when the widget is initialized and ready for interaction
+  /**
+   * Fired as soon as the installer script executes, before it loads or gates
+   * anything. For diagnostics / load-timing baselines ("did my embed run").
+   */
+  onScriptLoad?: (info: { version: string }) => void;
+  /**
+   * Fired when the floating launcher is painted on the page — at page-load time.
+   * Deferred installs: the critical launcher mounts. Eager floating installs:
+   * the full widget's launcher mounts. Use this for "widget appeared" analytics.
+   * Does NOT fire for inline / docked / composer-bar installs (no floating
+   * launcher) — use `onChatReady` there.
+   */
+  onLauncherShown?: (info: { deferred: boolean; element?: HTMLElement }) => void;
+  /**
+   * Fired when the full widget is initialized and its controller API is
+   * callable. Deferred installs: after the user first opens the panel. Eager
+   * installs: on page load.
+   */
+  onChatReady?: (handle: any) => void;
+  /**
+   * @deprecated Use `onChatReady`. Retained as a working alias; it will be
+   * removed in the next major version.
+   */
   onReady?: (handle: any) => void;
+  /**
+   * Fired when a load step fails (stylesheet, full bundle, or init), so you can
+   * detect ad-blocked / timed-out installs instead of failing silently.
+   */
+  onError?: (info: { phase: "css" | "bundle" | "init"; error: unknown }) => void;
 }
 
 declare global {
   interface Window {
     siteAgentConfig?: SiteAgentInstallConfig;
     AgentWidget?: any;
+    AgentWidgetLauncher?: any;
   }
 }
 
@@ -111,6 +139,56 @@ declare global {
   const windowConfig: SiteAgentInstallConfig = window.siteAgentConfig || {};
   const config: SiteAgentInstallConfig = { ...windowConfig, ...scriptConfig };
 
+  // --- Lifecycle helpers -----------------------------------------------------
+  // A throwing user callback must never break the installer.
+  const safeCall = <T>(fn: ((arg: T) => void) | undefined, arg: T): void => {
+    try {
+      fn?.(arg);
+    } catch (e) {
+      console.error("[Persona] lifecycle callback threw:", e);
+    }
+  };
+  const dispatchLifecycle = (name: string, detail: unknown): void => {
+    try {
+      window.dispatchEvent(new CustomEvent(name, { detail }));
+    } catch {
+      /* CustomEvent unsupported — ignore */
+    }
+  };
+  const fail = (phase: "css" | "bundle" | "init", error: unknown): void => {
+    console.error("Failed to install AgentWidget:", error);
+    safeCall(config.onError, { phase, error });
+    dispatchLifecycle("persona:error", { phase, error });
+  };
+  // `onReady` is the deprecated alias of `onChatReady`; warn once if it's used.
+  let warnedOnReadyDeprecated = false;
+  const resolveChatReady = (): ((handle: any) => void) | undefined => {
+    if (config.onChatReady) return config.onChatReady;
+    if (config.onReady) {
+      if (!warnedOnReadyDeprecated) {
+        warnedOnReadyDeprecated = true;
+        console.warn(
+          "[Persona] `onReady` is deprecated — use `onChatReady`. `onReady` still works but is removed in the next major."
+        );
+      }
+      return config.onReady;
+    }
+    return undefined;
+  };
+  // True when the config renders a standard floating launcher button — the only
+  // case that paints a clickable launcher at load. Shared by the deferral gate
+  // and the eager-path `onLauncherShown` so the event name stays honest.
+  const hasFloatingLauncher = (widgetConfig: any): boolean => {
+    const launcher = widgetConfig.launcher ?? {};
+    if (launcher.enabled === false) return false;             // inline embed
+    return (launcher.mountMode ?? "floating") === "floating"; // not docked / composer-bar
+  };
+
+  // Earliest signal: the installer has executed. Fire before any loading or
+  // preview-gating so it's a reliable "did my embed run" beacon for diagnostics.
+  safeCall(config.onScriptLoad, { version: config.version || "latest" });
+  dispatchLifecycle("persona:script-load", { version: config.version || "latest" });
+
   const isPreviewModeEnabled = (): boolean => {
     if (!config.previewQueryParam) {
       return true;
@@ -131,27 +209,31 @@ declare global {
 
   // Determine CDN base URL
   const getCdnBase = () => {
+    // For a custom URL override, derive the sibling launcher URL when the
+    // override mirrors the dist layout (…/index.global.js → …/launcher.global.js)
+    // so self-hosted deployments still get the optimization. A non-standard
+    // jsUrl yields null → eager-load fallback.
     if (config.cssUrl && config.jsUrl) {
-      return { cssUrl: config.cssUrl, jsUrl: config.jsUrl };
-    }
-    
-    const packageName = "@runtypelabs/persona";
-    const basePath = `/npm/${packageName}@${version}/dist`;
-    
-    if (cdn === "unpkg") {
-      return {
-        cssUrl: `https://unpkg.com${basePath}/widget.css`,
-        jsUrl: `https://unpkg.com${basePath}/index.global.js`
-      };
-    } else {
+      const derivedLauncherUrl = config.jsUrl.replace(/index\.global\.js($|\?)/, "launcher.global.js$1");
       return {
-        cssUrl: `https://cdn.jsdelivr.net${basePath}/widget.css`,
-        jsUrl: `https://cdn.jsdelivr.net${basePath}/index.global.js`
+        cssUrl: config.cssUrl,
+        jsUrl: config.jsUrl,
+        launcherUrl: (derivedLauncherUrl !== config.jsUrl ? derivedLauncherUrl : null) as string | null,
       };
     }
+
+    const packageName = "@runtypelabs/persona";
+    const basePath = `/npm/${packageName}@${version}/dist`;
+    const host = cdn === "unpkg" ? "https://unpkg.com" : "https://cdn.jsdelivr.net";
+
+    return {
+      cssUrl: `${host}${basePath}/widget.css`,
+      jsUrl: `${host}${basePath}/index.global.js`,
+      launcherUrl: `${host}${basePath}/launcher.global.js` as string | null,
+    };
   };
 
-  const { cssUrl, jsUrl } = getCdnBase();
+  const { cssUrl, jsUrl, launcherUrl } = getCdnBase();
 
   // Check if CSS is already loaded
   const isCssLoaded = () => {
@@ -238,41 +320,76 @@ declare global {
     });
   };
 
-  // Initialize widget
-  const initWidget = () => {
+  // Load the tiny launcher-only critical bundle (launcher.global.js)
+  const isLauncherLoaded = () => !!window.AgentWidgetLauncher;
+
+  const loadLauncher = (): Promise<void> => {
+    return new Promise((resolve, reject) => {
+      if (isLauncherLoaded() || !launcherUrl) {
+        resolve();
+        return;
+      }
+
+      const script = document.createElement("script");
+      script.src = launcherUrl;
+      script.async = true;
+      script.onload = () => resolve();
+      script.onerror = () => reject(new Error(`Failed to load launcher from ${launcherUrl}`));
+      document.head.appendChild(script);
+    });
+  };
+
+  // Warm the full bundle in the background (download-only, not executed) so the
+  // first open is quick. Runs at idle so it never competes with the launcher.
+  const prefetchFullBundle = (): void => {
+    const addPrefetch = () => {
+      if (isJsLoaded()) return;
+      const link = document.createElement("link");
+      link.rel = "prefetch";
+      link.as = "script";
+      link.href = jsUrl;
+      document.head.appendChild(link);
+    };
+    if (typeof requestIdleCallback !== "undefined") {
+      requestIdleCallback(addPrefetch, { timeout: 4000 });
+    } else {
+      setTimeout(addPrefetch, 1200);
+    }
+  };
+
+  // Merge top-level installer options into the widget config. Shared by the
+  // eager init path and the deferred-launcher path.
+  const buildWidgetInit = (): { target: string | HTMLElement; widgetConfig: any; hasApiConfig: boolean } => {
+    const target = config.target || "body";
+    const widgetConfig: any = { ...config.config };
+
+    if (config.apiUrl && !widgetConfig.apiUrl) widgetConfig.apiUrl = config.apiUrl;
+    if (config.clientToken && !widgetConfig.clientToken) widgetConfig.clientToken = config.clientToken;
+    if (config.flowId && !widgetConfig.flowId) widgetConfig.flowId = config.flowId;
+
+    const hasApiConfig = !!(widgetConfig.apiUrl || widgetConfig.clientToken);
+    return { target, widgetConfig, hasApiConfig };
+  };
+
+  // Initialize the full widget. When `openAfter` is true (the deferred-launcher
+  // handoff), open the panel immediately via the public controller API so the
+  // user's click on the critical launcher carries through.
+  const initWidget = (openAfter = false): any => {
     if (!window.AgentWidget || !window.AgentWidget.initAgentWidget) {
       console.warn("AgentWidget not available. Make sure the script loaded successfully.");
       return;
     }
 
-    const target = config.target || "body";
-    // Merge top-level config options into widget config
-    const widgetConfig = { ...config.config };
-    
-    // Merge apiUrl from top-level config into widget config if present
-    if (config.apiUrl && !widgetConfig.apiUrl) {
-      widgetConfig.apiUrl = config.apiUrl;
-    }
-    
-    // Merge clientToken from top-level config into widget config if present
-    if (config.clientToken && !widgetConfig.clientToken) {
-      widgetConfig.clientToken = config.clientToken;
-    }
-    
-    // Merge flowId from top-level config into widget config if present
-    if (config.flowId && !widgetConfig.flowId) {
-      widgetConfig.flowId = config.flowId;
-    }
+    const { target, widgetConfig, hasApiConfig } = buildWidgetInit();
 
     // Only initialize if we have either apiUrl OR clientToken (or other config)
-    const hasApiConfig = widgetConfig.apiUrl || widgetConfig.clientToken;
     if (!hasApiConfig && Object.keys(widgetConfig).length === 0) {
       return;
     }
 
     // Auto-apply markdown postprocessor if not explicitly set and available
     if (!widgetConfig.postprocessMessage && window.AgentWidget.markdownPostprocessor) {
-      widgetConfig.postprocessMessage = ({ text }: { text: string }) => 
+      widgetConfig.postprocessMessage = ({ text }: { text: string }) =>
         window.AgentWidget.markdownPostprocessor(text);
     }
 
@@ -285,32 +402,149 @@ declare global {
         windowKey: config.windowKey
       });
 
-      config.onReady?.(handle);
-      window.dispatchEvent(new CustomEvent("persona:ready", { detail: handle }));
+      // Handoff from the critical launcher: the user already clicked, so open
+      // the panel via the existing public controller method.
+      if (openAfter && handle && typeof handle.open === "function") {
+        handle.open();
+      }
+
+      // Eager floating installs paint their launcher at load time too — emit the
+      // same page-load "appeared" signal as the deferred path. The deferred
+      // handoff (openAfter) already fired it at launcher mount, and non-floating
+      // modes have no launcher, so guard on both.
+      if (!openAfter && hasFloatingLauncher(widgetConfig)) {
+        safeCall(config.onLauncherShown, { deferred: false });
+        dispatchLifecycle("persona:launcher-shown", { deferred: false });
+      }
+
+      // The full widget is initialized and its controller API is callable.
+      safeCall(resolveChatReady(), handle);
+      dispatchLifecycle("persona:chat-ready", handle);
+      dispatchLifecycle("persona:ready", handle); // deprecated alias — removed next major
+      return handle;
     } catch (error) {
-      console.error("Failed to initialize AgentWidget:", error);
+      fail("init", error);
     }
   };
 
+  // A persisted "open" state reopens the panel on reload with no click
+  // (ui.ts:7513). The installer can't see that from config, so it reads the very
+  // same storage key the widget writes. Mirrors normalizePersistStateConfig
+  // (ui.ts:213): openState persistence defaults on, storage to sessionStorage,
+  // key prefix to "persona-".
+  const hasPersistedOpenState = (widgetConfig: any): boolean => {
+    const persistState = widgetConfig.persistState;
+    if (!persistState) return false; // persistence off → nothing to restore
+    const asObject = typeof persistState === "object" ? persistState : null;
+    if (asObject && asObject.persist?.openState === false) return false; // open-state persistence opted out
+    const keyPrefix = (asObject && asObject.keyPrefix) || "persona-";
+    const storageType = (asObject && asObject.storage) || "session";
+    try {
+      const storage = storageType === "local" ? window.localStorage : window.sessionStorage;
+      return storage.getItem(`${keyPrefix}widget-open`) === "true";
+    } catch {
+      return false; // storage blocked (private mode) → the widget can't restore either
+    }
+  };
+
+  // The deferred-launcher optimization only applies to the common floating case
+  // that paints a collapsed launcher and waits for a click. Anything that starts
+  // open or renders differently eager-loads the full bundle exactly as before —
+  // including the two open triggers config alone can't express: a host
+  // onStateLoaded hook that may request open, and a restored "was open" state.
+  const shouldDeferPanel = (widgetConfig: any): boolean => {
+    if (!launcherUrl) return false;                                      // custom bundle URL override — can't derive launcher URL
+    if (!hasFloatingLauncher(widgetConfig)) return false;                // inline / docked / composer-bar
+    const launcher = widgetConfig.launcher ?? {};
+    if (launcher.autoExpand === true) return false;                      // starts open
+    if (typeof widgetConfig.onStateLoaded === "function") return false;  // hook may request open
+    if (hasPersistedOpenState(widgetConfig)) return false;               // restored "was open"
+    return true;
+  };
+
+  // Render the real launcher from the tiny critical bundle; load + mount the
+  // full widget on first click, then remove the critical launcher.
+  const mountDeferredLauncher = (target: string | HTMLElement, widgetConfig: any): void => {
+    let phase: "idle" | "loading" | "done" = "idle";
+    let launcherHandle: { destroy: () => void } | undefined;
+
+    const onOpen = () => {
+      if (phase !== "idle") return; // already loading or handed off
+      phase = "loading";
+      loadJS()
+        .then(() => {
+          initWidget(true);          // mount the full widget + open the panel
+          launcherHandle?.destroy();  // remove the critical launcher (same component → invisible)
+          phase = "done";
+        })
+        .catch((error) => {
+          phase = "idle";            // allow the click to be retried
+          console.error("Failed to load AgentWidget on open:", error);
+          safeCall(config.onError, { phase: "bundle", error });
+          dispatchLifecycle("persona:error", { phase: "bundle", error });
+        });
+    };
+
+    const mounted = window.AgentWidgetLauncher.mount({ target, config: widgetConfig, onOpen });
+    launcherHandle = mounted;
+
+    // The real launcher is now painted at page-load time — emit the page-load
+    // "appeared" signal (distinct from `onChatReady`, which waits for first open).
+    safeCall(config.onLauncherShown, { deferred: true, element: mounted.element });
+    dispatchLifecycle("persona:launcher-shown", { deferred: true, element: mounted.element });
+
+    // Warm the full bundle so the first open is quick.
+    prefetchFullBundle();
+  };
+
   // Main installation flow (called after hydration completes)
   const install = async () => {
     try {
-      await loadCSS();
-      await loadJS();
-      
       // Auto-init if we have config OR apiUrl OR clientToken
       const shouldAutoInit = autoInit && (
-        config.config || 
-        config.apiUrl || 
+        config.config ||
+        config.apiUrl ||
         config.clientToken
       );
-      
+
+      // Fast path: render the real launcher from the ~13 KB critical bundle and
+      // defer the full widget until first open. Only for the common floating
+      // case; everything else falls through to the eager path below.
+      if (shouldAutoInit) {
+        const { target, widgetConfig } = buildWidgetInit();
+        if (shouldDeferPanel(widgetConfig)) {
+          try {
+            // CSS + launcher in parallel so the launcher paints correctly styled.
+            await Promise.all([loadCSS(), loadLauncher()]);
+            if (window.AgentWidgetLauncher && window.AgentWidgetLauncher.mount) {
+              mountDeferredLauncher(target, widgetConfig);
+              return;
+            }
+          } catch (error) {
+            console.warn("Deferred launcher failed; falling back to eager load.", error);
+          }
+          // Fall through to the eager path on any failure.
+        }
+      }
+
+      // Eager path (unchanged behavior): load the full bundle, then init.
+      try {
+        await loadCSS();
+      } catch (error) {
+        return fail("css", error);
+      }
+      try {
+        await loadJS();
+      } catch (error) {
+        return fail("bundle", error);
+      }
       if (shouldAutoInit) {
         // Wait a tick to ensure AgentWidget is fully initialized
-        setTimeout(initWidget, 0);
+        setTimeout(() => initWidget(false), 0);
       }
     } catch (error) {
-      console.error("Failed to install AgentWidget:", error);
+      // Safety net for anything unexpected before the eager loads above.
+      fail("init", error);
     }
   };
 

package/src/launcher-global.ts

@@ -0,0 +1,115 @@
+/**
+ * Critical-path launcher entry — built to `launcher.global.js` (IIFE).
+ *
+ * Ships ONLY the real collapsed launcher (`createLauncherButton`) plus the full
+ * theme system, so the launcher paints pixel-identically to the full widget from
+ * a tiny bundle (~13 KB brotli vs ~134 KB for `index.global.js`). The heavy
+ * conversation panel is deferred until first open by the installer (Phase 2).
+ *
+ * The full Lucide icon registry is kept on purpose: any *supported* icon a site
+ * configures (`launcher.agentIconName` / `callToActionIconName`) must render at
+ * first paint with no flash, and the only synchronously-available source is this
+ * bundle. See the "Deferred Launcher Loading" pattern in CLAUDE.md.
+ *
+ * Public global (via tsup `--global-name AgentWidgetLauncher`):
+ *
+ *   window.AgentWidgetLauncher.mount({ target, config, onOpen })
+ *     → { root, element, update, destroy }
+ */
+import { createLauncherButton } from "./components/launcher";
+import { applyThemeVariables } from "./utils/theme";
+import { mergeWithDefaults } from "./defaults";
+import type { AgentWidgetConfig } from "./types";
+
+export interface AgentWidgetLauncherMountOptions {
+  /** Where to mount. Defaults to `document.body` (the floating launcher is `position: fixed`). */
+  target?: string | HTMLElement;
+  /** The same widget config the full widget will receive — drives theme, icons, position, copy. */
+  config?: AgentWidgetConfig;
+  /** Called when the launcher is clicked; the installer loads the full widget and opens the panel. */
+  onOpen: () => void;
+}
+
+export interface AgentWidgetLauncherHandle {
+  /** The `[data-persona-root]` wrapper that carries the theme CSS variables. */
+  root: HTMLElement;
+  /** The launcher button element itself. */
+  element: HTMLButtonElement;
+  /** Re-apply theme + re-render the launcher with new config. */
+  update: (config: AgentWidgetConfig) => void;
+  /** Remove the critical launcher (called at handoff once the full widget is mounted). */
+  destroy: () => void;
+}
+
+/**
+ * Marks the critical launcher's wrapper so the installer can find/remove it at
+ * handoff without disturbing the full widget's own `[data-persona-root]`.
+ */
+export const CRITICAL_LAUNCHER_ATTR = "data-persona-launcher-critical";
+
+const resolveTarget = (target?: string | HTMLElement): HTMLElement => {
+  if (target instanceof HTMLElement) return target;
+  if (typeof target === "string") {
+    const el = document.querySelector<HTMLElement>(target);
+    if (el) return el;
+  }
+  return document.body;
+};
+
+/**
+ * Mount the real collapsed launcher from the critical bundle.
+ *
+ * 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
+ * the eventual mount-then-remove handoff is invisible.
+ */
+export const mount = (
+  options: AgentWidgetLauncherMountOptions
+): AgentWidgetLauncherHandle => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    throw new Error(
+      "AgentWidgetLauncher can only be mounted in a browser environment"
+    );
+  }
+
+  const { onOpen } = options;
+  const target = resolveTarget(options.target);
+
+  // Render from the SAME effective config the full widget uses: `ui.ts` runs
+  // `mergeWithDefaults(config)` before building the launcher (ui.ts:495). Without
+  // this, the critical launcher misses launcher defaults like
+  // `callToActionIconPadding` and `agentIconName`, so it looks subtly different
+  // from the full widget that replaces it on open.
+  const config = mergeWithDefaults(options.config) as AgentWidgetConfig;
+
+  const root = document.createElement("div");
+  root.setAttribute("data-persona-root", "true");
+  root.setAttribute(CRITICAL_LAUNCHER_ATTR, "true");
+  applyThemeVariables(root, config);
+
+  const launcher = createLauncherButton(config, onOpen);
+  root.appendChild(launcher.element);
+  target.appendChild(root);
+
+  return {
+    root,
+    element: launcher.element,
+    update: (next: AgentWidgetConfig) => {
+      const merged = mergeWithDefaults(next) as AgentWidgetConfig;
+      applyThemeVariables(root, merged);
+      launcher.update(merged);
+    },
+    destroy: () => {
+      launcher.destroy();
+      root.remove();
+    },
+  };
+};
+
+// Note: the `window.AgentWidgetLauncher` global is created by tsup's
+// `--global-name AgentWidgetLauncher` at build time. The installer
+// (`install.ts`) declares the `Window` augmentation it needs; this entry never
+// reads the global, so re-declaring it here would only create a cross-file type
+// conflict.

package/src/runtime/init.test.ts

@@ -159,6 +159,77 @@ describe("initAgentWidget windowKey and ready notifications", () => {
   });
 });
 
+describe("initAgentWidget onChatReady / onReady deprecation", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    createAgentExperienceMock.mockReset();
+    createAgentExperienceMock.mockImplementation((_mount, config) => createMockController(config));
+  });
+
+  it("calls onChatReady after initialization without a deprecation warning", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const onChatReady = vi.fn();
+    const handle = initAgentWidget({
+      target: "#target",
+      onChatReady,
+      config: { launcher: { enabled: false } },
+    });
+
+    expect(onChatReady).toHaveBeenCalledOnce();
+    expect(warn).not.toHaveBeenCalled();
+
+    handle.destroy();
+    warn.mockRestore();
+  });
+
+  it("prefers onChatReady over the deprecated onReady (onReady never fires, no warning)", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="target"></div>`;
+
+    const onChatReady = vi.fn();
+    const onReady = vi.fn();
+    const handle = initAgentWidget({
+      target: "#target",
+      onChatReady,
+      onReady,
+      config: { launcher: { enabled: false } },
+    });
+
+    expect(onChatReady).toHaveBeenCalledOnce();
+    expect(onReady).not.toHaveBeenCalled();
+    expect(warn).not.toHaveBeenCalled();
+
+    handle.destroy();
+    warn.mockRestore();
+  });
+
+  it("still calls the deprecated onReady but warns at most once across multiple widgets", async () => {
+    // Fresh module so the once-per-page warn flag starts unset.
+    vi.resetModules();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { initAgentWidget } = await import("./init");
+    document.body.innerHTML = `<div id="a"></div><div id="b"></div>`;
+
+    const onReadyA = vi.fn();
+    const onReadyB = vi.fn();
+    const a = initAgentWidget({ target: "#a", onReady: onReadyA, config: { launcher: { enabled: false } } });
+    const b = initAgentWidget({ target: "#b", onReady: onReadyB, config: { launcher: { enabled: false } } });
+
+    expect(onReadyA).toHaveBeenCalledOnce();
+    expect(onReadyB).toHaveBeenCalledOnce();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(String(warn.mock.calls[0]?.[0])).toContain("`onReady` is deprecated");
+
+    a.destroy();
+    b.destroy();
+    warn.mockRestore();
+  });
+});
+
 describe("install script onReady and persona:ready event", () => {
   beforeEach(() => {
     document.body.innerHTML = "";

package/src/runtime/init.ts

@@ -3,6 +3,9 @@ import { AgentWidgetConfig as _AgentWidgetConfig, AgentWidgetInitOptions, AgentW
 import { isComposerBarMountMode, isDockedMountMode } from "../utils/dock";
 import { createWidgetHostLayout } from "./host-layout";
 
+// Warn at most once per page when the deprecated `onReady` alias is used.
+let warnedOnReadyDeprecated = false;
+
 const ensureTarget = (target: string | HTMLElement): HTMLElement => {
   if (typeof window === "undefined" || typeof document === "undefined") {
     throw new Error("Chat widget can only be mounted in a browser environment");
@@ -157,7 +160,20 @@ export const initAgentWidget = (
   };
 
   mountController();
-  options.onReady?.();
+  // Fired when the controller is mounted and its API is callable. `onReady` is
+  // the deprecated alias of `onChatReady` (removed next major) — warn once.
+  if (options.onChatReady) {
+    options.onChatReady();
+  } else if (options.onReady) {
+    if (!warnedOnReadyDeprecated) {
+      warnedOnReadyDeprecated = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[Persona] `onReady` is deprecated — use `onChatReady`. `onReady` still works but is removed in the next major."
+      );
+    }
+    options.onReady();
+  }
 
   const rebuildLayout = (nextConfig?: _AgentWidgetConfig) => {
     destroyCurrentController();