@runtypelabs/persona 3.2.1 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/runtime/host-layout.ts

@@ -198,7 +198,7 @@ const applyDockStyles = (
     dockSlot.style.minWidth = "0";
     dockSlot.style.minHeight = "0";
     dockSlot.style.overflow = "hidden";
-    dockSlot.style.zIndex = "9999";
+    dockSlot.style.zIndex = String(config?.launcher?.zIndex ?? 9999);
     dockSlot.style.transform = "none";
     dockSlot.style.transition = "none";
     dockSlot.style.pointerEvents = "auto";

package/src/types.ts

@@ -790,6 +790,14 @@ export type AgentWidgetLauncherConfig = {
    * @default 640
    */
   mobileBreakpoint?: number;
+  /**
+   * CSS z-index applied to the widget wrapper when it is in a positioned mode
+   * (floating panel, mobile fullscreen, or sidebar). Increase this value if
+   * other elements on the host page appear on top of the widget.
+   *
+   * @default 9999 in overlay modes (mobile fullscreen / sidebar); 50 for the regular floating panel
+   */
+  zIndex?: number;
   callToActionIconText?: string;
   callToActionIconName?: string;
   callToActionIconColor?: string;

package/src/ui.overlay-z-index.test.ts

@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createAgentExperience } from "./ui";
+
+const originalInnerWidth = window.innerWidth;
+
+const setInnerWidth = (value: number) => {
+  Object.defineProperty(window, "innerWidth", {
+    configurable: true,
+    writable: true,
+    value,
+  });
+};
+
+const createMount = () => {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return mount;
+};
+
+describe("createAgentExperience overlay z-index", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    setInnerWidth(originalInnerWidth);
+  });
+
+  it("defaults sidebar mode to the overlay z-index", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: {
+        sidebarMode: true,
+        position: "bottom-right",
+      },
+    });
+
+    const wrapper = mount.firstElementChild as HTMLElement | null;
+
+    expect(wrapper).not.toBeNull();
+    expect(wrapper?.style.zIndex).toBe("9999");
+
+    controller.destroy();
+  });
+
+  it("defaults mobile fullscreen to the overlay z-index", () => {
+    setInnerWidth(480);
+
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+    });
+
+    const wrapper = mount.firstElementChild as HTMLElement | null;
+
+    expect(wrapper).not.toBeNull();
+    expect(wrapper?.style.zIndex).toBe("9999");
+
+    controller.destroy();
+  });
+});

package/src/ui.ts

@@ -1474,6 +1474,7 @@ export const createAgentExperience = (
     // Determine panel styling based on mode, with theme overrides
     const position = config.launcher?.position ?? 'bottom-left';
     const isLeftSidebar = position === 'bottom-left' || position === 'top-left';
+    const overlayZIndex = config.launcher?.zIndex ?? 9999;
 
     // Default values based on mode
     let defaultPanelBorder = (sidebarMode || shouldGoFullscreen) ? 'none' : '1px solid var(--persona-border)';
@@ -1524,7 +1525,8 @@ export const createAgentExperience = (
         padding: 0 !important;
         display: flex !important;
         flex-direction: column !important;
-        z-index: inherit !important;
+        z-index: ${overlayZIndex} !important;
+        background-color: var(--persona-surface, #ffffff) !important;
       `;
 
       // Panel — fill wrapper, no radius/shadow
@@ -1690,6 +1692,7 @@ export const createAgentExperience = (
         padding: 0 !important;
         display: flex !important;
         flex-direction: column !important;
+        z-index: ${overlayZIndex} !important;
         ${isLeftSidebar ? 'left: 0 !important; right: auto !important;' : 'left: auto !important; right: 0 !important;'}
       `;
       
@@ -1744,7 +1747,11 @@ export const createAgentExperience = (
     if (!isInlineEmbed && !dockedMode) {
       const maxHeightStyles = 'max-height: -moz-available !important; max-height: stretch !important;';
       const paddingStyles = sidebarMode ? '' : 'padding-top: 1.25em !important;';
-      wrapper.style.cssText += maxHeightStyles + paddingStyles;
+      // Override z-index only when explicitly configured; otherwise the persona-z-50 class applies
+      const zIndexStyles = !sidebarMode && config.launcher?.zIndex != null
+        ? `z-index: ${config.launcher.zIndex} !important;`
+        : '';
+      wrapper.style.cssText += maxHeightStyles + paddingStyles + zIndexStyles;
     }
   };
   applyFullHeightStyles();