@flowsterix/react 0.4.2 → 0.6.0

package/dist/index.cjs

@@ -72,7 +72,17 @@ var defaultLabels = {
   ariaStepProgress: ({ current, total }) => `Step ${current} of ${total}`,
   ariaTimeRemaining: ({ ms }) => `${Math.ceil(ms / 1e3)} seconds remaining`,
   ariaDelayProgress: "Auto-advance progress",
-  formatTimeRemaining: ({ ms }) => `${Math.ceil(ms / 1e3)}s remaining`
+  formatTimeRemaining: ({ ms }) => `${Math.ceil(ms / 1e3)}s remaining`,
+  targetIssue: {
+    missingTitle: "Target not visible",
+    missingBody: "The target element is not currently visible. Make sure the UI piece is mounted and displayed.",
+    missingHint: "Showing the last known position until the element returns.",
+    hiddenTitle: "Target not visible",
+    hiddenBody: "The target element is not currently visible. Make sure the UI piece is mounted and displayed.",
+    hiddenHint: "Showing the last known position until the element returns.",
+    detachedTitle: "Target left the page",
+    detachedBody: "Navigate back to the screen that contains this element or reopen it before continuing the tour."
+  }
 };
 var LabelsContext = (0, import_react.createContext)(defaultLabels);
 var LabelsProvider = LabelsContext.Provider;
@@ -1663,7 +1673,7 @@ var useTourTarget = () => {
 };
 
 // src/hooks/useHudState.ts
-var import_react9 = require("react");
+var import_react10 = require("react");
 
 // src/hooks/useAdvanceRules.ts
 var import_react6 = require("react");
