@runtypelabs/persona 3.31.0 → 3.33.0

package/src/index-global.ts

@@ -31,3 +31,42 @@ export {
   listRegisteredStreamAnimations,
 } from "./utils/stream-animation";
 export type { StreamAnimationPlugin, StreamAnimationContext } from "./types";
+
+// ---------------------------------------------------------------------------
+// Deferred WebMCP polyfill loading.
+//
+// This bundle is built with `@mcp-b/webmcp-polyfill` external — the bridge's
+// default `import("@mcp-b/webmcp-polyfill")` is a bare specifier no browser
+// can resolve, so register a loader that imports the self-contained
+// `webmcp-polyfill.js` chunk from a sibling URL instead. Mirrors how
+// `install.ts` derives `launcher.global.js` from a `jsUrl` override.
+// ---------------------------------------------------------------------------
+
+import { setWebMcpPolyfillLoader } from "./webmcp-bridge";
+
+// Capture at module-evaluation time — `document.currentScript` is null once
+// execution leaves the script's initial synchronous run.
+const widgetScriptSrc: string | null =
+  typeof document !== "undefined"
+    ? ((document.currentScript as HTMLScriptElement | null)?.src ?? null)
+    : null;
+
+setWebMcpPolyfillLoader(() => {
+  const chunkUrl = widgetScriptSrc?.replace(
+    /index\.global\.js($|\?)/,
+    "webmcp-polyfill.js$1",
+  );
+  if (!chunkUrl || chunkUrl === widgetScriptSrc) {
+    return Promise.reject(
+      new Error(
+        "Could not derive the webmcp-polyfill.js URL from the widget script URL " +
+          `(${widgetScriptSrc ?? "unavailable"}). Self-hosted deployments that ` +
+          "rename index.global.js should install @mcp-b/webmcp-polyfill on the " +
+          "page themselves before enabling config.webmcp.",
+      ),
+    );
+  }
+  // Runtime-only dynamic import; the specifier is a computed URL, so esbuild
+  // leaves it untouched (and must not try to bundle it).
+  return import(/* @vite-ignore */ chunkUrl);
+});

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

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { createWidgetHostLayout } from "./host-layout";
 
@@ -194,6 +194,161 @@ describe("createWidgetHostLayout docked", () => {
     layout.destroy();
   });
 
