@flanksource/clicky-ui 0.3.16 → 0.3.18

package/dist/overlay/modalStack.d.ts

@@ -15,11 +15,19 @@ export declare function useModalStack(open: boolean): ModalStackPosition;
  * layer owns Escape, so a keypress dismisses one dialog/menu layer at a time.
  */
 export declare function useEscapeLayer(open: boolean, onEscape: () => void, enabled?: boolean): void;
+/**
+ * Registers a running guided tour while `active`, so floating layers lift above
+ * its dim. Symmetric with `useModalStack`, but a count rather than a stack: the
+ * tour overlay does not nest.
+ */
+export declare function useTourLayer(active: boolean): void;
 /**
  * z-index a floating layer (dropdown / combobox / tooltip / popover) should use
  * so it renders above any open modal — and below the next nested modal — or at
- * the popover floor when no modal is open. Subscribes to the modal stack so the
- * value tracks modals opening and closing.
+ * the popover floor when no modal is open. While a guided tour runs, the value
+ * also clears the tour's dim and step card, so a step that says "open this menu"
+ * shows the menu rather than hiding it under the overlay. Subscribes to the
+ * modal stack so the value tracks modals and tours opening and closing.
  */
 export declare function useFloatingZIndex(): number;
 //# sourceMappingURL=modalStack.d.ts.map

package/dist/overlay/modalStack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modalStack.d.ts","sourceRoot":"","sources":["../../src/overlay/modalStack.ts"],"names":[],"mappings":"AAgEA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,oFAAoF;IACpF,KAAK,EAAE,OAAO,CAAC;IACf,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CAoB/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,UAAO,QAgBjF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C"}
+{"version":3,"file":"modalStack.d.ts","sourceRoot":"","sources":["../../src/overlay/modalStack.ts"],"names":[],"mappings":"AAqEA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,oFAAoF;IACpF,KAAK,EAAE,OAAO,CAAC;IACf,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CAoB/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,UAAO,QAgBjF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAYlD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAQ1C"}

package/dist/overlay/modalStack.js

@@ -4,6 +4,7 @@ const stack = [];
 const listeners = /* @__PURE__ */ new Set();
 const escapeStack = [];
 let escapeDocument = null;
+let tourLayers = 0;
 function emit() {
   for (const listener of listeners) listener();
 }
@@ -14,7 +15,7 @@ function subscribe(listener) {
   };
 }
 function getSnapshot() {
-  return stack.join("\0");
+  return `${tourLayers}:` + stack.join("\0");
 }
 function onEscapeKeyDown(event) {
   if (event.defaultPrevented || event.key !== "Escape" || event.isComposing || event.keyCode === 229) {
@@ -73,15 +74,28 @@ function useEscapeLayer(open, onEscape, enabled = true) {
     return () => removeEscapeLayer(id);
   }, [enabled, id, open]);
 }
+function useTourLayer(active) {
+  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  useEffect(() => {
+    if (!active) return;
+    tourLayers += 1;
+    emit();
+    return () => {
+      tourLayers -= 1;
+      emit();
+    };
+  }, [active]);
+}
 function useFloatingZIndex() {
   useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-  if (stack.length === 0) return zIndex.popover;
-  const topModalZ = zIndex.modal + (stack.length - 1) * zIndex.modalStep;
-  return topModalZ + zIndex.popoverOverModalOffset;
+  const base = stack.length === 0 ? zIndex.popover : zIndex.modal + (stack.length - 1) * zIndex.modalStep + zIndex.popoverOverModalOffset;
+  if (tourLayers === 0) return base;
+  return Math.max(base, zIndex.tour + zIndex.tourCardOffset + zIndex.popoverOverModalOffset);
 }
 export {
   useEscapeLayer,
   useFloatingZIndex,
-  useModalStack
+  useModalStack,
+  useTourLayer
 };
 //# sourceMappingURL=modalStack.js.map

package/dist/overlay/modalStack.js.map

