help-layer 1.0.0 → 1.1.0

package/dist/types/config.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Validation and normalization of the helpConfig object. A pure function that does no DOM work.
+ */
+/**
+ * @typedef {object} HelpEntry
+ * @property {string} title heading shown on the marker / popup (non-empty)
+ * @property {string} text description body (non-empty)
+ * @property {{ top: number, left: number }} [position] if given, becomes a free placement not tied to an element
+ */
+/**
+ * The helpConfig itself. For element-bound entries the key is the `data-help-id` value;
+ * for free placement it is any identifier.
+ * @typedef {Object<string, HelpEntry>} HelpConfig
+ */
+export function isPlainObject(value: any): boolean;
 /**
  * Validate the shape of helpConfig. Throws an Error on any problem (fail fast).
  */

package/dist/types/floating.d.ts

@@ -23,6 +23,18 @@ export function makeVirtualElement(getDocRect: () => {
         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

package/dist/types/safe.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Isolation for user-supplied callbacks (render / onOpen / onClose / onEnable / onDisable).
+ *
+ * These run inside the library's own control flow (event handlers, teardown), so a throw from a
+ * caller's mistake must not derail us: it could leave a popup half-open or abort a teardown midway,
+ * stranding markers, observers and injected styles. We swallow the error and log it instead, so the
+ * developer still sees their bug while the library keeps its internal state consistent.
+ */
+/**
+ * Invoke a user callback, never letting it throw into library code.
+ * @template T
+ * @param {string} label name used in the error log (e.g. 'onClose')
+ * @param {((...args: any[]) => T)|undefined|null} fn the callback, or nullish to skip
+ * @param {...any} args arguments forwarded to fn
+ * @returns {T|undefined} fn's return value, or undefined when absent or it threw
+ */
+export function safeInvoke<T>(label: string, fn: ((...args: any[]) => T) | undefined | null, ...args: any[]): T | undefined;

package/dist/types/toggle.d.ts

@@ -1,21 +1,21 @@
 /**
- * @param {object} params
- * @param {object} params.config helpConfig
- * @param {string|HTMLElement} [params.toggle] DOM element that switches ON/OFF (if omitted, programmatic control only)
- * @param {() => void} [params.onEnable] called right after the mode is turned ON
- * @param {() => void} [params.onDisable] called right after the mode is turned OFF
- * @param {(record: import('./matcher.js').HelpRecord) => void} [params.onOpen] called when a popup is opened
- * @param {() => void} [params.onClose] called when a popup is closed
- * @param {boolean} [params.silent] suppress the warning log for unregistered keys
- * @param {string} [params.attribute] attribute name marking targets (default 'data-help-id')
- * @param {(record: import('./matcher.js').HelpRecord) => (Node|null|undefined)} [params.render] render the popup body with your own Node
+ * @param {object} options
+ * @param {object} options.config helpConfig
+ * @param {string|HTMLElement} [options.toggle] DOM element that switches ON/OFF (if omitted, programmatic control only)
+ * @param {() => void} [options.onEnable] called right after the mode is turned ON
+ * @param {() => void} [options.onDisable] called right after the mode is turned OFF
+ * @param {(record: import('./matcher.js').HelpRecord) => void} [options.onOpen] called when a popup is opened
+ * @param {() => void} [options.onClose] called when a popup is closed
+ * @param {boolean} [options.silent] suppress the warning log for unregistered keys
+ * @param {string} [options.attribute] attribute name marking targets (default 'data-help-id')
+ * @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} [params.markerLabel] character shown on the marker (default '?')
- * @param {import('@floating-ui/dom').Placement} [params.markerPlacement] corner to overlap the marker onto (default 'top-end')
- * @param {import('@floating-ui/dom').Placement} [params.popupPlacement] initial popup placement (default 'bottom-start')
- * @param {string} [params.nonce] nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
+ * @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 {string} [options.nonce] nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
  */
-export function createToggleController({ config, toggle, onEnable, onDisable, onOpen, onClose, silent, attribute, render, markerLabel, markerPlacement, popupPlacement, nonce, }: {
+export function createToggleController(options: {
     config: object;
     toggle?: string | HTMLElement;
     onEnable?: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "help-layer",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -32,11 +32,14 @@
     "lint:fix": "eslint src tests --fix",
     "typecheck": "tsc -p jsconfig.json",
     "check": "npm run lint && npm run typecheck && npm test",
+    "build:site": "node demo/build-site.js",
+    "build:demos": "node demo/build-framework-demos.js",
     "build:bundle": "node scripts/build.js",
     "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",
-    "demo": "node scripts/serve.js"
+    "demo": "npm run build:demos && node scripts/serve.js"
   },
   "devDependencies": {
     "@playwright/test": "^1.61.0",
@@ -45,8 +48,10 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^17.24.0",
     "eslint-plugin-promise": "^7.2.1",
+    "gifenc": "^1.0.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "pngjs": "^7.0.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "typescript": "^6.0.3",
@@ -64,7 +69,7 @@
     "shadow-dom",
     "framework-agnostic"
   ],
-  "author": "Y1-Effy <ssoruto@yahoo.co.jp>",
+  "author": "Y1-Effy",
   "license": "ISC",
   "description": "Framework-agnostic, drop-in help mode for existing web apps — toggleable help markers with description popups, Shadow DOM piercing, and full cleanup.",
   "repository": {

package/src/config.js

@@ -15,15 +15,17 @@
  * @typedef {Object<string, HelpEntry>} HelpConfig
  */
 
-function isPlainObject(value) {
+export function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 function isValidPosition(position) {
+  // Number.isFinite rejects NaN / Infinity / non-numbers, so a computed coordinate that became NaN
+  // fails validation here instead of silently pinning the marker to 0,0 at render time.
   return (
     isPlainObject(position) &&
-    typeof position.top === 'number' &&
-    typeof position.left === 'number'
+    Number.isFinite(position.top) &&
+    Number.isFinite(position.left)
   );
 }
 
@@ -46,7 +48,7 @@ export function validateConfig(config) {
       throw new Error(`helpConfig["${key}"].text must be a non-empty string`);
     }
     if (entry.position !== undefined && !isValidPosition(entry.position)) {
-      throw new Error(`helpConfig["${key}"].position must be { top: number, left: number }`);
+      throw new Error(`helpConfig["${key}"].position must be { top: finite number, left: finite number }`);
     }
   }
 }

package/src/floating.js

@@ -40,6 +40,37 @@ function place(el, x, y) {
   el.style.top = `${y}px`;
 }
 
+/**
+ * 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) {
+  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;
+}
+
 // Half of the default marker size (22px). The amount used to overlap the marker onto the
 // target's corner with an "inset". (If the marker-size CSS variable is changed, the resulting
 // drift is left as existing behavior = not compensated for here.)
@@ -66,16 +97,26 @@ function markerOffset(placement) {
  * @returns {() => void} cleanup
  */
 export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end') {
+  // Match the floating element's strategy to the reference: a fixed reference needs a fixed marker, or
+  // it jitters while scrolling (see isFixedReference). Inline !important beats the stylesheet's
+  // `position: absolute !important`.
+  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
+  if (strategy === 'fixed') {
+    markerEl.style.setProperty('position', 'fixed', 'important');
+  }
   const update = () => {
     computePosition(reference, markerEl, {
       placement,
+      strategy,
       middleware: [offset(markerOffset(placement))],
     }).then(({ x, y }) => {
       place(markerEl, x, y);
       if (onPlaced) {
         onPlaced();
       }
-    });
+    // Swallow silently: this runs every animation frame, so logging would flood the console, and a
+    // stray rejection must not surface in the host app's unhandledrejection handler (e.g. Sentry).
+    }).catch(() => {});
   };
   // animationFrame: true syncs repositioning to the rAF loop. With the default (scroll/resize
   // events only), computePosition resolves asynchronously, so left/top is written the frame after
@@ -93,13 +134,20 @@ export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end
  *   calling update repositions immediately (used for reference-side transform moves that autoUpdate doesn't pick up, etc.).
  */
 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);
-    });
+    // Same rationale as anchorMarker: swallow per-frame rejections so they don't reach the host.
+    }).catch(() => {});
   };
   // animationFrame: true for the same smooth-tracking reason as anchorMarker. The reference here is
   // the marker element, which itself moves per frame, so the popup must track per frame to stay glued.

