@xmachines/play-router 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/create-route-map.js

@@ -1,14 +1,66 @@
-import { URLPattern } from "urlpattern-polyfill";
+import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.js";
+function getURLPatternCtor() {
+    return globalThis["URLPattern"];
+}
+function getIndexKey(path) {
+    const trimmed = path.startsWith("/") ? path.slice(1) : path;
+    if (trimmed.length === 0)
+        return "/";
+    const segment = trimmed.split("/")[0];
+    if (segment === undefined || segment.startsWith(":"))
+        return "*";
+    return segment;
+}
+function getCandidates(patternBuckets, indexKey) {
+    const bucket = patternBuckets.get(indexKey) ?? [];
+    const wildcardBucket = patternBuckets.get("*") ?? [];
+    if (bucket.length === 0)
+        return wildcardBucket;
+    if (wildcardBucket.length === 0)
+        return bucket;
+    const merged = [];
+    let b = 0;
+    let w = 0;
+    while (b < bucket.length && w < wildcardBucket.length) {
+        if (bucket[b].order < wildcardBucket[w].order) {
+            merged.push(bucket[b]);
+            b += 1;
+        }
+        else {
+            merged.push(wildcardBucket[w]);
+            w += 1;
+        }
+    }
+    while (b < bucket.length) {
+        merged.push(bucket[b]);
+        b += 1;
+    }
+    while (w < wildcardBucket.length) {
+        merged.push(wildcardBucket[w]);
+        w += 1;
+    }
+    return merged;
+}
 /**
  * Create a RouteMap from a RouteTree for efficient path lookups.
  *
  * Architecture:
  * - Pure function - no side effects
  * - O(1) lookups for exact matches via Map
- * - O(n) fallback for pattern matching with URLPattern
+ * - O(k) bucket-indexed pattern matching with URLPattern, where k = routes in the
+ *   first-segment bucket (typically << total routes)
  * - Returns formatted state IDs (with # prefix)
  * - Extracts params from matched patterns
  *
+ * **URLPattern requirement:** Dynamic route pattern matching requires `URLPattern`
+ * to be available on `globalThis`. On Node.js < 24 and older browsers, load a polyfill
+ * before calling this function:
+ * ```typescript
+ * import "urlpattern-polyfill"; // before importing @xmachines/play-router
+ * ```
+ * If `URLPattern` is unavailable, a `URLPatternUnavailableError` is thrown.
+ * Static (exact) routes are unaffected by URLPattern availability.
+ *
  * Usage:
  * ```typescript
  * const routeTree = extractMachineRoutes(machine);
@@ -21,18 +73,24 @@ import { URLPattern } from "urlpattern-polyfill";
  * ```
  */
 export function createRouteMap(routeTree) {
-    // Build pattern matchers for routes with dynamic segments
-    const patternRoutes = [];
-    // Collect all routable routes with patterns
+    // Build bucket-indexed pattern matchers for routes with dynamic segments
+    const patternBuckets = new Map();
+    let patternOrder = 0;
+    const URLPatternCtor = getURLPatternCtor();
     function collectPatterns(node) {
         if (node.routable && node.pattern) {
+            if (!URLPatternCtor) {
+                throw new URLPatternUnavailableError();
+            }
             try {
-                // URLPattern expects patterns in format: /settings/:section
-                const pattern = new URLPattern({ pathname: node.pattern });
-                patternRoutes.push({ pattern, node });
+                const urlPattern = new URLPatternCtor({ pathname: node.pattern });
+                const bucketKey = getIndexKey(node.pattern);
+                const bucket = patternBuckets.get(bucketKey) ?? [];
+                bucket.push({ pattern: urlPattern, node, order: patternOrder++ });
+                patternBuckets.set(bucketKey, bucket);
             }
             catch (err) {
-                console.warn("[RouteMap] Invalid pattern:", node.pattern, err);
+                throw new InvalidRoutePatternError(node.pattern, { cause: err });
             }
         }
         for (const child of node.children) {
@@ -42,30 +100,23 @@ export function createRouteMap(routeTree) {
     collectPatterns(routeTree.root);
     return {
         resolve(path) {
-            // Try exact match first (O(1))
+            // O(1) exact match via routeTree.byPath Map (unchanged)
             const exactMatch = routeTree.byPath.get(path);
             if (exactMatch?.routable) {
-                return {
-                    to: `#${exactMatch.id}`,
-                    params: {},
-                };
+                return { to: `#${exactMatch.id}`, params: {} };
             }
-            // Try pattern matching (O(n))
-            for (const { pattern, node } of patternRoutes) {
+            // Bucket-indexed pattern match: only scan candidates for this path's first segment
+            const candidates = getCandidates(patternBuckets, getIndexKey(path));
+            for (const { pattern, node } of candidates) {
                 const match = pattern.exec({ pathname: path });
                 if (match) {
-                    // Extract pathname params (e.g., { section: "account" })
                     const params = {};
                     if (match.pathname.groups) {
                         Object.assign(params, match.pathname.groups);
                     }
-                    return {
-                        to: `#${node.id}`,
-                        params,
-                    };
+                    return { to: `#${node.id}`, params };
                 }
             }
-            // No match found
             return { to: null, params: {} };
         },
     };

package/dist/create-route-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-route-map.js","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAyBjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAAC,SAAoB;IAClD,0DAA0D;IAC1D,MAAM,aAAa,GAGd,EAAE,CAAC;IAER,4CAA4C;IAC5C,SAAS,eAAe,CAAC,IAA2B;QACnD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACnC,IAAI,CAAC;gBACJ,4DAA4D;gBAC5D,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC3D,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,OAAO,CAAC,IAAI,CAAC,6BAA6B,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAChE,CAAC;QACF,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,eAAe,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;IAED,eAAe,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAEhC,OAAO;QACN,OAAO,CAAC,IAAY;YACnB,+BAA+B;YAC/B,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,UAAU,EAAE,QAAQ,EAAE,CAAC;gBAC1B,OAAO;oBACN,EAAE,EAAE,IAAI,UAAU,CAAC,EAAE,EAAE;oBACvB,MAAM,EAAE,EAAE;iBACV,CAAC;YACH,CAAC;YAED,8BAA8B;YAC9B,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,aAAa,EAAE,CAAC;gBAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC/C,IAAI,KAAK,EAAE,CAAC;oBACX,yDAAyD;oBACzD,MAAM,MAAM,GAA2B,EAAE,CAAC;oBAC1C,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;wBAC3B,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;oBAC9C,CAAC;oBAED,OAAO;wBACN,EAAE,EAAE,IAAI,IAAI,CAAC,EAAE,EAAE;wBACjB,MAAM;qBACN,CAAC;gBACH,CAAC;YACF,CAAC;YAED,iBAAiB;YACjB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACjC,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"create-route-map.js","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,75 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Thrown when `RouterBridgeBase.syncActorFromRouter()` fails to process a router
+ * location change and send the corresponding `play.route` event to the actor.
+ *
+ * The `cause` property wraps the original error.
+ *
+ * **Error code:** `PLAY_ROUTER_SYNC_FAILED`
+ *
+ * @example
+ * ```typescript
+ * import { RouterSyncError } from "@xmachines/play-router/errors";
+ *
+ * try {
+ *   bridge.connect();
+ * } catch (err) {
+ *   if (err instanceof RouterSyncError) {
+ *     console.error("Router sync failed:", err.message, err.cause);
+ *   }
+ * }
+ * ```
+ */
+export declare class RouterSyncError extends PlayError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown by `createRouteMap()` when the `URLPattern` API is not available in the
+ * current runtime environment and no polyfill has been loaded.
+ *
+ * **How to fix:** Load `urlpattern-polyfill` at your application entry point, before
+ * any import of `@xmachines/play-router`:
+ *
+ * ```typescript
+ * // app entry point — must run first
+ * import "urlpattern-polyfill";
+ * ```
+ *
+ * URLPattern is natively available on Node.js ≥ 24 and modern browsers
+ * (Chrome 95+, Firefox 117+, Safari 16.4+). Use the polyfill on older targets.
+ *
+ * **Error code:** `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE`
+ */
+export declare class URLPatternUnavailableError extends PlayError {
+    constructor();
+}
+/**
+ * Thrown by `createRouteMap()` when a route pattern string cannot be compiled by
+ * `URLPattern`. The `pattern` field contains the rejected string; `cause` wraps the
+ * original `URLPattern` constructor error.
+ *
+ * Common causes:
+ * - Unmatched parentheses or brackets in the pattern string
+ * - Characters that are invalid in a URL pathname pattern
+ *
+ * **Error code:** `PLAY_ROUTE_MAP_INVALID_PATTERN`
+ *
+ * @example
+ * ```typescript
+ * import { InvalidRoutePatternError } from "@xmachines/play-router/errors";
+ *
+ * try {
+ *   const routeMap = createRouteMap(tree);
+ * } catch (err) {
+ *   if (err instanceof InvalidRoutePatternError) {
+ *     console.error(`Bad route pattern: "${err.pattern}"`, err.cause);
+ *   }
+ * }
+ * ```
+ */
+export declare class InvalidRoutePatternError extends PlayError {
+    /** The route pattern string that could not be compiled by URLPattern. */
+    readonly pattern: string;
+    constructor(pattern: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAInD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;;CASxD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;IACtD,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAUnD"}

package/dist/errors.js

@@ -0,0 +1,85 @@
+import { PlayError } from "@xmachines/play";
+/**
+ * Thrown when `RouterBridgeBase.syncActorFromRouter()` fails to process a router
+ * location change and send the corresponding `play.route` event to the actor.
+ *
+ * The `cause` property wraps the original error.
+ *
+ * **Error code:** `PLAY_ROUTER_SYNC_FAILED`
+ *
+ * @example
+ * ```typescript
+ * import { RouterSyncError } from "@xmachines/play-router/errors";
+ *
+ * try {
+ *   bridge.connect();
+ * } catch (err) {
+ *   if (err instanceof RouterSyncError) {
+ *     console.error("Router sync failed:", err.message, err.cause);
+ *   }
+ * }
+ * ```
+ */
+export class RouterSyncError extends PlayError {
+    constructor(message, options) {
+        super("RouterBridgeBase", "PLAY_ROUTER_SYNC_FAILED", message, options);
+        this.name = "RouterSyncError";
+    }
+}
+/**
+ * Thrown by `createRouteMap()` when the `URLPattern` API is not available in the
+ * current runtime environment and no polyfill has been loaded.
+ *
+ * **How to fix:** Load `urlpattern-polyfill` at your application entry point, before
+ * any import of `@xmachines/play-router`:
+ *
+ * ```typescript
+ * // app entry point — must run first
+ * import "urlpattern-polyfill";
+ * ```
+ *
+ * URLPattern is natively available on Node.js ≥ 24 and modern browsers
+ * (Chrome 95+, Firefox 117+, Safari 16.4+). Use the polyfill on older targets.
+ *
+ * **Error code:** `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE`
+ */
+export class URLPatternUnavailableError extends PlayError {
+    constructor() {
+        super("RouteMap", "PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE", "URLPattern is not available. Load a polyfill (e.g. urlpattern-polyfill) before using @xmachines/play-router on Node < 24 or older browsers.");
+        this.name = "URLPatternUnavailableError";
+    }
+}
+/**
+ * Thrown by `createRouteMap()` when a route pattern string cannot be compiled by
+ * `URLPattern`. The `pattern` field contains the rejected string; `cause` wraps the
+ * original `URLPattern` constructor error.
+ *
+ * Common causes:
+ * - Unmatched parentheses or brackets in the pattern string
+ * - Characters that are invalid in a URL pathname pattern
+ *
+ * **Error code:** `PLAY_ROUTE_MAP_INVALID_PATTERN`
+ *
+ * @example
+ * ```typescript
+ * import { InvalidRoutePatternError } from "@xmachines/play-router/errors";
+ *
+ * try {
+ *   const routeMap = createRouteMap(tree);
+ * } catch (err) {
+ *   if (err instanceof InvalidRoutePatternError) {
+ *     console.error(`Bad route pattern: "${err.pattern}"`, err.cause);
+ *   }
+ * }
+ * ```
+ */
+export class InvalidRoutePatternError extends PlayError {
+    /** The route pattern string that could not be compiled by URLPattern. */
+    pattern;
+    constructor(pattern, options) {
+        super("RouteMap", "PLAY_ROUTE_MAP_INVALID_PATTERN", `Invalid route pattern: "${pattern}"`, options);
+        this.name = "InvalidRoutePatternError";
+        this.pattern = pattern;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC7C,YAAY,OAAe,EAAE,OAAsB;QAClD,KAAK,CAAC,kBAAkB,EAAE,yBAAyB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAC/B,CAAC;CACD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,0BAA2B,SAAQ,SAAS;IACxD;QACC,KAAK,CACJ,UAAU,EACV,uCAAuC,EACvC,6IAA6I,CAC7I,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC1C,CAAC;CACD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,wBAAyB,SAAQ,SAAS;IACtD,yEAAyE;IAChE,OAAO,CAAS;IAEzB,YAAY,OAAe,EAAE,OAAsB;QAClD,KAAK,CACJ,UAAU,EACV,gCAAgC,EAChC,2BAA2B,OAAO,GAAG,EACrC,OAAO,CACP,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD"}

package/dist/extract-routes.d.ts

@@ -3,39 +3,13 @@ import type { RouteTree } from "./types.js";
 /**
  * Extract complete route tree from state machine graph
  *
- * Crawls machine starting from root, visits all state nodes (including nested
- * and parallel), extracts meta.route metadata, validates route references,
- * and builds hierarchical tree.
+ * Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
+ * then walks graph nodes to extract route metadata, validate route references,
+ * and build a hierarchical RouteTree. The graph is attached to the returned
+ * RouteTree for downstream transition-aware queries.
  *
  * @param machine - XState v5 state machine
- * @returns Route tree with root, byStateId map, and byPath map
- * @throws {Error} If route references non-existent state
- * @throws {Error} If route path is malformed (doesn't start with /)
- * @throws {Error} If parallel states define conflicting routes
- *
- * @example
- * ```typescript
- * import { createMachine } from 'xstate';
- * import { extractMachineRoutes } from '@xmachines/play-router';
- *
- * const machine = createMachine({
- *   initial: 'home',
- *   states: {
- *     home: { id: 'home', meta: { route: '/' } },
- *     dashboard: {
- *       id: 'dashboard',
- *       meta: { route: '/dashboard' },
- *       initial: 'overview',
- *       states: {
- *         overview: { id: 'overview', meta: { route: '/overview' } }
- *       }
- *     }
- *   }
- * });
- *
- * const tree = extractMachineRoutes(machine);
- * console.log(tree.byPath.get('/dashboard/overview'));
- * ```
+ * @returns Route tree with root, byStateId map, byPath map, and graph
  */
 export declare const extractMachineRoutes: (machine: AnyStateMachine) => RouteTree;
 //# sourceMappingURL=extract-routes.d.ts.map

package/dist/extract-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-routes.d.ts","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,eAAe,KAAG,SAsB/D,CAAC"}
+{"version":3,"file":"extract-routes.d.ts","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,KAAK,EAAE,SAAS,EAA6C,MAAM,YAAY,CAAC;AA+EvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,eAAe,KAAG,SAmB/D,CAAC"}

package/dist/extract-routes.js

@@ -1,61 +1,82 @@
-import { crawlMachine } from "./crawl-machine.js";
-import { extractRoute } from "./extract-route.js";
-import { detectDuplicateRoutes } from "./validate-routes.js";
+import { machineToGraph } from "./machine-to-graph.js";
+import { validateRouteFormat, validateStateExists, detectDuplicateRoutes, } from "./validate-routes.js";
 import { buildRouteTree } from "./build-tree.js";
 /**
- * Extract complete route tree from state machine graph
- *
- * Crawls machine starting from root, visits all state nodes (including nested
- * and parallel), extracts meta.route metadata, validates route references,
- * and builds hierarchical tree.
+ * Build statePath for a graph node by walking the parentId chain.
  *
- * @param machine - XState v5 state machine
- * @returns Route tree with root, byStateId map, and byPath map
- * @throws {Error} If route references non-existent state
- * @throws {Error} If route path is malformed (doesn't start with /)
- * @throws {Error} If parallel states define conflicting routes
+ * Produces an array of stateId segments from root to this node (excluding root),
+ * matching the format expected by buildRouteTree's parent lookup.
  *
- * @example
- * ```typescript
- * import { createMachine } from 'xstate';
- * import { extractMachineRoutes } from '@xmachines/play-router';
+ * @param graphNode - The node to build a path for
+ * @param graphNodeMap - Map from node id to GraphNode for O(1) parent lookup
+ * @returns Array of stateId segments (e.g. ["dashboard", "overview"])
+ */
+const buildStatePath = (graphNode, graphNodeMap) => {
+    const path = [];
+    let current = graphNode;
+    while (current && current.parentId !== undefined && current.parentId !== null) {
+        path.unshift(current.data.stateId);
+        current = graphNodeMap.get(current.parentId);
+    }
+    return path;
+};
+/**
+ * Extract route info from a graph node's MachineNodeData.
+ * Returns null if the node has no route (not routable).
+ */
+const extractRouteFromNode = (graphNode, stateIds, graphNodeMap) => {
+    const { stateId, route, meta } = graphNode.data;
+    // Node has no route — not routable
+    if (!route)
+        return null;
+    // Validate format (must start with /)
+    validateRouteFormat(route, stateId);
+    // Validate state exists in graph (redundant but guards against corruption)
+    validateStateExists(stateId, stateIds);
+    // Build statePath from parentId chain (works for both explicit IDs and auto-generated)
+    const statePath = buildStatePath(graphNode, graphNodeMap);
+    const pattern = route.includes(":") ? route : undefined;
+    // Reconstruct original metadata shape from graph data
+    const metadata = meta && typeof meta === "object" && "route" in meta
+        ? meta["route"]
+        : route;
+    const result = {
+        stateId,
+        statePath,
+        routePath: route,
+        isAbsolute: route.startsWith("/"),
+        routable: true,
+        metadata,
+    };
+    if (pattern)
+        result.pattern = pattern;
+    return result;
+};
+/**
+ * Extract complete route tree from state machine graph
  *
- * const machine = createMachine({
- *   initial: 'home',
- *   states: {
- *     home: { id: 'home', meta: { route: '/' } },
- *     dashboard: {
- *       id: 'dashboard',
- *       meta: { route: '/dashboard' },
- *       initial: 'overview',
- *       states: {
- *         overview: { id: 'overview', meta: { route: '/overview' } }
- *       }
- *     }
- *   }
- * });
+ * Converts the XState machine to a @statelyai/graph Graph via machineToGraph(),
+ * then walks graph nodes to extract route metadata, validate route references,
+ * and build a hierarchical RouteTree. The graph is attached to the returned
+ * RouteTree for downstream transition-aware queries.
  *
- * const tree = extractMachineRoutes(machine);
- * console.log(tree.byPath.get('/dashboard/overview'));
- * ```
+ * @param machine - XState v5 state machine
+ * @returns Route tree with root, byStateId map, byPath map, and graph
  */
 export const extractMachineRoutes = (machine) => {
-    // 1. Crawl machine graph to discover all states
-    const visits = crawlMachine(machine);
-    // 2. Build state map for validation
-    const stateMap = new Map();
-    for (const visit of visits) {
-        if (visit.node.id) {
-            stateMap.set(visit.node.id, visit.node);
-        }
-    }
-    // 3. Extract routes with validation
-    const routes = visits
-        .map((visit) => extractRoute(visit.node, visit.path, stateMap))
-        .filter((route) => route !== null);
+    // 1. Convert machine to graph
+    const graph = machineToGraph(machine);
+    // 2. Build state ID set for validation and node map for O(1) parent lookup
+    const stateIds = new Set(graph.nodes.map((n) => n.data.stateId));
+    const graphNodeMap = new Map(graph.nodes.map((n) => [n.id, n]));
+    // 3. Extract routes from graph nodes
+    const routes = graph.nodes
+        .map((node) => extractRouteFromNode(node, stateIds, graphNodeMap))
+        .filter((r) => r !== null);
     // 4. Detect duplicate routes
     detectDuplicateRoutes(routes);
-    // 5. Build hierarchical tree
-    return buildRouteTree(routes);
+    // 5. Build hierarchical tree and attach graph
+    const tree = buildRouteTree(routes);
+    return { ...tree, graph };
 };
 //# sourceMappingURL=extract-routes.js.map

package/dist/extract-routes.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract-routes.js","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,OAAwB,EAAa,EAAE;IAC3E,gDAAgD;IAChD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAErC,oCAAoC;IACpC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC9C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACnB,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IAED,oCAAoC;IACpC,MAAM,MAAM,GAAG,MAAM;SACnB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;SAC9D,MAAM,CAAC,CAAC,KAAK,EAAsC,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;IAExE,6BAA6B;IAC7B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAE9B,6BAA6B;IAC7B,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC,CAAC"}
+{"version":3,"file":"extract-routes.js","sourceRoot":"","sources":["../src/extract-routes.ts"],"names":[],"mappings":"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"}

package/dist/find-route.d.ts

@@ -0,0 +1,44 @@
+import type { RouteTree, RouteNode } from "./types.js";
+/**
+ * Find route node by state ID
+ *
+ * Looks up route node using the state's ID property. Used to get URL path
+ * from state ID for browser URL sync after play.route transitions.
+ *
+ * @param tree - Route tree from extractMachineRoutes
+ * @param id - State ID (e.g., 'dashboard', 'settings.profile')
+ * @returns Route node if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * const node = findRouteById(tree, 'dashboard');
+ * if (node) {
+ *   console.log(node.fullPath); // '/dashboard'
+ * }
+ * ```
+ */
+export declare const findRouteById: (tree: RouteTree, id: string) => RouteNode | undefined;
+/**
+ * Find route node by URL path
+ *
+ * Looks up route node using the URL path. Used to get state ID from browser
+ * URL for sending play.route events on navigation.
+ *
+ * When multiple states share the same path (e.g., root and a state both at "/"),
+ * prefers routable nodes (with meta.route) over non-routable nodes.
+ *
+ * Supports pattern matching for dynamic routes (e.g., '/settings/:section?').
+ *
+ * @param tree - Route tree from extractMachineRoutes
+ * @param path - URL path (e.g., '/dashboard', '/settings/profile')
+ * @returns Route node if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const tree = extractMachineRoutes(machine);
+ * const node = findRouteByPath(tree, '/dashboard');
+ * ```
+ */
+export declare const findRouteByPath: (tree: RouteTree, path: string) => RouteNode | undefined;
+//# sourceMappingURL=find-route.d.ts.map

package/dist/find-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-route.d.ts","sourceRoot":"","sources":["../src/find-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAuEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,SAEvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,EAAE,MAAM,MAAM,KAAG,SAAS,GAAG,SAyB3E,CAAC"}