@@ -1878,6 +1888,7 @@ var useAdvanceRules = (target) => {
 // src/hooks/useHiddenTargetFallback.ts
 var import_react7 = require("react");
 var DEFAULT_DELAY_MS = 900;
+var DEFAULT_GRACE_PERIOD_MS = 400;
 var useHiddenTargetFallback = ({
   step,
   target,
@@ -1885,7 +1896,9 @@ var useHiddenTargetFallback = ({
   onSkip
 }) => {
   const [usingScreenFallback, setUsingScreenFallback] = (0, import_react7.useState)(false);
+  const [isInGracePeriod, setIsInGracePeriod] = (0, import_react7.useState)(false);
   const timeoutRef = (0, import_react7.useRef)(null);
+  const graceTimeoutRef = (0, import_react7.useRef)(null);
   const skipTriggeredRef = (0, import_react7.useRef)(false);
   const hiddenMode = step?.targetBehavior?.hidden ?? "screen";
   const hiddenDelayMs = Math.max(
@@ -1898,26 +1911,44 @@ var useHiddenTargetFallback = ({
       timeoutRef.current = null;
     }
   };
+  const clearGraceTimeout = () => {
+    if (graceTimeoutRef.current !== null) {
+      globalThis.clearTimeout(graceTimeoutRef.current);
+      graceTimeoutRef.current = null;
+    }
+  };
   (0, import_react7.useEffect)(() => {
     skipTriggeredRef.current = false;
     setUsingScreenFallback(false);
+    setIsInGracePeriod(false);
     clearPendingTimeout();
-    return clearPendingTimeout;
+    clearGraceTimeout();
+    return () => {
+      clearPendingTimeout();
+      clearGraceTimeout();
+    };
   }, [step?.id]);
   (0, import_react7.useEffect)(() => {
     if (!isBrowser) return void 0;
     if (!step) return void 0;
     clearPendingTimeout();
+    clearGraceTimeout();
     const isHiddenOrDetached = (target.visibility === "hidden" || target.visibility === "detached") && target.status === "ready";
     const isMissingWithNoRect = target.visibility === "missing" && target.status === "resolving" && target.rect === null && target.lastResolvedRect === null;
-    const shouldHandleHiddenTarget = !target.isScreen && (isHiddenOrDetached || isMissingWithNoRect);
+    const isMissingAfterNavigation = target.visibility === "missing" && target.status === "resolving" && target.rect === null;
+    const shouldHandleHiddenTarget = !target.isScreen && (isHiddenOrDetached || isMissingWithNoRect || isMissingAfterNavigation);
     if (!shouldHandleHiddenTarget) {
       setUsingScreenFallback(false);
+      setIsInGracePeriod(false);
       return void 0;
     }
+    setIsInGracePeriod(true);
     if (hiddenMode !== "screen") {
       setUsingScreenFallback(false);
     }
+    graceTimeoutRef.current = globalThis.setTimeout(() => {
+      setIsInGracePeriod(false);
+    }, DEFAULT_GRACE_PERIOD_MS);
     timeoutRef.current = globalThis.setTimeout(() => {
       if (hiddenMode === "screen") {
         setUsingScreenFallback(true);
@@ -1928,7 +1959,10 @@ var useHiddenTargetFallback = ({
         onSkip();
       }
     }, hiddenDelayMs);
-    return clearPendingTimeout;
+    return () => {
+      clearPendingTimeout();
+      clearGraceTimeout();
+    };
   }, [
     step,
     target.visibility,
@@ -1956,18 +1990,82 @@ var useHiddenTargetFallback = ({
   }, [target, usingScreenFallback, viewportRect]);
   return {
     target: resolvedTarget,
-    usingScreenFallback
+    usingScreenFallback,
+    isInGracePeriod
   };
 };
 
-// src/hooks/useViewportRect.ts
+// src/hooks/useRouteMismatch.ts
 var import_react8 = require("react");
+
+// src/router/utils.ts
+var ensurePrefix = (value, prefix) => value.startsWith(prefix) ? value : `${prefix}${value}`;
+var isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+var toSearchString = (value) => {
+  if (!isNonEmptyString(value)) {
+    if (value instanceof URLSearchParams) {
+      const serialized = value.toString();
+      return serialized.length > 0 ? `?${serialized}` : "";
+    }
+    if (typeof value === "object" && value !== null) {
+      try {
+        const params = new URLSearchParams();
+        for (const [key, raw] of Object.entries(
+          value
+        )) {
+          if (raw === void 0 || raw === null) continue;
+          params.set(key, String(raw));
+        }
+        const serialized = params.toString();
+        return serialized.length > 0 ? `?${serialized}` : "";
+      } catch {
+        return "";
+      }
+    }
+    return "";
+  }
+  if (value === "?") return "";
+  return value.startsWith("?") ? value : ensurePrefix(value, "?");
+};
+var toHashString = (value) => {
+  if (!isNonEmptyString(value)) {
+    return "";
+  }
+  if (value === "#") return "";
+  return value.startsWith("#") ? value : ensurePrefix(value, "#");
+};
+var createPathString = (pathname, search, hash) => {
+  const normalizedPath = isNonEmptyString(pathname) ? pathname.startsWith("/") ? pathname : `/${pathname}` : "/";
+  const searchPart = toSearchString(search);
+  const hashPart = toHashString(hash);
+  return `${normalizedPath}${searchPart}${hashPart}`;
+};
+
+// src/hooks/useRouteMismatch.ts
+var useRouteMismatch = (step) => {
+  const [currentPath, setCurrentPath] = (0, import_react8.useState)(() => getCurrentRoutePath());
+  (0, import_react8.useEffect)(() => {
+    return subscribeToRouteChanges((path) => {
+      setCurrentPath(path);
+    });
+  }, []);
+  const expectedRoute = step?.route;
+  const isRouteMismatch = step !== null && expectedRoute !== void 0 && !matchRoute({ pattern: expectedRoute, path: currentPath });
+  return {
+    isRouteMismatch,
+    currentPath,
+    expectedRoute
+  };
+};
+
+// src/hooks/useViewportRect.ts
+var import_react9 = require("react");
 var useViewportRect = () => {
-  const [viewport, setViewport] = (0, import_react8.useState)(
+  const [viewport, setViewport] = (0, import_react9.useState)(
     () => getViewportRect()
   );
-  const rafRef = (0, import_react8.useRef)(null);
-  (0, import_react8.useEffect)(() => {
+  const rafRef = (0, import_react9.useRef)(null);
+  (0, import_react9.useEffect)(() => {
     if (!isBrowser) return;
     const updateViewport = () => {
       rafRef.current = null;
@@ -2009,12 +2107,12 @@ var normalizeFlowFilter = (value) => {
 };
 var useHudState = (options = {}) => {
   const { flowId } = options;
-  const flowFilter = (0, import_react9.useMemo)(() => normalizeFlowFilter(flowId), [flowId]);
-  const { state, activeStep, activeFlowId, flows, next, complete } = useTour();
+  const flowFilter = (0, import_react10.useMemo)(() => normalizeFlowFilter(flowId), [flowId]);
+  const { state, activeStep, activeFlowId, flows, next, complete, pause, resume } = useTour();
   const target = useTourTarget();
   const viewportRect = useViewportRect();
   useAdvanceRules(target);
-  const matchesFlowFilter = (0, import_react9.useMemo)(() => {
+  const matchesFlowFilter = (0, import_react10.useMemo)(() => {
     if (!flowFilter || flowFilter.length === 0) return true;
     if (!activeFlowId) return false;
     return flowFilter.includes(activeFlowId);
@@ -2022,15 +2120,15 @@ var useHudState = (options = {}) => {
   const isRunning = state?.status === "running";
   const runningState = isRunning && matchesFlowFilter ? state : null;
   const runningStep = runningState && activeStep ? activeStep : null;
-  const [shouldRender, setShouldRender] = (0, import_react9.useState)(
+  const [shouldRender, setShouldRender] = (0, import_react10.useState)(
     Boolean(runningStep)
   );
-  (0, import_react9.useEffect)(() => {
+  (0, import_react10.useEffect)(() => {
     if (runningStep) {
       setShouldRender(true);
     }
   }, [runningStep?.id]);
-  (0, import_react9.useEffect)(() => {
+  (0, import_react10.useEffect)(() => {
     if (!shouldRender) return;
     if (runningStep) return;
     if (target.status !== "idle") return;
@@ -2041,7 +2139,20 @@ var useHudState = (options = {}) => {
       window.clearTimeout(timeoutId);
     };
   }, [runningStep, shouldRender, target.status]);
-  const skipHiddenStep = (0, import_react9.useCallback)(() => {
+  const { isRouteMismatch, currentPath } = useRouteMismatch(activeStep);
+  const pausedForMissingTargetRef = (0, import_react10.useRef)(null);
+  (0, import_react10.useEffect)(() => {
+    if (!isRouteMismatch) return;
+    if (!runningState || runningState.status !== "running") return;
+    pause();
+  }, [isRouteMismatch, runningState, pause]);
+  (0, import_react10.useEffect)(() => {
+    if (isRouteMismatch) return;
+    if (pausedForMissingTargetRef.current !== null) return;
+    if (!state || state.status !== "paused") return;
+    resume();
+  }, [isRouteMismatch, state, resume]);
+  const skipHiddenStep = (0, import_react10.useCallback)(() => {
     if (!runningState || runningState.status !== "running") return;
     if (!activeFlowId) return;
     const flow = flows.get(activeFlowId);
@@ -2053,12 +2164,41 @@ var useHudState = (options = {}) => {
       next();
     }
   }, [activeFlowId, complete, flows, next, runningState]);
-  const { target: hudTarget } = useHiddenTargetFallback({
+  const { target: hudTarget, isInGracePeriod } = useHiddenTargetFallback({
     step: runningStep,
     target,
     viewportRect,
     onSkip: skipHiddenStep
   });
+  (0, import_react10.useEffect)(() => {
+    if (isRouteMismatch) return;
+    if (activeStep?.route !== void 0) return;
+    if (isInGracePeriod) return;
+    if (target.visibility !== "missing") return;
+    if (target.isScreen) return;
+    if (!runningState || runningState.status !== "running") return;
+    pausedForMissingTargetRef.current = currentPath;
+    pause();
+  }, [
+    isRouteMismatch,
+    activeStep?.route,
+    isInGracePeriod,
+    target.visibility,
+    target.isScreen,
+    runningState,
+    currentPath,
+    pause
+  ]);
+  (0, import_react10.useEffect)(() => {
+    if (pausedForMissingTargetRef.current === null) return;
+    if (!state || state.status !== "paused") return;
+    if (currentPath === pausedForMissingTargetRef.current) return;
+    pausedForMissingTargetRef.current = null;
+    resume();
+  }, [currentPath, state, resume]);
+  (0, import_react10.useEffect)(() => {
+    pausedForMissingTargetRef.current = null;
+  }, [activeStep?.id]);
   const canRenderStep = Boolean(runningStep && runningState);
   const focusTrapActive = canRenderStep;
   const flowHudOptions = matchesFlowFilter && activeFlowId ? flows.get(activeFlowId)?.hud ?? null : null;
@@ -2075,29 +2215,30 @@ var useHudState = (options = {}) => {
     flowHudOptions,
     hudRenderMode,
     matchesFlowFilter,
-    activeFlowId
+    activeFlowId,
+    isInGracePeriod
   };
 };
 
 // src/hooks/useHudDescription.ts
-var import_react10 = require("react");
+var import_react11 = require("react");
 var sanitizeForId = (value) => {
   const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return normalized.length > 0 ? normalized : "step";
 };
 var useHudDescription = (options) => {
   const { step, fallbackAriaDescribedBy } = options;
-  const targetDescription = (0, import_react10.useMemo)(() => {
+  const targetDescription = (0, import_react11.useMemo)(() => {
     if (!step) return null;
     if (typeof step.target !== "object") return null;
     const description = step.target.description;
     return typeof description === "string" ? description : null;
   }, [step]);
-  const descriptionId = (0, import_react10.useMemo)(() => {
+  const descriptionId = (0, import_react11.useMemo)(() => {
     if (!step || !targetDescription) return void 0;
     return `tour-step-${sanitizeForId(step.id)}-description`;
   }, [step, targetDescription]);
-  const combinedAriaDescribedBy = (0, import_react10.useMemo)(() => {
+  const combinedAriaDescribedBy = (0, import_react11.useMemo)(() => {
     const parts = [fallbackAriaDescribedBy, descriptionId].filter(Boolean);
     return parts.length > 0 ? parts.join(" ") : void 0;
   }, [descriptionId, fallbackAriaDescribedBy]);
@@ -2109,10 +2250,10 @@ var useHudDescription = (options) => {
 };
 
 // src/hooks/useHudShortcuts.ts
-var import_react12 = require("react");
+var import_react13 = require("react");
 
 // src/hooks/useTourControls.ts
-var import_react11 = require("react");
+var import_react12 = require("react");
 var hasManualAdvance = (rules) => rules.some((rule) => rule.type === "manual");
 var didPreviousAdvanceViaRoute = (rules) => rules.some((rule) => rule.type === "route");
 var didPreviousAdvanceViaTargetEvent = (rules) => rules.some((rule) => rule.type === "event" && rule.on === "target");
@@ -2128,7 +2269,7 @@ var useTourControls = () => {
     flows,
     activeStep
   } = tour;
-  const computed = (0, import_react11.useMemo)(() => {
+  const computed = (0, import_react12.useMemo)(() => {
     if (!state || state.status !== "running" || !activeStep) {
       return {
         isActive: false,
@@ -2177,11 +2318,11 @@ var useTourControls = () => {
   } = computed;
   const canGoBack = showBackButton && !backDisabled;
   const canGoNext = showNextButton && !nextDisabled;
-  const goBack = (0, import_react11.useCallback)(() => {
+  const goBack = (0, import_react12.useCallback)(() => {
     if (!canGoBack) return;
     back();
   }, [back, canGoBack]);
-  const goNext = (0, import_react11.useCallback)(() => {
+  const goNext = (0, import_react12.useCallback)(() => {
     if (!canGoNext) return;
     if (isLast) {
       complete();
@@ -2189,7 +2330,7 @@ var useTourControls = () => {
       next();
     }
   }, [canGoNext, complete, isLast, next]);
-  return (0, import_react11.useMemo)(
+  return (0, import_react12.useMemo)(
     () => ({
       showBackButton,
       backDisabled,
@@ -2234,7 +2375,7 @@ var useHudShortcuts = (target, options) => {
   const escapeEnabled = options?.escape ?? true;
   const { state } = useTour();
   const { cancel, canGoBack, goBack, canGoNext, goNext, isActive } = useTourControls();
-  (0, import_react12.useEffect)(() => {
+  (0, import_react13.useEffect)(() => {
     if (!isBrowser) return void 0;
     if (!enabled) return void 0;
     if (!target) return void 0;
@@ -2298,10 +2439,10 @@ var useHudShortcuts = (target, options) => {
 };
 
 // src/hooks/useTourHud.ts
-var import_react15 = require("react");
+var import_react16 = require("react");
 
 // src/hooks/useBodyScrollLock.ts
-var import_react13 = require("react");
+var import_react14 = require("react");
 var lockCount = 0;
 var previousOverflow = null;
 var acquireLock = () => {
@@ -2322,7 +2463,7 @@ var releaseLock = () => {
   }
 };
 var useBodyScrollLock = (enabled) => {
-  (0, import_react13.useEffect)(() => {
+  (0, import_react14.useEffect)(() => {
     if (!enabled) return;
     acquireLock();
     return () => {
@@ -2332,42 +2473,45 @@ var useBodyScrollLock = (enabled) => {
 };
 
 // src/hooks/useHudTargetIssue.ts
-var import_react14 = require("react");
-var deriveTargetIssue = (target) => {
+var import_react15 = require("react");
+var deriveTargetIssue = (params) => {
+  const { target, labels } = params;
   if (target.isScreen) return null;
   if (target.status === "idle") return null;
   switch (target.visibility) {
     case "missing":
       return {
         type: "missing",
-        title: "Looking for the target",
-        body: "Flowsterix is still trying to find this element. Make sure the UI piece is mounted or adjust the selector.",
-        hint: target.rectSource === "stored" ? "Showing the last known position until the element returns." : void 0
+        title: labels.targetIssue.missingTitle,
+        body: labels.targetIssue.missingBody,
+        hint: target.rectSource === "stored" ? labels.targetIssue.missingHint : void 0
       };
     case "hidden":
       return {
         type: "hidden",
-        title: "Target is hidden",
-        body: "The element exists but is currently hidden, collapsed, or zero-sized. Expand it so the highlight can lock on."
+        title: labels.targetIssue.hiddenTitle,
+        body: labels.targetIssue.hiddenBody,
+        hint: target.rectSource === "stored" ? labels.targetIssue.hiddenHint : void 0
       };
     case "detached":
       return {
         type: "detached",
-        title: "Target left the page",
-        body: "Navigate back to the screen that contains this element or reopen it before continuing the tour."
+        title: labels.targetIssue.detachedTitle,
+        body: labels.targetIssue.detachedBody
       };
     default:
       return null;
   }
 };
 var useHudTargetIssue = (target, options) => {
+  const labels = useTourLabels();
   const delayMs = Math.max(0, options?.delayMs ?? 500);
-  const [armed, setArmed] = (0, import_react14.useState)(false);
-  const rawIssue = (0, import_react14.useMemo)(
-    () => deriveTargetIssue(target),
-    [target.isScreen, target.rectSource, target.status, target.visibility]
+  const [armed, setArmed] = (0, import_react15.useState)(false);
+  const rawIssue = (0, import_react15.useMemo)(
+    () => deriveTargetIssue({ target, labels }),
+    [target.isScreen, target.rectSource, target.status, target.visibility, labels]
   );
-  (0, import_react14.useEffect)(() => {
+  (0, import_react15.useEffect)(() => {
     if (!rawIssue) {
       setArmed(false);
       return;
@@ -2401,7 +2545,7 @@ var useTourHud = (options = {}) => {
   const { backdropInteraction, lockBodyScroll } = useTour();
   const hudState = useHudState();
   const disableDefaultHud = hudState.hudRenderMode === "none";
-  const [popoverNode, setPopoverNode] = (0, import_react15.useState)(null);
+  const [popoverNode, setPopoverNode] = (0, import_react16.useState)(null);
   const popoverOptions = hudState.flowHudOptions?.popover;
   const description = useHudDescription({
     step: hudState.runningStep,
@@ -2425,7 +2569,7 @@ var useTourHud = (options = {}) => {
     radius: overlayRadius,
     interactionMode: hudState.flowHudOptions?.backdrop?.interaction ?? backdropInteraction
   };
-  const popover = (0, import_react15.useMemo)(() => {
+  const popover = (0, import_react16.useMemo)(() => {
     return {
       offset: popoverOptions?.offset ?? 16,
       role: popoverOptions?.role ?? "dialog",
@@ -2437,13 +2581,13 @@ var useTourHud = (options = {}) => {
       placement: hudState.runningStep?.placement
     };
   }, [hudState.runningStep?.placement, popoverOptions]);
-  const descriptionResult = (0, import_react15.useMemo)(() => {
+  const descriptionResult = (0, import_react16.useMemo)(() => {
     return {
       ...description,
       text: description.targetDescription
     };
   }, [description]);
-  const focusManager = (0, import_react15.useMemo)(
+  const focusManager = (0, import_react16.useMemo)(
     () => ({
       active: hudState.focusTrapActive,
       target: hudState.hudTarget,
@@ -2473,7 +2617,7 @@ var useTourHud = (options = {}) => {
 };
 
 // src/hooks/useTourOverlay.ts
-var import_react16 = require("react");
+var import_react17 = require("react");
 var DEFAULT_PADDING = 12;
 var DEFAULT_RADIUS = 12;
 var DEFAULT_EDGE_BUFFER = 0;
@@ -2483,11 +2627,12 @@ var useTourOverlay = (options) => {
     padding = DEFAULT_PADDING,
     radius = DEFAULT_RADIUS,
     edgeBuffer = DEFAULT_EDGE_BUFFER,
-    interactionMode = "passthrough"
+    interactionMode = "passthrough",
+    isInGracePeriod = false
   } = options;
-  const hasShownRef = (0, import_react16.useRef)(false);
-  const lastReadyTargetRef = (0, import_react16.useRef)(null);
-  (0, import_react16.useEffect)(() => {
+  const hasShownRef = (0, import_react17.useRef)(false);
+  const lastReadyTargetRef = (0, import_react17.useRef)(null);
+  (0, import_react17.useEffect)(() => {
     if (!isBrowser) return;
     if (target.status === "ready") {
       hasShownRef.current = true;
@@ -2537,15 +2682,15 @@ var useTourOverlay = (options) => {
     height: highlightHeight,
     radius: highlightRadius
   } : null;
-  const maskCapable = (0, import_react16.useMemo)(() => supportsMasking(), []);
-  const isActive = target.status === "ready" || target.status === "resolving" && cachedTarget !== null;
+  const maskCapable = (0, import_react17.useMemo)(() => supportsMasking(), []);
+  const isActive = target.status === "ready" || target.status === "resolving" && cachedTarget !== null || isInGracePeriod;
   const shouldMask = maskCapable && isActive;
-  const maskId = (0, import_react16.useMemo)(
+  const maskId = (0, import_react17.useMemo)(
     () => `tour-overlay-mask-${Math.random().toString(36).slice(2, 10)}`,
     []
   );
   const maskUrl = shouldMask ? `url(#${maskId})` : void 0;
-  const fallbackSegments = (0, import_react16.useMemo)(() => {
+  const fallbackSegments = (0, import_react17.useMemo)(() => {
     if (!isActive || shouldMask || !hasHighlightBounds || !highlightRect) {
       return null;
     }
@@ -2598,7 +2743,7 @@ var useTourOverlay = (options) => {
     viewport.height,
     viewport.width
   ]);
-  const blockerSegments = (0, import_react16.useMemo)(() => {
+  const blockerSegments = (0, import_react17.useMemo)(() => {
     if (interactionMode !== "block") {
       return null;
     }
@@ -2723,12 +2868,12 @@ var useRadixDialogAdapter = (options = {}) => {
 };
 
 // src/hooks/useDelayAdvance.ts
-var import_react17 = require("react");
+var import_react18 = require("react");
 var getTimestamp = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 var useDelayAdvance = () => {
   const { delayInfo, activeStep, state } = useTour();
-  const [now, setNow] = (0, import_react17.useState)(() => getTimestamp());
-  (0, import_react17.useEffect)(() => {
+  const [now, setNow] = (0, import_react18.useState)(() => getTimestamp());
+  (0, import_react18.useEffect)(() => {
     if (!delayInfo) return;
     if (!activeStep || activeStep.id !== delayInfo.stepId) return;
     if (!state || state.status !== "running") return;
@@ -2745,12 +2890,12 @@ var useDelayAdvance = () => {
       }
     };
   }, [delayInfo, activeStep, state]);
-  (0, import_react17.useEffect)(() => {
+  (0, import_react18.useEffect)(() => {
     if (!delayInfo) {
       setNow(getTimestamp());
     }
   }, [delayInfo]);
-  return (0, import_react17.useMemo)(() => {
+  return (0, import_react18.useMemo)(() => {
     const matchingStep = !!delayInfo && !!activeStep && activeStep.id === delayInfo.stepId;
     const isRunning = matchingStep && state?.status === "running";
     if (!delayInfo) {
@@ -2803,9 +2948,9 @@ var useDelayAdvance = () => {
 };
 
 // src/components/OverlayBackdrop.tsx
-var import_react18 = require("react");
+var import_react19 = require("react");
 var import_react_dom = require("react-dom");
-var import_react19 = require("motion/react");
+var import_react20 = require("motion/react");
 var import_jsx_runtime3 = require("react/jsx-runtime");
 var styles = {
   root: {
@@ -2892,9 +3037,9 @@ var OverlayBackdrop = ({
     viewport
   } = overlay;
   const hasHighlightBounds = Boolean(highlight.rect);
-  const prevScreenTargetRef = (0, import_react18.useRef)(null);
+  const prevScreenTargetRef = (0, import_react19.useRef)(null);
   const shouldSnapHighlight = prevScreenTargetRef.current === true && !highlight.isScreen && hasHighlightBounds;
-  (0, import_react18.useEffect)(() => {
+  (0, import_react19.useEffect)(() => {
     prevScreenTargetRef.current = highlight.isScreen;
   }, [highlight.isScreen]);
   const resolvedBlur = typeof blurAmount === "number" ? `${blurAmount}px` : "0px";
@@ -2962,7 +3107,7 @@ var OverlayBackdrop = ({
         "aria-hidden": ariaHidden,
         "data-tour-overlay": "",
         children: [
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react19.AnimatePresence, { mode: "popLayout", children: shouldMask ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react20.AnimatePresence, { mode: "popLayout", children: shouldMask ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             MotionSvg,
             {
               width: "0",
@@ -3021,7 +3166,7 @@ var OverlayBackdrop = ({
             },
             "tour-mask"
           ) : null }),
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react19.AnimatePresence, { mode: "popLayout", children: showBaseOverlay ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react20.AnimatePresence, { mode: "popLayout", children: showBaseOverlay ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             MotionDiv,
             {
               className: overlayClassName,
@@ -3049,7 +3194,7 @@ var OverlayBackdrop = ({
             },
             "tour-overlay"
           ) : null }),
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react19.AnimatePresence, { mode: "popLayout", children: fallbackSegments ? fallbackSegments.map((segment) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react20.AnimatePresence, { mode: "popLayout", children: fallbackSegments ? fallbackSegments.map((segment) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             MotionDiv,
             {
               className: segmentClassName,
@@ -3100,7 +3245,7 @@ var OverlayBackdrop = ({
               ))
             }
           ) : null,
-          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react19.AnimatePresence, { mode: "popLayout", children: showHighlightRing && isActive && hasHighlightBounds ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(import_react20.AnimatePresence, { mode: "popLayout", children: showHighlightRing && isActive && hasHighlightBounds ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             MotionDiv,
             {
               className: ringClassName,
@@ -3131,7 +3276,7 @@ var OverlayBackdrop = ({
 };
 
 // src/components/TourPopoverPortal.tsx
-var import_react20 = require("react");
+var import_react21 = require("react");
 var import_react_dom2 = require("react-dom");
 var import_dom13 = require("@floating-ui/dom");
 var FLOATING_OFFSET = 8;
@@ -3192,12 +3337,12 @@ var TourPopoverPortal = ({
   const popoverContentTransition = transitionsOverride?.popoverContent ?? adapter.transitions.popoverContent ?? DEFAULT_POPOVER_CONTENT_TRANSITION;
   const viewport = useViewportRect();
   const prefersMobileLayout = viewport.width <= MOBILE_BREAKPOINT || viewport.height <= MOBILE_HEIGHT_BREAKPOINT;
-  const prefersMobileRef = (0, import_react20.useRef)(prefersMobileLayout);
-  (0, import_react20.useEffect)(() => {
+  const prefersMobileRef = (0, import_react21.useRef)(prefersMobileLayout);
+  (0, import_react21.useEffect)(() => {
     prefersMobileRef.current = prefersMobileLayout;
   }, [prefersMobileLayout]);
-  const lastReadyTargetRef = (0, import_react20.useRef)(null);
-  (0, import_react20.useEffect)(() => {
+  const lastReadyTargetRef = (0, import_react21.useRef)(null);
+  (0, import_react21.useEffect)(() => {
     if (target.status === "ready" && target.rect) {
       lastReadyTargetRef.current = {
         rect: { ...target.rect },
@@ -3210,9 +3355,10 @@ var TourPopoverPortal = ({
   const cachedTarget = lastReadyTargetRef.current;
   const resolvedRect = target.rect ?? target.lastResolvedRect ?? cachedTarget?.rect ?? null;
   const resolvedIsScreen = target.status === "ready" ? target.isScreen : cachedTarget?.isScreen ?? target.isScreen;
+  const shouldHidePopover = !resolvedRect && !target.isScreen;
   const fallbackRect = resolvedRect ?? viewport;
   const fallbackIsScreen = resolvedIsScreen;
-  const [floatingSize, setFloatingSize] = (0, import_react20.useState)(null);
+  const [floatingSize, setFloatingSize] = (0, import_react21.useState)(null);
   const clampVertical = (value) => Math.min(viewport.height - 24, Math.max(24, value));
   const clampHorizontal = (value) => Math.min(viewport.width - 24, Math.max(24, value));
   const screenCenteredTop = viewport.height / 2 - (floatingSize?.height ?? 0) / 2;
@@ -3223,7 +3369,7 @@ var TourPopoverPortal = ({
   const leftBase = fallbackIsScreen ? screenCenteredLeft : fallbackRect.left + fallbackRect.width / 2 - floatingWidth / 2;
   const left = clampHorizontal(leftBase);
   const fallbackTransform = "translate3d(0px, 0px, 0px)";
-  const fallbackPosition = (0, import_react20.useMemo)(
+  const fallbackPosition = (0, import_react21.useMemo)(
     () => ({
       top,
       left,
@@ -3231,7 +3377,7 @@ var TourPopoverPortal = ({
     }),
     [fallbackTransform, left, top]
   );
-  const centerInitialPosition = (0, import_react20.useMemo)(
+  const centerInitialPosition = (0, import_react21.useMemo)(
     () => ({
       top: viewport.height / 2,
       left: viewport.width / 2,
@@ -3239,23 +3385,23 @@ var TourPopoverPortal = ({
     }),
     [viewport.height, viewport.width]
   );
-  const floatingRef = (0, import_react20.useRef)(null);
-  const cachedFloatingPositionRef = (0, import_react20.useRef)(null);
-  const appliedFloatingCacheRef = (0, import_react20.useRef)(null);
-  const deferredScreenSnapRef = (0, import_react20.useRef)(null);
-  const [layoutMode, setLayoutMode] = (0, import_react20.useState)(
+  const floatingRef = (0, import_react21.useRef)(null);
+  const cachedFloatingPositionRef = (0, import_react21.useRef)(null);
+  const appliedFloatingCacheRef = (0, import_react21.useRef)(null);
+  const deferredScreenSnapRef = (0, import_react21.useRef)(null);
+  const [layoutMode, setLayoutMode] = (0, import_react21.useState)(
     () => prefersMobileLayout ? "mobile" : "floating"
   );
-  const [floatingPosition, setFloatingPosition] = (0, import_react20.useState)(fallbackPosition);
-  const [dragPosition, setDragPosition] = (0, import_react20.useState)(null);
-  const [isDragging, setIsDragging] = (0, import_react20.useState)(false);
-  const dragStateRef = (0, import_react20.useRef)(null);
-  const overflowRetryRef = (0, import_react20.useRef)({
+  const [floatingPosition, setFloatingPosition] = (0, import_react21.useState)(fallbackPosition);
+  const [dragPosition, setDragPosition] = (0, import_react21.useState)(null);
+  const [isDragging, setIsDragging] = (0, import_react21.useState)(false);
+  const dragStateRef = (0, import_react21.useRef)(null);
+  const overflowRetryRef = (0, import_react21.useRef)({
     stepId: null,
     attempts: 0
   });
-  const overflowRetryTimeoutRef = (0, import_react20.useRef)(null);
-  (0, import_react20.useLayoutEffect)(() => {
+  const overflowRetryTimeoutRef = (0, import_react21.useRef)(null);
+  (0, import_react21.useLayoutEffect)(() => {
     if (!isBrowser) return;
     const node = floatingRef.current;
     if (!node) return;
@@ -3274,25 +3420,25 @@ var TourPopoverPortal = ({
   const autoAlignment = resolvedPlacement.endsWith(
     "-start"
   ) ? "start" : resolvedPlacement.endsWith("-end") ? "end" : void 0;
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     setDragPosition(null);
     setLayoutMode(prefersMobileRef.current ? "mobile" : "floating");
     cachedFloatingPositionRef.current = null;
     appliedFloatingCacheRef.current = null;
   }, [target.stepId]);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     if (layoutMode !== "manual") {
       setDragPosition(null);
     }
   }, [layoutMode]);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     cachedFloatingPositionRef.current = floatingPosition;
     const cacheKey = getFloatingCacheKey(target);
     if (cacheKey) {
       floatingPositionCache.set(cacheKey, floatingPosition);
     }
   }, [floatingPosition, target.isScreen, target.stepId]);
-  const dockedPosition = (0, import_react20.useMemo)(
+  const dockedPosition = (0, import_react21.useMemo)(
     () => ({
       top: viewport.height - DOCKED_MARGIN,
       left: viewport.width - DOCKED_MARGIN,
@@ -3300,7 +3446,7 @@ var TourPopoverPortal = ({
     }),
     [viewport.height, viewport.width]
   );
-  const mobilePosition = (0, import_react20.useMemo)(
+  const mobilePosition = (0, import_react21.useMemo)(
     () => ({
       top: viewport.height - MOBILE_HORIZONTAL_GUTTER,
       left: viewport.width / 2,
@@ -3308,17 +3454,17 @@ var TourPopoverPortal = ({
     }),
     [viewport.height, viewport.width]
   );
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     if (layoutMode === "docked") {
       setFloatingPosition(dockedPosition);
     }
   }, [dockedPosition, layoutMode]);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     if (layoutMode === "mobile") {
       setFloatingPosition(mobilePosition);
     }
   }, [layoutMode, mobilePosition]);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     if (prefersMobileLayout) {
       if (layoutMode !== "mobile") {
         setLayoutMode("mobile");
@@ -3331,7 +3477,7 @@ var TourPopoverPortal = ({
       setFloatingPosition(fallbackPosition);
     }
   }, [fallbackPosition, layoutMode, prefersMobileLayout]);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     if (layoutMode !== "floating") return;
     const stepId = target.stepId;
     if (!stepId) return;
@@ -3355,7 +3501,7 @@ var TourPopoverPortal = ({
     target.stepId
   ]);
   const shouldDeferScreenSnap = layoutMode === "floating" && target.isScreen && Boolean(layoutId);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     return () => {
       if (deferredScreenSnapRef.current !== null) {
         cancelAnimationFrame(deferredScreenSnapRef.current);
@@ -3363,7 +3509,7 @@ var TourPopoverPortal = ({
       }
     };
   }, []);
-  (0, import_react20.useLayoutEffect)(() => {
+  (0, import_react21.useLayoutEffect)(() => {
     if (layoutMode !== "floating") return;
     if (target.status === "ready" && !target.isScreen) return;
     if (shouldDeferScreenSnap) return;
@@ -3375,7 +3521,7 @@ var TourPopoverPortal = ({
     target.isScreen,
     target.status
   ]);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     if (!shouldDeferScreenSnap) return;
     if (deferredScreenSnapRef.current !== null) {
       cancelAnimationFrame(deferredScreenSnapRef.current);
@@ -3402,14 +3548,14 @@ var TourPopoverPortal = ({
       }
     };
   }, [fallbackPosition, shouldDeferScreenSnap]);
-  (0, import_react20.useEffect)(() => {
+  (0, import_react21.useEffect)(() => {
     return () => {
       if (overflowRetryTimeoutRef.current !== null) {
         window.clearTimeout(overflowRetryTimeoutRef.current);
       }
     };
   }, []);
-  (0, import_react20.useLayoutEffect)(() => {
+  (0, import_react21.useLayoutEffect)(() => {
     if (!isBrowser) return;
     const floatingEl = floatingRef.current;
     const rectInfo = target.rect;
@@ -3543,7 +3689,7 @@ var TourPopoverPortal = ({
     target.status,
     target.stepId
   ]);
-  (0, import_react20.useLayoutEffect)(() => {
+  (0, import_react21.useLayoutEffect)(() => {
     if (layoutMode !== "manual" || !dragPosition) return;
     setFloatingPosition({
       top: dragPosition.top,
@@ -3628,7 +3774,7 @@ var TourPopoverPortal = ({
     }
     event.preventDefault();
   };
-  (0, import_react20.useEffect)(() => endDrag, []);
+  (0, import_react21.useEffect)(() => endDrag, []);
   const shouldUseFallbackInitial = layoutMode !== "mobile" && (Boolean(target.lastResolvedRect) || Boolean(cachedTarget));
   const floatingCacheKey = layoutMode === "mobile" ? null : getFloatingCacheKey(target);
   const persistedFloatingInitial = floatingCacheKey && floatingPositionCache.has(floatingCacheKey) ? floatingPositionCache.get(floatingCacheKey) ?? null : null;
@@ -3715,11 +3861,12 @@ var TourPopoverPortal = ({
     dragHandleProps,
     descriptionProps
   };
+  if (shouldHidePopover) return null;
   return (0, import_react_dom2.createPortal)(children(context), host);
 };
 
 // src/components/TourFocusManager.tsx
-var import_react21 = require("react");
+var import_react22 = require("react");
 var import_react_dom3 = require("react-dom");
 
 // src/utils/focus.ts
@@ -3796,18 +3943,18 @@ var TourFocusManager = ({
   highlightRect,
   guardElementFocusRing
 }) => {
-  const previousFocusRef = (0, import_react21.useRef)(null);
-  const guardNodesRef = (0, import_react21.useRef)({
+  const previousFocusRef = (0, import_react22.useRef)(null);
+  const guardNodesRef = (0, import_react22.useRef)({
     "target-start": null,
     "target-end": null,
     "popover-start": null,
     "popover-end": null
   });
-  const lastTabDirectionRef = (0, import_react21.useRef)("forward");
-  const suppressGuardHopRef = (0, import_react21.useRef)(null);
-  const [targetRingActive, setTargetRingActive] = (0, import_react21.useState)(false);
-  const [popoverRingActive, setPopoverRingActive] = (0, import_react21.useState)(false);
-  const [popoverRect, setPopoverRect] = (0, import_react21.useState)(null);
+  const lastTabDirectionRef = (0, import_react22.useRef)("forward");
+  const suppressGuardHopRef = (0, import_react22.useRef)(null);
+  const [targetRingActive, setTargetRingActive] = (0, import_react22.useState)(false);
+  const [popoverRingActive, setPopoverRingActive] = (0, import_react22.useState)(false);
+  const [popoverRect, setPopoverRect] = (0, import_react22.useState)(null);
   const restoreFocus = () => {
     const previous = previousFocusRef.current;
     previousFocusRef.current = null;
@@ -3817,7 +3964,7 @@ var TourFocusManager = ({
       });
     }
   };
-  (0, import_react21.useLayoutEffect)(() => {
+  (0, import_react22.useLayoutEffect)(() => {
     if (!isBrowser) return;
     if (!active) {
       restoreFocus();
@@ -3833,7 +3980,7 @@ var TourFocusManager = ({
       restoreFocus();
     };
   }, [active, popoverNode, target.element]);
-  (0, import_react21.useEffect)(() => {
+  (0, import_react22.useEffect)(() => {
     if (!isBrowser) return;
     if (!active) return;
     const doc = popoverNode?.ownerDocument ?? target.element?.ownerDocument ?? document;
@@ -4027,7 +4174,7 @@ var TourFocusManager = ({
     target.stepId,
     target.visibility
   ]);
-  (0, import_react21.useLayoutEffect)(() => {
+  (0, import_react22.useLayoutEffect)(() => {
     if (popoverRingActive && popoverNode) {
       setPopoverRect(popoverNode.getBoundingClientRect());
     } else {
@@ -4083,7 +4230,7 @@ var TourFocusManager = ({
 };
 
 // src/motion/useHudMotion.ts
-var import_react22 = require("react");
+var import_react23 = require("react");
 var DEFAULT_HIGHLIGHT_TRANSITION2 = {
   duration: 0.35,
   ease: "easeOut",
@@ -4110,7 +4257,7 @@ var DEFAULT_POPOVER_CONTENT_TRANSITION2 = {
 };
 var useHudMotion = () => {
   const adapter = useAnimationAdapter();
-  return (0, import_react22.useMemo)(() => {
+  return (0, import_react23.useMemo)(() => {
     const components = {
       ...adapter.components
     };
@@ -4126,49 +4273,6 @@ var useHudMotion = () => {
     };
   }, [adapter]);
 };
-
-// src/router/utils.ts
-var ensurePrefix = (value, prefix) => value.startsWith(prefix) ? value : `${prefix}${value}`;
-var isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
-var toSearchString = (value) => {
-  if (!isNonEmptyString(value)) {
-    if (value instanceof URLSearchParams) {
-      const serialized = value.toString();
-      return serialized.length > 0 ? `?${serialized}` : "";
-    }
-    if (typeof value === "object" && value !== null) {
-      try {
-        const params = new URLSearchParams();
-        for (const [key, raw] of Object.entries(
-          value
-        )) {
-          if (raw === void 0 || raw === null) continue;
-          params.set(key, String(raw));
-        }
-        const serialized = params.toString();
-        return serialized.length > 0 ? `?${serialized}` : "";
-      } catch {
-        return "";
-      }
-    }
-    return "";
-  }
-  if (value === "?") return "";
-  return value.startsWith("?") ? value : ensurePrefix(value, "?");
-};
-var toHashString = (value) => {
-  if (!isNonEmptyString(value)) {
-    return "";
-  }
-  if (value === "#") return "";
-  return value.startsWith("#") ? value : ensurePrefix(value, "#");
-};
-var createPathString = (pathname, search, hash) => {
-  const normalizedPath = isNonEmptyString(pathname) ? pathname.startsWith("/") ? pathname : `/${pathname}` : "/";
-  const searchPart = toSearchString(search);
-  const hashPart = toHashString(hash);
-  return `${normalizedPath}${searchPart}${hashPart}`;
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AnimationAdapterProvider,