help-layer 1.1.0 → 1.3.0

package/dist/types/aria-isolation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {object} state teardown registry
+ * @param {object} params
+ * @param {HTMLElement|null} params.toggleEl the toggle (must stay reachable), or null for programmatic-only
+ * @param {(el: Element) => boolean} params.isLibraryNode whether a body child belongs to the library UI
+ */
+export function isolateBackgroundFromAT(state: object, { toggleEl, isLibraryNode }: {
+    toggleEl: HTMLElement | null;
+    isLibraryNode: (el: Element) => boolean;
+}): void;

package/dist/types/floating.d.ts

@@ -1,70 +1 @@
-/**
- * Create a "virtual reference element" for free-placement items not bound to an element.
- * When getDocRect() returns document coordinates, this converts them to viewport
- * coordinates according to the current scroll. Because autoUpdate re-evaluates on every
- * scroll, the element sticks to the given coordinate while scrolling along with the page.
- * @param {() => {top:number,left:number,width?:number,height?:number}} getDocRect
- */
-export function makeVirtualElement(getDocRect: () => {
-    top: number;
-    left: number;
-    width?: number;
-    height?: number;
-}): {
-    contextElement: HTMLElement;
-    getBoundingClientRect(): {
-        x: number;
-        y: number;
-        left: number;
-        top: number;
-        right: number;
-        bottom: number;
-        width: number;
-        height: number;
-    };
-};
-/**
- * Whether the reference lives in a `position: fixed` subtree. Such a reference stays put in the
- * viewport while the page scrolls, so an absolutely-positioned floating element (which scrolls with
- * the document) would have to be re-corrected every frame and visibly jitters. For these we switch the
- * floating element to Floating UI's `fixed` strategy (and position:fixed) so both live in the same
- * viewport space and stay glued without per-frame correction.
- *
- * Virtual elements (free placements) aren't in the DOM and already track scroll via their getRect, so
- * they report false. Walks across shadow boundaries via the host so Shadow DOM targets are handled too.
- * @param {Element|object} reference
- */
-export function isFixedReference(reference: Element | object): boolean;
-/**
- * Overlap the marker onto a corner of the target (element or virtual element), stick it there, and keep it following.
- * @param {Element|object} reference
- * @param {HTMLElement} markerEl
- * @param {() => void} [onPlaced] called every time placement is finalized (used to trigger the overlap-avoidance pass, etc.)
- * @param {import('@floating-ui/dom').Placement} [placement] corner to overlap (top-end/top-start/bottom-end/bottom-start). Default 'top-end'
- * @returns {() => void} cleanup
- */
-export function anchorMarker(reference: Element | object, markerEl: HTMLElement, onPlaced?: () => void, placement?: import("@floating-ui/dom").Placement): () => void;
-/**
- * Place the popup below the target, and at screen edges use flip (flip to the opposite side) /
- * shift (nudge) to avoid clipping. Only follows while visible.
- * @param {Element|object} reference
- * @param {HTMLElement} popupEl
- * @param {import('@floating-ui/dom').Placement} [placement] initial placement (Floating UI placement). Default 'bottom-start'
- * @returns {{ update: () => void, cleanup: () => void }}
- *   calling update repositions immediately (used for reference-side transform moves that autoUpdate doesn't pick up, etc.).
- */
-export function anchorPopup(reference: Element | object, popupEl: HTMLElement, placement?: import("@floating-ui/dom").Placement): {
-    update: () => void;
-    cleanup: () => void;
-};
-/**
- * Watch a reference element's position/size changes and call onUpdate on every change.
- * (Used for non-placement purposes, e.g. keeping the blocking layer's clip-path hole following the toggle position.)
- * autoUpdate requires a floating element, so floatingEl is just passed as a dummy that
- * onUpdate doesn't actually position.
- * @param {Element} referenceEl
- * @param {HTMLElement} floatingEl
- * @param {() => void} onUpdate
- * @returns {() => void} cleanup
- */
-export function watchReference(referenceEl: Element, floatingEl: HTMLElement, onUpdate: () => void): () => void;
+export * from "./floating.self.js";

