@runtypelabs/persona 3.7.0 → 3.8.1

package/dist/theme-reference.d.ts

@@ -214,6 +214,17 @@ interface MessageTokens {
         /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
         shadow?: string;
     };
+    /** Border color between messages in the thread. */
+    border?: TokenReference<'color'>;
+}
+/** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
+interface CollapsibleWidgetTokens {
+    /** Background for content areas. */
+    container?: TokenReference<'color'>;
+    /** Background for code blocks inside collapsible sections. */
+    surface?: TokenReference<'color'>;
+    /** Border color for collapsible sections. */
+    border?: TokenReference<'color'>;
 }
 interface MarkdownTokens {
     inlineCode: {
@@ -242,6 +253,27 @@ interface MarkdownTokens {
             fontWeight?: string;
         };
     };
+    /** Fenced code block styling. */
+    codeBlock?: {
+        background?: TokenReference<'color'>;
+        borderColor?: TokenReference<'color'>;
+        textColor?: TokenReference<'color'>;
+    };
+    /** Table styling. */
+    table?: {
+        headerBackground?: TokenReference<'color'>;
+        borderColor?: TokenReference<'color'>;
+    };
+    /** Horizontal rule styling. */
+    hr?: {
+        color?: TokenReference<'color'>;
+    };
+    /** Blockquote styling. */
+    blockquote?: {
+        borderColor?: TokenReference<'color'>;
+        background?: TokenReference<'color'>;
+        textColor?: TokenReference<'color'>;
+    };
 }
 interface VoiceTokens {
     recording: {
@@ -404,6 +436,8 @@ interface ComponentTokens {
         tab?: ArtifactTabTokens;
         pane?: ArtifactPaneTokens;
     };
+    /** Collapsible widget chrome (tool/reasoning/approval bubbles). */
+    collapsibleWidget?: CollapsibleWidgetTokens;
 }
 interface PaletteExtras {
     transitions?: Record<string, string>;

package/dist/widget.css

@@ -834,6 +834,10 @@
   overflow-y: auto;
 }
 
+.persona-widget-body {
+  overscroll-behavior: contain;
+}
+
 .persona-overflow-hidden {
   overflow: hidden;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "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/components/artifact-card.ts

@@ -24,7 +24,7 @@ function renderDefaultArtifactCard(
   root.className =
     "persona-flex persona-w-full persona-max-w-full persona-items-center persona-gap-3 persona-rounded-xl persona-px-4 persona-py-3";
   root.style.border = "1px solid var(--persona-border, #e5e7eb)";
-  root.style.backgroundColor = "var(--persona-bg, #ffffff)";
+  root.style.backgroundColor = "var(--persona-surface, #ffffff)";
   root.style.cursor = "pointer";
   root.tabIndex = 0;
   root.setAttribute("role", "button");

package/src/components/header-builder.ts

@@ -1,6 +1,7 @@
 import { createElement, createElementInDocument } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
 import { AgentWidgetConfig } from "../types";
+import { PORTALED_OVERLAY_Z_INDEX } from "../utils/constants";
 
 /** CSS `color` values; variables are set on `[data-persona-root]` from `theme.components.header`. */
 export const HEADER_THEME_CSS = {
@@ -233,6 +234,7 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
 
         // Position tooltip above button
         portaledTooltip.style.position = "fixed";
+        portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
         portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
         portaledTooltip.style.top = `${buttonRect.top - 8}px`;
         portaledTooltip.style.transform = "translate(-50%, -100%)";
@@ -389,6 +391,7 @@ export const buildHeader = (context: HeaderBuildContext): HeaderElements => {
 
       // Position tooltip above button
       portaledTooltip.style.position = "fixed";
+      portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
       portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
       portaledTooltip.style.top = `${buttonRect.top - 8}px`;
       portaledTooltip.style.transform = "translate(-50%, -100%)";

package/src/components/launcher.ts

@@ -3,6 +3,7 @@ import { AgentWidgetConfig } from "../types";
 import { positionMap } from "../utils/positioning";
 import { isDockedMountMode } from "../utils/dock";
 import { renderLucideIcon } from "../utils/icons";
+import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
 
 export interface LauncherButton {
   element: HTMLButtonElement;
@@ -174,12 +175,16 @@ export const createLauncherButton = (
         : positionMap["bottom-right"];
 
     const floatingBase =
-      "persona-fixed persona-flex persona-items-center persona-gap-3 persona-rounded-launcher persona-bg-persona-surface persona-py-2.5 persona-pl-3 persona-pr-3 persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer persona-z-50";
+      "persona-fixed persona-flex persona-items-center persona-gap-3 persona-rounded-launcher persona-bg-persona-surface persona-py-2.5 persona-pl-3 persona-pr-3 persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
     const dockedBase =
       "persona-relative persona-mt-4 persona-mb-4 persona-mx-auto persona-flex persona-items-center persona-justify-center persona-rounded-launcher persona-bg-persona-surface persona-transition hover:persona-translate-y-[-2px] persona-cursor-pointer";
 
     button.className = dockedMode ? dockedBase : `${floatingBase} ${positionClass}`;
-    
+
+    if (!dockedMode) {
+      button.style.zIndex = String(launcher.zIndex ?? DEFAULT_OVERLAY_Z_INDEX);
+    }
+
     // Apply launcher border and shadow from config (with defaults matching previous Tailwind classes)
     const defaultBorder = "1px solid var(--persona-border, #e5e7eb)";
     const defaultShadow = "var(--persona-shadow, 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1))";

package/src/components/panel.ts

@@ -2,6 +2,7 @@ import { createElement } from "../utils/dom";
 import { AgentWidgetConfig } from "../types";
 import { positionMap } from "../utils/positioning";
 import { isDockedMountMode } from "../utils/dock";
+import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
 import { buildHeader, attachHeaderToContainer, HeaderElements } from "./header-builder";
 import { buildHeaderWithLayout } from "./header-layouts";
 import { buildComposer, ComposerElements } from "./composer-builder";
@@ -58,8 +59,9 @@ export const createWrapper = (config?: AgentWidgetConfig): PanelWrapper => {
 
   const wrapper = createElement(
     "div",
-    `persona-widget-wrapper persona-fixed ${position} persona-z-50 persona-transition`
+    `persona-widget-wrapper persona-fixed ${position} persona-transition`
   );
+  wrapper.style.zIndex = String(config?.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX);
 
   const panel = createElement(
     "div",

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

@@ -228,7 +228,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("fixed");
-      expect(dockSlot?.style.zIndex).toBe("9999");
+      expect(dockSlot?.style.zIndex).toBe("100000");
       expect(layout.shell?.dataset.personaDockMobileFullscreen).toBe("true");
 
       layout.destroy();

package/src/runtime/host-layout.ts

@@ -3,6 +3,7 @@ import type {
   AgentWidgetStateSnapshot,
 } from "../types";
 import { isDockedMountMode, resolveDockConfig } from "../utils/dock";
+import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
 
 export type WidgetHostLayoutMode = "direct" | "docked";
 
@@ -198,7 +199,7 @@ const applyDockStyles = (
     dockSlot.style.minWidth = "0";
     dockSlot.style.minHeight = "0";
     dockSlot.style.overflow = "hidden";
-    dockSlot.style.zIndex = String(config?.launcher?.zIndex ?? 9999);
+    dockSlot.style.zIndex = String(config?.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX);
     dockSlot.style.transform = "none";
     dockSlot.style.transition = "none";
     dockSlot.style.pointerEvents = "auto";

package/src/styles/widget.css

@@ -834,6 +834,10 @@
   overflow-y: auto;
 }
 
+.persona-widget-body {
+  overscroll-behavior: contain;
+}
+
 .persona-overflow-hidden {
   overflow: hidden;
 }

package/src/types/theme.ts

@@ -233,6 +233,18 @@ export interface MessageTokens {
     /** Assistant bubble box-shadow (token ref or raw CSS, e.g. `none`). */
     shadow?: string;
   };
+  /** Border color between messages in the thread. */
+  border?: TokenReference<'color'>;
+}
+
+/** Collapsible widget chrome (tool bubbles, reasoning bubbles, approval bubbles). */
+export interface CollapsibleWidgetTokens {
+  /** Background for content areas. */
+  container?: TokenReference<'color'>;
+  /** Background for code blocks inside collapsible sections. */
+  surface?: TokenReference<'color'>;
+  /** Border color for collapsible sections. */
+  border?: TokenReference<'color'>;
 }
 
 export interface MarkdownTokens {
@@ -262,6 +274,27 @@ export interface MarkdownTokens {
       fontWeight?: string;
     };
   };
+  /** Fenced code block styling. */
+  codeBlock?: {
+    background?: TokenReference<'color'>;
+    borderColor?: TokenReference<'color'>;
+    textColor?: TokenReference<'color'>;
+  };
+  /** Table styling. */
+  table?: {
+    headerBackground?: TokenReference<'color'>;
+    borderColor?: TokenReference<'color'>;
+  };
+  /** Horizontal rule styling. */
+  hr?: {
+    color?: TokenReference<'color'>;
+  };
+  /** Blockquote styling. */
+  blockquote?: {
+    borderColor?: TokenReference<'color'>;
+    background?: TokenReference<'color'>;
+    textColor?: TokenReference<'color'>;
+  };
 }
 
 export interface VoiceTokens {
@@ -438,6 +471,8 @@ export interface ComponentTokens {
     tab?: ArtifactTabTokens;
     pane?: ArtifactPaneTokens;
   };
+  /** Collapsible widget chrome (tool/reasoning/approval bubbles). */
+  collapsibleWidget?: CollapsibleWidgetTokens;
 }
 
 export interface PaletteExtras {

package/src/types.ts

@@ -813,11 +813,16 @@ export type AgentWidgetLauncherConfig = {
    */
   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.
+   * CSS z-index applied to the widget wrapper and launcher button in all
+   * positioned modes (floating panel, mobile fullscreen, sidebar, docked
+   * mobile fullscreen). 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
+   * In viewport-covering modes (sidebar, mobile fullscreen), the widget
+   * also elevates the host element's stacking context and locks
+   * document scroll to prevent background scrolling.
+   *
+   * @default 100000
    */
   zIndex?: number;
   callToActionIconText?: string;

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

@@ -39,7 +39,7 @@ describe("createAgentExperience overlay z-index", () => {
     const wrapper = mount.firstElementChild as HTMLElement | null;
 
     expect(wrapper).not.toBeNull();
-    expect(wrapper?.style.zIndex).toBe("9999");
+    expect(wrapper?.style.zIndex).toBe("100000");
 
     controller.destroy();
   });
@@ -55,7 +55,39 @@ describe("createAgentExperience overlay z-index", () => {
     const wrapper = mount.firstElementChild as HTMLElement | null;
 
     expect(wrapper).not.toBeNull();
-    expect(wrapper?.style.zIndex).toBe("9999");
+    expect(wrapper?.style.zIndex).toBe("100000");
+
+    controller.destroy();
+  });
+
+  it("defaults floating panel wrapper to the overlay z-index", () => {
+    setInnerWidth(1024);
+
+    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("100000");
+
+    controller.destroy();
+  });
+
+  it("respects a custom zIndex", () => {
+    const mount = createMount();
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: {
+        sidebarMode: true,
+        zIndex: 42,
+      },
+    });
+
+    const wrapper = mount.firstElementChild as HTMLElement | null;
+    expect(wrapper?.style.zIndex).toBe("42");
 
     controller.destroy();
   });

package/src/ui.ts

@@ -40,7 +40,9 @@ import {
   resolveFollowStateFromScroll,
   resolveFollowStateFromWheel
 } from "./utils/auto-follow";
-import { statusCopy } from "./utils/constants";
+import { statusCopy, DEFAULT_OVERLAY_Z_INDEX, PORTALED_OVERLAY_Z_INDEX } from "./utils/constants";
+import { syncOverlayHostStacking } from "./utils/overlay-host-stacking";
+import { acquireScrollLock } from "./utils/scroll-lock";
 import { isDockedMountMode, resolveDockConfig } from "./utils/dock";
 import { createLauncherButton } from "./components/launcher";
 import { createWrapper, buildPanel, buildHeader, buildComposer, attachHeaderToContainer } from "./components/panel";
@@ -1287,6 +1289,7 @@ export const createAgentExperience = (
     if (openPrevented === true) return;
     event.preventDefault();
     event.stopPropagation();
+    artifactsPaneUserHidden = false;
     session.selectArtifact(artifactId);
     syncArtifactPane();
   });
@@ -1546,7 +1549,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;
+    const overlayZIndex = config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX;
 
     // Default values based on mode
     let defaultPanelBorder = (sidebarMode || shouldGoFullscreen) ? 'none' : '1px solid var(--persona-border)';
@@ -1819,9 +1822,8 @@ 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;';
-      // 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;`
+      const zIndexStyles = !sidebarMode
+        ? `z-index: ${config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX} !important;`
         : '';
       wrapper.style.cssText += maxHeightStyles + paddingStyles + zIndexStyles;
     }
@@ -1834,6 +1836,16 @@ export const createAgentExperience = (
 
   const destroyCallbacks: Array<() => void> = [];
 
+  let teardownHostStacking: (() => void) | null = null;
+  let releaseScrollLock: (() => void) | null = null;
+
+  destroyCallbacks.push(() => {
+    teardownHostStacking?.();
+    teardownHostStacking = null;
+    releaseScrollLock?.();
+    releaseScrollLock = null;
+  });
+
   if (artifactPanelResizeObs) {
     destroyCallbacks.push(() => {
       artifactPanelResizeObs?.disconnect();
@@ -2033,7 +2045,8 @@ export const createAgentExperience = (
       container.appendChild(scrollToBottomButton);
     }
     updateScrollToBottomButtonOffset();
-    scrollToBottomButton.style.display = autoFollow.isFollowing() ? "none" : "";
+    const hasOverflow = getScrollBottomOffset(body) > 0;
+    scrollToBottomButton.style.display = (autoFollow.isFollowing() || !hasOverflow) ? "none" : "";
   };
 
   const pauseAutoScroll = () => {
@@ -2620,12 +2633,46 @@ export const createAgentExperience = (
     const prevOpen = open;
     open = nextOpen;
     updateOpenState();
-    
+
+    // Sync host stacking and scroll lock for viewport-covering modes
+    const isViewportCovering = (() => {
+      const sm = config.launcher?.sidebarMode ?? false;
+      const ow = mount.ownerDocument.defaultView ?? window;
+      const mf = config.launcher?.mobileFullscreen ?? true;
+      const mb = config.launcher?.mobileBreakpoint ?? 640;
+      const isMobile = ow.innerWidth <= mb;
+      const dockedMF = isDockedMountMode(config) && mf && isMobile;
+      return sm || (mf && isMobile && launcherEnabled) || dockedMF;
+    })();
+
+    if (open && isViewportCovering) {
+      if (!teardownHostStacking) {
+        const root = mount.getRootNode();
+        const hostEl = root instanceof ShadowRoot
+          ? (root.host as HTMLElement)
+          : mount.closest<HTMLElement>(".persona-host");
+        if (hostEl) {
+          teardownHostStacking = syncOverlayHostStacking(
+            hostEl,
+            config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX
+          );
+        }
+      }
+      if (!releaseScrollLock) {
+        releaseScrollLock = acquireScrollLock(mount.ownerDocument);
+      }
+    } else if (!open) {
+      teardownHostStacking?.();
+      teardownHostStacking = null;
+      releaseScrollLock?.();
+      releaseScrollLock = null;
+    }
+
     if (open) {
       recalcPanelHeight();
       scheduleAutoScroll(true);
     }
-    
+
     // Emit widget state events
     const stateEvent: AgentWidgetStateEvent = {
       open,
@@ -3572,6 +3619,35 @@ export const createAgentExperience = (
       // overwrites updateOpenState()'s display:none when docked+closed. Re-sync after every recalc.
       updateScrollToBottomButtonOffset();
       updateOpenState();
+
+      // Sync scroll lock and host stacking when viewport mode changes (e.g. orientation change)
+      if (open && launcherEnabled) {
+        const ow = mount.ownerDocument.defaultView ?? window;
+        const isMobile = ow.innerWidth <= (config.launcher?.mobileBreakpoint ?? 640);
+        const sm = config.launcher?.sidebarMode ?? false;
+        const mf = config.launcher?.mobileFullscreen ?? true;
+        const dockedMF = isDockedMountMode(config) && mf && isMobile;
+        const isVC = sm || (mf && isMobile && launcherEnabled) || dockedMF;
+
+        if (isVC && !releaseScrollLock) {
+          const root = mount.getRootNode();
+          const hostEl = root instanceof ShadowRoot
+            ? (root.host as HTMLElement)
+            : mount.closest<HTMLElement>(".persona-host");
+          if (hostEl && !teardownHostStacking) {
+            teardownHostStacking = syncOverlayHostStacking(
+              hostEl,
+              config.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX
+            );
+          }
+          releaseScrollLock = acquireScrollLock(mount.ownerDocument);
+        } else if (!isVC) {
+          teardownHostStacking?.();
+          teardownHostStacking = null;
+          releaseScrollLock?.();
+          releaseScrollLock = null;
+        }
+      }
     }
   };
 
@@ -3671,6 +3747,7 @@ export const createAgentExperience = (
       // Clear messages in session (this will trigger onMessagesChanged which re-renders)
       session.clearMessages();
       messageCache.clear();
+      resumeAutoScroll();
 
       // Always clear the default localStorage key
       try {
@@ -4250,6 +4327,7 @@ export const createAgentExperience = (
 
               // Position tooltip above button
               portaledTooltip.style.position = "fixed";
+              portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
               portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
               portaledTooltip.style.top = `${buttonRect.top - 8}px`;
               portaledTooltip.style.transform = "translate(-50%, -100%)";
@@ -4464,6 +4542,7 @@ export const createAgentExperience = (
 
                 // Position tooltip above button
                 portaledTooltip.style.position = "fixed";
+                portaledTooltip.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
                 portaledTooltip.style.left = `${buttonRect.left + buttonRect.width / 2}px`;
                 portaledTooltip.style.top = `${buttonRect.top - 8}px`;
                 portaledTooltip.style.transform = "translate(-50%, -100%)";
@@ -4994,6 +5073,7 @@ export const createAgentExperience = (
       artifactsPaneUserHidden = false;
       session.clearMessages();
       messageCache.clear();
+      resumeAutoScroll();
 
       // Always clear the default localStorage key
       try {

package/src/utils/constants.ts

@@ -7,6 +7,19 @@ export const statusCopy: Record<AgentWidgetSessionStatus, string> = {
   error: "Offline"
 };
 
+/**
+ * Default z-index for widget overlays. Used for the floating panel, launcher
+ * button, sidebar, mobile fullscreen, and docked mobile fullscreen modes.
+ * Integrators can override via `launcher.zIndex`.
+ */
+export const DEFAULT_OVERLAY_Z_INDEX = 100000;
+
+/**
+ * Z-index for elements portaled to document.body (tooltips, dropdowns).
+ * Must be above the widget overlay so portaled UI is not clipped.
+ */
+export const PORTALED_OVERLAY_Z_INDEX = DEFAULT_OVERLAY_Z_INDEX + 1;
+
 
 
 

package/src/utils/dropdown.ts

@@ -1,5 +1,6 @@
 import { createElement } from "./dom";
 import { renderLucideIcon } from "./icons";
+import { PORTALED_OVERLAY_Z_INDEX } from "./constants";
 
 export interface DropdownMenuItem {
   id: string;
@@ -73,7 +74,7 @@ export function createDropdownMenu(options: CreateDropdownOptions): DropdownMenu
   if (portal) {
     // Fixed positioning — menu is portaled outside the anchor's overflow context
     menu.style.position = "fixed";
-    menu.style.zIndex = "10000";
+    menu.style.zIndex = String(PORTALED_OVERLAY_Z_INDEX);
   } else {
     // Absolute positioning — menu lives inside the anchor
     menu.style.position = "absolute";

package/src/utils/overlay-host-stacking.test.ts

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it } from "vitest";
+import { syncOverlayHostStacking } from "./overlay-host-stacking";
+
+describe("syncOverlayHostStacking", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("sets position relative on a static element and restores on teardown", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host);
+    expect(host.style.position).toBe("relative");
+    expect(host.style.zIndex).toBe("100000");
+    expect(host.style.isolation).toBe("isolate");
+
+    teardown();
+    expect(host.style.position).toBe("");
+    expect(host.style.zIndex).toBe("");
+    expect(host.style.isolation).toBe("");
+  });
+
+  it("preserves existing positioned value", () => {
+    const host = document.createElement("div");
+    host.style.position = "absolute";
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host);
+    expect(host.style.position).toBe("absolute");
+    expect(host.style.zIndex).toBe("100000");
+
+    teardown();
+    expect(host.style.position).toBe("absolute");
+    expect(host.style.zIndex).toBe("");
+  });
+
+  it("accepts custom z-index", () => {
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host, 42);
+    expect(host.style.zIndex).toBe("42");
+
+    teardown();
+  });
+
+  it("restores previous inline z-index on teardown", () => {
+    const host = document.createElement("div");
+    host.style.zIndex = "5";
+    document.body.appendChild(host);
+
+    const teardown = syncOverlayHostStacking(host);
+    expect(host.style.zIndex).toBe("100000");
+
+    teardown();
+    expect(host.style.zIndex).toBe("5");
+  });
+});

package/src/utils/overlay-host-stacking.ts

@@ -0,0 +1,38 @@
+import { DEFAULT_OVERLAY_Z_INDEX } from "./constants";
+
+/**
+ * Elevates the light-DOM host element's stacking context so viewport-covering
+ * overlays (sidebar, fullscreen) can escape parent stacking traps.
+ *
+ * - If the host has `position: static`, sets it to `relative` (required for
+ *   `z-index` to take effect).
+ * - Applies `z-index` matching the overlay default.
+ * - Applies `isolation: isolate` to create a predictable stacking context.
+ *
+ * @returns A teardown function that restores only the properties that were changed.
+ */
+export function syncOverlayHostStacking(
+  host: HTMLElement,
+  zIndex: number = DEFAULT_OVERLAY_Z_INDEX
+): () => void {
+  const originalPosition = host.style.position;
+  const originalZIndex = host.style.zIndex;
+  const originalIsolation = host.style.isolation;
+
+  const computed = getComputedStyle(host);
+  const positionWasSet = computed.position === "static" || computed.position === "";
+  if (positionWasSet) {
+    host.style.position = "relative";
+  }
+
+  host.style.zIndex = String(zIndex);
+  host.style.isolation = "isolate";
+
+  return () => {
+    if (positionWasSet) {
+      host.style.position = originalPosition;
+    }
+    host.style.zIndex = originalZIndex;
+    host.style.isolation = originalIsolation;
+  };
+}