help-layer 1.1.0 → 1.3.0

package/src/markers.js

@@ -1,21 +1,33 @@
 /**
  * Marker manager.
  * Markers can be dynamically mounted/unmounted per help record (SPA dynamic-element support).
- * Each marker keeps following its target (an element, or the virtual element of a free placement)
- * via Floating UI's autoUpdate. On every finalized placement it triggers the overlap-avoidance pass,
- * debounced with rAF.
+ *
+ * Positioning runs in ONE shared requestAnimationFrame loop owned by the manager (not one Floating UI
+ * autoUpdate per marker). Each frame the loop:
+ *   1. reads every visible marker's reference rect (and the shared offsetParent geometry) once,
+ *   2. computes each marker's corner-overlap position synchronously (markers only need an offset,
+ *      never flip/shift — those are popup-only), runs overlap avoidance on the centers, and
+ *   3. writes left/top in a single batched pass.
+ * Folding tracking + overlap into one read-then-write loop avoids the layout thrashing and the
+ * doubled rect reads of running N independent animation-frame loops, which is what made large marker
+ * counts expensive. Smoothness is unchanged: writes still happen every frame before paint.
  *
  * Marker identifier (id):
  * - element-bound: the target element itself (distinguishes multiple elements with the same data-help-id)
  * - free placement: the config key string
  */
 import { createMarker } from './dom-builder.js';
-import { anchorMarker, makeVirtualElement } from './floating.js';
+import { isFixedReference, isReferenceHidden, makeVirtualElement } from './floating.js';
+import { markerViewportTopLeft, viewportToAbsolute } from './geometry.js';
 import { resolveOverlaps } from './overlap.js';
 
 // Temporary class added to the target element only while the marker is hovered/focused (matches the style.js definition).
 const TARGET_HIGHLIGHT_CLASS = 'help-layer-target-highlight';
 