@@ -1 +1 @@
-{"version":3,"file":"modalStack.js","sources":["../../src/overlay/modalStack.ts"],"sourcesContent":["import { useEffect, useId, useRef, useSyncExternalStore } from \"react\";\nimport { zIndex } from \"./zIndex\";\n\n// A process-wide stack of the currently open modals, topmost last. Modals mount\n// independently (no shared provider), so the stack lives at module scope and is\n// shared through useSyncExternalStore. It lets nested modals cooperate: only the\n// topmost reacts to Escape, and each renders above the one it opened over.\nconst stack: string[] = [];\nconst listeners = new Set<() => void>();\nconst escapeStack: Array<{ id: string; onEscape: () => void }> = [];\nlet escapeDocument: Document | null = null;\n\nfunction emit() {\n  for (const listener of listeners) listener();\n}\n\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n// The snapshot is the stack identity; it only changes when an entry is pushed or\n// popped, so subscribers re-render exactly when their position could have moved.\nfunction getSnapshot() {\n  return stack.join(\"\\u0000\");\n}\n\nfunction onEscapeKeyDown(event: KeyboardEvent) {\n  if (\n    event.defaultPrevented ||\n    event.key !== \"Escape\" ||\n    event.isComposing ||\n    (event as KeyboardEvent & { keyCode?: number }).keyCode === 229\n  ) {\n    return;\n  }\n\n  const top = escapeStack[escapeStack.length - 1];\n  if (!top) return;\n\n  event.preventDefault();\n  event.stopPropagation();\n  event.stopImmediatePropagation();\n  top.onEscape();\n}\n\nfunction ensureEscapeListener() {\n  if (escapeDocument || typeof document === \"undefined\") return;\n  escapeDocument = document;\n  escapeDocument.addEventListener(\"keydown\", onEscapeKeyDown);\n}\n\nfunction removeEscapeLayer(id: string) {\n  const index = escapeStack.findIndex((entry) => entry.id === id);\n  if (index !== -1) escapeStack.splice(index, 1);\n\n  if (escapeStack.length === 0 && escapeDocument) {\n    escapeDocument.removeEventListener(\"keydown\", onEscapeKeyDown);\n    escapeDocument = null;\n  }\n}\n\nexport type ModalStackPosition = {\n  /** Whether this modal is the topmost open one and should own global affordances. */\n  isTop: boolean;\n  /** Zero-based depth in the stack; drives the stacking order of nested modals. */\n  depth: number;\n};\n\n/**\n * Registers a modal in the global stack while `open`, returning its live\n * position. Used so a nested modal sits above its opener and only the topmost\n * modal closes on Escape.\n */\nexport function useModalStack(open: boolean): ModalStackPosition {\n  const id = useId();\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  useEffect(() => {\n    if (!open) return;\n    stack.push(id);\n    emit();\n    return () => {\n      const index = stack.indexOf(id);\n      if (index !== -1) stack.splice(index, 1);\n      emit();\n    };\n  }, [open, id]);\n\n  const depth = stack.indexOf(id);\n  return {\n    isTop: depth !== -1 && depth === stack.length - 1,\n    depth: depth === -1 ? 0 : depth,\n  };\n}\n\n/**\n * Registers an Escape-closeable overlay while `open`. The topmost registered\n * layer owns Escape, so a keypress dismisses one dialog/menu layer at a time.\n */\nexport function useEscapeLayer(open: boolean, onEscape: () => void, enabled = true) {\n  const id = useId();\n  const onEscapeRef = useRef(onEscape);\n  onEscapeRef.current = onEscape;\n\n  useEffect(() => {\n    if (!open || !enabled) return;\n\n    ensureEscapeListener();\n    escapeStack.push({\n      id,\n      onEscape: () => onEscapeRef.current(),\n    });\n\n    return () => removeEscapeLayer(id);\n  }, [enabled, id, open]);\n}\n\n/**\n * z-index a floating layer (dropdown / combobox / tooltip / popover) should use\n * so it renders above any open modal — and below the next nested modal — or at\n * the popover floor when no modal is open. Subscribes to the modal stack so the\n * value tracks modals opening and closing.\n */\nexport function useFloatingZIndex(): number {\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  if (stack.length === 0) return zIndex.popover;\n  const topModalZ = zIndex.modal + (stack.length - 1) * zIndex.modalStep;\n  return topModalZ + zIndex.popoverOverModalOffset;\n}\n"],"names":[],"mappings":";;AAOA,MAAM,QAAkB,CAAA;AACxB,MAAM,gCAAgB,IAAA;AACtB,MAAM,cAA2D,CAAA;AACjE,IAAI,iBAAkC;AAEtC,SAAS,OAAO;AACd,aAAW,YAAY,UAAW,UAAA;AACpC;AAEA,SAAS,UAAU,UAAsB;AACvC,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAIA,SAAS,cAAc;AACrB,SAAO,MAAM,KAAK,IAAQ;AAC5B;AAEA,SAAS,gBAAgB,OAAsB;AAC7C,MACE,MAAM,oBACN,MAAM,QAAQ,YACd,MAAM,eACL,MAA+C,YAAY,KAC5D;AACA;AAAA,EACF;AAEA,QAAM,MAAM,YAAY,YAAY,SAAS,CAAC;AAC9C,MAAI,CAAC,IAAK;AAEV,QAAM,eAAA;AACN,QAAM,gBAAA;AACN,QAAM,yBAAA;AACN,MAAI,SAAA;AACN;AAEA,SAAS,uBAAuB;AAC9B,MAAI,kBAAkB,OAAO,aAAa,YAAa;AACvD,mBAAiB;AACjB,iBAAe,iBAAiB,WAAW,eAAe;AAC5D;AAEA,SAAS,kBAAkB,IAAY;AACrC,QAAM,QAAQ,YAAY,UAAU,CAAC,UAAU,MAAM,OAAO,EAAE;AAC9D,MAAI,UAAU,GAAI,aAAY,OAAO,OAAO,CAAC;AAE7C,MAAI,YAAY,WAAW,KAAK,gBAAgB;AAC9C,mBAAe,oBAAoB,WAAW,eAAe;AAC7D,qBAAiB;AAAA,EACnB;AACF;AAcO,SAAS,cAAc,MAAmC;AAC/D,QAAM,KAAK,MAAA;AACX,uBAAqB,WAAW,aAAa,WAAW;AAExD,YAAU,MAAM;AACd,QAAI,CAAC,KAAM;AACX,UAAM,KAAK,EAAE;AACb,SAAA;AACA,WAAO,MAAM;AACX,YAAM,QAAQ,MAAM,QAAQ,EAAE;AAC9B,UAAI,UAAU,GAAI,OAAM,OAAO,OAAO,CAAC;AACvC,WAAA;AAAA,IACF;AAAA,EACF,GAAG,CAAC,MAAM,EAAE,CAAC;AAEb,QAAM,QAAQ,MAAM,QAAQ,EAAE;AAC9B,SAAO;AAAA,IACL,OAAO,UAAU,MAAM,UAAU,MAAM,SAAS;AAAA,IAChD,OAAO,UAAU,KAAK,IAAI;AAAA,EAAA;AAE9B;AAMO,SAAS,eAAe,MAAe,UAAsB,UAAU,MAAM;AAClF,QAAM,KAAK,MAAA;AACX,QAAM,cAAc,OAAO,QAAQ;AACnC,cAAY,UAAU;AAEtB,YAAU,MAAM;AACd,QAAI,CAAC,QAAQ,CAAC,QAAS;AAEvB,yBAAA;AACA,gBAAY,KAAK;AAAA,MACf;AAAA,MACA,UAAU,MAAM,YAAY,QAAA;AAAA,IAAQ,CACrC;AAED,WAAO,MAAM,kBAAkB,EAAE;AAAA,EACnC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC;AACxB;AAQO,SAAS,oBAA4B;AAC1C,uBAAqB,WAAW,aAAa,WAAW;AACxD,MAAI,MAAM,WAAW,EAAG,QAAO,OAAO;AACtC,QAAM,YAAY,OAAO,SAAS,MAAM,SAAS,KAAK,OAAO;AAC7D,SAAO,YAAY,OAAO;AAC5B;"}
+{"version":3,"file":"modalStack.js","sources":["../../src/overlay/modalStack.ts"],"sourcesContent":["import { useEffect, useId, useRef, useSyncExternalStore } from \"react\";\nimport { zIndex } from \"./zIndex\";\n\n// A process-wide stack of the currently open modals, topmost last. Modals mount\n// independently (no shared provider), so the stack lives at module scope and is\n// shared through useSyncExternalStore. It lets nested modals cooperate: only the\n// topmost reacts to Escape, and each renders above the one it opened over.\nconst stack: string[] = [];\nconst listeners = new Set<() => void>();\nconst escapeStack: Array<{ id: string; onEscape: () => void }> = [];\nlet escapeDocument: Document | null = null;\n// Running guided tours. A tour dims the page from `zIndex.tour`, far above the\n// modal band, so floating content opened *during* a tour (the menu a step tells\n// the user to open) has to clear that dim or it renders invisibly underneath.\nlet tourLayers = 0;\n\nfunction emit() {\n  for (const listener of listeners) listener();\n}\n\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n// The snapshot is the stack identity plus the tour-layer count; it only changes\n// when an entry is pushed or popped, so subscribers re-render exactly when their\n// position could have moved.\nfunction getSnapshot() {\n  return `${tourLayers}:` + stack.join(\"\\u0000\");\n}\n\nfunction onEscapeKeyDown(event: KeyboardEvent) {\n  if (\n    event.defaultPrevented ||\n    event.key !== \"Escape\" ||\n    event.isComposing ||\n    (event as KeyboardEvent & { keyCode?: number }).keyCode === 229\n  ) {\n    return;\n  }\n\n  const top = escapeStack[escapeStack.length - 1];\n  if (!top) return;\n\n  event.preventDefault();\n  event.stopPropagation();\n  event.stopImmediatePropagation();\n  top.onEscape();\n}\n\nfunction ensureEscapeListener() {\n  if (escapeDocument || typeof document === \"undefined\") return;\n  escapeDocument = document;\n  escapeDocument.addEventListener(\"keydown\", onEscapeKeyDown);\n}\n\nfunction removeEscapeLayer(id: string) {\n  const index = escapeStack.findIndex((entry) => entry.id === id);\n  if (index !== -1) escapeStack.splice(index, 1);\n\n  if (escapeStack.length === 0 && escapeDocument) {\n    escapeDocument.removeEventListener(\"keydown\", onEscapeKeyDown);\n    escapeDocument = null;\n  }\n}\n\nexport type ModalStackPosition = {\n  /** Whether this modal is the topmost open one and should own global affordances. */\n  isTop: boolean;\n  /** Zero-based depth in the stack; drives the stacking order of nested modals. */\n  depth: number;\n};\n\n/**\n * Registers a modal in the global stack while `open`, returning its live\n * position. Used so a nested modal sits above its opener and only the topmost\n * modal closes on Escape.\n */\nexport function useModalStack(open: boolean): ModalStackPosition {\n  const id = useId();\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  useEffect(() => {\n    if (!open) return;\n    stack.push(id);\n    emit();\n    return () => {\n      const index = stack.indexOf(id);\n      if (index !== -1) stack.splice(index, 1);\n      emit();\n    };\n  }, [open, id]);\n\n  const depth = stack.indexOf(id);\n  return {\n    isTop: depth !== -1 && depth === stack.length - 1,\n    depth: depth === -1 ? 0 : depth,\n  };\n}\n\n/**\n * Registers an Escape-closeable overlay while `open`. The topmost registered\n * layer owns Escape, so a keypress dismisses one dialog/menu layer at a time.\n */\nexport function useEscapeLayer(open: boolean, onEscape: () => void, enabled = true) {\n  const id = useId();\n  const onEscapeRef = useRef(onEscape);\n  onEscapeRef.current = onEscape;\n\n  useEffect(() => {\n    if (!open || !enabled) return;\n\n    ensureEscapeListener();\n    escapeStack.push({\n      id,\n      onEscape: () => onEscapeRef.current(),\n    });\n\n    return () => removeEscapeLayer(id);\n  }, [enabled, id, open]);\n}\n\n/**\n * Registers a running guided tour while `active`, so floating layers lift above\n * its dim. Symmetric with `useModalStack`, but a count rather than a stack: the\n * tour overlay does not nest.\n */\nexport function useTourLayer(active: boolean): void {\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n\n  useEffect(() => {\n    if (!active) return;\n    tourLayers += 1;\n    emit();\n    return () => {\n      tourLayers -= 1;\n      emit();\n    };\n  }, [active]);\n}\n\n/**\n * z-index a floating layer (dropdown / combobox / tooltip / popover) should use\n * so it renders above any open modal — and below the next nested modal — or at\n * the popover floor when no modal is open. While a guided tour runs, the value\n * also clears the tour's dim and step card, so a step that says \"open this menu\"\n * shows the menu rather than hiding it under the overlay. Subscribes to the\n * modal stack so the value tracks modals and tours opening and closing.\n */\nexport function useFloatingZIndex(): number {\n  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n  const base =\n    stack.length === 0\n      ? zIndex.popover\n      : zIndex.modal + (stack.length - 1) * zIndex.modalStep + zIndex.popoverOverModalOffset;\n  if (tourLayers === 0) return base;\n  return Math.max(base, zIndex.tour + zIndex.tourCardOffset + zIndex.popoverOverModalOffset);\n}\n"],"names":[],"mappings":";;AAOA,MAAM,QAAkB,CAAA;AACxB,MAAM,gCAAgB,IAAA;AACtB,MAAM,cAA2D,CAAA;AACjE,IAAI,iBAAkC;AAItC,IAAI,aAAa;AAEjB,SAAS,OAAO;AACd,aAAW,YAAY,UAAW,UAAA;AACpC;AAEA,SAAS,UAAU,UAAsB;AACvC,YAAU,IAAI,QAAQ;AACtB,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAKA,SAAS,cAAc;AACrB,SAAO,GAAG,UAAU,MAAM,MAAM,KAAK,IAAQ;AAC/C;AAEA,SAAS,gBAAgB,OAAsB;AAC7C,MACE,MAAM,oBACN,MAAM,QAAQ,YACd,MAAM,eACL,MAA+C,YAAY,KAC5D;AACA;AAAA,EACF;AAEA,QAAM,MAAM,YAAY,YAAY,SAAS,CAAC;AAC9C,MAAI,CAAC,IAAK;AAEV,QAAM,eAAA;AACN,QAAM,gBAAA;AACN,QAAM,yBAAA;AACN,MAAI,SAAA;AACN;AAEA,SAAS,uBAAuB;AAC9B,MAAI,kBAAkB,OAAO,aAAa,YAAa;AACvD,mBAAiB;AACjB,iBAAe,iBAAiB,WAAW,eAAe;AAC5D;AAEA,SAAS,kBAAkB,IAAY;AACrC,QAAM,QAAQ,YAAY,UAAU,CAAC,UAAU,MAAM,OAAO,EAAE;AAC9D,MAAI,UAAU,GAAI,aAAY,OAAO,OAAO,CAAC;AAE7C,MAAI,YAAY,WAAW,KAAK,gBAAgB;AAC9C,mBAAe,oBAAoB,WAAW,eAAe;AAC7D,qBAAiB;AAAA,EACnB;AACF;AAcO,SAAS,cAAc,MAAmC;AAC/D,QAAM,KAAK,MAAA;AACX,uBAAqB,WAAW,aAAa,WAAW;AAExD,YAAU,MAAM;AACd,QAAI,CAAC,KAAM;AACX,UAAM,KAAK,EAAE;AACb,SAAA;AACA,WAAO,MAAM;AACX,YAAM,QAAQ,MAAM,QAAQ,EAAE;AAC9B,UAAI,UAAU,GAAI,OAAM,OAAO,OAAO,CAAC;AACvC,WAAA;AAAA,IACF;AAAA,EACF,GAAG,CAAC,MAAM,EAAE,CAAC;AAEb,QAAM,QAAQ,MAAM,QAAQ,EAAE;AAC9B,SAAO;AAAA,IACL,OAAO,UAAU,MAAM,UAAU,MAAM,SAAS;AAAA,IAChD,OAAO,UAAU,KAAK,IAAI;AAAA,EAAA;AAE9B;AAMO,SAAS,eAAe,MAAe,UAAsB,UAAU,MAAM;AAClF,QAAM,KAAK,MAAA;AACX,QAAM,cAAc,OAAO,QAAQ;AACnC,cAAY,UAAU;AAEtB,YAAU,MAAM;AACd,QAAI,CAAC,QAAQ,CAAC,QAAS;AAEvB,yBAAA;AACA,gBAAY,KAAK;AAAA,MACf;AAAA,MACA,UAAU,MAAM,YAAY,QAAA;AAAA,IAAQ,CACrC;AAED,WAAO,MAAM,kBAAkB,EAAE;AAAA,EACnC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC;AACxB;AAOO,SAAS,aAAa,QAAuB;AAClD,uBAAqB,WAAW,aAAa,WAAW;AAExD,YAAU,MAAM;AACd,QAAI,CAAC,OAAQ;AACb,kBAAc;AACd,SAAA;AACA,WAAO,MAAM;AACX,oBAAc;AACd,WAAA;AAAA,IACF;AAAA,EACF,GAAG,CAAC,MAAM,CAAC;AACb;AAUO,SAAS,oBAA4B;AAC1C,uBAAqB,WAAW,aAAa,WAAW;AACxD,QAAM,OACJ,MAAM,WAAW,IACb,OAAO,UACP,OAAO,SAAS,MAAM,SAAS,KAAK,OAAO,YAAY,OAAO;AACpE,MAAI,eAAe,EAAG,QAAO;AAC7B,SAAO,KAAK,IAAI,MAAM,OAAO,OAAO,OAAO,iBAAiB,OAAO,sBAAsB;AAC3F;"}

