@flowsterix/react 0.3.1 → 0.4.0

package/dist/{chunk-L6HQUDEA.mjs → chunk-2ZX2Y3JL.mjs}

@@ -1,7 +1,7 @@
 import {
   createPathString,
   notifyRouteChange
-} from "./chunk-WTGQUDPT.mjs";
+} from "./chunk-B44EX7YT.mjs";
 
 // src/router/tanstackRouterAdapter.tsx
 import { useRouterState } from "@tanstack/react-router";

package/dist/{chunk-WTGQUDPT.mjs → chunk-B44EX7YT.mjs}

@@ -222,6 +222,12 @@ var notifyRouteChange = (path) => {
 var subscribeToRouteChanges = (listener) => {
   return routeGatingChannel.subscribe(listener);
 };
+var matchRoute = (params) => {
+  const { pattern, path } = params;
+  if (!pattern) return true;
+  if (typeof pattern === "string") return path === pattern;
+  return pattern.test(path);
+};
 
 // src/router/utils.ts
 var ensurePrefix = (value, prefix) => value.startsWith(prefix) ? value : `${prefix}${value}`;
@@ -278,5 +284,6 @@ export {
   getCurrentRoutePath,
   notifyRouteChange,
   subscribeToRouteChanges,
+  matchRoute,
   createPathString
 };

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -305,6 +305,127 @@ var supportsMasking = () => {
   return cachedMaskSupport;
 };
 
+// src/router/routeGating.ts
+var DEFAULT_POLL_MS = 150;
+var normalizePathname = (pathname) => {
+  if (typeof pathname !== "string" || pathname.length === 0) {
+    return "/";
+  }
+  return pathname.startsWith("/") ? pathname : `/${pathname}`;
+};
+var normalizePrefixedSegment = (value, prefix) => {
+  if (typeof value !== "string" || value.length === 0) {
+    return "";
+  }
+  return value.startsWith(prefix) ? value : `${prefix}${value}`;
+};
+var getWindowPath = () => {
+  if (!isBrowser) return "/";
+  const { pathname, search, hash } = window.location;
+  return normalizePathname(pathname) + normalizePrefixedSegment(search, "?") + normalizePrefixedSegment(hash, "#");
+};
+var normalizeExternalPath = (path) => {
+  if (path.length === 0) {
+    return "/";
+  }
+  try {
+    const parsed = new URL(path, "http://flowsterix.local");
+    return normalizePathname(parsed.pathname) + normalizePrefixedSegment(parsed.search, "?") + normalizePrefixedSegment(parsed.hash, "#");
+  } catch {
+    const [withoutHash, hash = ""] = path.split("#");
+    const [base, search = ""] = withoutHash.split("?");
+    return normalizePathname(base) + normalizePrefixedSegment(search ? `?${search}` : "", "?") + normalizePrefixedSegment(hash ? `#${hash}` : "", "#");
+  }
+};
+var RouteGatingChannel = class {
+  #listeners = /* @__PURE__ */ new Set();
+  #currentPath = getWindowPath();
+  #teardown = null;
+  #attachDefaultListeners() {
+    if (!isBrowser) return;
+    if (this.#teardown) return;
+    let lastPath = getWindowPath();
+    const emitIfChanged = () => {
+      const nextPath = getWindowPath();
+      if (nextPath === lastPath) return;
+      lastPath = nextPath;
+      this.notify(nextPath);
+    };
+    const handler = () => emitIfChanged();
+    window.addEventListener("popstate", handler);
+    window.addEventListener("hashchange", handler);
+    const pollId = window.setInterval(emitIfChanged, DEFAULT_POLL_MS);
+    this.#teardown = () => {
+      window.removeEventListener("popstate", handler);
+      window.removeEventListener("hashchange", handler);
+      window.clearInterval(pollId);
+      this.#teardown = null;
+    };
+  }
+  #detachDefaultListeners() {
+    if (this.#listeners.size > 0) return;
+    this.#teardown?.();
+    this.#teardown = null;
+  }
+  getCurrentPath() {
+    if (isBrowser) {
+      this.#currentPath = getWindowPath();
+    }
+    return this.#currentPath;
+  }
+  notify(path) {
+    const resolved = typeof path === "string" && path.length > 0 ? normalizeExternalPath(path) : this.getCurrentPath();
+    if (resolved === this.#currentPath) {
+      this.#currentPath = resolved;
+      return;
+    }
+    this.#currentPath = resolved;
+    for (const listener of Array.from(this.#listeners)) {
+      try {
+        listener(resolved);
+      } catch (error) {
+        console.warn("[tour][route-gating] listener error", error);
+      }
+    }
+  }
+  subscribe(listener) {
+    if (this.#listeners.has(listener)) {
+      return () => {
+        this.#listeners.delete(listener);
+        this.#detachDefaultListeners();
+      };
+    }
+    this.#listeners.add(listener);
+    if (this.#listeners.size === 1) {
+      this.#attachDefaultListeners();
+    }
+    const current = this.getCurrentPath();
+    try {
+      listener(current);
+    } catch (error) {
+      console.warn("[tour][route-gating] listener error", error);
+    }
+    return () => {
+      this.#listeners.delete(listener);
+      this.#detachDefaultListeners();
+    };
+  }
+};
+var routeGatingChannel = new RouteGatingChannel();
+var getCurrentRoutePath = () => routeGatingChannel.getCurrentPath();
+var notifyRouteChange = (path) => {
+  routeGatingChannel.notify(path);
+};
+var subscribeToRouteChanges = (listener) => {
+  return routeGatingChannel.subscribe(listener);
+};
+var matchRoute = (params) => {
+  const { pattern, path } = params;
+  if (!pattern) return true;
+  if (typeof pattern === "string") return path === pattern;
+  return pattern.test(path);
+};
+
 // src/context.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var TourContext = (0, import_react4.createContext)(void 0);
@@ -352,9 +473,7 @@ var TourProvider = ({
   );
   const [debugEnabled, setDebugEnabled] = (0, import_react4.useState)(defaultDebug);
   const [delayInfo, setDelayInfo] = (0, import_react4.useState)(null);
-  const autoStartFlow = (0, import_react4.useMemo)(() => {
-    return flows.find((flow) => flow.autoStart);
-  }, [flows]);
+  const [eligibleAutoStart, setEligibleAutoStart] = (0, import_react4.useState)(null);
   const teardownStore = (0, import_react4.useCallback)(() => {
     unsubscribeRef.current?.();
     unsubscribeRef.current = null;
@@ -558,48 +677,102 @@ var TourProvider = ({
     [ensureStore, resolveResumeStrategy, runResumeHooks]
   );
   (0, import_react4.useEffect)(() => {
-    if (!autoStartFlow) {
-      autoStartRequestedRef.current = null;
+    const autoStartFlows = flows.filter((f) => f.autoStart);
+    if (autoStartFlows.length === 0) {
+      setEligibleAutoStart(null);
+      return;
+    }
+    if (!storageAdapter && !fallbackStorageRef.current && isBrowser) {
+      fallbackStorageRef.current = (0, import_core.createLocalStorageAdapter)();
+    }
+    const resolvedStorageAdapter = storageAdapter ?? fallbackStorageRef.current;
+    if (!resolvedStorageAdapter) {
+      setEligibleAutoStart({
+        flow: autoStartFlows[0],
+        resolvedState: null,
+        stepIndex: 0
+      });
       return;
     }
-    if (activeFlowId) return;
-    if (autoStartRequestedRef.current === autoStartFlow.id) return;
-    autoStartRequestedRef.current = autoStartFlow.id;
     let cancelled = false;
-    const maybeAutoStart = async () => {
-      if (!storageAdapter && !fallbackStorageRef.current && isBrowser) {
-        fallbackStorageRef.current = (0, import_core.createLocalStorageAdapter)();
-      }
-      const resolvedStorageAdapter = storageAdapter ? storageAdapter : fallbackStorageRef.current;
-      if (!resolvedStorageAdapter) {
-        startFlow(autoStartFlow.id, { resume: true });
-        return;
-      }
-      const storageKey = storageNamespace ? `${storageNamespace}:${autoStartFlow.id}` : `${DEFAULT_STORAGE_PREFIX}:${autoStartFlow.id}`;
-      const snapshot = await (0, import_core.resolveMaybePromise)(
-        resolvedStorageAdapter.get(storageKey)
+    const findEligible = async () => {
+      const storageKeys = autoStartFlows.map(
+        (f) => storageNamespace ? `${storageNamespace}:${f.id}` : `${DEFAULT_STORAGE_PREFIX}:${f.id}`
+      );
+      const snapshots = await Promise.all(
+        storageKeys.map(
+          (key) => (0, import_core.resolveMaybePromise)(resolvedStorageAdapter.get(key))
+        )
       );
       if (cancelled) return;
-      const currentVersionStr = (0, import_core.serializeVersion)(autoStartFlow.version);
-      const storedVersionStr = typeof snapshot?.version === "number" ? (0, import_core.serializeVersion)({ major: snapshot.version, minor: 0 }) : snapshot?.version;
-      if (snapshot && storedVersionStr === currentVersionStr) {
-        const storedState = snapshot.value;
-        const isFinished = storedState.status === "completed";
-        const isSkipped = storedState.status === "cancelled" && storedState.cancelReason === "skipped";
-        if (isFinished || isSkipped) {
+      for (let i = 0; i < autoStartFlows.length; i++) {
+        const flow = autoStartFlows[i];
+        const snapshot = snapshots[i];
+        if (!snapshot) {
+          setEligibleAutoStart({ flow, resolvedState: null, stepIndex: 0 });
           return;
         }
+        const storedVersionStr = typeof snapshot.version === "number" ? (0, import_core.serializeVersion)({ major: snapshot.version, minor: 0 }) : snapshot.version;
+        const storedVersion = (0, import_core.parseVersion)(storedVersionStr);
+        const stepIdMap = (0, import_core.buildStepIdMap)(flow);
+        const { state: resolvedState } = (0, import_core.handleVersionMismatch)({
+          storedState: snapshot.value,
+          storedVersion,
+          definition: flow,
+          currentVersion: flow.version,
+          stepIdMap,
+          now: () => Date.now()
+        });
+        if (resolvedState.status === "completed") continue;
+        if (resolvedState.status === "cancelled" && resolvedState.cancelReason === "skipped") {
+          continue;
+        }
+        const stepIndex = Math.max(0, resolvedState.stepIndex);
+        setEligibleAutoStart({ flow, resolvedState, stepIndex });
+        return;
       }
-      startFlow(autoStartFlow.id, { resume: true });
+      setEligibleAutoStart(null);
     };
-    void maybeAutoStart();
+    void findEligible();
     return () => {
       cancelled = true;
+    };
+  }, [flows, storageAdapter, storageNamespace]);
+  (0, import_react4.useEffect)(() => {
+    if (!eligibleAutoStart) {
+      autoStartRequestedRef.current = null;
+      return;
+    }
+    if (activeFlowId) return;
+    if (autoStartRequestedRef.current === eligibleAutoStart.flow.id) return;
+    const { flow, stepIndex } = eligibleAutoStart;
+    const step = flow.steps[stepIndex];
+    if (!step?.route) {
+      autoStartRequestedRef.current = flow.id;
+      startFlow(flow.id, { resume: true });
+      return;
+    }
+    const currentPath = getCurrentRoutePath();
+    if (matchRoute({ pattern: step.route, path: currentPath })) {
+      autoStartRequestedRef.current = flow.id;
+      startFlow(flow.id, { resume: true });
+      return;
+    }
+    const unsubscribe = subscribeToRouteChanges((path) => {
+      if (activeFlowId) return;
+      if (autoStartRequestedRef.current === flow.id) return;
+      if (matchRoute({ pattern: step.route, path })) {
+        autoStartRequestedRef.current = flow.id;
+        startFlow(flow.id, { resume: true });
+      }
+    });
+    return () => {
+      unsubscribe();
       if (!activeFlowId) {
         autoStartRequestedRef.current = null;
       }
     };
-  }, [activeFlowId, autoStartFlow, startFlow, storageAdapter, storageNamespace]);
+  }, [activeFlowId, eligibleAutoStart, startFlow]);
   const next = (0, import_react4.useCallback)(() => getActiveStore().next(), [getActiveStore]);
   const back = (0, import_react4.useCallback)(() => getActiveStore().back(), [getActiveStore]);
   const goToStep = (0, import_react4.useCallback)(
@@ -1493,123 +1666,6 @@ var import_react9 = require("react");
 
 // src/hooks/useAdvanceRules.ts
 var import_react6 = require("react");
-
-// src/router/routeGating.ts
-var DEFAULT_POLL_MS = 150;
-var normalizePathname = (pathname) => {
-  if (typeof pathname !== "string" || pathname.length === 0) {
-    return "/";
-  }
-  return pathname.startsWith("/") ? pathname : `/${pathname}`;
-};
-var normalizePrefixedSegment = (value, prefix) => {
-  if (typeof value !== "string" || value.length === 0) {
-    return "";
-  }
-  return value.startsWith(prefix) ? value : `${prefix}${value}`;
-};
-var getWindowPath = () => {
-  if (!isBrowser) return "/";
-  const { pathname, search, hash } = window.location;
-  return normalizePathname(pathname) + normalizePrefixedSegment(search, "?") + normalizePrefixedSegment(hash, "#");
-};
-var normalizeExternalPath = (path) => {
-  if (path.length === 0) {
-    return "/";
-  }
-  try {
-    const parsed = new URL(path, "http://flowsterix.local");
-    return normalizePathname(parsed.pathname) + normalizePrefixedSegment(parsed.search, "?") + normalizePrefixedSegment(parsed.hash, "#");
-  } catch {
-    const [withoutHash, hash = ""] = path.split("#");
-    const [base, search = ""] = withoutHash.split("?");
-    return normalizePathname(base) + normalizePrefixedSegment(search ? `?${search}` : "", "?") + normalizePrefixedSegment(hash ? `#${hash}` : "", "#");
-  }
-};
-var RouteGatingChannel = class {
-  #listeners = /* @__PURE__ */ new Set();
-  #currentPath = getWindowPath();
-  #teardown = null;
-  #attachDefaultListeners() {
-    if (!isBrowser) return;
-    if (this.#teardown) return;
-    let lastPath = getWindowPath();
-    const emitIfChanged = () => {
-      const nextPath = getWindowPath();
-      if (nextPath === lastPath) return;
-      lastPath = nextPath;
-      this.notify(nextPath);
-    };
-    const handler = () => emitIfChanged();
-    window.addEventListener("popstate", handler);
-    window.addEventListener("hashchange", handler);
-    const pollId = window.setInterval(emitIfChanged, DEFAULT_POLL_MS);
-    this.#teardown = () => {
-      window.removeEventListener("popstate", handler);
-      window.removeEventListener("hashchange", handler);
-      window.clearInterval(pollId);
-      this.#teardown = null;
-    };
-  }
-  #detachDefaultListeners() {
-    if (this.#listeners.size > 0) return;
-    this.#teardown?.();
-    this.#teardown = null;
-  }
-  getCurrentPath() {
-    if (isBrowser) {
-      this.#currentPath = getWindowPath();
-    }
-    return this.#currentPath;
-  }
-  notify(path) {
-    const resolved = typeof path === "string" && path.length > 0 ? normalizeExternalPath(path) : this.getCurrentPath();
-    if (resolved === this.#currentPath) {
-      this.#currentPath = resolved;
-      return;
-    }
-    this.#currentPath = resolved;
-    for (const listener of Array.from(this.#listeners)) {
-      try {
-        listener(resolved);
-      } catch (error) {
-        console.warn("[tour][route-gating] listener error", error);
-      }
-    }
-  }
-  subscribe(listener) {
-    if (this.#listeners.has(listener)) {
-      return () => {
-        this.#listeners.delete(listener);
-        this.#detachDefaultListeners();
-      };
-    }
-    this.#listeners.add(listener);
-    if (this.#listeners.size === 1) {
-      this.#attachDefaultListeners();
-    }
-    const current = this.getCurrentPath();
-    try {
-      listener(current);
-    } catch (error) {
-      console.warn("[tour][route-gating] listener error", error);
-    }
-    return () => {
-      this.#listeners.delete(listener);
-      this.#detachDefaultListeners();
-    };
-  }
-};
-var routeGatingChannel = new RouteGatingChannel();
-var getCurrentRoutePath = () => routeGatingChannel.getCurrentPath();
-var notifyRouteChange = (path) => {
-  routeGatingChannel.notify(path);
-};
-var subscribeToRouteChanges = (listener) => {
-  return routeGatingChannel.subscribe(listener);
-};
-
-// src/hooks/useAdvanceRules.ts
 var DEFAULT_POLL_MS2 = 250;
 var isListenerTarget = (value) => {
   return !!value && typeof value.addEventListener === "function" && typeof value.removeEventListener === "function";
@@ -3390,7 +3446,7 @@ var TourPopoverPortal = ({
           padding: FLOATING_OFFSET,
           alignment: autoAlignment
         })
-      ] : [(0, import_dom13.flip)({ padding: FLOATING_OFFSET })],
+      ] : [(0, import_dom13.flip)({ padding: FLOATING_OFFSET, fallbackStrategy: "bestFit" })],
       (0, import_dom13.shift)({ padding: FLOATING_OFFSET })
     ];
     const updatePosition = async () => {

package/dist/index.mjs

@@ -6,16 +6,20 @@ import {
   getScrollParents,
   getViewportRect,
   isBrowser,
+  matchRoute,
   notifyRouteChange,
   portalHost,
   subscribeToRouteChanges,
   supportsMasking
-} from "./chunk-WTGQUDPT.mjs";
+} from "./chunk-B44EX7YT.mjs";
 
 // src/context.tsx
 import {
+  buildStepIdMap,
   createFlowStore,
   createLocalStorageAdapter,
+  handleVersionMismatch,
+  parseVersion,
   resolveMaybePromise,
   serializeVersion
 } from "@flowsterix/core";
@@ -210,9 +214,7 @@ var TourProvider = ({
   );
   const [debugEnabled, setDebugEnabled] = useState2(defaultDebug);
   const [delayInfo, setDelayInfo] = useState2(null);
-  const autoStartFlow = useMemo2(() => {
-    return flows.find((flow) => flow.autoStart);
-  }, [flows]);
+  const [eligibleAutoStart, setEligibleAutoStart] = useState2(null);
   const teardownStore = useCallback(() => {
     unsubscribeRef.current?.();
     unsubscribeRef.current = null;
@@ -416,48 +418,102 @@ var TourProvider = ({
     [ensureStore, resolveResumeStrategy, runResumeHooks]
   );
   useEffect2(() => {
-    if (!autoStartFlow) {
-      autoStartRequestedRef.current = null;
+    const autoStartFlows = flows.filter((f) => f.autoStart);
+    if (autoStartFlows.length === 0) {
+      setEligibleAutoStart(null);
+      return;
+    }
+    if (!storageAdapter && !fallbackStorageRef.current && isBrowser) {
+      fallbackStorageRef.current = createLocalStorageAdapter();
+    }
+    const resolvedStorageAdapter = storageAdapter ?? fallbackStorageRef.current;
+    if (!resolvedStorageAdapter) {
+      setEligibleAutoStart({
+        flow: autoStartFlows[0],
+        resolvedState: null,
+        stepIndex: 0
+      });
       return;
     }
-    if (activeFlowId) return;
-    if (autoStartRequestedRef.current === autoStartFlow.id) return;
-    autoStartRequestedRef.current = autoStartFlow.id;
     let cancelled = false;
-    const maybeAutoStart = async () => {
-      if (!storageAdapter && !fallbackStorageRef.current && isBrowser) {
-        fallbackStorageRef.current = createLocalStorageAdapter();
-      }
-      const resolvedStorageAdapter = storageAdapter ? storageAdapter : fallbackStorageRef.current;
-      if (!resolvedStorageAdapter) {
-        startFlow(autoStartFlow.id, { resume: true });
-        return;
-      }
-      const storageKey = storageNamespace ? `${storageNamespace}:${autoStartFlow.id}` : `${DEFAULT_STORAGE_PREFIX}:${autoStartFlow.id}`;
-      const snapshot = await resolveMaybePromise(
-        resolvedStorageAdapter.get(storageKey)
+    const findEligible = async () => {
+      const storageKeys = autoStartFlows.map(
+        (f) => storageNamespace ? `${storageNamespace}:${f.id}` : `${DEFAULT_STORAGE_PREFIX}:${f.id}`
+      );
+      const snapshots = await Promise.all(
+        storageKeys.map(
+          (key) => resolveMaybePromise(resolvedStorageAdapter.get(key))
+        )
       );
       if (cancelled) return;
-      const currentVersionStr = serializeVersion(autoStartFlow.version);
-      const storedVersionStr = typeof snapshot?.version === "number" ? serializeVersion({ major: snapshot.version, minor: 0 }) : snapshot?.version;
-      if (snapshot && storedVersionStr === currentVersionStr) {
-        const storedState = snapshot.value;
-        const isFinished = storedState.status === "completed";
-        const isSkipped = storedState.status === "cancelled" && storedState.cancelReason === "skipped";
-        if (isFinished || isSkipped) {
+      for (let i = 0; i < autoStartFlows.length; i++) {
+        const flow = autoStartFlows[i];
+        const snapshot = snapshots[i];
+        if (!snapshot) {
+          setEligibleAutoStart({ flow, resolvedState: null, stepIndex: 0 });
           return;
         }
+        const storedVersionStr = typeof snapshot.version === "number" ? serializeVersion({ major: snapshot.version, minor: 0 }) : snapshot.version;
+        const storedVersion = parseVersion(storedVersionStr);
+        const stepIdMap = buildStepIdMap(flow);
+        const { state: resolvedState } = handleVersionMismatch({
+          storedState: snapshot.value,
+          storedVersion,
+          definition: flow,
+          currentVersion: flow.version,
+          stepIdMap,
+          now: () => Date.now()
+        });
+        if (resolvedState.status === "completed") continue;
+        if (resolvedState.status === "cancelled" && resolvedState.cancelReason === "skipped") {
+          continue;
+        }
+        const stepIndex = Math.max(0, resolvedState.stepIndex);
+        setEligibleAutoStart({ flow, resolvedState, stepIndex });
+        return;
       }
-      startFlow(autoStartFlow.id, { resume: true });
+      setEligibleAutoStart(null);
     };
-    void maybeAutoStart();
+    void findEligible();
     return () => {
       cancelled = true;
+    };
+  }, [flows, storageAdapter, storageNamespace]);
+  useEffect2(() => {
+    if (!eligibleAutoStart) {
+      autoStartRequestedRef.current = null;
+      return;
+    }
+    if (activeFlowId) return;
+    if (autoStartRequestedRef.current === eligibleAutoStart.flow.id) return;
+    const { flow, stepIndex } = eligibleAutoStart;
+    const step = flow.steps[stepIndex];
+    if (!step?.route) {
+      autoStartRequestedRef.current = flow.id;
+      startFlow(flow.id, { resume: true });
+      return;
+    }
+    const currentPath = getCurrentRoutePath();
+    if (matchRoute({ pattern: step.route, path: currentPath })) {
+      autoStartRequestedRef.current = flow.id;
+      startFlow(flow.id, { resume: true });
+      return;
+    }
+    const unsubscribe = subscribeToRouteChanges((path) => {
+      if (activeFlowId) return;
+      if (autoStartRequestedRef.current === flow.id) return;
+      if (matchRoute({ pattern: step.route, path })) {
+        autoStartRequestedRef.current = flow.id;
+        startFlow(flow.id, { resume: true });
+      }
+    });
+    return () => {
+      unsubscribe();
       if (!activeFlowId) {
         autoStartRequestedRef.current = null;
       }
     };
-  }, [activeFlowId, autoStartFlow, startFlow, storageAdapter, storageNamespace]);
+  }, [activeFlowId, eligibleAutoStart, startFlow]);
   const next = useCallback(() => getActiveStore().next(), [getActiveStore]);
   const back = useCallback(() => getActiveStore().back(), [getActiveStore]);
   const goToStep = useCallback(
@@ -3137,7 +3193,7 @@ var TourPopoverPortal = ({
           padding: FLOATING_OFFSET,
           alignment: autoAlignment
         })
-      ] : [flip({ padding: FLOATING_OFFSET })],
+      ] : [flip({ padding: FLOATING_OFFSET, fallbackStrategy: "bestFit" })],
       shift({ padding: FLOATING_OFFSET })
     ];
     const updatePosition = async () => {

package/dist/router/index.cjs

@@ -35,6 +35,7 @@ __export(router_exports, {
   getCurrentRoutePath: () => getCurrentRoutePath,
   getTanStackRouter: () => getTanStackRouter,
   getTourRouter: () => getTourRouter,
+  matchRoute: () => matchRoute,
   notifyRouteChange: () => notifyRouteChange,
   routeGatingChannel: () => routeGatingChannel,
   setTanStackRouter: () => setTanStackRouter,
@@ -161,6 +162,12 @@ var notifyRouteChange = (path) => {
 var subscribeToRouteChanges = (listener) => {
   return routeGatingChannel.subscribe(listener);
 };
+var matchRoute = (params) => {
+  const { pattern, path } = params;
+  if (!pattern) return true;
+  if (typeof pattern === "string") return path === pattern;
+  return pattern.test(path);
+};
 
 // src/router/utils.ts
 var ensurePrefix = (value, prefix) => value.startsWith(prefix) ? value : `${prefix}${value}`;
@@ -268,6 +275,7 @@ var useTanStackRouterTourAdapter = () => {
   getCurrentRoutePath,
   getTanStackRouter,
   getTourRouter,
+  matchRoute,
   notifyRouteChange,
   routeGatingChannel,
   setTanStackRouter,

package/dist/router/index.d.ts

@@ -1,4 +1,4 @@
-export { getCurrentRoutePath, notifyRouteChange, routeGatingChannel, subscribeToRouteChanges, } from './routeGating';
+export { getCurrentRoutePath, matchRoute, notifyRouteChange, routeGatingChannel, subscribeToRouteChanges, } from './routeGating';
 export { createPathString } from './utils';
 export { useTanStackRouterTourAdapter } from './tanstackRouterAdapter';
 export { getTanStackRouter, getTourRouter, setTanStackRouter, setTourRouter, TanStackRouterSync, } from './tanstackRouterSync';

package/dist/router/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE1C,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAA;AAEtE,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE1C,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAA;AAEtE,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,sBAAsB,CAAA"}

package/dist/router/index.mjs

@@ -5,20 +5,22 @@ import {
   setTanStackRouter,
   setTourRouter,
   useTanStackRouterTourAdapter
-} from "../chunk-L6HQUDEA.mjs";
+} from "../chunk-2ZX2Y3JL.mjs";
 import {
   createPathString,
   getCurrentRoutePath,
+  matchRoute,
   notifyRouteChange,
   routeGatingChannel,
   subscribeToRouteChanges
-} from "../chunk-WTGQUDPT.mjs";
+} from "../chunk-B44EX7YT.mjs";
 export {
   TanStackRouterSync,
   createPathString,
   getCurrentRoutePath,
   getTanStackRouter,
   getTourRouter,
+  matchRoute,
   notifyRouteChange,
   routeGatingChannel,
   setTanStackRouter,

package/dist/router/nextAppRouterAdapter.mjs

@@ -1,7 +1,7 @@
 import {
   createPathString,
   notifyRouteChange
-} from "../chunk-WTGQUDPT.mjs";
+} from "../chunk-B44EX7YT.mjs";
 
 // src/router/nextAppRouterAdapter.tsx
 import * as NextNavigation from "next/navigation";

package/dist/router/nextPagesRouterAdapter.mjs

@@ -1,7 +1,7 @@
 import {
   createPathString,
   notifyRouteChange
-} from "../chunk-WTGQUDPT.mjs";
+} from "../chunk-B44EX7YT.mjs";
 
 // src/router/nextPagesRouterAdapter.tsx
 import * as NextRouter from "next/router";

package/dist/router/reactRouterAdapter.mjs

@@ -1,7 +1,7 @@
 import {
   createPathString,
   notifyRouteChange
-} from "../chunk-WTGQUDPT.mjs";
+} from "../chunk-B44EX7YT.mjs";
 
 // src/router/reactRouterAdapter.tsx
 import { useEffect } from "react";

package/dist/router/routeGating.d.ts

@@ -9,5 +9,9 @@ export declare const routeGatingChannel: RouteGatingChannel;
 export declare const getCurrentRoutePath: () => string;
 export declare const notifyRouteChange: (path?: string) => void;
 export declare const subscribeToRouteChanges: (listener: RouteChangeListener) => () => void;
+export declare const matchRoute: (params: {
+    pattern: string | RegExp | undefined;
+    path: string;
+}) => boolean;
 export {};
 //# sourceMappingURL=routeGating.d.ts.map

package/dist/router/routeGating.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routeGating.d.ts","sourceRoot":"","sources":["../../src/router/routeGating.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAsDxD,cAAM,kBAAkB;;IAsCtB,cAAc,IAAI,MAAM;IAOxB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM;IAmBpB,SAAS,CAAC,QAAQ,EAAE,mBAAmB;CAyBxC;AAED,eAAO,MAAM,kBAAkB,oBAA2B,CAAA;AAE1D,eAAO,MAAM,mBAAmB,cAA4C,CAAA;AAE5E,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,SAE9C,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,UAAU,mBAAmB,eAEpE,CAAA"}
+{"version":3,"file":"routeGating.d.ts","sourceRoot":"","sources":["../../src/router/routeGating.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;AAsDxD,cAAM,kBAAkB;;IAsCtB,cAAc,IAAI,MAAM;IAOxB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM;IAmBpB,SAAS,CAAC,QAAQ,EAAE,mBAAmB;CAyBxC;AAED,eAAO,MAAM,kBAAkB,oBAA2B,CAAA;AAE1D,eAAO,MAAM,mBAAmB,cAA4C,CAAA;AAE5E,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,SAE9C,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,UAAU,mBAAmB,eAEpE,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,QAAQ;IACjC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC,IAAI,EAAE,MAAM,CAAA;CACb,KAAG,OAKH,CAAA"}

package/dist/router/tanstackRouterAdapter.mjs

@@ -5,8 +5,8 @@ import {
   setTanStackRouter,
   setTourRouter,
   useTanStackRouterTourAdapter
-} from "../chunk-L6HQUDEA.mjs";
-import "../chunk-WTGQUDPT.mjs";
+} from "../chunk-2ZX2Y3JL.mjs";
+import "../chunk-B44EX7YT.mjs";
 export {
   TanStackRouterSync,
   getTanStackRouter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowsterix/react",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "React bindings for Flowsterix - guided tours and onboarding flows",
   "license": "MIT",
   "repository": {
@@ -64,7 +64,7 @@
   ],
   "dependencies": {
     "@floating-ui/dom": "^1.7.4",
-    "@flowsterix/core": "0.3.0"
+    "@flowsterix/core": "0.4.0"
   },
   "peerDependencies": {
     "react": ">=18",