help-layer 1.2.0 → 1.3.0

package/dist/types/floating.d.ts

@@ -1,78 +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;
-/**
- * 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;
-/**
- * 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'
- * @param {() => void} [onHidden] called once each time the target transitions from visible to hidden
- *   (lets the caller close a popup that was open on this now-hidden marker)
- * @returns {() => void} cleanup
- */
-export function anchorMarker(reference: Element | object, markerEl: HTMLElement, onPlaced?: () => void, placement?: import("@floating-ui/dom").Placement, onHidden?: () => void): () => 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,18 +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, 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;
@@ -22,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,6 +1,6 @@
 {
   "name": "help-layer",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -43,15 +43,14 @@
     "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",
@@ -80,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/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,7 +4,8 @@
  *
  * 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.
  */
 
 // Each initHelpLayer instance builds its own popup; a fixed id would collide when the
@@ -36,7 +37,11 @@ export function createMarker(title, label = '?') {
  * Also returns references to titleEl/textEl (used to update the content) and the close button closeEl.
  */
 export function createPopup() {
-  const titleId = `help-layer-popup-title-${popupSeq++}`;
+  // 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';
@@ -46,6 +51,9 @@ export function createPopup() {
   // 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');
@@ -54,6 +62,7 @@ export function createPopup() {
 
   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');

package/src/floating.floatingui.js

@@ -0,0 +1,71 @@
+/**
+ * Alternate positioning backend built on Floating UI (@floating-ui/dom).
+ *
+ * This is the original implementation, kept verbatim so the library can switch back to Floating UI at
+ * any time. To revert:
+ *   1. in floating.js, change the re-export to `export * from './floating.floatingui.js';`
+ *   2. move `@floating-ui/dom` from devDependencies back to dependencies
+ *   3. restore the `@floating-ui/*` entries in the demo import maps (demo/index.html, demo/stress.html)
+ * The default backend is the dependency-free ./floating.self.js. The reference helpers
+ * (isFixedReference / isReferenceHidden / makeVirtualElement) are shared via ./reference.js, so both
+ * backends expose an identical public surface.
+ *
+ * Floating UI in a nutshell:
+ * - computePosition(reference, floating, options) returns the optimal (x,y) for "this moment".
+ * - autoUpdate(reference, floating, update) re-runs update on scroll/resize/element-size changes
+ *   (internally via ResizeObserver, etc.); the returned cleanup stops watching.
+ */
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
+
+import { isFixedReference, isReferenceHidden, makeVirtualElement } from './reference.js';
+
+// Re-export the shared reference helpers so this backend's surface matches floating.self.js exactly.
+export { isFixedReference, isReferenceHidden, makeVirtualElement };
+
+function place(el, x, y) {
+  el.style.left = `${x}px`;
+  el.style.top = `${y}px`;
+}
+
+/**
+ * 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, popupEl, placement = 'bottom-start') {
+  // The reference is the clicked marker. If it's fixed (anchored to a fixed target), the popup must be
+  // fixed too or it jitters on scroll. Set position every open so reopening on a normal marker restores
+  // absolute. Inline !important beats the stylesheet's `position: absolute !important`.
+  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
+  popupEl.style.setProperty('position', strategy, 'important');
+  const update = () => {
+    computePosition(reference, popupEl, {
+      placement,
+      strategy,
+      middleware: [offset(8), flip({ padding: 8 }), shift({ padding: 8 })],
+    }).then(({ x, y }) => {
+      place(popupEl, x, y);
+    // Swallow per-frame rejections so a stray rejection doesn't reach the host's unhandledrejection
+    // handler (e.g. Sentry); this runs every animation frame, so logging would also flood the console.
+    }).catch(() => {});
+  };
+  // animationFrame: true so the popup tracks smoothly: its reference is the marker element, which the
+  // markers.js loop moves per frame, so the popup must re-evaluate per frame to stay glued.
+  const cleanup = autoUpdate(reference, popupEl, update, { animationFrame: true });
+  return { update, cleanup };
+}
+
+/**
+ * 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, floatingEl, onUpdate) {
+  return autoUpdate(referenceEl, floatingEl, onUpdate);
+}