package/dist/overlay/tour-anchor.cjs

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const ROOT_POLL_MS = 50;
+function resolveTourRoot(source) {
+  return (typeof source === "function" ? source() : source) ?? null;
+}
+function rootWindow(root) {
+  var _a;
+  if (root instanceof Document) return root.defaultView;
+  return ((_a = root.ownerDocument) == null ? void 0 : _a.defaultView) ?? null;
+}
+function observableNode(root) {
+  return root instanceof Document ? root.documentElement ?? root : root;
+}
+function isDisplayed(element) {
+  if (!element.isConnected || element.hidden) return false;
+  const view = element.ownerDocument.defaultView;
+  if (!view) return true;
+  const style = view.getComputedStyle(element);
+  return style.display !== "none" && style.visibility !== "hidden";
+}
+function queryAnchor(root, target) {
+  var _a;
+  if (typeof target === "string") return root.querySelector(target);
+  if (typeof target !== "function") return target;
+  const resolved = target(root) ?? null;
+  const ElementCtor = ((_a = rootWindow(root)) == null ? void 0 : _a.HTMLElement) ?? HTMLElement;
+  if (resolved !== null && !(resolved instanceof ElementCtor)) {
+    throw new Error(`Tour target resolver returned ${String(resolved)}, expected an HTMLElement`);
+  }
+  return resolved;
+}
+function tryResolve(rootSource, target) {
+  const root = resolveTourRoot(rootSource);
+  if (!root) return null;
+  const element = queryAnchor(root, target);
+  return element && isDisplayed(element) ? element : null;
+}
+function watchForAnchor(rootSource, target, onFound) {
+  let frame = null;
+  let observer = null;
+  let observedNode = null;
+  let stopped = false;
+  const observeRoot = () => {
+    const root = resolveTourRoot(rootSource);
+    if (!root) return;
+    const node = observableNode(root);
+    if (observedNode === node) return;
+    observer == null ? void 0 : observer.disconnect();
+    observedNode = node;
+    observer = new MutationObserver(attempt);
+    observer.observe(node, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ["class", "style", "hidden", "data-state", "aria-hidden"]
+    });
+  };
+  const frameScheduler = () => {
+    const root = resolveTourRoot(rootSource);
+    return root ? rootWindow(root) : null;
+  };
+  function run() {
+    frame = null;
+    if (stopped) return;
+    observeRoot();
+    const element = tryResolve(rootSource, target);
+    if (element) onFound(element);
+  }
+  function attempt() {
+    if (stopped || frame !== null) return;
+    const view = frameScheduler();
+    frame = (view == null ? void 0 : view.requestAnimationFrame) ? view.requestAnimationFrame(run) : setTimeout(run, 16);
+  }
+  observeRoot();
+  const poll = setInterval(() => {
+    if (!observedNode) attempt();
+  }, ROOT_POLL_MS);
+  return () => {
+    var _a, _b;
+    stopped = true;
+    clearInterval(poll);
+    if (frame !== null) (_b = (_a = frameScheduler()) == null ? void 0 : _a.cancelAnimationFrame) == null ? void 0 : _b.call(_a, frame);
+    observer == null ? void 0 : observer.disconnect();
+  };
+}
+function resolveAnchor(options) {
+  const { root, target, timeoutMs, signal } = options;
+  const immediate = tryResolve(root, target);
+  if (immediate) return Promise.resolve({ status: "found", element: immediate });
+  if (signal == null ? void 0 : signal.aborted) return Promise.resolve({ status: "timeout" });
+  return new Promise((resolve) => {
+    const disposers = [];
+    let settled = false;
+    const finish = (resolution) => {
+      if (settled) return;
+      settled = true;
+      for (const dispose of disposers) dispose();
+      resolve(resolution);
+    };
+    disposers.push(watchForAnchor(root, target, (element) => finish({ status: "found", element })));
+    const timer = setTimeout(() => finish({ status: "timeout" }), timeoutMs);
+    disposers.push(() => clearTimeout(timer));
+    if (signal) {
+      const onAbort = () => finish({ status: "timeout" });
+      signal.addEventListener("abort", onAbort);
+      disposers.push(() => signal.removeEventListener("abort", onAbort));
+    }
+  });
+}
+exports.queryAnchor = queryAnchor;
+exports.resolveAnchor = resolveAnchor;
+exports.resolveTourRoot = resolveTourRoot;
+//# sourceMappingURL=tour-anchor.cjs.map

