@runtypelabs/persona 4.6.1 → 4.8.0

package/src/runtime/host-layout.test.ts

@@ -527,4 +527,167 @@ describe("createWidgetHostLayout docked", () => {
       layout.destroy();
     });
   });
+
+  describe("detached docked", () => {
+    it("leaves the dock slot flush when detachedPanel is unset", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          dock: { width: "320px" },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.padding).toBe("");
+      expect(dockSlot?.style.background).toBe("");
+
+      layout.destroy();
+    });
+
+    it("pads the dock slot with the default inset and canvas when detached", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "320px" },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.padding).toBe("16px");
+      expect(dockSlot?.style.background).toBe("transparent");
+      expect(dockSlot?.style.boxSizing).toBe("border-box");
+
+      layout.destroy();
+    });
+
+    it("resolves detached inset and canvas from panel theme tokens", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "320px" },
+        },
+        theme: {
+          components: { panel: { inset: "24px", canvasBackground: "#eee" } },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.padding).toBe("24px");
+      expect(dockSlot?.style.background).toBe("rgb(238, 238, 238)");
+
+      layout.destroy();
+    });
+
+    it("shrinks the emerge host by the inset so it fits the padded slot", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "320px", reveal: "emerge" },
+        },
+      });
+
+      const host = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="host"]');
+      // jsdom simplifies the calc expression (320px - 2 * 16px).
+      expect(host?.style.width).toBe("calc(288px)");
+
+      layout.destroy();
+    });
+
+    it("resolves a percentage emerge width to px before subtracting the inset", () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+
+      const layout = createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "50%", reveal: "emerge" },
+        },
+      });
+      const shell = layout.shell!;
+      Object.defineProperty(shell, "clientWidth", { get: () => 800, configurable: true });
+      layout.updateConfig({
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          detachedPanel: true,
+          dock: { width: "50%", reveal: "emerge" },
+        },
+      });
+
+      const host = shell.querySelector<HTMLElement>('[data-persona-dock-role="host"]');
+      // 50% of 800px resolved to px, then jsdom simplifies (400px - 2 * 16px).
+      expect(host?.style.width).toBe("calc(368px)");
+
+      layout.destroy();
+    });
+
+    it("clears detached chrome and pads nothing while the panel is collapsed", () => {
+      for (const reveal of ["resize", "emerge"] as const) {
+        const parent = document.createElement("div");
+        document.body.appendChild(parent);
+        const target = document.createElement("div");
+        parent.appendChild(target);
+
+        const layout = createWidgetHostLayout(target, {
+          launcher: {
+            mountMode: "docked",
+            autoExpand: false,
+            detachedPanel: true,
+            dock: { width: "320px", reveal },
+          },
+        });
+
+        const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+        // Collapsed: truly 0-width slot with no padding/background/box-sizing residue.
+        expect(dockSlot?.style.width, reveal).toBe("0px");
+        expect(dockSlot?.style.padding, reveal).toBe("");
+        expect(dockSlot?.style.background, reveal).toBe("");
+        expect(dockSlot?.style.boxSizing, reveal).toBe("");
+        // Padding rides the width transition so the canvas gutter shrinks with the column.
+        expect(dockSlot?.style.transition, reveal).toContain("padding");
+
+        // Opening restores the chrome; closing clears it again.
+        layout.syncWidgetState({ open: true, launcherEnabled: true });
+        expect(dockSlot?.style.padding, reveal).toBe("16px");
+        expect(dockSlot?.style.boxSizing, reveal).toBe("border-box");
+        layout.syncWidgetState({ open: false, launcherEnabled: true });
+        expect(dockSlot?.style.padding, reveal).toBe("");
+        expect(dockSlot?.style.boxSizing, reveal).toBe("");
+
+        layout.destroy();
+        document.body.innerHTML = "";
+      }
+    });
+  });
 });

package/src/runtime/host-layout.ts