+// Fallback marker size if the real size can't be measured yet (matches the CSS default). Used only
+// until a laid-out marker reports a non-zero offsetWidth, which is then cached.
+const DEFAULT_MARKER_SIZE = 24;
+
 /** @param {import('./matcher.js').HelpRecord} record */
 function referenceFor(record) {
   if (record.kind === 'free') {
@@ -33,64 +45,155 @@ function referenceFor(record) {
  * @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, {
   onMarkerClick,
   onOverlapResolved,
+  onMarkerHidden,
   markerLabel = '?',
   markerPlacement = 'top-end',
 }) {
-  /** @type {Map<Element|string, {record:import('./matcher.js').HelpRecord, el:HTMLElement, cleanup:() => void}>} */
+  /**
+   * @typedef {object} MarkerEntry
+   * @property {import('./matcher.js').HelpRecord} record
+   * @property {HTMLElement} el
+   * @property {Element|object} reference positioning reference (element or virtual element)
+   * @property {'fixed'|'absolute'} strategy positioning strategy chosen from the reference
+   * @property {import('./types.js').Placement} placement corner to overlap onto
+   * @property {() => void} cleanup
+   * @property {boolean} hidden whether the target is currently reported hidden (edge tracking for onMarkerHidden)
+   * @property {DOMRect=} refRect the reference rect read during the current frame's read phase
+   * @property {{left:number,top:number}|null} lastBaseEl previous frame's pre-overlap position (element space) — movement detection
+   * @property {number|undefined} lastLeft last written left (px), to skip redundant DOM writes
+   * @property {number|undefined} lastTop last written top (px)
+   */
+  /** @type {Map<Element|string, MarkerEntry>} */
   const markers = new Map();
   let rafId = null;
   // Don't schedule a new rAF during teardown (prevents a frame lingering after teardown).
   let tornDown = false;
+  // Cached marker size (square). Measured once from a laid-out marker; 0 until then.
+  let markerSize = 0;
+  // Visible-marker count from the previous frame, to detect membership changes (a marker entering or
+  // leaving the visible set means overlap must be recomputed even if no surviving marker's base moved).
+  let prevVisibleCount = -1;
 
-  function runOverlapPass() {
-    rafId = null;
-    const entries = [...markers.values()];
-    // With one marker or fewer, overlap is impossible. Skip getBoundingClientRect (forced reflow)
-    // and the O(n^2) push-out math entirely (avoids a per-frame reflow while scrolling on screens
-    // with few targets). However, right after dropping from 2 to 1, if the remaining one still has
-    // a leftover push-out transform, clear it and let an open popup follow that move (in steady
-    // state, with an empty transform, do nothing).
-    if (entries.length <= 1) {
-      const el = entries.length === 1 ? entries[0].el : null;
-      if (el && el.style.transform) {
-        el.style.transform = '';
-        if (onOverlapResolved) {
-          onOverlapResolved();
+  // One positioning pass: read references + offsetParent once, compute corner placements + overlap,
+  // then write left/top in a batch. Pure of scheduling so it can run either synchronously (initial
+  // placement, to avoid a one-frame flash at 0,0) or from the continuous rAF loop (tracking).
+  function positionAll() {
+    if (tornDown || markers.size === 0) {
+      return;
+    }
+
+    // --- Read phase: visibility edges + reference rects, plus the shared offsetParent geometry. ---
+    const bodyRect = document.body.getBoundingClientRect();
+    const bodyClientLeft = document.body.clientLeft;
+    const bodyClientTop = document.body.clientTop;
+
+    /** @type {MarkerEntry[]} */
+    const visible = [];
+    for (const entry of markers.values()) {
+      if (isReferenceHidden(entry.reference)) {
+        // Target went hidden (e.g. display:none). Hide the marker too instead of leaving it stranded
+        // (a display:none target measures 0x0, which would otherwise fling the marker to 0,0). Inline
+        // !important beats the stylesheet's `display:block !important`. Fire onMarkerHidden only on the
+        // visible -> hidden edge (e.g. to close a popup open on this marker).
+        if (!entry.hidden) {
+          entry.hidden = true;
+          entry.lastBaseEl = null; // force a fresh placement when it reshows
+          entry.el.style.setProperty('display', 'none', 'important');
+          if (onMarkerHidden) {
+            onMarkerHidden(entry.record);
+          }
         }
+        continue;
       }
-      return;
+      if (entry.hidden) {
+        entry.hidden = false;
+        entry.el.style.removeProperty('display'); // back to the stylesheet's display:block
+      }
+      entry.refRect = entry.reference.getBoundingClientRect();
+      visible.push(entry);
     }
 
-    // Clear the accumulated transform to measure base centers, then reapply after resolving overlaps.
-    entries.forEach((e) => { e.el.style.transform = ''; });
-    const centers = entries.map((e) => {
-      const r = e.el.getBoundingClientRect();
-      return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
-    });
-    const offsets = resolveOverlaps(centers);
-    entries.forEach((e, i) => {
-      const { dx, dy } = offsets[i];
-      e.el.style.transform = (dx || dy) ? `translate(${dx}px, ${dy}px)` : '';
-    });
+    // Cache the marker size once a real measurement is available (custom --help-layer-marker-size honored).
+    if (!markerSize && visible.length) {
+      const measured = visible[0].el.offsetWidth;
+      if (measured > 0) {
+        markerSize = measured;
+      }
+    }
+    const size = markerSize || DEFAULT_MARKER_SIZE;
 
-    // Marker positions moved, so give an open popup etc. the chance to follow.
-    if (onOverlapResolved) {
-      onOverlapResolved();
+    // --- Compute phase (no DOM): base positions, movement/membership detection, overlap offsets. ---
+    let dirty = visible.length !== prevVisibleCount;
+    prevVisibleCount = visible.length;
+    /** @type {{left:number,top:number}[]} */
+    const bases = [];
+    /** @type {{x:number,y:number}[]} */
+    const centers = [];
+    for (const entry of visible) {
+      const bv = markerViewportTopLeft(entry.refRect, size, entry.placement);
+      centers.push({ x: bv.left + size / 2, y: bv.top + size / 2 });
+      // Convert the viewport position to what we actually write. For absolute markers this is
+      // scroll-invariant (refRect and bodyRect both shift with scroll), so plain page scroll produces
+      // no write — the marker rides the document for free. A write happens only when the target really
+      // moves relative to the document (layout, resize, animation).
+      const be = entry.strategy === 'fixed'
+        ? { left: bv.left, top: bv.top }
+        : viewportToAbsolute(bv.left, bv.top, bodyRect, bodyClientLeft, bodyClientTop);
+      bases.push(be);
+      if (!entry.lastBaseEl || entry.lastBaseEl.left !== be.left || entry.lastBaseEl.top !== be.top) {
+        dirty = true;
+      }
+      entry.lastBaseEl = be;
+    }
+
+    // --- Write phase: only when something changed, and only the markers whose position differs. ---
+    if (dirty && visible.length) {
+      const offsets = resolveOverlaps(centers);
+      let moved = false;
+      for (let i = 0; i < visible.length; i++) {
+        const entry = visible[i];
+        const left = bases[i].left + offsets[i].dx;
+        const top = bases[i].top + offsets[i].dy;
+        if (entry.lastLeft !== left || entry.lastTop !== top) {
+          entry.el.style.left = `${left}px`;
+          entry.el.style.top = `${top}px`;
+          entry.lastLeft = left;
+          entry.lastTop = top;
+          moved = true;
+        }
+      }
+      // Marker positions moved, so give an open popup etc. the chance to follow.
+      if (moved && onOverlapResolved) {
+        onOverlapResolved();
+      }
     }
   }
 
-  function scheduleOverlapPass() {
-    if (rafId !== null || tornDown) {
+  // Continuous tracking: position every frame, then re-schedule. Stops re-scheduling once there are no
+  // markers left (or after teardown); ensureLoop() restarts it on the next mount.
+  function frameTick() {
+    rafId = null;
+    if (tornDown || markers.size === 0) {
       return;
     }
-    rafId = requestAnimationFrame(runOverlapPass);
+    positionAll();
+    rafId = requestAnimationFrame(frameTick);
+  }
+
+  function ensureLoop() {
+    if (rafId !== null || tornDown || markers.size === 0) {
+      return;
+    }
+    rafId = requestAnimationFrame(frameTick);
   }
 
   /** @param {import('./matcher.js').HelpRecord} record */
@@ -105,7 +208,14 @@ export function createMarkerManager(state, {
     const handleClick = () => onMarkerClick(record, el);
     el.addEventListener('click', handleClick);
 
-    const cleanupAnchor = anchorMarker(referenceFor(record), el, scheduleOverlapPass, markerPlacement);
+    const reference = referenceFor(record);
+    // Match the strategy to the reference: a fixed reference needs a fixed marker, or it scrolls with
+    // the document while the fixed target stays put and visibly drifts (see isFixedReference). Inline
+    // !important beats the stylesheet's `position: absolute !important`.
+    const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
+    if (strategy === 'fixed') {
+      el.style.setProperty('position', 'fixed', 'important');
+    }
 
     // Target-element highlight (element-bound only; free placement has no target, so skip).
     // Show an outline on the target only while the marker is hovered/focused, to make clear "which element this explains".
@@ -125,7 +235,6 @@ export function createMarkerManager(state, {
         return;
       }
       done = true;
-      cleanupAnchor();
       el.removeEventListener('click', handleClick);
       if (target) {
         el.removeEventListener('mouseenter', addHighlight);
@@ -136,10 +245,22 @@ export function createMarkerManager(state, {
       }
       el.remove();
       markers.delete(record.id);
-      scheduleOverlapPass();
+      ensureLoop(); // keep the loop alive so the next frame re-packs the remaining markers
     };
 
-    markers.set(record.id, { record, el, cleanup });
+    markers.set(record.id, {
+      record,
+      el,
+      reference,
+      strategy,
+      placement: markerPlacement,
+      cleanup,
+      hidden: false,
+      lastBaseEl: null,
+      lastLeft: undefined,
+      lastTop: undefined,
+    });
+    ensureLoop();
   }
 
   function unmount(id) {
@@ -151,6 +272,10 @@ export function createMarkerManager(state, {
 
   function mountAll(records) {
     records.forEach(mount);
+    // Place the whole batch synchronously (before paint) so markers don't flash at (0,0) for a frame
+    // on enable; the rAF loop started by mount() then takes over tracking. Done once per batch (not
+    // per mount) to keep this O(n), not O(n^2).
+    positionAll();
   }
 
   // Register a single teardown for the whole manager with state

package/src/overlap.js

@@ -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/src/popup.js

@@ -1,7 +1,7 @@
 /**
  * The single popup shared across the whole library.
- * Placed on its target (the clicked marker) with Floating UI; at screen edges, flip/shift avoid
- * clipping. While visible it follows via autoUpdate.
+ * Placed on its target (the clicked marker) via the positioning seam (anchorPopup in floating.js);
+ * at screen edges, flip/shift avoid clipping. While visible it follows the marker per animation frame.
  *
  * Accessibility:
  * - On open, move focus to the popup (role=dialog).
@@ -19,7 +19,7 @@ import { safeInvoke } from './safe.js';
  *   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, { onClose, render, popupPlacement = 'bottom-start' } = {}) {
   const { root, titleEl, textEl, closeEl } = createPopup();
@@ -42,6 +42,34 @@ export function createPopupController(state, { onClose, render, popupPlacement =
     }
   }
 
+  // Focus trap. aria-modal="true" promises AT that the rest of the page is inert, but keyboard Tab
+  // would still escape to the markers/toggle behind the popup (they're "library elements", so the
+  // blocking layer lets their keys through). Keep Tab cycling inside the dialog to match the promise.
+  const FOCUSABLE = 'a[href],button,input,select,textarea,[tabindex]:not([tabindex="-1"])';
+  function trapTab(event) {
+    if (event.key !== 'Tab') {
+      return;
+    }
+    // Recompute every keypress: a custom render() can add its own focusables to the body. We don't
+    // filter by layout visibility here — the popup's contents are controlled (a close button plus
+    // whatever render returns), and a layout probe (offsetParent/getClientRects) is unreliable anyway.
+    const focusable = [...root.querySelectorAll(FOCUSABLE)].filter((el) => el instanceof HTMLElement);
+    event.preventDefault();
+    if (focusable.length === 0) {
+      // Nothing focusable inside: hold focus on the dialog itself rather than letting it escape.
+      root.focus({ preventScroll: true });
+      return;
+    }
+    const count = focusable.length;
+    const index = focusable.indexOf(document.activeElement instanceof HTMLElement ? document.activeElement : null);
+    // Step in the requested direction, wrapping at both ends. When focus is on the dialog root
+    // (index -1), Tab starts at the first element and Shift+Tab at the last.
+    const next = index === -1
+      ? (event.shiftKey ? focusable[count - 1] : focusable[0])
+      : focusable[(index + (event.shiftKey ? -1 : 1) + count) % count];
+    next.focus({ preventScroll: true });
+  }
+
   /**
    * @param {import('./matcher.js').HelpRecord} record
    * @param {HTMLElement} referenceEl placement reference (the clicked marker element)
@@ -64,14 +92,18 @@ export function createPopupController(state, { onClose, render, popupPlacement =
     stopAnchor();
     anchor = anchorPopup(referenceEl, root, popupPlacement);
 
-    // preventScroll: the popup is positioned asynchronously (computePosition().then), so at this
-    // point it's still at its stale position; a default focus would scroll toward that, causing a
-    // visible jump. flip/shift keep it in the viewport, so suppressing the scroll is safe.
+    // Keep Tab inside the dialog while it's open (removed in hide()). Capture phase so it runs before
+    // any focusable's own keydown can act on the Tab.
+    root.addEventListener('keydown', trapTab, true);
+
+    // preventScroll: anchorPopup positions the popup synchronously above, so it's already in place,
+    // but focusing it can still nudge an ancestor scroll container toward it; flip/shift keep it in
+    // the viewport, so suppressing that scroll is safe and avoids a visible jump.
     root.focus({ preventScroll: true });
   }
 
   // Reposition immediately, only when open.
-  // (Called e.g. right after a marker shifts due to the overlap-avoidance transform.)
+  // (Called e.g. right after a marker's left/top shifts from the overlap-avoidance pass.)
   function reposition() {
     if (anchor) {
       anchor.update();
@@ -82,6 +114,7 @@ export function createPopupController(state, { onClose, render, popupPlacement =
     // Call onClose only if it was open (catches both the close-path and teardown-path close routes at one point).
     const wasOpen = openId !== null;
     stopAnchor();
+    root.removeEventListener('keydown', trapTab, true);
     openId = null;
     triggerEl = null;
     root.style.setProperty('display', 'none', 'important');

package/src/reference.js

@@ -0,0 +1,74 @@
+/**
+ * Backend-agnostic helpers about a positioning "reference" (the element a marker/popup points at,
+ * or a virtual element for free placements). These touch only the DOM — no positioning library — so
+ * both the self-implemented and the Floating UI positioning backends share them unchanged.
+ */
+import { docRectToViewportRect } from './geometry.js';
+
+/**
+ * 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) {
+  return {
+    // Kept for parity with the Floating UI backend (its autoUpdate uses contextElement to know which
+    // scroll ancestors to watch). Harmless for the self backend, which reads the rect directly.
+    contextElement: document.body,
+    getBoundingClientRect() {
+      return docRectToViewportRect(getDocRect(), { x: window.scrollX, y: window.scrollY });
+    },
+  };
+}
+
+/**
+ * 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) {
+  if (!(reference instanceof Element)) {
+    return false;
+  }
+  let node = reference;
+  while (node) {
+    if (getComputedStyle(node).position === 'fixed') {
+      return true;
+    }
+    const parent = node.parentElement;
+    if (parent) {
+      node = parent;
+    } else {
+      const root = node.getRootNode();
+      node = root instanceof ShadowRoot ? root.host : null;
+    }
+  }
+  return false;
+}
+
+/**
+ * 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) {
+  if (!(reference instanceof Element)) {
+    return false;
+  }
+  // checkVisibility() catches display:none (incl. an ancestor), content-visibility, and—with the
+  // option—visibility:hidden, in one cheap call without any extra observers. NOTE: do NOT use
+  // offsetParent here; it is null for position:fixed elements too (which this lib supports as
+  // targets) and would wrongly hide their markers. Engines without checkVisibility fall back to the
+  // rect: a display:none element measures 0x0 (the worst case — the marker would jump to 0,0).
+  if (typeof reference.checkVisibility === 'function') {
+    return !reference.checkVisibility({ visibilityProperty: true, contentVisibilityAuto: true });
+  }
+  const r = reference.getBoundingClientRect();
+  return r.width === 0 && r.height === 0;
+}

package/src/style.js

@@ -13,7 +13,7 @@ const STYLE_ATTR = 'data-help-layer-style';
 
 // The theme is fully exposed via CSS custom properties. Users can change the look just by
 // overriding the following variables in host-side CSS (e.g. :root or any scope):
-//   --help-layer-marker-size       marker diameter (default 22px)
+//   --help-layer-marker-size       marker diameter (default 24px, WCAG 2.5.8 minimum target size)
 //   --help-layer-marker-bg         marker background color (default #2563eb)
 //   --help-layer-marker-color      marker text color (default #fff)
 //   --help-layer-popup-bg          popup background color (default #fff)
@@ -58,15 +58,15 @@ const CSS = `
   pointer-events: auto !important;
   top: 0;
   left: 0;
-  width: var(--help-layer-marker-size, 22px) !important;
-  height: var(--help-layer-marker-size, 22px) !important;
+  width: var(--help-layer-marker-size, 24px) !important;
+  height: var(--help-layer-marker-size, 24px) !important;
   border-radius: 50%;
   background: var(--help-layer-marker-bg, #2563eb);
   color: var(--help-layer-marker-color, #fff);
   font-family: sans-serif;
   font-size: 13px;
   font-weight: bold;
-  line-height: var(--help-layer-marker-size, 22px);
+  line-height: var(--help-layer-marker-size, 24px);
   text-align: center;
   cursor: pointer;
   user-select: none;
@@ -136,8 +136,8 @@ const CSS = `
   pointer-events: auto !important;
   top: 6px;
   right: 6px;
-  width: 22px;
-  height: 22px;
+  width: 24px;
+  height: 24px;
   padding: 0;
   border: none;
   border-radius: 4px;

package/src/toggle.js

@@ -3,6 +3,7 @@
  * Starts each subsystem (style injection, marker manager, popup, blocking layer, DOM observation)
  * and aggregates their teardown into the cleanup registry (state).
  */
+import { isolateBackgroundFromAT } from './aria-isolation.js';
 import { activateBlockingLayer } from './blocking-layer.js';
 import { isPlainObject, normalizeConfig, validateConfig } from './config.js';
 import { createMarkerManager } from './markers.js';
@@ -48,8 +49,8 @@ function resolveToggleElement(toggle) {
  * @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) {
@@ -120,6 +121,14 @@ export function createToggleController(options) {
       },
       // When overlap avoidance moves a marker, make the open popup follow.
       onOverlapResolved: () => popup.reposition(),
+      // If a target is hidden (e.g. display:none) while its popup is open, close it (its marker just
+      // collapsed to 0x0) — same as the SPA-removal path. Return focus to the toggle since the marker
+      // is no longer focusable.
+      onMarkerHidden: (record) => {
+        if (popup.isOpen(record.id)) {
+          popup.close(toggleEl ?? undefined);
+        }
+      },
     });
 
     // Initial mount (free placements + elements currently in the DOM, including Shadow DOM)
@@ -151,7 +160,7 @@ export function createToggleController(options) {
         popup.root.contains(target) ||
         (typeof target.closest === 'function' && !!target.closest('.help-layer-marker')));
 
-    activateBlockingLayer(state, {
+    const layer = activateBlockingLayer(state, {
       toggleEl,
       onBackgroundClick: () => popup.close(),
       isLibraryElement,
@@ -163,6 +172,15 @@ export function createToggleController(options) {
         }
       },
     });
+
+    // Semantic blocking for assistive tech: remove the host from the a11y tree while ON (the layer/
+    // popup/markers and the toggle stay reachable). Runs last so the just-mounted library nodes are
+    // present and skipped by the initial scan.
+    const isLibraryNode = (el) =>
+      el === layer ||
+      el === popup.root ||
+      (!!el.classList && el.classList.contains('help-layer-marker'));
+    isolateBackgroundFromAT(state, { toggleEl, isLibraryNode });
   }
 
   function turnOff() {

package/src/types.js

@@ -0,0 +1,17 @@
+/**
+ * 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 @floating-ui/dom. A placement is a side, optionally
+ * suffixed with an alignment: `top` / `top-start` / `top-end` / ... for the four sides.
+ *
+ * @typedef {(
+ *   'top' | 'top-start' | 'top-end' |
+ *   'right' | 'right-start' | 'right-end' |
+ *   'bottom' | 'bottom-start' | 'bottom-end' |
+ *   'left' | 'left-start' | 'left-end'
+ * )} Placement
+ */
+
+// No runtime exports; this module exists solely to host the typedefs above.
+export {};