package/dist/overlay/tour-anchor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-anchor.cjs","sources":["../../src/overlay/tour-anchor.ts"],"sourcesContent":["import type { TourRoot, TourRootSource, TourTarget } from \"./tour-types\";\n\n/**\n * The ONLY place a tour touches the DOM. Everything else — Tour.tsx included —\n * goes through here, which is what makes shadow-root support structural rather\n * than a convention: there is no `document` reference to accidentally reintroduce.\n *\n * An anchor may not exist when its step is entered (lazy route, data still\n * loading, a collapsed panel), so resolution is a bounded wait: query, then\n * observe mutations and re-query on the next frame, until the element appears or\n * the budget expires.\n */\n\nexport type AnchorResolution =\n  | { status: \"found\"; element: HTMLElement }\n  | { status: \"timeout\" };\n\nexport type ResolveAnchorOptions = {\n  root: TourRootSource;\n  target: TourTarget;\n  timeoutMs: number;\n  signal?: AbortSignal | undefined;\n};\n\n/** How often a not-yet-attached root is retried; once attached the observer takes over. */\nconst ROOT_POLL_MS = 50;\n\n/** Resolves a root source, returning `null` while a lazily attached root is absent. */\nexport function resolveTourRoot(source: TourRootSource): TourRoot | null {\n  return (typeof source === \"function\" ? source() : source) ?? null;\n}\n\nfunction rootWindow(root: TourRoot): (Window & typeof globalThis) | null {\n  if (root instanceof Document) return root.defaultView;\n  return root.ownerDocument?.defaultView ?? null;\n}\n\n/** MutationObserver needs a Node; a Document must be observed via its element. */\nfunction observableNode(root: TourRoot): Node {\n  return root instanceof Document ? (root.documentElement ?? root) : root;\n}\n\n/**\n * \"Displayed\" rather than \"laid out\": deliberately not `getClientRects().length`,\n * because jsdom lays nothing out and every unit test would then time out. The\n * distinction we actually care about is whether the element is in the tree and\n * not hidden.\n */\nfunction isDisplayed(element: HTMLElement): boolean {\n  if (!element.isConnected || element.hidden) return false;\n  const view = element.ownerDocument.defaultView;\n  if (!view) return true;\n  const style = view.getComputedStyle(element);\n  return style.display !== \"none\" && style.visibility !== \"hidden\";\n}\n\n/** One synchronous lookup. Throws when a resolver returns something unusable. */\nexport function queryAnchor(root: TourRoot, target: TourTarget): HTMLElement | null {\n  if (typeof target === \"string\") return root.querySelector<HTMLElement>(target);\n  if (typeof target !== \"function\") return target;\n\n  const resolved = target(root) ?? null;\n  const ElementCtor = rootWindow(root)?.HTMLElement ?? HTMLElement;\n  if (resolved !== null && !(resolved instanceof ElementCtor)) {\n    throw new Error(`Tour target resolver returned ${String(resolved)}, expected an HTMLElement`);\n  }\n  return resolved;\n}\n\n/** A displayed match under the current root, or null while it is still absent. */\nfunction tryResolve(rootSource: TourRootSource, target: TourTarget): HTMLElement | null {\n  const root = resolveTourRoot(rootSource);\n  if (!root) return null;\n  const element = queryAnchor(root, target);\n  return element && isDisplayed(element) ? element : null;\n}\n\n/**\n * Watches for `target` under `root`, calling `onFound` once. Re-queries are\n * coalesced into one animation frame so a chatty React commit cannot run\n * `querySelector` hundreds of times, and a root that has not attached yet is\n * polled until it can be observed — so a late-mounting shadow root needs no\n * second waiting mechanism that could hang on its own.\n */\nfunction watchForAnchor(\n  rootSource: TourRootSource,\n  target: TourTarget,\n  onFound: (element: HTMLElement) => void,\n): () => void {\n  let frame: number | null = null;\n  let observer: MutationObserver | null = null;\n  let observedNode: Node | null = null;\n  let stopped = false;\n\n  const observeRoot = () => {\n    const root = resolveTourRoot(rootSource);\n    if (!root) return;\n    const node = observableNode(root);\n    if (observedNode === node) return;\n    observer?.disconnect();\n    observedNode = node;\n    observer = new MutationObserver(attempt);\n    observer.observe(node, {\n      subtree: true,\n      childList: true,\n      attributes: true,\n      attributeFilter: [\"class\", \"style\", \"hidden\", \"data-state\", \"aria-hidden\"],\n    });\n  };\n\n  // Resolved lazily: with a late-attaching root there is no window to schedule\n  // against until it exists, and the interval below carries us until then.\n  const frameScheduler = () => {\n    const root = resolveTourRoot(rootSource);\n    return root ? rootWindow(root) : null;\n  };\n\n  function run() {\n    frame = null;\n    if (stopped) return;\n    observeRoot();\n    const element = tryResolve(rootSource, target);\n    if (element) onFound(element);\n  }\n\n  function attempt() {\n    if (stopped || frame !== null) return;\n    const view = frameScheduler();\n    frame = view?.requestAnimationFrame\n      ? view.requestAnimationFrame(run)\n      : (setTimeout(run, 16) as unknown as number);\n  }\n\n  observeRoot();\n  const poll = setInterval(() => {\n    if (!observedNode) attempt();\n  }, ROOT_POLL_MS);\n\n  return () => {\n    stopped = true;\n    clearInterval(poll);\n    if (frame !== null) frameScheduler()?.cancelAnimationFrame?.(frame);\n    observer?.disconnect();\n  };\n}\n\n/** Waits for `target` under `root`, up to `timeoutMs`. */\nexport function resolveAnchor(options: ResolveAnchorOptions): Promise<AnchorResolution> {\n  const { root, target, timeoutMs, signal } = options;\n\n  const immediate = tryResolve(root, target);\n  if (immediate) return Promise.resolve({ status: \"found\", element: immediate });\n  if (signal?.aborted) return Promise.resolve({ status: \"timeout\" });\n\n  return new Promise<AnchorResolution>((resolve) => {\n    const disposers: Array<() => void> = [];\n    let settled = false;\n\n    const finish = (resolution: AnchorResolution) => {\n      if (settled) return;\n      settled = true;\n      for (const dispose of disposers) dispose();\n      resolve(resolution);\n    };\n\n    disposers.push(watchForAnchor(root, target, (element) => finish({ status: \"found\", element })));\n\n    const timer = setTimeout(() => finish({ status: \"timeout\" }), timeoutMs);\n    disposers.push(() => clearTimeout(timer));\n\n    if (signal) {\n      const onAbort = () => finish({ status: \"timeout\" });\n      signal.addEventListener(\"abort\", onAbort);\n      disposers.push(() => signal.removeEventListener(\"abort\", onAbort));\n    }\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/overlay/tour-anchor.d.ts

