@xmachines/play-router 1.0.0-beta.8 → 1.0.0

package/dist/create-route-map.js

@@ -1,73 +1,34 @@
-import { URLPattern } from "urlpattern-polyfill";
+import { extractMachineRoutes } from "./extract-routes.js";
+import { getRoutableRoutes } from "./query.js";
+import { RouteMap } from "./base-route-map.js";
 /**
- * Create a RouteMap from a RouteTree for efficient path lookups.
+ * Create a `RouteMap` from an XState state machine.
  *
- * Architecture:
- * - Pure function - no side effects
- * - O(1) lookups for exact matches via Map
- * - O(n) fallback for pattern matching with URLPattern
- * - Returns formatted state IDs (with # prefix)
- * - Extracts params from matched patterns
+ * Extracts all routable states (those with `meta.route`) and builds a bidirectional
+ * path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
+ * subclasses to translate browser URL changes into `play.route` actor events and
+ * vice-versa.
  *
- * Usage:
+ * @param machine - XState v5 state machine with `meta.route` annotations on states.
+ * @param options - Optional configuration. Pass `{ cacheSize }` to override the
+ *   default LRU cache size for parameterized path lookups.
+ * @returns A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+ *
+ * @example
  * ```typescript
- * const routeTree = extractMachineRoutes(machine);
- * const routeMap = createRouteMap(routeTree);
+ * import { createRouteMap } from '@xmachines/play-router';
+ * import { connectRouter } from '@xmachines/play-dom-router';
  *
- * const { to, params } = routeMap.resolve('/settings/account');
- * if (to) {
- *   actor.send({ type: 'play.route', to, params });
- * }
+ * const routeMap = createRouteMap(myMachine);
+ * const disconnect = connectRouter({ actor, router, routeMap });
  * ```
  */
