@runtypelabs/persona 3.31.1 → 3.34.0

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";
 
@@ -108,7 +108,7 @@ describe("createWidgetHostLayout docked", () => {
     layout.destroy();
   });
 
-  it("push reveal translates a track; main column width stays fixed in px", () => {
+  it("push reveal offsets a track with margin (no transform); main column width stays fixed in px", () => {
     const parent = document.createElement("div");
     parent.style.width = "800px";
     document.body.appendChild(parent);
@@ -132,15 +132,20 @@ describe("createWidgetHostLayout docked", () => {
     expect(shell.dataset.personaDockReveal).toBe("push");
     expect(contentSlot?.style.width).toBe("800px");
     expect(pushTrack?.style.width).toBe("1120px");
-    expect(pushTrack?.style.transform).toBe("translateX(0)");
+    expect(pushTrack?.style.marginLeft).toBe("0px");
+    // The track must NOT carry a transform: a transformed ancestor becomes the
+    // containing block for `position: fixed` host chrome and pushes it
+    // off-screen (regression guard, see host-layout.ts push branch).
+    expect(pushTrack?.style.transform).toBe("");
 
     layout.syncWidgetState({ open: true, launcherEnabled: true });
-    expect(pushTrack?.style.transform).toBe("translateX(-320px)");
+    expect(pushTrack?.style.marginLeft).toBe("-320px");
+    expect(pushTrack?.style.transform).toBe("");
 
     layout.destroy();
   });
 
-  it("push reveal on the left uses negative translate when closed", () => {
+  it("push reveal on the left uses negative margin when closed", () => {
     const parent = document.createElement("div");
     parent.style.width = "600px";
     document.body.appendChild(parent);
@@ -159,10 +164,12 @@ describe("createWidgetHostLayout docked", () => {
     layout.updateConfig({ launcher: dockConfig });
 
     const pushTrack = shell.querySelector<HTMLElement>('[data-persona-dock-role="push-track"]');
-    expect(pushTrack?.style.transform).toBe("translateX(-200px)");
+    expect(pushTrack?.style.marginLeft).toBe("-200px");
+    expect(pushTrack?.style.transform).toBe("");
 
     layout.syncWidgetState({ open: true, launcherEnabled: true });
-    expect(pushTrack?.style.transform).toBe("translateX(0)");
+    expect(pushTrack?.style.marginLeft).toBe("0px");
+    expect(pushTrack?.style.transform).toBe("");
 
     layout.destroy();
   });
@@ -194,6 +201,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 (in-flow/absolute contexts)", () => {
+    // push: the slot is an in-flow `position: relative` column — max-height cap
+    // only, no sticky. 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 {
@@ -235,6 +397,41 @@ describe("createWidgetHostLayout docked", () => {
     });
   });
 
+  it("resets the push track margin when a desktop push offset enters mobile fullscreen", () => {
+    const parent = document.createElement("div");
+    parent.style.width = "800px";
+    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: "push" },
+      },
+    });
+    const pushTrack = layout.shell?.querySelector<HTMLElement>(
+      '[data-persona-dock-role="push-track"]',
+    );
+
+    // Desktop, expanded: track carries a negative margin offset.
+    withInnerWidth(800, () => {
+      layout.syncWidgetState({ open: true, launcherEnabled: true });
+    });
+    expect(pushTrack?.style.marginLeft).toBe("-320px");
+
+    // Same layout falls into mobile fullscreen (viewport resize): the stale
+    // margin must be cleared or the width:100% track renders 320px off-screen.
+    withInnerWidth(500, () => {
+      window.dispatchEvent(new Event("resize"));
+    });
+    expect(layout.shell?.dataset.personaDockMobileFullscreen).toBe("true");
+    expect(pushTrack?.style.marginLeft).toBe("0px");
+
+    layout.destroy();
+  });
+
   it("does not use fixed fullscreen above mobile breakpoint", () => {
     withInnerWidth(800, () => {
       const parent = document.createElement("div");
@@ -277,7 +474,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 +522,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,84 @@ 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:
+ * push gets the max-height cap only, like overlay, since the dock slot is an
+ * in-flow `position: relative` column there rather than a viewport-pinned one.
+ * (The push track itself is offset with `margin-left`, not a transform, so it
+ * no longer establishes a containing block for fixed/sticky descendants.)
+ */
+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 +132,7 @@ const clearMobileFullscreenDockSlotStyles = (dockSlot: HTMLElement): void => {
   dockSlot.style.width = "";
   dockSlot.style.height = "";
   dockSlot.style.maxWidth = "";
+  dockSlot.style.maxHeight = "";
   dockSlot.style.minWidth = "";
   clearOverlayDockSlotStyles(dockSlot);
 };
@@ -72,6 +152,7 @@ const clearPushTrackStyles = (pushTrack: HTMLElement): void => {
   pushTrack.style.alignItems = "";
   pushTrack.style.transition = "";
   pushTrack.style.transform = "";
+  pushTrack.style.marginLeft = "";
 };
 
 const resetContentSlotFlexSizing = (contentSlot: HTMLElement): void => {
@@ -215,6 +296,11 @@ const applyDockStyles = (
       pushTrack.style.flex = "1 1 auto";
       pushTrack.style.alignItems = "stretch";
       pushTrack.style.transform = "none";
+      // Reset the desktop push offset: this fullscreen path applies styles
+      // inline without going through clearPushTrackStyles, so a stale negative
+      // marginLeft from a prior expanded desktop render would shift the now
+      // width:100% track off-screen on mobile.
+      pushTrack.style.marginLeft = "0";
       pushTrack.style.transition = "none";
       contentSlot.style.flex = "1 1 auto";
       contentSlot.style.width = "100%";
@@ -227,6 +313,7 @@ const applyDockStyles = (
 
   shell.removeAttribute("data-persona-dock-mobile-fullscreen");
   clearMobileFullscreenDockSlotStyles(dockSlot);
+  applyDockSlotMaxHeight(dockSlot, dock.maxHeight);
 
   if (dock.reveal === "overlay") {
     shell.style.display = "flex";
@@ -279,15 +366,24 @@ const applyDockStyles = (
 
     const panelPx = parseDockWidthToPx(dock.width, shell.clientWidth);
     const contentPx = Math.max(0, shell.clientWidth);
-    const dockTransition = dock.animate ? "transform 180ms ease" : "none";
-    const translate =
+    const dockTransition = dock.animate ? "margin-left 180ms ease" : "none";
+    // Slide the wide track with a negative left margin rather than a CSS
+    // transform. A `transform` (even `translateX(0)`) turns the push track into
+    // the containing block for any `position: fixed` descendant, so host pages
+    // that render viewport-fixed chrome inside the pushed content (e.g. the
+    // dashboard editor's `fixed top-0 right-0` toolbar) resolve `right: 0`
+    // against the track's right edge — `panelPx` past the viewport, off-screen.
+    // `margin-left` produces the identical visual offset (the track is clipped
+    // by the overflow:hidden shell) without establishing a containing block for
+    // fixed OR absolutely-positioned descendants.
+    const marginOffsetPx =
       dock.side === "right"
         ? expanded
-          ? `translateX(-${panelPx}px)`
-          : "translateX(0)"
+          ? -panelPx
+          : 0
         : expanded
-          ? "translateX(0)"
-          : `translateX(-${panelPx}px)`;
+          ? 0
+          : -panelPx;
 
     pushTrack.style.display = "flex";
     pushTrack.style.flexDirection = "row";
@@ -298,7 +394,10 @@ const applyDockStyles = (
     pushTrack.style.height = "100%";
     pushTrack.style.width = `${contentPx + panelPx}px`;
     pushTrack.style.transition = dockTransition;
-    pushTrack.style.transform = translate;
+    pushTrack.style.marginLeft = `${marginOffsetPx}px`;
+    // Defensively clear any transform a previous reveal mode may have set —
+    // leaving one would re-establish the fixed-position containing block.
+    pushTrack.style.transform = "";
 
     contentSlot.style.flex = "0 0 auto";
     contentSlot.style.flexGrow = "0";
@@ -315,6 +414,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 +448,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 +529,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;

package/src/runtime/init.test.ts

@@ -424,11 +424,11 @@ describe("initAgentWidget docked mode", () => {
     const panelSlot = shell.querySelector<HTMLElement>('[data-persona-dock-role="panel"]')!;
     expect(pushTrack).not.toBeNull();
     expect(panelSlot.style.width).toBe("400px");
-    expect(pushTrack?.style.transform).toBe("translateX(-400px)");
+    expect(pushTrack?.style.marginLeft).toBe("-400px");
 
     handle.close();
     expect(panelSlot.style.width).toBe("400px");
-    expect(pushTrack?.style.transform).toBe("translateX(0)");
+    expect(pushTrack?.style.marginLeft).toBe("0px");
 
     handle.destroy();
     wrapper.remove();