@@ -0,0 +1,30 @@
+import { TourRoot, TourRootSource, TourTarget } from './tour-types';
+/**
+ * The ONLY place a tour touches the DOM. Everything else — Tour.tsx included —
+ * goes through here, which is what makes shadow-root support structural rather
+ * than a convention: there is no `document` reference to accidentally reintroduce.
+ *
+ * An anchor may not exist when its step is entered (lazy route, data still
+ * loading, a collapsed panel), so resolution is a bounded wait: query, then
+ * observe mutations and re-query on the next frame, until the element appears or
+ * the budget expires.
+ */
+export type AnchorResolution = {
+    status: "found";
+    element: HTMLElement;
+} | {
+    status: "timeout";
+};
+export type ResolveAnchorOptions = {
+    root: TourRootSource;
+    target: TourTarget;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+};
+/** Resolves a root source, returning `null` while a lazily attached root is absent. */
+export declare function resolveTourRoot(source: TourRootSource): TourRoot | null;
+/** One synchronous lookup. Throws when a resolver returns something unusable. */
+export declare function queryAnchor(root: TourRoot, target: TourTarget): HTMLElement | null;
+/** Waits for `target` under `root`, up to `timeoutMs`. */
+export declare function resolveAnchor(options: ResolveAnchorOptions): Promise<AnchorResolution>;
+//# sourceMappingURL=tour-anchor.d.ts.map

package/dist/overlay/tour-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-anchor.d.ts","sourceRoot":"","sources":["../../src/overlay/tour-anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEzE;;;;;;;;;GASG;AAEH,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GACzC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAE1B,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC,CAAC;AAKF,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,GAAG,IAAI,CAEvE;AA0BD,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAUlF;AA+ED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6BtF"}

package/dist/overlay/tour-anchor.js

@@ -0,0 +1,114 @@
+const ROOT_POLL_MS = 50;
+function resolveTourRoot(source) {
+  return (typeof source === "function" ? source() : source) ?? null;
+}
+function rootWindow(root) {
+  var _a;
+  if (root instanceof Document) return root.defaultView;
+  return ((_a = root.ownerDocument) == null ? void 0 : _a.defaultView) ?? null;
+}
+function observableNode(root) {
+  return root instanceof Document ? root.documentElement ?? root : root;
+}
+function isDisplayed(element) {
+  if (!element.isConnected || element.hidden) return false;
+  const view = element.ownerDocument.defaultView;
+  if (!view) return true;
+  const style = view.getComputedStyle(element);
+  return style.display !== "none" && style.visibility !== "hidden";
+}
+function queryAnchor(root, target) {
+  var _a;
+  if (typeof target === "string") return root.querySelector(target);
+  if (typeof target !== "function") return target;
+  const resolved = target(root) ?? null;
+  const ElementCtor = ((_a = rootWindow(root)) == null ? void 0 : _a.HTMLElement) ?? HTMLElement;
+  if (resolved !== null && !(resolved instanceof ElementCtor)) {
+    throw new Error(`Tour target resolver returned ${String(resolved)}, expected an HTMLElement`);
+  }
+  return resolved;
+}
+function tryResolve(rootSource, target) {
+  const root = resolveTourRoot(rootSource);
+  if (!root) return null;
+  const element = queryAnchor(root, target);
+  return element && isDisplayed(element) ? element : null;
+}
+function watchForAnchor(rootSource, target, onFound) {
+  let frame = null;
+  let observer = null;
+  let observedNode = null;
+  let stopped = false;
+  const observeRoot = () => {
+    const root = resolveTourRoot(rootSource);
+    if (!root) return;
+    const node = observableNode(root);
+    if (observedNode === node) return;
+    observer == null ? void 0 : observer.disconnect();
+    observedNode = node;
+    observer = new MutationObserver(attempt);
+    observer.observe(node, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ["class", "style", "hidden", "data-state", "aria-hidden"]
+    });
+  };
+  const frameScheduler = () => {
+    const root = resolveTourRoot(rootSource);
+    return root ? rootWindow(root) : null;
+  };
+  function run() {
+    frame = null;
+    if (stopped) return;
+    observeRoot();
+    const element = tryResolve(rootSource, target);
+    if (element) onFound(element);
+  }
+  function attempt() {
+    if (stopped || frame !== null) return;
+    const view = frameScheduler();
+    frame = (view == null ? void 0 : view.requestAnimationFrame) ? view.requestAnimationFrame(run) : setTimeout(run, 16);
+  }
+  observeRoot();
+  const poll = setInterval(() => {
+    if (!observedNode) attempt();
+  }, ROOT_POLL_MS);
+  return () => {
+    var _a, _b;
+    stopped = true;
+    clearInterval(poll);
+    if (frame !== null) (_b = (_a = frameScheduler()) == null ? void 0 : _a.cancelAnimationFrame) == null ? void 0 : _b.call(_a, frame);
+    observer == null ? void 0 : observer.disconnect();
+  };
+}
+function resolveAnchor(options) {
+  const { root, target, timeoutMs, signal } = options;
+  const immediate = tryResolve(root, target);
+  if (immediate) return Promise.resolve({ status: "found", element: immediate });
+  if (signal == null ? void 0 : signal.aborted) return Promise.resolve({ status: "timeout" });
+  return new Promise((resolve) => {
+    const disposers = [];
+    let settled = false;
+    const finish = (resolution) => {
+      if (settled) return;
+      settled = true;
+      for (const dispose of disposers) dispose();
+      resolve(resolution);
+    };
+    disposers.push(watchForAnchor(root, target, (element) => finish({ status: "found", element })));
+    const timer = setTimeout(() => finish({ status: "timeout" }), timeoutMs);
+    disposers.push(() => clearTimeout(timer));
+    if (signal) {
+      const onAbort = () => finish({ status: "timeout" });
+      signal.addEventListener("abort", onAbort);
+      disposers.push(() => signal.removeEventListener("abort", onAbort));
+    }
+  });
+}
+export {
+  queryAnchor,
+  resolveAnchor,
+  resolveTourRoot
+};
+//# sourceMappingURL=tour-anchor.js.map