@@ -5,6 +5,12 @@ import type {
 } from "../types";
 import { isDockedMountMode, resolveDockConfig } from "../utils/dock";
 import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
+import { createThemeObserver, getActiveTheme } from "../utils/theme";
+import {
+  DEFAULT_PANEL_CANVAS_BACKGROUND,
+  DEFAULT_PANEL_INSET,
+  resolveTokenValue,
+} from "../utils/tokens";
 
 export type WidgetHostLayoutMode = "direct" | "docked";
 
@@ -208,6 +214,51 @@ const orderDockChildren = (
   }
 };
 
+/**
+ * Detached inset + canvas literals for the dockSlot. The panel CSS vars are set
+ * inline on the widget root inside the slot, so they cannot cascade up to the
+ * slot; resolve the token values here and apply literals.
+ */
+const resolveDetachedSlotStyles = (
+  config: AgentWidgetConfig | undefined
+): { inset: string; canvasBackground: string } => {
+  const theme = getActiveTheme(config);
+  const panel = theme.components?.panel;
+  const resolve = (raw: string | undefined, fallback: string): string => {
+    if (raw == null || raw === "") return fallback;
+    return resolveTokenValue(theme, raw) ?? raw;
+  };
+  return {
+    inset: resolve(panel?.inset, DEFAULT_PANEL_INSET),
+    canvasBackground: resolve(panel?.canvasBackground, DEFAULT_PANEL_CANVAS_BACKGROUND),
+  };
+};
+
+type DetachedSlotStyles = { inset: string; canvasBackground: string };
+
+/**
+ * Detached docked mode pads the slot so the canvas shows around the panel card.
+ * Padding, never margin, keeps parseDockWidthToPx push math truthful; box-sizing
+ * border-box keeps the slot outer width (and max-height) inclusive of the
+ * padding so the panel shrinks inside rather than overflowing.
+ */
+const applyDetachedDockSlotChrome = (
+  dockSlot: HTMLElement,
+  detached: boolean,
+  inset: string,
+  canvasBackground: string
+): void => {
+  if (!detached) {
+    dockSlot.style.padding = "";
+    dockSlot.style.background = "";
+    dockSlot.style.boxSizing = "";
+    return;
+  }
+  dockSlot.style.boxSizing = "border-box";
+  dockSlot.style.padding = inset;
+  dockSlot.style.background = canvasBackground;
+};
+
 const applyDockStyles = (
   shell: HTMLElement,
   pushTrack: HTMLElement,
@@ -215,10 +266,16 @@ const applyDockStyles = (
   dockSlot: HTMLElement,
   host: HTMLElement,
   config: AgentWidgetConfig | undefined,
-  expanded: boolean
+  expanded: boolean,
+  // Cached slot styles; null when not detached. Resolved once per config/scheme
+  // change so getActiveTheme never runs on the resize/ResizeObserver path.
+  detachedSlotStyles: DetachedSlotStyles | null
 ): void => {
   const dock = resolveDockConfig(config);
   const usePush = dock.reveal === "push";
+  const detached = detachedSlotStyles != null;
+  const detachedInset = detachedSlotStyles?.inset ?? "";
+  const detachedCanvas = detachedSlotStyles?.canvasBackground ?? "";
 
   migrateDockChildren(shell, pushTrack, contentSlot, dockSlot, usePush);
   orderDockChildren(shell, pushTrack, contentSlot, dockSlot, dock.side, usePush);
@@ -260,6 +317,8 @@ const applyDockStyles = (
     clearMobileFullscreenDockSlotStyles(dockSlot);
     resetContentSlotFlexSizing(contentSlot);
     clearEmergeDockStyles(host, dockSlot);
+    // Mobile fullscreen is flush regardless of detachedPanel.
+    applyDetachedDockSlotChrome(dockSlot, false, "", "");
 
     shell.style.display = "flex";
     shell.style.flexDirection = "column";
@@ -314,6 +373,9 @@ const applyDockStyles = (
   shell.removeAttribute("data-persona-dock-mobile-fullscreen");
   clearMobileFullscreenDockSlotStyles(dockSlot);
   applyDockSlotMaxHeight(dockSlot, dock.maxHeight);
+  // Chrome only when open: a collapsed detached slot with padding + border-box
+  // floors at 2*inset, painting a permanent canvas strip past the 0px width.
+  applyDetachedDockSlotChrome(dockSlot, detached && expanded, detachedInset, detachedCanvas);
 
   if (dock.reveal === "overlay") {
     shell.style.display = "flex";
@@ -435,8 +497,10 @@ const applyDockStyles = (
     }
 
     const width = expanded ? dock.width : "0px";
+    // Detached collapse snaps padding off as width animates to 0; animate padding
+    // alongside so the canvas gutter shrinks with the column.
     const dockTransition = dock.animate
-      ? "width 180ms ease, min-width 180ms ease, max-width 180ms ease, flex-basis 180ms ease"
+      ? `width 180ms ease, min-width 180ms ease, max-width 180ms ease, flex-basis 180ms ease${detached ? ", padding 180ms ease" : ""}`
       : "none";
     const collapsedClosed = !expanded;
 
@@ -454,9 +518,17 @@ const applyDockStyles = (
 
     if (isEmerge) {
       dockSlot.style.alignItems = dock.side === "right" ? "flex-start" : "flex-end";
-      host.style.width = dock.width;
-      host.style.minWidth = dock.width;
-      host.style.maxWidth = dock.width;
+      // Emerge pins the host to a fixed width and reveals it as the slot grows.
+      // When detached, shrink that fixed width by the padding so the host fits
+      // the padded slot content-box instead of overflowing one side. Resolve a
+      // percentage dock.width to px first: a raw % re-resolves against the
+      // padding-reduced content box and un-pins as the slot animates open.
+      const emergeHostWidth = detached
+        ? `calc(${parseDockWidthToPx(dock.width, shell.clientWidth)}px - (2 * ${detachedInset}))`
+        : dock.width;
+      host.style.width = emergeHostWidth;
+      host.style.minWidth = emergeHostWidth;
+      host.style.maxWidth = emergeHostWidth;
       host.style.boxSizing = "border-box";
     }
   }
@@ -518,12 +590,38 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
     resizeObserver = null;
   };
 
+  // Resolved once per config/scheme change; the resize paths reuse this so
+  // getActiveTheme never runs per frame.
+  let detachedSlotStyles: DetachedSlotStyles | null = null;
+  const refreshDetachedSlotStyles = (): void => {
+    detachedSlotStyles =
+      config?.launcher?.detachedPanel === true ? resolveDetachedSlotStyles(config) : null;
+  };
+  refreshDetachedSlotStyles();
+
+  const reapplyDockStyles = (): void => {
+    applyDockStyles(shell, pushTrack, contentSlot, dockSlot, host, config, expanded, detachedSlotStyles);
+  };
+
+  // Scheme-dependent canvas tokens are baked to literals at layout time, so an
+  // OS dark-mode flip leaves a stale canvas until we recompute and re-apply.
+  let cleanupSchemeObserver: (() => void) | null = null;
+  const syncSchemeObserver = (): void => {
+    cleanupSchemeObserver?.();
+    cleanupSchemeObserver = null;
+    if (config?.launcher?.detachedPanel !== true || config?.colorScheme !== "auto") return;
+    cleanupSchemeObserver = createThemeObserver(() => {
+      refreshDetachedSlotStyles();
+      reapplyDockStyles();
+    });
+  };
+
   const syncPushResizeObserver = (): void => {
     disconnectResizeObserver();
     if (resolveDockConfig(config).reveal !== "push") return;
     if (typeof ResizeObserver === "undefined") return;
     resizeObserver = new ResizeObserver(() => {
-      applyDockStyles(shell, pushTrack, contentSlot, dockSlot, host, config, expanded);
+      reapplyDockStyles();
     });
     resizeObserver.observe(shell);
   };
@@ -531,7 +629,7 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
   let heightChainChecked = false;
 
   const layout = (): void => {
-    applyDockStyles(shell, pushTrack, contentSlot, dockSlot, host, config, expanded);
+    reapplyDockStyles();
     syncPushResizeObserver();
     // Check the height chain once, the first time the panel is actually shown
     // in a layout that depends on it (mobile fullscreen is fixed-position and
@@ -562,6 +660,7 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
   }
 
   layout();
+  syncSchemeObserver();
 
   return {
     mode: "docked",
@@ -578,10 +677,14 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
       if ((config?.launcher?.enabled ?? true) === false) {
         expanded = true;
       }
+      refreshDetachedSlotStyles();
       layout();
+      syncSchemeObserver();
     },
     destroy() {
       ownerWindow?.removeEventListener("resize", onViewportResize);
+      cleanupSchemeObserver?.();
+      cleanupSchemeObserver = null;
       disconnectResizeObserver();
       if (originalParent.isConnected) {
         if (originalNextSibling && originalNextSibling.parentNode === originalParent) {

package/src/runtime/init.ts

@@ -19,71 +19,28 @@ const ensureTarget = (target: string | HTMLElement): HTMLElement => {
   return target;
 };
 
-const widgetCssHref = (): string | null => {
-  try {
-    // This works in ESM builds but not in IIFE builds
-    if (typeof import.meta !== "undefined" && import.meta.url) {
-      return new URL("../widget.css", import.meta.url).href;
-    }
-  } catch {
-    // Fallback for IIFE builds where CSS should be loaded separately
-  }
-  return null;
-};
-
+// CSS arrives via the installer's link[data-persona] or a consumer import of
+// @runtypelabs/persona/widget.css; the widget never self-locates its stylesheet.
+// A new URL(..., import.meta.url) here breaks consumer bundlers (webpack
+// resolves the literal at build time), so shadow roots only clone the head link.
 const mountStyles = (root: ShadowRoot | HTMLElement, ownerDocument: Document) => {
-  const href = widgetCssHref();
-
-  const adoptExistingStylesheet = () => {
-    if (!(root instanceof ShadowRoot)) {
-      return;
-    }
-
-    if (root.querySelector('link[data-persona]')) {
-      return;
-    }
-
-    const globalLink = ownerDocument.head.querySelector<HTMLLinkElement>(
-      'link[data-persona]'
-    );
-    if (!globalLink) {
-      return;
-    }
+  if (!(root instanceof ShadowRoot)) {
+    return;
+  }
 
-    const clonedLink = globalLink.cloneNode(true) as HTMLLinkElement;
-    root.insertBefore(clonedLink, root.firstChild);
-  };
+  if (root.querySelector('link[data-persona]')) {
+    return;
+  }
 
-  if (root instanceof ShadowRoot) {
-    // For shadow DOM, we need to load CSS into the shadow root
-    if (href) {
-      const link = ownerDocument.createElement("link");
-      link.rel = "stylesheet";
-      link.href = href;
-      link.setAttribute("data-persona", "true");
-      root.insertBefore(link, root.firstChild);
-    } else {
-      adoptExistingStylesheet();
-    }
-    // If href is null (IIFE build), CSS should already be loaded globally
-  } else {
-    // For non-shadow DOM, check if CSS is already loaded
-    const existing = ownerDocument.head.querySelector<HTMLLinkElement>(
-      "link[data-persona]"
-    );
-    if (!existing) {
-      if (href) {
-        // ESM build - load CSS dynamically
-        const link = ownerDocument.createElement("link");
-        link.rel = "stylesheet";
-        link.href = href;
-        link.setAttribute("data-persona", "true");
-        ownerDocument.head.appendChild(link);
-      }
-      // IIFE build - CSS should be loaded via <link> tag before script
-      // If not found, we'll assume it's loaded globally or warn in dev
-    }
+  const globalLink = ownerDocument.head.querySelector<HTMLLinkElement>(
+    'link[data-persona]'
+  );
+  if (!globalLink) {
+    return;
   }
+
+  const clonedLink = globalLink.cloneNode(true) as HTMLLinkElement;
+  root.insertBefore(clonedLink, root.firstChild);
 };
 
 export type AgentWidgetInitHandle = AgentWidgetController & { host: HTMLElement };

package/src/runtime/persist-state.test.ts

@@ -16,6 +16,23 @@ const baseConfig = () => ({
 const inject = (controller: ReturnType<typeof createAgentExperience>) =>
   controller.injectAssistantMessage({ content: "hello world" });
 
+const deferred = () => {
+  let resolve!: () => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+};
+
+const flushMicrotasks = async (times = 4) => {
+  for (let index = 0; index < times; index += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    await Promise.resolve();
+  }
+};
+
 describe("persistState gates storage adapter", () => {
   afterEach(() => {
     document.body.innerHTML = "";
@@ -149,4 +166,105 @@ describe("persistState gates storage adapter", () => {
     expect(controller.getMessages()).toEqual([]);
     controller.destroy();
   });
+
+  it("serializes async saves and preserves the newest transcript", async () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const firstSave = deferred();
+    const payloads: Array<{ messages?: Array<{ content?: string }> }> = [];
+    const save = vi.fn((state: { messages?: Array<{ content?: string }> }) => {
+      payloads.push(state);
+      return save.mock.calls.length === 1 ? firstSave.promise : Promise.resolve();
+    });
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save },
+    });
+
+    controller.injectAssistantMessage({ content: "first" });
+    controller.injectAssistantMessage({ content: "second" });
+
+    expect(save).toHaveBeenCalledTimes(1);
+    firstSave.resolve();
+    await flushMicrotasks();
+
+    expect(save).toHaveBeenCalledTimes(2);
+    expect(payloads[1].messages?.map((message) => message.content)).toEqual([
+      "first",
+      "second",
+    ]);
+    controller.destroy();
+  });
+
+  it("orders clear after pending saves so stale state cannot be resurrected", async () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const firstSave = deferred();
+    const operations: string[] = [];
+    const save = vi.fn(() => {
+      operations.push("save");
+      return save.mock.calls.length === 1 ? firstSave.promise : Promise.resolve();
+    });
+    const clear = vi.fn(() => {
+      operations.push("clear");
+      return Promise.resolve();
+    });
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save, clear },
+    });
+
+    inject(controller);
+    controller.clearChat();
+
+    expect(operations).toEqual(["save"]);
+    firstSave.resolve();
+    await flushMicrotasks(20);
+
+    expect(operations).toEqual(["save", "save", "clear"]);
+    expect(clear).toHaveBeenCalledTimes(1);
+    controller.destroy();
+  });
+
+  it("continues queued storage mutations after an async save rejects", async () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const firstSave = deferred();
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const save = vi.fn(() =>
+      save.mock.calls.length === 1 ? firstSave.promise : Promise.resolve()
+    );
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save },
+    });
+
+    controller.injectAssistantMessage({ content: "first" });
+    controller.injectAssistantMessage({ content: "second" });
+    firstSave.reject(new Error("storage unavailable"));
+    await flushMicrotasks(8);
+
+    expect(save).toHaveBeenCalledTimes(2);
+    expect(errorSpy).toHaveBeenCalledWith(
+      "[AgentWidget] Failed to persist state:",
+      expect.any(Error)
+    );
+    errorSpy.mockRestore();
+    controller.destroy();
+  });
+
+  it("keeps synchronous adapters synchronous", () => {
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const save = vi.fn();
+    const controller = createAgentExperience(mount, {
+      ...baseConfig(),
+      storageAdapter: { save },
+    });
+
+    inject(controller);
+
+    expect(save).toHaveBeenCalledTimes(1);
+    controller.destroy();
+  });
 });