-export function createRouteMap(routeTree) {
-    // Build pattern matchers for routes with dynamic segments
-    const patternRoutes = [];
-    // Collect all routable routes with patterns
-    function collectPatterns(node) {
-        if (node.routable && node.pattern) {
-            try {
-                // URLPattern expects patterns in format: /settings/:section
-                const pattern = new URLPattern({ pathname: node.pattern });
-                patternRoutes.push({ pattern, node });
-            }
-            catch (err) {
-                console.warn("[RouteMap] Invalid pattern:", node.pattern, err);
-            }
-        }
-        for (const child of node.children) {
-            collectPatterns(child);
-        }
-    }
-    collectPatterns(routeTree.root);
-    return {
-        resolve(path) {
-            // Try exact match first (O(1))
-            const exactMatch = routeTree.byPath.get(path);
-            if (exactMatch?.routable) {
-                return {
-                    to: `#${exactMatch.id}`,
-                    params: {},
-                };
-            }
-            // Try pattern matching (O(n))
-            for (const { pattern, node } of patternRoutes) {
-                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,
-                    };
-                }
-            }
-            // No match found
-            return { to: null, params: {} };
-        },
-    };
+export function createRouteMap(machine, options) {
+    const routeTree = extractMachineRoutes(machine);
+    const routes = getRoutableRoutes(routeTree);
+    return new RouteMap(routes.map((node) => ({
+        stateId: node.stateId,
+        path: node.fullPath,
+    })), options);
 }
 //# sourceMappingURL=create-route-map.js.map

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":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAmB/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB,EAAE,OAAyB;IACjF,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO,IAAI,QAAQ,CAClB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,QAAQ;KACnB,CAAC,CAAC,EACH,OAAO,CACP,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,152 @@
+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 `RouterBridgeBase.connect()` when a second bridge tries to connect
+ * to an actor that already has an active bridge connection.
+ *
+ * One actor may only be connected to one router bridge at a time. Two bridges
+ * sharing the same actor would both receive and process every router navigation
+ * event, sending duplicate `play.route` events to the actor and producing
+ * conflicting echo-suppression state via `lastSyncedPath`.
+ *
+ * **How to fix:** Call `bridge.disconnect()` on the first bridge before
+ * connecting a second one, or ensure only one `connectRouter()` call is active
+ * per actor at any given time.
+ *
+ * **Error code:** `PLAY_ROUTER_DUPLICATE_BRIDGE`
+ *
+ * @example
+ * ```typescript
+ * import { DuplicateBridgeError } from "@xmachines/play-router/errors";
+ *
+ * try {
+ *   bridge.connect();
+ * } catch (err) {
+ *   if (err instanceof DuplicateBridgeError) {
+ *     console.error("Actor already has an active router bridge — disconnect first.");
+ *   }
+ * }
+ * ```
+ */
+export declare class DuplicateBridgeError extends PlayError {
+    constructor();
+}
+/**
+ * Thrown by the `RouteMap` constructor when a parameterized route is registered but
+ * 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 `validateRouteFormat()` when a state declares `meta.route` with an
+ * empty string path.
+ *
+ * **Error code:** `PLAY_ROUTE_EMPTY_PATH`
+ */
+export declare class EmptyRoutePathError extends PlayError {
+    /** The state ID whose route path is empty. */
+    readonly stateId: string;
+    constructor(stateId: string);
+}
+/**
+ * Thrown by `validateStateExists()` when a route references a state ID that does
+ * not exist in the machine graph.
+ *
+ * **Error code:** `PLAY_ROUTE_INVALID_STATE_ID`
+ */
+export declare class InvalidStateIdError extends PlayError {
+    /** The state ID that was referenced but not found. */
+    readonly stateId: string;
+    constructor(stateId: string);
+}
+/**
+ * Thrown by `detectDuplicateRoutes()` when two or more states share the same URL path.
+ *
+ * **Error code:** `PLAY_ROUTE_DUPLICATE_PATH`
+ */
+export declare class DuplicateRoutePathError extends PlayError {
+    /** Human-readable list of conflicting path → state-ID mappings. */
+    readonly duplicates: string[];
+    constructor(duplicates: string[]);
+}
+/**
+ * Thrown by `machineToGraph()` when an XState state node has an unrecognised
+ * `.type` value.
+ *
+ * **Error code:** `PLAY_ROUTE_UNKNOWN_STATE_TYPE`
+ */
+export declare class UnknownStateTypeError extends PlayError {
+    /** The unrecognised state type string. */
+    readonly stateType: string;
+    /** The ID of the state node with the unknown type. */
+    readonly nodeId: string;
+    constructor(stateType: string, nodeId: string, validTypes: string[]);
+}
+/**
+ * Thrown by the `RouteMap` constructor 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(machine);
+ * } 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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;;CAUlD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,0BAA2B,SAAQ,SAAS;;CASxD;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;CAS3B;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;IACrD,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;gBAElB,UAAU,EAAE,MAAM,EAAE;CAWhC;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;IACnD,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE;CAWnE;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,186 @@
+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 `RouterBridgeBase.connect()` when a second bridge tries to connect
+ * to an actor that already has an active bridge connection.
+ *
+ * One actor may only be connected to one router bridge at a time. Two bridges
+ * sharing the same actor would both receive and process every router navigation
+ * event, sending duplicate `play.route` events to the actor and producing
+ * conflicting echo-suppression state via `lastSyncedPath`.
+ *
+ * **How to fix:** Call `bridge.disconnect()` on the first bridge before
+ * connecting a second one, or ensure only one `connectRouter()` call is active
+ * per actor at any given time.
+ *
+ * **Error code:** `PLAY_ROUTER_DUPLICATE_BRIDGE`
+ *
+ * @example
+ * ```typescript
+ * import { DuplicateBridgeError } from "@xmachines/play-router/errors";
+ *
+ * try {
+ *   bridge.connect();
+ * } catch (err) {
+ *   if (err instanceof DuplicateBridgeError) {
+ *     console.error("Actor already has an active router bridge — disconnect first.");
+ *   }
+ * }
+ * ```
+ */
+export class DuplicateBridgeError extends PlayError {
+    constructor() {
+        super("RouterBridgeBase", "PLAY_ROUTER_DUPLICATE_BRIDGE", "An actor can only be connected to one router bridge at a time. " +
+            "Call disconnect() on the existing bridge before connecting a new one.");
+        this.name = "DuplicateBridgeError";
+    }
+}
+/**
+ * Thrown by the `RouteMap` constructor when a parameterized route is registered but
+ * 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 `validateRouteFormat()` when a state declares `meta.route` with an
+ * empty string path.
+ *
+ * **Error code:** `PLAY_ROUTE_EMPTY_PATH`
+ */
+export class EmptyRoutePathError extends PlayError {
+    /** The state ID whose route path is empty. */
+    stateId;
+    constructor(stateId) {
+        super("RouteMap", "PLAY_ROUTE_EMPTY_PATH", `Empty route path in state "${stateId}": routes must have a non-empty path`);
+        this.name = "EmptyRoutePathError";
+        this.stateId = stateId;
+    }
+}
+/**
+ * Thrown by `validateStateExists()` when a route references a state ID that does
+ * not exist in the machine graph.
+ *
+ * **Error code:** `PLAY_ROUTE_INVALID_STATE_ID`
+ */
+export class InvalidStateIdError extends PlayError {
+    /** The state ID that was referenced but not found. */
+    stateId;
+    constructor(stateId) {
+        super("RouteMap", "PLAY_ROUTE_INVALID_STATE_ID", `Route references non-existent state ID: ${stateId}`);
+        this.name = "InvalidStateIdError";
+        this.stateId = stateId;
+    }
+}
+/**
+ * Thrown by `detectDuplicateRoutes()` when two or more states share the same URL path.
+ *
+ * **Error code:** `PLAY_ROUTE_DUPLICATE_PATH`
+ */
+export class DuplicateRoutePathError extends PlayError {
+    /** Human-readable list of conflicting path → state-ID mappings. */
+    duplicates;
+    constructor(duplicates) {
+        super("RouteMap", "PLAY_ROUTE_DUPLICATE_PATH", `Duplicate route paths detected:\n${duplicates.join("\n")}\n\n` +
+            `Each route path must map to exactly one state.\n` +
+            `Use different paths (e.g., /dashboard vs /) or conditional rendering within a single state.`);
+        this.name = "DuplicateRoutePathError";
+        this.duplicates = duplicates;
+    }
+}
+/**
+ * Thrown by `machineToGraph()` when an XState state node has an unrecognised
+ * `.type` value.
+ *
+ * **Error code:** `PLAY_ROUTE_UNKNOWN_STATE_TYPE`
+ */
+export class UnknownStateTypeError extends PlayError {
+    /** The unrecognised state type string. */
+    stateType;
+    /** The ID of the state node with the unknown type. */
+    nodeId;
+    constructor(stateType, nodeId, validTypes) {
+        super("machineToGraph", "PLAY_ROUTE_UNKNOWN_STATE_TYPE", `Unknown XState state type "${stateType}" on node "${nodeId}". ` +
+            `Expected one of: ${validTypes.join(", ")}.`);
+        this.name = "UnknownStateTypeError";
+        this.stateType = stateType;
+        this.nodeId = nodeId;
+    }
+}
+/**
+ * Thrown by the `RouteMap` constructor 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(machine);
+ * } 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":"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"}

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;AA2EvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,eAAe,KAAG,SAmB/D,CAAC"}

package/dist/extract-routes.js

@@ -1,61 +1,83 @@
-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 } 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);
-    // 4. Detect duplicate routes
-    detectDuplicateRoutes(routes);
-    // 5. Build hierarchical tree
-    return buildRouteTree(routes);
+    // 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. Build hierarchical tree and attach graph.
+    // Duplicate-route detection happens inside buildRouteTree, AFTER relative
+    // routes are resolved to full paths — raw route strings are not comparable
+    // (two relative "settings" routes under different parents are distinct).
+    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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"}