package/dist/types/floating.floatingui.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Place the popup below the target, and at screen edges use flip / shift to avoid clipping.
+ * @param {Element|object} reference
+ * @param {HTMLElement} popupEl
+ * @param {import('./types.js').Placement} [placement] initial placement. Default 'bottom-start'
+ * @returns {{ update: () => void, cleanup: () => void }}
+ */
+export function anchorPopup(reference: Element | object, popupEl: HTMLElement, placement?: import("./types.js").Placement): {
+    update: () => void;
+    cleanup: () => void;
+};
+/**
+ * Watch a reference element's position/size changes and call onUpdate on every change.
+ * (Used to keep the blocking layer's clip-path hole following the toggle.) autoUpdate requires a
+ * floating element, so floatingEl is passed as a dummy that onUpdate doesn't actually position.
+ * @param {Element} referenceEl
+ * @param {HTMLElement} floatingEl
+ * @param {() => void} onUpdate
+ * @returns {() => void} cleanup
+ */
+export function watchReference(referenceEl: Element, floatingEl: HTMLElement, onUpdate: () => void): () => void;
+import { isFixedReference } from './reference.js';
+import { isReferenceHidden } from './reference.js';
+import { makeVirtualElement } from './reference.js';
+export { isFixedReference, isReferenceHidden, makeVirtualElement };

package/dist/types/floating.self.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Place the popup on a side of the target with a gap, flipping/shifting at screen edges to stay
+ * visible, and keep it following while open.
+ * @param {Element|object} reference
+ * @param {HTMLElement} popupEl
+ * @param {import('./types.js').Placement} [placement] initial placement. Default 'bottom-start'
+ * @returns {{ update: () => void, cleanup: () => void }}
+ */
+export function anchorPopup(reference: Element | object, popupEl: HTMLElement, placement?: import("./types.js").Placement): {
+    update: () => void;
+    cleanup: () => void;
+};
+/**
+ * Watch a reference element's position/size changes and call onUpdate on every change.
+ * (Used to keep the blocking layer's clip-path hole following the toggle.) floatingEl is accepted for
+ * signature parity with the Floating UI backend but isn't used here.
+ * @param {Element} referenceEl
+ * @param {HTMLElement} _floatingEl unused (kept for backend parity)
+ * @param {() => void} onUpdate
+ * @returns {() => void} cleanup
+ */
+export function watchReference(referenceEl: Element, _floatingEl: HTMLElement, onUpdate: () => void): () => void;
+import { isFixedReference } from './reference.js';
+import { isReferenceHidden } from './reference.js';
+import { makeVirtualElement } from './reference.js';
+export { isFixedReference, isReferenceHidden, makeVirtualElement };

package/dist/types/geometry.d.ts

@@ -1,8 +1,8 @@
 /**
  * Pure geometry calculations. Takes no DOM elements, only numbers already read off.
  *
- * Clamping things that overflow the viewport is handled by Floating UI's shift()
- * middleware. toDocumentPosition is used for the virtual-element math of free placement, etc.
+ * Clamping things that overflow the viewport is handled by computePopupPosition's shift step
+ * below. toDocumentPosition is used for the virtual-element math of free placement, etc.
  */
 /**
  * Given getBoundingClientRect() values (viewport-relative) and the scroll offset,
@@ -14,8 +14,8 @@ export function toDocumentPosition(rect: any, scroll: any): {
 };
 /**
  * Convert a document-coordinate rect into a viewport-coordinate rect by subtracting
- * the current scroll offset. This is what the getBoundingClientRect of a Floating UI
- * virtual reference element (a free-placement marker) returns.
+ * the current scroll offset. This is what the getBoundingClientRect of a virtual
+ * reference element (a free-placement marker) returns.
  * @param {{top:number,left:number,width?:number,height?:number}} docRect
  * @param {{x:number,y:number}} scroll
  */