package/dist/overlay/tour-anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-anchor.js","sources":["../../src/overlay/tour-anchor.ts"],"sourcesContent":["import type { TourRoot, TourRootSource, TourTarget } from \"./tour-types\";\n\n/**\n * The ONLY place a tour touches the DOM. Everything else — Tour.tsx included —\n * goes through here, which is what makes shadow-root support structural rather\n * than a convention: there is no `document` reference to accidentally reintroduce.\n *\n * An anchor may not exist when its step is entered (lazy route, data still\n * loading, a collapsed panel), so resolution is a bounded wait: query, then\n * observe mutations and re-query on the next frame, until the element appears or\n * the budget expires.\n */\n\nexport type AnchorResolution =\n  | { status: \"found\"; element: HTMLElement }\n  | { status: \"timeout\" };\n\nexport type ResolveAnchorOptions = {\n  root: TourRootSource;\n  target: TourTarget;\n  timeoutMs: number;\n  signal?: AbortSignal | undefined;\n};\n\n/** How often a not-yet-attached root is retried; once attached the observer takes over. */\nconst ROOT_POLL_MS = 50;\n\n/** Resolves a root source, returning `null` while a lazily attached root is absent. */\nexport function resolveTourRoot(source: TourRootSource): TourRoot | null {\n  return (typeof source === \"function\" ? source() : source) ?? null;\n}\n\nfunction rootWindow(root: TourRoot): (Window & typeof globalThis) | null {\n  if (root instanceof Document) return root.defaultView;\n  return root.ownerDocument?.defaultView ?? null;\n}\n\n/** MutationObserver needs a Node; a Document must be observed via its element. */\nfunction observableNode(root: TourRoot): Node {\n  return root instanceof Document ? (root.documentElement ?? root) : root;\n}\n\n/**\n * \"Displayed\" rather than \"laid out\": deliberately not `getClientRects().length`,\n * because jsdom lays nothing out and every unit test would then time out. The\n * distinction we actually care about is whether the element is in the tree and\n * not hidden.\n */\nfunction isDisplayed(element: HTMLElement): boolean {\n  if (!element.isConnected || element.hidden) return false;\n  const view = element.ownerDocument.defaultView;\n  if (!view) return true;\n  const style = view.getComputedStyle(element);\n  return style.display !== \"none\" && style.visibility !== \"hidden\";\n}\n\n/** One synchronous lookup. Throws when a resolver returns something unusable. */\nexport function queryAnchor(root: TourRoot, target: TourTarget): HTMLElement | null {\n  if (typeof target === \"string\") return root.querySelector<HTMLElement>(target);\n  if (typeof target !== \"function\") return target;\n\n  const resolved = target(root) ?? null;\n  const ElementCtor = rootWindow(root)?.HTMLElement ?? HTMLElement;\n  if (resolved !== null && !(resolved instanceof ElementCtor)) {\n    throw new Error(`Tour target resolver returned ${String(resolved)}, expected an HTMLElement`);\n  }\n  return resolved;\n}\n\n/** A displayed match under the current root, or null while it is still absent. */\nfunction tryResolve(rootSource: TourRootSource, target: TourTarget): HTMLElement | null {\n  const root = resolveTourRoot(rootSource);\n  if (!root) return null;\n  const element = queryAnchor(root, target);\n  return element && isDisplayed(element) ? element : null;\n}\n\n/**\n * Watches for `target` under `root`, calling `onFound` once. Re-queries are\n * coalesced into one animation frame so a chatty React commit cannot run\n * `querySelector` hundreds of times, and a root that has not attached yet is\n * polled until it can be observed — so a late-mounting shadow root needs no\n * second waiting mechanism that could hang on its own.\n */\nfunction watchForAnchor(\n  rootSource: TourRootSource,\n  target: TourTarget,\n  onFound: (element: HTMLElement) => void,\n): () => void {\n  let frame: number | null = null;\n  let observer: MutationObserver | null = null;\n  let observedNode: Node | null = null;\n  let stopped = false;\n\n  const observeRoot = () => {\n    const root = resolveTourRoot(rootSource);\n    if (!root) return;\n    const node = observableNode(root);\n    if (observedNode === node) return;\n    observer?.disconnect();\n    observedNode = node;\n    observer = new MutationObserver(attempt);\n    observer.observe(node, {\n      subtree: true,\n      childList: true,\n      attributes: true,\n      attributeFilter: [\"class\", \"style\", \"hidden\", \"data-state\", \"aria-hidden\"],\n    });\n  };\n\n  // Resolved lazily: with a late-attaching root there is no window to schedule\n  // against until it exists, and the interval below carries us until then.\n  const frameScheduler = () => {\n    const root = resolveTourRoot(rootSource);\n    return root ? rootWindow(root) : null;\n  };\n\n  function run() {\n    frame = null;\n    if (stopped) return;\n    observeRoot();\n    const element = tryResolve(rootSource, target);\n    if (element) onFound(element);\n  }\n\n  function attempt() {\n    if (stopped || frame !== null) return;\n    const view = frameScheduler();\n    frame = view?.requestAnimationFrame\n      ? view.requestAnimationFrame(run)\n      : (setTimeout(run, 16) as unknown as number);\n  }\n\n  observeRoot();\n  const poll = setInterval(() => {\n    if (!observedNode) attempt();\n  }, ROOT_POLL_MS);\n\n  return () => {\n    stopped = true;\n    clearInterval(poll);\n    if (frame !== null) frameScheduler()?.cancelAnimationFrame?.(frame);\n    observer?.disconnect();\n  };\n}\n\n/** Waits for `target` under `root`, up to `timeoutMs`. */\nexport function resolveAnchor(options: ResolveAnchorOptions): Promise<AnchorResolution> {\n  const { root, target, timeoutMs, signal } = options;\n\n  const immediate = tryResolve(root, target);\n  if (immediate) return Promise.resolve({ status: \"found\", element: immediate });\n  if (signal?.aborted) return Promise.resolve({ status: \"timeout\" });\n\n  return new Promise<AnchorResolution>((resolve) => {\n    const disposers: Array<() => void> = [];\n    let settled = false;\n\n    const finish = (resolution: AnchorResolution) => {\n      if (settled) return;\n      settled = true;\n      for (const dispose of disposers) dispose();\n      resolve(resolution);\n    };\n\n    disposers.push(watchForAnchor(root, target, (element) => finish({ status: \"found\", element })));\n\n    const timer = setTimeout(() => finish({ status: \"timeout\" }), timeoutMs);\n    disposers.push(() => clearTimeout(timer));\n\n    if (signal) {\n      const onAbort = () => finish({ status: \"timeout\" });\n      signal.addEventListener(\"abort\", onAbort);\n      disposers.push(() => signal.removeEventListener(\"abort\", onAbort));\n    }\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/overlay/tour-context.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const TourContext = react.createContext(null);
+function useTour() {
+  const ctx = react.useContext(TourContext);
+  if (!ctx) throw new Error("useTour must be used within a <TourProvider>");
+  return ctx;
+}
+exports.TourContext = TourContext;
+exports.useTour = useTour;
+//# sourceMappingURL=tour-context.cjs.map

package/dist/overlay/tour-context.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-context.cjs","sources":["../../src/overlay/tour-context.ts"],"sourcesContent":["import { createContext, useContext } from \"react\";\nimport type { TourCompletionStatus } from \"./tour-progress\";\nimport type { TourDefinition } from \"./tour-types\";\n\n/** Status of the running tour. `waiting` means its anchor has not appeared yet. */\nexport type TourStatus = \"idle\" | \"navigating\" | \"waiting\" | \"active\";\n\nexport type TourState = {\n  /** Running tour, or null. */\n  tourId: string | null;\n  /** Zero-based index within the running tour. */\n  index: number;\n  /** Enabled step count of the running tour — the denominator of \"2 of 6\". */\n  total: number;\n  status: TourStatus;\n};\n\nexport type TourContextValue = TourState & {\n  /**\n   * Start a registered tour. `at` jumps to a step id or index; `force` ignores a\n   * recorded completion, which is what a \"Take a tour\" button passes.\n   */\n  start: (tourId: string, options?: { at?: string | number; force?: boolean }) => void;\n  /** Advance; completes the tour on the last step. */\n  next: () => void;\n  back: () => void;\n  /** Jump within the running tour by step id or zero-based index. */\n  goTo: (step: string | number) => void;\n  /** End the running tour and record the outcome. Defaults to `\"dismissed\"`. */\n  finish: (status?: TourCompletionStatus) => void;\n  /** Has this tour been completed or dismissed at its current `version`? */\n  isFinished: (tourId: string) => boolean;\n  /** Forget completions so tours are eligible again — a \"Replay tours\" button. */\n  reset: (tourId?: string) => void;\n  /** Registered tours, for building a \"Take a tour\" menu. */\n  tours: TourDefinition[];\n};\n\nexport const TourContext = createContext<TourContextValue | null>(null);\n\n/** Access the tour API. Must be called under a `<TourProvider>`. */\nexport function useTour(): TourContextValue {\n  const ctx = useContext(TourContext);\n  if (!ctx) throw new Error(\"useTour must be used within a <TourProvider>\");\n  return ctx;\n}\n"],"names":["createContext","useContext"],"mappings":";;;AAsCO,MAAM,cAAcA,MAAAA,cAAuC,IAAI;AAG/D,SAAS,UAA4B;AAC1C,QAAM,MAAMC,MAAAA,WAAW,WAAW;AAClC,MAAI,CAAC,IAAK,OAAM,IAAI,MAAM,8CAA8C;AACxE,SAAO;AACT;;;"}

package/dist/overlay/tour-context.d.ts

@@ -0,0 +1,40 @@
+import { TourCompletionStatus } from './tour-progress';
+import { TourDefinition } from './tour-types';
+/** Status of the running tour. `waiting` means its anchor has not appeared yet. */
+export type TourStatus = "idle" | "navigating" | "waiting" | "active";
+export type TourState = {
+    /** Running tour, or null. */
+    tourId: string | null;
+    /** Zero-based index within the running tour. */
+    index: number;
+    /** Enabled step count of the running tour — the denominator of "2 of 6". */
+    total: number;
+    status: TourStatus;
+};
+export type TourContextValue = TourState & {
+    /**
+     * Start a registered tour. `at` jumps to a step id or index; `force` ignores a
+     * recorded completion, which is what a "Take a tour" button passes.
+     */
+    start: (tourId: string, options?: {
+        at?: string | number;
+        force?: boolean;
+    }) => void;
+    /** Advance; completes the tour on the last step. */
+    next: () => void;
+    back: () => void;
+    /** Jump within the running tour by step id or zero-based index. */
+    goTo: (step: string | number) => void;
+    /** End the running tour and record the outcome. Defaults to `"dismissed"`. */
+    finish: (status?: TourCompletionStatus) => void;
+    /** Has this tour been completed or dismissed at its current `version`? */
+    isFinished: (tourId: string) => boolean;
+    /** Forget completions so tours are eligible again — a "Replay tours" button. */
+    reset: (tourId?: string) => void;
+    /** Registered tours, for building a "Take a tour" menu. */
+    tours: TourDefinition[];
+};
+export declare const TourContext: import('react').Context<TourContextValue | null>;
+/** Access the tour API. Must be called under a `<TourProvider>`. */
+export declare function useTour(): TourContextValue;
+//# sourceMappingURL=tour-context.d.ts.map

