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

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

@@ -1 +1 @@
-{"version":3,"file":"create-route-map.d.ts","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAgBvD;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG;QACtB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC/B,CAAC;CACF;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CA0D7D"}
+{"version":3,"file":"create-route-map.d.ts","sourceRoot":"","sources":["../src/create-route-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAG9C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CAU5F"}

package/dist/create-route-map.js

@@ -1,124 +1,34 @@
-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;
-}
+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(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
+ * 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.
  *
- * **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, parameterized routes will not match and a
- * `console.warn` is emitted. Static (exact) routes are unaffected.
+ * @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.
  *
- * Usage:
+ * @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 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) {
-                console.warn("[RouteMap] URLPattern is not available. Load a polyfill (e.g. urlpattern-polyfill) before using @xmachines/play-router on Node < 24 or older browsers.");
-                return;
-            }
-            try {
-                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);
-            }
-        }
-        for (const child of node.children) {
-            collectPatterns(child);
-        }
-    }
-    collectPatterns(routeTree.root);
-    return {
-        resolve(path) {
-            // O(1) exact match via routeTree.byPath Map (unchanged)
-            const exactMatch = routeTree.byPath.get(path);
-            if (exactMatch?.routable) {
-                return { to: `#${exactMatch.id}`, params: {} };
-            }
-            // 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) {
-                    const params = {};
-                    if (match.pathname.groups) {
-                        Object.assign(params, match.pathname.groups);
-                    }
-                    return { to: `#${node.id}`, params };
-                }
-            }
-            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":"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"}
+{"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"}