package/src/observer.js

@@ -9,6 +9,8 @@
  * elements and mounts/unmounts markers dynamically.
  */
 
+import { safeInvoke } from './safe.js';
+
 const ELEMENT_NODE = 1;
 
 /**
@@ -115,11 +117,13 @@ export function createMutationWatcher({ root = document, selector, onAdded, onRe
       // For added nodes, get both "matching elements" and "shadowRoots to start observing" in one traversal per subtree.
       record.addedNodes.forEach((node) => {
         const { matches, shadowRoots } = scanSubtree(node, selector);
-        matches.forEach((el) => onAdded(el));
+        // Isolate each callback: a throw on one element must not abort the rest of the batch nor
+        // kill ongoing observation (which would silently stop all later SPA tracking).
+        matches.forEach((el) => safeInvoke('observer onAdded', onAdded, el));
         shadowRoots.forEach(observe);
       });
       record.removedNodes.forEach((node) => {
-        scanSubtree(node, selector).matches.forEach((el) => onRemoved(el));
+        scanSubtree(node, selector).matches.forEach((el) => safeInvoke('observer onRemoved', onRemoved, el));
       });
     }
   };

package/src/popup.js

@@ -9,6 +9,7 @@
  */
 import { createPopup } from './dom-builder.js';
 import { anchorPopup } from './floating.js';