package/dist/overlay/tour-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-context.d.ts","sourceRoot":"","sources":["../../src/overlay/tour-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtE,MAAM,MAAM,SAAS,GAAG;IACtB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG;IACzC;;;OAGG;IACH,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACrF,oDAAoD;IACpD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,mEAAmE;IACnE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC;IACtC,8EAA8E;IAC9E,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAChD,0EAA0E;IAC1E,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,gFAAgF;IAChF,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,2DAA2D;IAC3D,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,WAAW,kDAA+C,CAAC;AAExE,oEAAoE;AACpE,wBAAgB,OAAO,IAAI,gBAAgB,CAI1C"}

package/dist/overlay/tour-context.js

@@ -0,0 +1,12 @@
+import { useContext, createContext } from "react";
+const TourContext = createContext(null);
+function useTour() {
+  const ctx = useContext(TourContext);
+  if (!ctx) throw new Error("useTour must be used within a <TourProvider>");
+  return ctx;
+}
+export {
+  TourContext,
+  useTour
+};
+//# sourceMappingURL=tour-context.js.map

package/dist/overlay/tour-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-context.js","sources":["../../src/overlay/tour-context.ts"],"sourcesContent":["import { createContext, useContext } from \"react\";\nimport type { TourCompletionStatus } from \"./tour-progress\";\nimport type { TourDefinition } from \"./tour-types\";\n\n/** Status of the running tour. `waiting` means its anchor has not appeared yet. */\nexport type TourStatus = \"idle\" | \"navigating\" | \"waiting\" | \"active\";\n\nexport type TourState = {\n  /** Running tour, or null. */\n  tourId: string | null;\n  /** Zero-based index within the running tour. */\n  index: number;\n  /** Enabled step count of the running tour — the denominator of \"2 of 6\". */\n  total: number;\n  status: TourStatus;\n};\n\nexport type TourContextValue = TourState & {\n  /**\n   * Start a registered tour. `at` jumps to a step id or index; `force` ignores a\n   * recorded completion, which is what a \"Take a tour\" button passes.\n   */\n  start: (tourId: string, options?: { at?: string | number; force?: boolean }) => void;\n  /** Advance; completes the tour on the last step. */\n  next: () => void;\n  back: () => void;\n  /** Jump within the running tour by step id or zero-based index. */\n  goTo: (step: string | number) => void;\n  /** End the running tour and record the outcome. Defaults to `\"dismissed\"`. */\n  finish: (status?: TourCompletionStatus) => void;\n  /** Has this tour been completed or dismissed at its current `version`? */\n  isFinished: (tourId: string) => boolean;\n  /** Forget completions so tours are eligible again — a \"Replay tours\" button. */\n  reset: (tourId?: string) => void;\n  /** Registered tours, for building a \"Take a tour\" menu. */\n  tours: TourDefinition[];\n};\n\nexport const TourContext = createContext<TourContextValue | null>(null);\n\n/** Access the tour API. Must be called under a `<TourProvider>`. */\nexport function useTour(): TourContextValue {\n  const ctx = useContext(TourContext);\n  if (!ctx) throw new Error(\"useTour must be used within a <TourProvider>\");\n  return ctx;\n}\n"],"names":[],"mappings":";AAsCO,MAAM,cAAc,cAAuC,IAAI;AAG/D,SAAS,UAA4B;AAC1C,QAAM,MAAM,WAAW,WAAW;AAClC,MAAI,CAAC,IAAK,OAAM,IAAI,MAAM,8CAA8C;AACxE,SAAO;AACT;"}

package/dist/overlay/tour-geometry.cjs

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function anchorRadius(element) {
+  const view = element.ownerDocument.defaultView;
+  if (!view) return 0;
+  const raw = view.getComputedStyle(element).borderTopLeftRadius;
+  if (!raw) return 0;
+  if (raw.endsWith("%")) {
+    const percent = Number.parseFloat(raw);
+    if (!Number.isFinite(percent)) return 0;
+    return element.getBoundingClientRect().width * percent / 100;
+  }
+  const px = Number.parseFloat(raw);
+  return Number.isFinite(px) ? px : 0;
+}
+function spotlightRect(options) {
+  const { anchor, padding, radius, viewport } = options;
+  const left = clamp(anchor.left - padding, 0, viewport.width);
+  const top = clamp(anchor.top - padding, 0, viewport.height);
+  const right = clamp(anchor.right + padding, 0, viewport.width);
+  const bottom = clamp(anchor.bottom + padding, 0, viewport.height);
+  const width = Math.max(right - left, 0);
+  const height = Math.max(bottom - top, 0);
+  const requested = radius ?? 0;
+  return {
+    x: left,
+    y: top,
+    width,
+    height,
+    radius: clamp(requested, 0, Math.min(width, height) / 2)
+  };
+}
+function roundedRectPath(rect) {
+  const { x, y, width, height, radius: r } = rect;
+  if (r <= 0) {
+    return `M${x},${y} H${x + width} V${y + height} H${x} Z`;
+  }
+  return [
+    `M${x + r},${y}`,
+    `H${x + width - r}`,
+    `A${r},${r} 0 0 1 ${x + width},${y + r}`,
+    `V${y + height - r}`,
+    `A${r},${r} 0 0 1 ${x + width - r},${y + height}`,
+    `H${x + r}`,
+    `A${r},${r} 0 0 1 ${x},${y + height - r}`,
+    `V${y + r}`,
+    `A${r},${r} 0 0 1 ${x + r},${y}`,
+    "Z"
+  ].join(" ");
+}
+function spotlightClipPath(options) {
+  const { viewport, cutout } = options;
+  const outer = `M0,0 H${viewport.width} V${viewport.height} H0 Z`;
+  if (!cutout || cutout.width <= 0 || cutout.height <= 0) {
+    return `path(evenodd, "${outer}")`;
+  }
+  return `path(evenodd, "${outer} ${roundedRectPath(cutout)}")`;
+}
+exports.anchorRadius = anchorRadius;
+exports.spotlightClipPath = spotlightClipPath;
+exports.spotlightRect = spotlightRect;
+//# sourceMappingURL=tour-geometry.cjs.map