+  it("clamps the dock slot to the viewport guard and pins resize/emerge sticky", () => {
+    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,
+          dock: { width: "320px", reveal },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.maxHeight, reveal).not.toBe("");
+      expect(dockSlot?.style.position, reveal).toBe("sticky");
+      expect(dockSlot?.style.top, reveal).toBe("0px");
+
+      layout.destroy();
+      document.body.innerHTML = "";
+    }
+  });
+
+  it("clamps push and overlay dock slots without sticky (transform/absolute contexts)", () => {
+    // push: the slot lives inside the translated track, where a transformed
+    // ancestor defeats sticky — cap only. overlay: keeps absolute positioning.
+    const cases = [
+      { reveal: "push" as const, position: "relative" },
+      { reveal: "overlay" as const, position: "absolute" },
+    ];
+    for (const { reveal, position } of cases) {
+      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,
+          dock: { width: "320px", reveal },
+        },
+      });
+
+      const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+      expect(dockSlot?.style.maxHeight, reveal).not.toBe("");
+      expect(dockSlot?.style.position, reveal).toBe(position);
+
+      layout.destroy();
+      document.body.innerHTML = "";
+    }
+  });
+
+  it("honors a custom dock.maxHeight and the false opt-out", () => {
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const target = document.createElement("div");
+    parent.appendChild(target);
+
+    const dockConfig = {
+      mountMode: "docked" as const,
+      autoExpand: false,
+      dock: { width: "320px", maxHeight: "600px" },
+    };
+    const layout = createWidgetHostLayout(target, { launcher: dockConfig });
+
+    const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+    expect(dockSlot?.style.maxHeight).toBe("600px");
+
+    layout.updateConfig({
+      launcher: { ...dockConfig, dock: { width: "320px", maxHeight: false } },
+    });
+    expect(dockSlot?.style.maxHeight).toBe("");
+    expect(dockSlot?.style.position).toBe("relative");
+    expect(dockSlot?.style.top).toBe("");
+
+    layout.destroy();
+  });
+
+  describe("height-chain warning", () => {
+    const withOffsetHeight = (impl: (el: HTMLElement) => number, fn: () => void): void => {
+      const original = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "offsetHeight");
+      Object.defineProperty(HTMLElement.prototype, "offsetHeight", {
+        configurable: true,
+        get(this: HTMLElement) {
+          return impl(this);
+        },
+      });
+      try {
+        fn();
+      } finally {
+        if (original) {
+          Object.defineProperty(HTMLElement.prototype, "offsetHeight", original);
+        }
+      }
+    };
+
+    const mountDocked = () => {
+      const parent = document.createElement("div");
+      document.body.appendChild(parent);
+      const target = document.createElement("div");
+      parent.appendChild(target);
+      return createWidgetHostLayout(target, {
+        launcher: {
+          mountMode: "docked",
+          autoExpand: true,
+          dock: { width: "320px" },
+        },
+      });
+    };
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
+    it("warns once when a percentage height does not resolve against the shell's parent", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      // Fixed-height probe measures (environment works); 100% probe collapses
+      // to 0 (no ancestor provides a definite height).
+      withOffsetHeight((el) => (el.style.height === "1px" ? 1 : 0), () => {
+        const layout = mountDocked();
+        layout.syncWidgetState({ open: false, launcherEnabled: true });
+        layout.syncWidgetState({ open: true, launcherEnabled: true });
+        layout.destroy();
+      });
+      const heightWarnings = warn.mock.calls.filter((c) =>
+        String(c[0]).includes("definite height")
+      );
+      expect(heightWarnings).toHaveLength(1);
+      expect(String(heightWarnings[0][0])).toContain("100dvh");
+    });
+
+    it("does not warn when the height chain resolves", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      withOffsetHeight(() => 1, () => {
+        const layout = mountDocked();
+        layout.destroy();
+      });
+      expect(
+        warn.mock.calls.filter((c) => String(c[0]).includes("definite height"))
+      ).toHaveLength(0);
+    });
+
+    it("does not warn when the environment cannot measure layout (jsdom default)", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const layout = mountDocked();
+      layout.destroy();
+      expect(
+        warn.mock.calls.filter((c) => String(c[0]).includes("definite height"))
+      ).toHaveLength(0);
+    });
+  });
+
   const withInnerWidth = (width: number, fn: () => void): void => {
     const prev = window.innerWidth;
     try {
@@ -277,7 +432,7 @@ describe("createWidgetHostLayout docked", () => {
 
       const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
       layout.syncWidgetState({ open: true, launcherEnabled: true });
-      expect(dockSlot?.style.position).toBe("relative");
+      expect(dockSlot?.style.position).toBe("sticky");
       expect(layout.shell?.dataset.personaDockMobileFullscreen).toBeUndefined();
 
       layout.destroy();
@@ -325,7 +480,7 @@ describe("createWidgetHostLayout docked", () => {
 
       const dockSlot = layout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
       layout.syncWidgetState({ open: false, launcherEnabled: true });
-      expect(dockSlot?.style.position).toBe("relative");
+      expect(dockSlot?.style.position).toBe("sticky");
 
       layout.destroy();
     });

package/src/runtime/host-layout.ts

@@ -1,5 +1,6 @@
 import type {
   AgentWidgetConfig,
+  AgentWidgetDockConfig,
   AgentWidgetStateSnapshot,
 } from "../types";
 import { isDockedMountMode, resolveDockConfig } from "../utils/dock";
@@ -26,6 +27,83 @@ const parseDockWidthToPx = (width: string, shellClientWidth: number): number =>
   return 420;
 };
 
+/**
+ * Viewport-overflow guard. The docked shell sizes itself with `height: 100%`,
+ * which only resolves when an ancestor provides a definite height; without one
+ * the dock column would grow with the conversation and scroll off the page.
+ * Clamping the slot keeps the panel viewport-sized (messages scroll
+ * internally) even when the page's height chain is missing. `100vh` is set
+ * first as a fallback for engines without `dvh` support — an invalid value
+ * leaves the previous one in place.
+ */
+const applyDockSlotMaxHeight = (
+  dockSlot: HTMLElement,
+  maxHeight: string | false
+): void => {
+  if (maxHeight === false) {
+    dockSlot.style.maxHeight = "";
+    return;
+  }
+  dockSlot.style.maxHeight = "100vh";
+  dockSlot.style.maxHeight = maxHeight;
+};
+
+/**
+ * Sticky keeps the resize/emerge dock column pinned to the top of the viewport
+ * when the surrounding page is taller than the screen (e.g. a missing height
+ * chain or a deliberately scrolling page). With a properly sized shell it
+ * behaves exactly like the previous `position: relative`. Not used for push:
+ * there the slot lives inside the translated push track, and that transformed
+ * ancestor defeats sticky (verified in Chromium) — push gets the max-height
+ * cap only, like overlay.
+ */
+const applyInFlowDockSlotPosition = (
+  dockSlot: HTMLElement,
+  maxHeight: string | false
+): void => {
+  if (maxHeight === false) {
+    dockSlot.style.position = "relative";
+    dockSlot.style.top = "";
+  } else {
+    dockSlot.style.position = "sticky";
+    dockSlot.style.top = "0";
+  }
+};
+
+/**
+ * Warns once per docked mount when no ancestor of the dock target provides a
+ * definite height, which is the common misconfiguration behind a dock panel
+ * that grows past the viewport. Probes with a throwaway `height: 100%` child
+ * of the shell's parent; a fixed-height reference probe first checks the
+ * environment can measure at all (display: none subtrees and jsdom measure
+ * everything as 0, and must not produce a false warning).
+ */
+const warnIfDockHeightChainUnresolved = (
+  shell: HTMLElement,
+  dock: Required<AgentWidgetDockConfig>
+): void => {
+  const parent = shell.parentElement;
+  if (!parent) return;
+  const probe = shell.ownerDocument.createElement("div");
+  probe.style.cssText =
+    "width:0;height:1px;margin:0;padding:0;border:0;visibility:hidden;";
+  parent.appendChild(probe);
+  const measurable = probe.offsetHeight > 0;
+  probe.style.height = "100%";
+  const resolved = probe.offsetHeight > 0;
+  probe.remove();
+  if (!measurable || resolved) return;
+  console.warn(
+    "[AgentWidget] Docked mode: no ancestor of the dock target provides a definite height, " +
+      "so the dock panel cannot size to your layout." +
+      (dock.maxHeight === false
+        ? " The viewport guard is disabled (dock.maxHeight: false), so the panel will grow with the conversation and overflow the viewport."
+        : ` Falling back to clamping the panel to ${dock.maxHeight} (configurable via launcher.dock.maxHeight).`) +
+      " To size the panel from your layout instead, give the height chain a definite height " +
+      "(e.g. `html, body { height: 100% }`) down to the dock target's parent."
+  );
+};
+
 const setDirectHostStyles = (host: HTMLElement, config?: AgentWidgetConfig): void => {
   const launcherEnabled = config?.launcher?.enabled ?? true;
   host.className = "persona-host";
@@ -53,6 +131,7 @@ const clearMobileFullscreenDockSlotStyles = (dockSlot: HTMLElement): void => {
   dockSlot.style.width = "";
   dockSlot.style.height = "";
   dockSlot.style.maxWidth = "";
+  dockSlot.style.maxHeight = "";
   dockSlot.style.minWidth = "";
   clearOverlayDockSlotStyles(dockSlot);
 };
@@ -227,6 +306,7 @@ const applyDockStyles = (
 
   shell.removeAttribute("data-persona-dock-mobile-fullscreen");
   clearMobileFullscreenDockSlotStyles(dockSlot);
+  applyDockSlotMaxHeight(dockSlot, dock.maxHeight);
 
   if (dock.reveal === "overlay") {
     shell.style.display = "flex";
@@ -315,6 +395,7 @@ const applyDockStyles = (
     dockSlot.style.minWidth = dock.width;
     dockSlot.style.maxWidth = dock.width;
     dockSlot.style.position = "relative";
+    dockSlot.style.top = "";
     dockSlot.style.overflow = "hidden";
     dockSlot.style.transition = "none";
     dockSlot.style.pointerEvents = expanded ? "auto" : "none";
@@ -348,7 +429,7 @@ const applyDockStyles = (
     dockSlot.style.maxWidth = width;
     dockSlot.style.minWidth = width;
     dockSlot.style.minHeight = "0";
-    dockSlot.style.position = "relative";
+    applyInFlowDockSlotPosition(dockSlot, dock.maxHeight);
     dockSlot.style.overflow =
       isEmerge ? "hidden" : collapsedClosed ? "hidden" : "visible";
     dockSlot.style.transition = dockTransition;
@@ -429,9 +510,22 @@ const createDockedLayout = (target: HTMLElement, config?: AgentWidgetConfig): Wi
     resizeObserver.observe(shell);
   };
 
+  let heightChainChecked = false;
+
   const layout = (): void => {
     applyDockStyles(shell, pushTrack, contentSlot, dockSlot, host, config, expanded);
     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
+    // doesn't — keep checking until a dependent layout comes around).
+    if (
+      expanded &&
+      !heightChainChecked &&
+      shell.dataset.personaDockMobileFullscreen !== "true"
+    ) {
+      heightChainChecked = true;
+      warnIfDockHeightChainUnresolved(shell, resolveDockConfig(config));
+    }
   };
 
   const ownerWindow = shell.ownerDocument.defaultView;