+import { safeInvoke } from './safe.js';
 
 /**
  * @param {object} state teardown registry
@@ -22,6 +23,9 @@ import { anchorPopup } from './floating.js';
  */
 export function createPopupController(state, { onClose, render, popupPlacement = 'bottom-start' } = {}) {
   const { root, titleEl, textEl, closeEl } = createPopup();
+  // Drive the open/close state with an inline !important display so it beats both this library's own
+  // stylesheet and any host rule (e.g. div { display:none !important }). Start hidden.
+  root.style.setProperty('display', 'none', 'important');
   document.body.appendChild(root);
 
   // The close (×) button. root is removed on teardown, so explicitly detaching the listener isn't needed.
@@ -45,14 +49,15 @@ export function createPopupController(state, { onClose, render, popupPlacement =
   function open(record, referenceEl) {
     titleEl.textContent = record.title;
     // If render exists, replace the body with a custom Node; otherwise fall back to safe text rendering.
-    const custom = render ? render(record) : null;
+    // A throwing render yields undefined here, so we degrade to the safe textContent path below.
+    const custom = safeInvoke('render', render, record);
     textEl.textContent = '';
     if (custom) {
       textEl.appendChild(custom);
     } else {
       textEl.textContent = record.text;
     }
-    root.style.display = 'block';
+    root.style.setProperty('display', 'block', 'important');
     openId = record.id;
     triggerEl = referenceEl;
 
@@ -79,9 +84,9 @@ export function createPopupController(state, { onClose, render, popupPlacement =
     stopAnchor();
     openId = null;
     triggerEl = null;
-    root.style.display = 'none';
-    if (wasOpen && onClose) {
-      onClose();
+    root.style.setProperty('display', 'none', 'important');
+    if (wasOpen) {
+      safeInvoke('onClose', onClose);
     }
   }
 

package/src/safe.js

@@ -0,0 +1,29 @@
+/**
+ * Isolation for user-supplied callbacks (render / onOpen / onClose / onEnable / onDisable).
+ *
+ * These run inside the library's own control flow (event handlers, teardown), so a throw from a
+ * caller's mistake must not derail us: it could leave a popup half-open or abort a teardown midway,
+ * stranding markers, observers and injected styles. We swallow the error and log it instead, so the
+ * developer still sees their bug while the library keeps its internal state consistent.
+ */
+
+/**
+ * Invoke a user callback, never letting it throw into library code.
+ * @template T
+ * @param {string} label name used in the error log (e.g. 'onClose')
+ * @param {((...args: any[]) => T)|undefined|null} fn the callback, or nullish to skip
+ * @param {...any} args arguments forwarded to fn
+ * @returns {T|undefined} fn's return value, or undefined when absent or it threw
+ */
+export function safeInvoke(label, fn, ...args) {
+  if (!fn) {
+    return undefined;
+  }
+  try {
+    return fn(...args);
+  } catch (err) {
+    // Always logged regardless of `silent` (that flag only gates unregistered-key warnings).
+    console.error(`[help-layer] ${label} threw:`, err);
+    return undefined;
+  }
+}

package/src/state.js

@@ -14,7 +14,13 @@ export function createState() {
     teardownAll() {
       while (cleanupFns.length > 0) {
         const cleanup = cleanupFns.pop();
-        cleanup();
+        // A throwing cleanup (e.g. a user onClose run during teardown) must not abort the rest of
+        // the unwind, otherwise later-registered subsystems (markers, observer, styles) would leak.
+        try {
+          cleanup();
+        } catch (err) {
+          console.error('[help-layer] teardown step threw:', err);
+        }
       }
     },
   };

package/src/style.js

@@ -25,15 +25,18 @@ const STYLE_ATTR = 'data-help-layer-style';
 //   --help-layer-overlay-cursor    cursor over the blocked area (default default; e.g. not-allowed / help)
 const CSS = `
 .help-layer-blocking-layer {
-  position: fixed;
-  inset: 0;
+  /* Structural properties !important so a host can't accidentally un-fix or restack the layer and
+     defeat the blocking guarantee. */
+  position: fixed !important;
+  inset: 0 !important;
+  pointer-events: auto !important;
   /* Default transparent (unchanged). Set --help-layer-overlay-bg to tint it into a scrim that signals
      "the host app is inactive". The clip-path hole isn't painted, so the toggle stays untinted. */
   background: var(--help-layer-overlay-bg, transparent);
   /* Cursor over the blocked area only (the toggle shows through the hole and keeps its own cursor).
      e.g. not-allowed / help makes "this won't respond" obvious without needing a tint. */
   cursor: var(--help-layer-overlay-cursor, default);
-  z-index: ${Z_BLOCKING_LAYER};
+  z-index: ${Z_BLOCKING_LAYER} !important;
 }
 
 .help-layer-marker {
@@ -43,11 +46,20 @@ const CSS = `
   margin: 0;
   padding: 0;
   border: none;
-  position: absolute;
+  /* Structural properties are !important so a host's broad rules (e.g. button { display:none }) can't
+     hide or distort the marker. top/left stay non-important because place() writes them inline per
+     frame; !important there would override that and pin the marker to 0,0. Theme stays var()-driven.
+     Note: for targets in a position:fixed subtree, floating.js overrides this with an inline
+     position:fixed !important (inline important beats this rule) so the marker doesn't jitter. */
+  position: absolute !important;
+  display: block !important;
+  visibility: visible !important;
+  opacity: 1 !important;
+  pointer-events: auto !important;
   top: 0;
   left: 0;
-  width: var(--help-layer-marker-size, 22px);
-  height: var(--help-layer-marker-size, 22px);
+  width: var(--help-layer-marker-size, 22px) !important;
+  height: var(--help-layer-marker-size, 22px) !important;
   border-radius: 50%;
   background: var(--help-layer-marker-bg, #2563eb);
   color: var(--help-layer-marker-color, #fff);
@@ -59,7 +71,7 @@ const CSS = `
   cursor: pointer;
   user-select: none;
   box-shadow: 0 1px 4px rgba(0, 0, 0, 0.35);
-  z-index: ${Z_TOP};
+  z-index: ${Z_TOP} !important;
 }
 
 .help-layer-marker:focus-visible {
@@ -68,7 +80,13 @@ const CSS = `
 }
 
 .help-layer-popup {
-  position: absolute;
+  /* Structural !important guards against host resets; top/left stay inline (place()), and display is
+     deliberately NOT !important here — popup.js toggles it via an inline !important declaration so the
+     open/close state itself can also beat a host rule without this stylesheet fighting the toggle. */
+  position: absolute !important;
+  visibility: visible !important;
+  opacity: 1 !important;
+  pointer-events: auto !important;
   top: 0;
   left: 0;
   display: none;
@@ -81,7 +99,7 @@ const CSS = `
   font-family: sans-serif;
   font-size: 13px;
   line-height: 1.5;
-  z-index: ${Z_POPUP};
+  z-index: ${Z_POPUP} !important;
 }
 
 .help-layer-popup:focus {
@@ -112,7 +130,10 @@ const CSS = `
   /* reset of the button element */
   appearance: none;
   -webkit-appearance: none;
-  position: absolute;
+  /* Keep the close affordance visible/placed even under host button { ... } rules. */
+  display: block !important;
+  position: absolute !important;
+  pointer-events: auto !important;
   top: 6px;
   right: 6px;
   width: 22px;

package/src/toggle.js

@@ -4,7 +4,7 @@
  * and aggregates their teardown into the cleanup registry (state).
  */
 import { activateBlockingLayer } from './blocking-layer.js';
-import { normalizeConfig, validateConfig } from './config.js';
+import { isPlainObject, normalizeConfig, validateConfig } from './config.js';
 import { createMarkerManager } from './markers.js';
 import {
   collectElementRecords,
@@ -15,49 +15,65 @@ import {
 } from './matcher.js';
 import { createMutationWatcher } from './observer.js';
 import { createPopupController } from './popup.js';
+import { safeInvoke } from './safe.js';
 import { createState } from './state.js';
 import { injectStyles, removeStyles } from './style.js';
 
 function resolveToggleElement(toggle) {
-  const toggleEl = typeof toggle === 'string' ? document.querySelector(toggle) : toggle;
-  if (!toggleEl) {
-    throw new Error(`help-layer: toggle element not found for selector "${toggle}"`);
+  if (typeof toggle === 'string') {
+    const el = document.querySelector(toggle);
+    if (!el) {
+      throw new Error(`help-layer: toggle element not found for selector "${toggle}"`);
+    }
+    return /** @type {HTMLElement} */ (el);
+  }
+  // Reject truthy garbage (a number, a plain object, ...) early; otherwise it would be accepted as a
+  // toggle and only blow up cryptically later at toggleEl.addEventListener.
+  if (toggle instanceof HTMLElement) {
+    return toggle;
   }
-  return toggleEl;
+  throw new Error('help-layer: toggle must be a CSS selector string or a DOM element');
 }
 
 /**
- * @param {object} params
- * @param {object} params.config helpConfig
- * @param {string|HTMLElement} [params.toggle] DOM element that switches ON/OFF (if omitted, programmatic control only)
- * @param {() => void} [params.onEnable] called right after the mode is turned ON
- * @param {() => void} [params.onDisable] called right after the mode is turned OFF
- * @param {(record: import('./matcher.js').HelpRecord) => void} [params.onOpen] called when a popup is opened
- * @param {() => void} [params.onClose] called when a popup is closed
- * @param {boolean} [params.silent] suppress the warning log for unregistered keys
- * @param {string} [params.attribute] attribute name marking targets (default 'data-help-id')
- * @param {(record: import('./matcher.js').HelpRecord) => (Node|null|undefined)} [params.render] render the popup body with your own Node
+ * @param {object} options
+ * @param {object} options.config helpConfig
+ * @param {string|HTMLElement} [options.toggle] DOM element that switches ON/OFF (if omitted, programmatic control only)
+ * @param {() => void} [options.onEnable] called right after the mode is turned ON
+ * @param {() => void} [options.onDisable] called right after the mode is turned OFF
+ * @param {(record: import('./matcher.js').HelpRecord) => void} [options.onOpen] called when a popup is opened
+ * @param {() => void} [options.onClose] called when a popup is closed
+ * @param {boolean} [options.silent] suppress the warning log for unregistered keys
+ * @param {string} [options.attribute] attribute name marking targets (default 'data-help-id')
+ * @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} [params.markerLabel] character shown on the marker (default '?')
- * @param {import('@floating-ui/dom').Placement} [params.markerPlacement] corner to overlap the marker onto (default 'top-end')
- * @param {import('@floating-ui/dom').Placement} [params.popupPlacement] initial popup placement (default 'bottom-start')
- * @param {string} [params.nonce] nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
+ * @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 {string} [options.nonce] nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
  */
-export function createToggleController({
-  config,
-  toggle,
-  onEnable,
-  onDisable,
-  onOpen,
-  onClose,
-  silent = false,
-  attribute = 'data-help-id',
-  render,
-  markerLabel = '?',
-  markerPlacement = 'top-end',
-  popupPlacement = 'bottom-start',
-  nonce,
-}) {
+export function createToggleController(options) {
+  // Validate before destructuring so initHelpLayer() / initHelpLayer(null) get a clear message
+  // instead of a cryptic "Cannot destructure property 'config' of undefined".
+  if (!isPlainObject(options)) {
+    throw new Error('help-layer: initHelpLayer requires an options object');
+  }
+  const {
+    config,
+    toggle,
+    onEnable,
+    onDisable,
+    onOpen,
+    onClose,
+    silent = false,
+    attribute = 'data-help-id',
+    render,
+    markerLabel = '?',
+    markerPlacement = 'top-end',
+    popupPlacement = 'bottom-start',
+    nonce,
+  } = options;
+
   let activeConfig = config;
   validateConfig(activeConfig);
   // The toggle element is optional. If omitted, it's driven solely by programmatic control like enable()/disable().
@@ -100,9 +116,7 @@ export function createToggleController({
           return;
         }
         popup.open(record, markerEl);
-        if (onOpen) {
-          onOpen(record);
-        }
+        safeInvoke('onOpen', onOpen, record);
       },
       // When overlap avoidance moves a marker, make the open popup follow.
       onOverlapResolved: () => popup.reposition(),
@@ -165,9 +179,7 @@ export function createToggleController({
       return;
     }
     turnOn();
-    if (onEnable) {
-      onEnable();
-    }
+    safeInvoke('onEnable', onEnable);
   }
 
   function disable() {
@@ -175,9 +187,7 @@ export function createToggleController({
       return;
     }
     turnOff();
-    if (onDisable) {
-      onDisable();
-    }
+    safeInvoke('onDisable', onDisable);
   }
 
   function toggleMode() {
@@ -204,9 +214,7 @@ export function createToggleController({
       return;
     }
     popup.open(entry.record, entry.el);
-    if (onOpen) {
-      onOpen(entry.record);
-    }
+    safeInvoke('onOpen', onOpen, entry.record);
   }
 
   // Close the open description (does not turn the mode itself OFF).