package/dist/overlay/tour-geometry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-geometry.cjs","sources":["../../src/overlay/tour-geometry.ts"],"sourcesContent":["/**\n * Pure spotlight maths. The dim layer is one full-viewport element clipped with\n * `clip-path: path(evenodd, ...)`: the clipped-away hole does not hit-test, so\n * the dim blocks clicks while the anchor underneath stays live — the pointer\n * semantics come free, which no other cutout technique gives us (a\n * `box-shadow: 0 0 0 9999px` ring has them exactly inverted).\n */\n\nexport type Viewport = { width: number; height: number };\n\nexport type SpotlightRect = {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n  radius: number;\n};\n\nfunction clamp(value: number, min: number, max: number): number {\n  return Math.min(Math.max(value, min), max);\n}\n\n/**\n * The anchor's own computed corner radius, so the cutout traces the control\n * rather than boxing it. A percentage radius resolves against the element's\n * width, matching how the browser paints it.\n */\nexport function anchorRadius(element: HTMLElement): number {\n  const view = element.ownerDocument.defaultView;\n  if (!view) return 0;\n  const raw = view.getComputedStyle(element).borderTopLeftRadius;\n  if (!raw) return 0;\n  if (raw.endsWith(\"%\")) {\n    const percent = Number.parseFloat(raw);\n    if (!Number.isFinite(percent)) return 0;\n    return (element.getBoundingClientRect().width * percent) / 100;\n  }\n  const px = Number.parseFloat(raw);\n  return Number.isFinite(px) ? px : 0;\n}\n\n/**\n * Anchor rect grown by `padding` and clamped to the viewport. The radius grows\n * with the padding so the cutout stays concentric with the control it traces,\n * and is capped at half the shorter side so an over-large radius cannot fold the\n * path in on itself.\n */\nexport function spotlightRect(options: {\n  anchor: DOMRect;\n  padding: number;\n  radius?: number | undefined;\n  viewport: Viewport;\n}): SpotlightRect {\n  const { anchor, padding, radius, viewport } = options;\n  const left = clamp(anchor.left - padding, 0, viewport.width);\n  const top = clamp(anchor.top - padding, 0, viewport.height);\n  const right = clamp(anchor.right + padding, 0, viewport.width);\n  const bottom = clamp(anchor.bottom + padding, 0, viewport.height);\n\n  const width = Math.max(right - left, 0);\n  const height = Math.max(bottom - top, 0);\n  const requested = radius ?? 0;\n\n  return {\n    x: left,\n    y: top,\n    width,\n    height,\n    radius: clamp(requested, 0, Math.min(width, height) / 2),\n  };\n}\n\nfunction roundedRectPath(rect: SpotlightRect): string {\n  const { x, y, width, height, radius: r } = rect;\n  if (r <= 0) {\n    return `M${x},${y} H${x + width} V${y + height} H${x} Z`;\n  }\n  return [\n    `M${x + r},${y}`,\n    `H${x + width - r}`,\n    `A${r},${r} 0 0 1 ${x + width},${y + r}`,\n    `V${y + height - r}`,\n    `A${r},${r} 0 0 1 ${x + width - r},${y + height}`,\n    `H${x + r}`,\n    `A${r},${r} 0 0 1 ${x},${y + height - r}`,\n    `V${y + r}`,\n    `A${r},${r} 0 0 1 ${x + r},${y}`,\n    \"Z\",\n  ].join(\" \");\n}\n\n/**\n * `path(evenodd, \"...\")` for the dim: the viewport rect minus a rounded cutout.\n * A missing or degenerate cutout yields the plain viewport rect, so a zero-size\n * anchor dims the page rather than emitting an invalid path the browser drops\n * (which would leave the dim uncut and the page unusable).\n */\nexport function spotlightClipPath(options: {\n  viewport: Viewport;\n  cutout: SpotlightRect | null;\n}): string {\n  const { viewport, cutout } = options;\n  const outer = `M0,0 H${viewport.width} V${viewport.height} H0 Z`;\n  if (!cutout || cutout.width <= 0 || cutout.height <= 0) {\n    return `path(evenodd, \"${outer}\")`;\n  }\n  return `path(evenodd, \"${outer} ${roundedRectPath(cutout)}\")`;\n}\n"],"names":[],"mappings":";;AAkBA,SAAS,MAAM,OAAe,KAAa,KAAqB;AAC9D,SAAO,KAAK,IAAI,KAAK,IAAI,OAAO,GAAG,GAAG,GAAG;AAC3C;AAOO,SAAS,aAAa,SAA8B;AACzD,QAAM,OAAO,QAAQ,cAAc;AACnC,MAAI,CAAC,KAAM,QAAO;AAClB,QAAM,MAAM,KAAK,iBAAiB,OAAO,EAAE;AAC3C,MAAI,CAAC,IAAK,QAAO;AACjB,MAAI,IAAI,SAAS,GAAG,GAAG;AACrB,UAAM,UAAU,OAAO,WAAW,GAAG;AACrC,QAAI,CAAC,OAAO,SAAS,OAAO,EAAG,QAAO;AACtC,WAAQ,QAAQ,sBAAA,EAAwB,QAAQ,UAAW;AAAA,EAC7D;AACA,QAAM,KAAK,OAAO,WAAW,GAAG;AAChC,SAAO,OAAO,SAAS,EAAE,IAAI,KAAK;AACpC;AAQO,SAAS,cAAc,SAKZ;AAChB,QAAM,EAAE,QAAQ,SAAS,QAAQ,aAAa;AAC9C,QAAM,OAAO,MAAM,OAAO,OAAO,SAAS,GAAG,SAAS,KAAK;AAC3D,QAAM,MAAM,MAAM,OAAO,MAAM,SAAS,GAAG,SAAS,MAAM;AAC1D,QAAM,QAAQ,MAAM,OAAO,QAAQ,SAAS,GAAG,SAAS,KAAK;AAC7D,QAAM,SAAS,MAAM,OAAO,SAAS,SAAS,GAAG,SAAS,MAAM;AAEhE,QAAM,QAAQ,KAAK,IAAI,QAAQ,MAAM,CAAC;AACtC,QAAM,SAAS,KAAK,IAAI,SAAS,KAAK,CAAC;AACvC,QAAM,YAAY,UAAU;AAE5B,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG;AAAA,IACH;AAAA,IACA;AAAA,IACA,QAAQ,MAAM,WAAW,GAAG,KAAK,IAAI,OAAO,MAAM,IAAI,CAAC;AAAA,EAAA;AAE3D;AAEA,SAAS,gBAAgB,MAA6B;AACpD,QAAM,EAAE,GAAG,GAAG,OAAO,QAAQ,QAAQ,MAAM;AAC3C,MAAI,KAAK,GAAG;AACV,WAAO,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,IAAI,MAAM,KAAK,CAAC;AAAA,EACtD;AACA,SAAO;AAAA,IACL,IAAI,IAAI,CAAC,IAAI,CAAC;AAAA,IACd,IAAI,IAAI,QAAQ,CAAC;AAAA,IACjB,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,KAAK,IAAI,IAAI,CAAC;AAAA,IACtC,IAAI,IAAI,SAAS,CAAC;AAAA,IAClB,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,QAAQ,CAAC,IAAI,IAAI,MAAM;AAAA,IAC/C,IAAI,IAAI,CAAC;AAAA,IACT,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,SAAS,CAAC;AAAA,IACvC,IAAI,IAAI,CAAC;AAAA,IACT,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC;AAAA,IAC9B;AAAA,EAAA,EACA,KAAK,GAAG;AACZ;AAQO,SAAS,kBAAkB,SAGvB;AACT,QAAM,EAAE,UAAU,OAAA,IAAW;AAC7B,QAAM,QAAQ,SAAS,SAAS,KAAK,KAAK,SAAS,MAAM;AACzD,MAAI,CAAC,UAAU,OAAO,SAAS,KAAK,OAAO,UAAU,GAAG;AACtD,WAAO,kBAAkB,KAAK;AAAA,EAChC;AACA,SAAO,kBAAkB,KAAK,IAAI,gBAAgB,MAAM,CAAC;AAC3D;;;;"}

package/dist/overlay/tour-geometry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure spotlight maths. The dim layer is one full-viewport element clipped with
+ * `clip-path: path(evenodd, ...)`: the clipped-away hole does not hit-test, so
+ * the dim blocks clicks while the anchor underneath stays live — the pointer
+ * semantics come free, which no other cutout technique gives us (a
+ * `box-shadow: 0 0 0 9999px` ring has them exactly inverted).
+ */
+export type Viewport = {
+    width: number;
+    height: number;
+};
+export type SpotlightRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+};
+/**
+ * The anchor's own computed corner radius, so the cutout traces the control
+ * rather than boxing it. A percentage radius resolves against the element's
+ * width, matching how the browser paints it.
+ */
+export declare function anchorRadius(element: HTMLElement): number;
+/**
+ * Anchor rect grown by `padding` and clamped to the viewport. The radius grows
+ * with the padding so the cutout stays concentric with the control it traces,
+ * and is capped at half the shorter side so an over-large radius cannot fold the
+ * path in on itself.
+ */
+export declare function spotlightRect(options: {
+    anchor: DOMRect;
+    padding: number;
+    radius?: number | undefined;
+    viewport: Viewport;
+}): SpotlightRect;
+/**
+ * `path(evenodd, "...")` for the dim: the viewport rect minus a rounded cutout.
+ * A missing or degenerate cutout yields the plain viewport rect, so a zero-size
+ * anchor dims the page rather than emitting an invalid path the browser drops
+ * (which would leave the dim uncut and the page unusable).
+ */
+export declare function spotlightClipPath(options: {
+    viewport: Viewport;
+    cutout: SpotlightRect | null;
+}): string;
+//# sourceMappingURL=tour-geometry.d.ts.map