@@ -37,3 +37,84 @@ export function docRectToViewportRect(docRect: {
     width: number;
     height: number;
 };
+/**
+ * Compute a marker's top-left in viewport coordinates so it overlaps a corner of the reference rect,
+ * replicating what Floating UI's computePosition(placement) + offset(markerOffset) produced before.
+ *
+ * placement is "<side>" or "<side>-<align>" where side is top/bottom/left/right and align is
+ * start/end (omitted = centered). The marker is a square of the given size. mainAxis bites INSET
+ * inward (overlapping the target edge); crossAxis nudges INSET inward from the aligned edge.
+ * @param {{top:number,left:number,width:number,height:number}} refRect viewport rect of the target
+ * @param {number} size marker width/height (square)
+ * @param {string} placement a placement string (see Placement in types.js; default 'top-end')
+ * @returns {{left:number, top:number}} viewport coordinates of the marker's top-left corner
+ */
+export function markerViewportTopLeft(refRect: {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}, size: number, placement?: string): {
+    left: number;
+    top: number;
+};
+/**
+ * Convert a viewport coordinate into the left/top to set on a `position:absolute` element whose
+ * offsetParent is `document.body`. Both the marker's reference rect and the body rect come from
+ * getBoundingClientRect (viewport space), so their difference is scroll-invariant — which is exactly
+ * why the marker stays anchored to its target as the page scrolls. clientLeft/clientTop subtract the
+ * body's border so the offset is measured from the body's padding-box origin (the absolute origin).
+ * For `position:fixed` markers no conversion is needed (viewport coordinates are used as-is).
+ * @param {number} vx viewport x
+ * @param {number} vy viewport y
+ * @param {{left:number, top:number}} bodyRect document.body's getBoundingClientRect
+ * @param {number} clientLeft document.body.clientLeft (left border width)
+ * @param {number} clientTop document.body.clientTop (top border width)
+ * @returns {{left:number, top:number}}
+ */
+export function viewportToAbsolute(vx: number, vy: number, bodyRect: {
+    left: number;
+    top: number;
+}, clientLeft: number, clientTop: number): {
+    left: number;
+    top: number;
+};
+/**
+ * Compute the popup's top-left in viewport coordinates, replicating the small subset of Floating UI
+ * we relied on: place on a side of the reference with a gap (offset), flip to the opposite side when
+ * the preferred side doesn't fit (main axis), and shift along the cross axis to keep it inside the
+ * viewport (with padding). This covers the popup's case — a single element over document.body whose
+ * clipping boundary is the viewport — and is intentionally simpler than Floating UI (no nested
+ * clipping ancestors / transforms / RTL).
+ *
+ * placement is "<side>" or "<side>-<align>" (side: top/bottom/left/right; align: start/end, omitted = center).
+ * @param {{top:number,left:number,width:number,height:number}} refRect viewport rect of the reference
+ * @param {{width:number,height:number}} popupSize the popup's measured size
+ * @param {{width:number,height:number}} viewport innerWidth/innerHeight
+ * @param {object} [opts]
+ * @param {string} [opts.placement] default 'bottom-start'
+ * @param {number} [opts.offset] gap between reference and popup along the main axis (default 8)
+ * @param {number} [opts.padding] minimum gap kept from the viewport edges (default 8)
+ * @returns {{left:number, top:number, placement:string}} resolved viewport coords + the side actually used
+ */
+export function computePopupPosition(refRect: {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}, popupSize: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, opts?: {
+    placement?: string;
+    offset?: number;
+    padding?: number;
+}): {
+    left: number;
+    top: number;
+    placement: string;
+};
+export const MARKER_INSET: 12;

package/dist/types/index.d.ts

@@ -18,8 +18,8 @@
  *   Return a Node to display it; if nothing is returned, fall back to safe text display (the title is always record.title).
  *   ⚠️ The return value is inserted as-is without sanitization. If it contains untrusted data, neutralize it on the caller side (XSS prevention)
  * @param {string} [options.markerLabel] - character shown on the marker (default '?')
- * @param {import('@floating-ui/dom').Placement} [options.markerPlacement] - corner to overlap the marker onto (default 'top-end')
- * @param {import('@floating-ui/dom').Placement} [options.popupPlacement] - initial popup placement (default 'bottom-start')
+ * @param {import('./types.js').Placement} [options.markerPlacement] - corner to overlap the marker onto (default 'top-end')
+ * @param {import('./types.js').Placement} [options.popupPlacement] - initial popup placement (default 'bottom-start')
  * @param {string} [options.nonce] - nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
  * @returns {{
  *   enable(): void,
@@ -44,8 +44,8 @@ export function initHelpLayer(options: {
     attribute?: string;
     render?: (record: import("./matcher.js").HelpRecord) => (Node | null | undefined);
     markerLabel?: string;
-    markerPlacement?: import("@floating-ui/dom").Placement;
-    popupPlacement?: import("@floating-ui/dom").Placement;
+    markerPlacement?: import("./types.js").Placement;
+    popupPlacement?: import("./types.js").Placement;
     nonce?: string;
 }): {
     enable(): void;

package/dist/types/markers.d.ts

@@ -2,15 +2,18 @@
  * @param {object} state teardown registry
  * @param {object} options
  * @param {(record: import('./matcher.js').HelpRecord, markerEl: HTMLElement) => void} options.onMarkerClick
- * @param {() => void} [options.onOverlapResolved]
+ * @param {() => void} [options.onOverlapResolved] called once per frame in which any marker actually moved
+ * @param {(record: import('./matcher.js').HelpRecord) => void} [options.onMarkerHidden] called when a
+ *   marker's target transitions to hidden (e.g. display:none) — lets the caller close a popup open on it
  * @param {string} [options.markerLabel] character shown on the marker (default '?')
- * @param {import('@floating-ui/dom').Placement} [options.markerPlacement] corner to overlap (default 'top-end')
+ * @param {import('./types.js').Placement} [options.markerPlacement] corner to overlap (default 'top-end')
  */
-export function createMarkerManager(state: object, { onMarkerClick, onOverlapResolved, markerLabel, markerPlacement, }: {
+export function createMarkerManager(state: object, { onMarkerClick, onOverlapResolved, onMarkerHidden, markerLabel, markerPlacement, }: {
     onMarkerClick: (record: import("./matcher.js").HelpRecord, markerEl: HTMLElement) => void;
     onOverlapResolved?: () => void;
+    onMarkerHidden?: (record: import("./matcher.js").HelpRecord) => void;
     markerLabel?: string;
-    markerPlacement?: import("@floating-ui/dom").Placement;
+    markerPlacement?: import("./types.js").Placement;
 }): {
     mount: (record: import("./matcher.js").HelpRecord) => void;
     unmount: (id: any) => void;
@@ -19,6 +22,41 @@ export function createMarkerManager(state: object, { onMarkerClick, onOverlapRes
     findByKey(key: any): {
         record: import("./matcher.js").HelpRecord;
         el: HTMLElement;
+        /**
+         * positioning reference (element or virtual element)
+         */
+        reference: Element | object;
+        /**
+         * positioning strategy chosen from the reference
+         */
+        strategy: "fixed" | "absolute";
+        /**
+         * corner to overlap onto
+         */
+        placement: import("./types.js").Placement;
         cleanup: () => void;
+        /**
+         * whether the target is currently reported hidden (edge tracking for onMarkerHidden)
+         */
+        hidden: boolean;
+        /**
+         * the reference rect read during the current frame's read phase
+         */
+        refRect?: DOMRect | undefined;
+        /**
+         * previous frame's pre-overlap position (element space) — movement detection
+         */
+        lastBaseEl: {
+            left: number;
+            top: number;
+        } | null;
+        /**
+         * last written left (px), to skip redundant DOM writes
+         */
+        lastLeft: number | undefined;
+        /**
+         * last written top (px)
+         */
+        lastTop: number | undefined;
     };
 };

package/dist/types/overlap.d.ts

@@ -1,8 +1,8 @@
 /**
  * Overlap avoidance between markers (pure function).
  *
- * Takes an array of each marker's "base position" (the center coordinate Floating UI
- * decided on) and returns an array of extra offsets that push overlapping ones apart.
+ * Takes an array of each marker's "base position" (the center coordinate the positioning
+ * pass decided on) and returns an array of extra offsets that push overlapping ones apart.
  * Touches no DOM.
  *
  * The algorithm is a simple iterative push-out (a lightweight force-based separation):

package/dist/types/popup.d.ts

@@ -6,12 +6,12 @@
  *   Escape hatch to render the body area with your own DOM node. Return a Node to display it;
  *   if nothing is returned, fall back to safe text rendering (textContent). The title is always record.title.
  *   Note: the return value is appendChild'd as-is without sanitization, so untrusted data must be neutralized by the caller.
- * @param {import('@floating-ui/dom').Placement} [options.popupPlacement] initial placement (default 'bottom-start')
+ * @param {import('./types.js').Placement} [options.popupPlacement] initial placement (default 'bottom-start')
  */
 export function createPopupController(state: object, { onClose, render, popupPlacement }?: {
     onClose?: () => void;
     render?: (record: import("./matcher.js").HelpRecord) => (Node | null | undefined);
-    popupPlacement?: import("@floating-ui/dom").Placement;
+    popupPlacement?: import("./types.js").Placement;
 }): {
     root: HTMLDivElement;
     isOpen(id: any): boolean;

package/dist/types/reference.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Create a "virtual reference element" for free-placement items not bound to an element.
+ * getDocRect() returns document coordinates; this converts them to viewport coordinates for the
+ * current scroll, so the element tracks the page as it scrolls (it's re-read every frame).
+ * @param {() => {top:number,left:number,width?:number,height?:number}} getDocRect
+ */
+export function makeVirtualElement(getDocRect: () => {
+    top: number;
+    left: number;
+    width?: number;
+    height?: number;
+}): {
+    contextElement: HTMLElement;
+    getBoundingClientRect(): {
+        x: number;
+        y: number;
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+        width: number;
+        height: number;
+    };
+};
+/**
+ * Whether the reference lives in a `position: fixed` subtree. Such a reference stays put in the
+ * viewport while the page scrolls, so an absolutely-positioned floating element (which scrolls with
+ * the document) would drift; for these we switch the floating element to a fixed strategy so both
+ * live in the same viewport space and stay glued without per-frame correction.
+ *
+ * Virtual elements (free placements) aren't in the DOM and already track scroll via their getRect, so
+ * they report false. Walks across shadow boundaries via the host so Shadow DOM targets are handled too.
+ * @param {Element|object} reference
+ */
+export function isFixedReference(reference: Element | object): boolean;
+/**
+ * Whether a reference element is currently not rendered (hidden). Free placements use a virtual
+ * element with no host node, so they are never "hidden" (return false).
+ * @param {Element|object} reference
+ */
+export function isReferenceHidden(reference: Element | object): boolean;

package/dist/types/toggle.d.ts

@@ -11,8 +11,8 @@
  * @param {(record: import('./matcher.js').HelpRecord) => (Node|null|undefined)} [options.render] render the popup body with your own Node
  *   (the return value is inserted as-is without sanitization, so untrusted data must be neutralized by the caller)
  * @param {string} [options.markerLabel] character shown on the marker (default '?')
- * @param {import('@floating-ui/dom').Placement} [options.markerPlacement] corner to overlap the marker onto (default 'top-end')
- * @param {import('@floating-ui/dom').Placement} [options.popupPlacement] initial popup placement (default 'bottom-start')
+ * @param {import('./types.js').Placement} [options.markerPlacement] corner to overlap the marker onto (default 'top-end')
+ * @param {import('./types.js').Placement} [options.popupPlacement] initial popup placement (default 'bottom-start')
  * @param {string} [options.nonce] nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
  */
 export function createToggleController(options: {
@@ -26,8 +26,8 @@ export function createToggleController(options: {
     attribute?: string;
     render?: (record: import("./matcher.js").HelpRecord) => (Node | null | undefined);
     markerLabel?: string;
-    markerPlacement?: import("@floating-ui/dom").Placement;
-    popupPlacement?: import("@floating-ui/dom").Placement;
+    markerPlacement?: import("./types.js").Placement;
+    popupPlacement?: import("./types.js").Placement;
     nonce?: string;
 }): {
     enable: () => void;

package/dist/types/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared type definitions (JSDoc only — no runtime code).
+ *
+ * `Placement` mirrors the placement strings Floating UI accepts, defined locally so the library (and
+ * its generated .d.ts) carry no dependency on
+ */
+export type Placement = ("top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end");

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "help-layer",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
     "node": ">=18"
   },
-  "main": "src/index.js",
+  "main": "dist/help-layer.esm.js",
+  "module": "dist/help-layer.esm.js",
   "unpkg": "dist/help-layer.iife.js",
   "types": "dist/types/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "import": "./src/index.js"
+      "import": "./dist/help-layer.esm.js"
     },
     "./dist/*": "./dist/*"
   },
@@ -38,19 +39,18 @@
     "build:types": "tsc -p jsconfig.json --declaration --emitDeclarationOnly --noEmit false --rootDir src --outDir dist/types",
     "build": "npm run build:bundle && npm run build:types",
     "record:gif": "npm run build:demos && node scripts/record-demo.js",
-    "prepublishOnly": "npm run build",
+    "prepack": "npm run build",
     "demo": "npm run build:demos && node scripts/serve.js"
   },
   "devDependencies": {
+    "@floating-ui/dom": "^1.7.6",
     "@playwright/test": "^1.61.0",
     "esbuild": "^0.28.1",
-    "eslint": "^9.39.2",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-n": "^17.24.0",
-    "eslint-plugin-promise": "^7.2.1",
+    "eslint": "^10.5.0",
+    "eslint-plugin-import-x": "^4.17.0",
     "gifenc": "^1.0.3",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
     "pngjs": "^7.0.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
@@ -79,8 +79,5 @@
   "homepage": "https://github.com/Y1-Effy/HelpLayer#readme",
   "bugs": {
     "url": "https://github.com/Y1-Effy/HelpLayer/issues"
-  },
-  "dependencies": {
-    "@floating-ui/dom": "^1.7.6"
   }
 }

package/src/aria-isolation.js

@@ -0,0 +1,67 @@
+/**
+ * Semantic background blocking for assistive technology (AT).
+ *
+ * The clip-path layer / focus containment / key suppression block pointer, physical focus, and
+ * physical keys, but a screen reader's virtual cursor (browse mode) reads and can activate background
+ * content regardless of focus or hit-testing. So while ON we also remove the host from the
+ * accessibility tree with `inert` (which both excludes from the a11y tree and suppresses interaction),
+ * giving AT users the same "host is inactive" guarantee.
+ *
+ * Why operate at document.body's top level: `inert` is inherited and cannot be cancelled on a
+ * descendant of an inert subtree. The toggle is host-owned and may be deeply nested, so—exactly like
+ * the clip-path "hole" that lets the toggle show through—we inert each body child that is neither a
+ * library node nor the branch containing the toggle. The toggle's own top-level branch stays
+ * reachable (a bounded leak when the toggle is nested; none when it's a direct body child).
+ */
+
+const ELEMENT_NODE = 1;
+
+/**
+ * @param {object} state teardown registry
+ * @param {object} params
+ * @param {HTMLElement|null} params.toggleEl the toggle (must stay reachable), or null for programmatic-only
+ * @param {(el: Element) => boolean} params.isLibraryNode whether a body child belongs to the library UI
+ */
+export function isolateBackgroundFromAT(state, { toggleEl, isLibraryNode }) {
+  /** @type {Set<Element>} */
+  const isolated = new Set();
+
+  /** @param {Node} node */
+  function isolate(node) {
+    if (node.nodeType !== ELEMENT_NODE) {
+      return;
+    }
+    const el = /** @type {Element} */ (node);
+    // Skip library UI, the toggle's branch, and anything the host already made inert (so restore
+    // doesn't clobber the host's own inert state).
+    if (
+      isLibraryNode(el) ||
+      (toggleEl && (el === toggleEl || el.contains(toggleEl))) ||
+      el.hasAttribute('inert')
+    ) {
+      return;
+    }
+    el.toggleAttribute('inert', true);
+    isolated.add(el);
+  }
+
+  for (const child of [...document.body.children]) {
+    isolate(child);
+  }
+
+  // The host may add top-level nodes while ON (SPA route changes, portals, ...). Keep them isolated
+  // too. Only direct body children matter here, so childList without subtree is enough.
+  const observer = new MutationObserver((records) => {
+    for (const record of records) {
+      record.addedNodes.forEach(isolate);
+    }
+  });
+  observer.observe(document.body, { childList: true });
+
+  state.track(() => {
+    observer.disconnect();
+    // Remove inert only from the nodes we added it to (leave any host-owned inert untouched).
+    isolated.forEach((el) => el.removeAttribute('inert'));
+    isolated.clear();
+  });
+}

package/src/blocking-layer.js

@@ -8,7 +8,7 @@
  *    rectangle (the hole). Inside the hole the layer isn't painted and hit-testing passes through,
  *    so the toggle can be clicked natively without touching z-index at all. Unlike approaches that
  *    shuffle z-index, this doesn't break depending on ancestor stacking contexts.
- *    The hole is updated via autoUpdate to follow the toggle's scroll/resize.
+ *    The hole is updated via watchReference (a per-frame rAF tracker) to follow the toggle's scroll/resize.
  *
  * 2. Focus containment:
  *    On ON, blur activeElement, and via focusin (capture) detect focus moving to anything other

package/src/dom-builder.js

@@ -4,10 +4,14 @@
  *
  * Accessibility:
  * - Markers are <button> elements so they are focusable and can be activated with Enter/Space.
- * - The popup uses role="dialog" + aria-labelledby (the title element) to describe itself to assistive tech.
+ * - The popup uses role="dialog" + aria-labelledby (the title element) so assistive tech announces it,
+ *   plus aria-describedby (the body element) so the description text is read out, not just the title.
  */
 
-const POPUP_TITLE_ID = 'help-layer-popup-title';
+// Each initHelpLayer instance builds its own popup; a fixed id would collide when the
+// library is initialized more than once on a page (invalid duplicate id + ambiguous
+// aria-labelledby). Hand out a unique id per popup instead.
+let popupSeq = 0;
 
 export function createBlockingLayer() {
   const layer = document.createElement('div');
@@ -33,18 +37,32 @@ export function createMarker(title, label = '?') {
  * Also returns references to titleEl/textEl (used to update the content) and the close button closeEl.
  */
 export function createPopup() {
+  // One sequence value per popup, shared by the title and body ids (then advanced once), so two
+  // instances on a page never collide on either id.
+  const seq = popupSeq++;
+  const titleId = `help-layer-popup-title-${seq}`;
+  const textId = `help-layer-popup-text-${seq}`;
+
   const root = document.createElement('div');
   root.className = 'help-layer-popup';
   root.setAttribute('role', 'dialog');
-  root.setAttribute('aria-labelledby', POPUP_TITLE_ID);
+  // aria-modal tells AT that content outside the dialog is inert while it's shown (the host is also
+  // inert'd at the document level during help mode). Harmless when hidden: display:none drops the
+  // popup from the a11y tree.
+  root.setAttribute('aria-modal', 'true');
+  root.setAttribute('aria-labelledby', titleId);
+  // Point at the body container (not its contents) so the description is announced even after a custom
+  // render swaps the body's children — the container id stays stable.
+  root.setAttribute('aria-describedby', textId);
   root.tabIndex = -1;
 
   const titleEl = document.createElement('div');
   titleEl.className = 'help-layer-popup__title';
-  titleEl.id = POPUP_TITLE_ID;
+  titleEl.id = titleId;
 
   const textEl = document.createElement('div');
   textEl.className = 'help-layer-popup__text';
+  textEl.id = textId;
 
   // Explicit close affordance. Wiring the click is popup.js's job (only element creation here).
   const closeEl = document.createElement('button');