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

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

@@ -1,25 +1,26 @@
 /**
- * BaseRouteMap — Shared bidirectional route mapping base class
+ * RouteMap — Shared bidirectional route mapping base class
  *
  * Provides bucket-based pattern matching shared across all framework adapters.
  * Adapters extend this class rather than duplicating the pattern-match logic.
  *
  * Algorithm: O(1) exact match via Map, then bucket-based O(k) pattern match
  * where k = routes in the first-segment bucket (typically << total routes).
+ * Uses URLPattern for parameterized route matching.
  */
 /**
  * A single state ID ↔ path mapping entry.
  *
- * Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
+ * Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
  * Adapter packages re-export a structurally compatible `RouteMapping` type under
  * their own name. This type is published from `@xmachines/play-router` as
- * `BaseRouteMapping` to avoid name collisions with those adapter-local types.
+ * `RouteMapping` to avoid name collisions with those adapter-local types.
  *
  * @example
  * ```typescript
- * const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
- * const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
- * const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
+ * const mapping: RouteMapping = { stateId: "home", path: "/" };
+ * const paramMapping: RouteMapping = { stateId: "profile", path: "/profile/:userId" };
+ * const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:section?" };
  * ```
  */
 export interface RouteMapping {
@@ -31,24 +32,32 @@ export interface RouteMapping {
 /**
  * Shared bidirectional route map base class.
  *
- * All framework adapter `RouteMap` classes extend this — they add no logic of their
+ * All framework adapters use this class as their route map — they add no logic of their
  * own and inherit the full public API from here.
  *
  * **Lookup strategy:**
  * - Static paths (no `:param`) → O(1) `Map` lookup
- * - Dynamic paths → O(k) bucket-indexed scan using `RegExp`, where `k` is the number
+ * - Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
  *   of routes sharing the same first path segment
- * - Results are cached after the first match
+ * - Results are cached after the first match in an LRU cache (default 500 entries,
+ *   configurable via the `cacheSize` constructor option)
  *
- * **Pattern syntax** (`:param` / `:param?`):
+ * **Pattern syntax** (`:param` / `:param?` / `*`):
  * - `:param` — required segment, matches exactly one non-`/` segment
  * - `:param?` — optional segment, matches zero or one non-`/` segment
+ * - `*` — wildcard, matches any number of segments (URLPattern semantics)
+ *
+ * **StateId forms:** stateIds may be registered and looked up in either
+ * `"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
+ * `getStateIdByPath` returns the stateId exactly as registered;
+ * `getPathByStateId` accepts both forms. Registering the same stateId in both
+ * forms refers to one entry (the later registration wins for reverse lookup).
  *
  * @example
  * ```typescript
- * import { BaseRouteMap } from "@xmachines/play-router";
+ * import { RouteMap } from "@xmachines/play-router";
  *
- * const map = new BaseRouteMap([
+ * const map = new RouteMap([
  *   { stateId: "home",     path: "/" },
  *   { stateId: "profile",  path: "/profile/:userId" },
  *   { stateId: "settings", path: "/settings/:section?" },
@@ -63,7 +72,8 @@ export interface RouteMapping {
  * map.getPathByStateId("missing");         // null
  * ```
  */
-export declare class BaseRouteMap {
+export declare class RouteMap {
+    /** Keyed on the canonical (bare, `#`-stripped) stateId form. */
     private stateIdToPath;
     private pathToStateId;
     private patternBuckets;
@@ -72,13 +82,21 @@ export declare class BaseRouteMap {
      * Build a route map from an array of state ID ↔ path mappings.
      *
      * Static paths (no `:param`) are indexed in an O(1) `Map`.
-     * Parameterized paths are compiled to `RegExp` and grouped into first-segment
+     * Parameterized paths are compiled to `URLPattern` and grouped into first-segment
      * buckets for efficient candidate selection.
      *
      * @param mappings - Array of `{ stateId, path }` entries. Order determines
      *   priority when multiple patterns could match the same path.
+     * @param options - Optional configuration.
+     *   `options.cacheSize`: Maximum number of resolved parameterized path lookups
+     *   to cache. Defaults to `500`. Increase for applications with many unique
+     *   parameterized URL values (e.g. user profile pages with thousands of distinct IDs).
+     *   After eviction the path falls back to the O(k) bucket pattern scan — correct
+     *   but slower. Minimum effective value is `1` (QuickLRU constraint).
      */
-    constructor(mappings: RouteMapping[]);
+    constructor(mappings: RouteMapping[], { cacheSize }?: {
+        cacheSize?: number;
+    });
     /**
      * Resolve a URL path to its mapped state ID.
      *
@@ -99,17 +117,20 @@ export declare class BaseRouteMap {
     /**
      * Look up the path pattern registered for a state ID.
      *
+     * Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
+     * which form was used at registration — lookups are canonicalized internally,
+     * so consumers never need to try both forms.
+     *
      * @param stateId - State machine state ID (e.g., `"profile"`, `"#settings"`)
      * @returns The registered path pattern, or `null` if the state ID is unknown
      *
      * @example
      * ```typescript
      * map.getPathByStateId("profile");   // "/profile/:userId"
+     * map.getPathByStateId("#profile");  // "/profile/:userId" (same entry)
      * map.getPathByStateId("missing");   // null
      * ```
      */
     getPathByStateId(stateId: string): string | null;
-    private getIndexKey;
-    private getCandidates;
 }
 //# sourceMappingURL=base-route-map.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"base-route-map.d.ts","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAA0E;IAChG,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;OASG;gBACS,QAAQ,EAAE,YAAY,EAAE;IA4BpC;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAsB7C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIhD,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,aAAa;CA8BrB"}
+{"version":3,"file":"base-route-map.d.ts","sourceRoot":"","sources":["../src/base-route-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0BH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,QAAQ;IACpB,gEAAgE;IAChE,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAGpB;IACF,OAAO,CAAC,cAAc,CAAkC;IAExD;;;;;;;;;;;;;;;OAeG;gBACS,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,SAAe,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAmCtF;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuB7C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAGhD"}

package/dist/base-route-map.js

@@ -1,34 +1,57 @@
 /**
- * BaseRouteMap — Shared bidirectional route mapping base class
+ * RouteMap — Shared bidirectional route mapping base class
  *
  * Provides bucket-based pattern matching shared across all framework adapters.
  * Adapters extend this class rather than duplicating the pattern-match logic.
  *
  * Algorithm: O(1) exact match via Map, then bucket-based O(k) pattern match
  * where k = routes in the first-segment bucket (typically << total routes).
+ * Uses URLPattern for parameterized route matching.
  */
 import QuickLRU from "quick-lru";
+import { getURLPatternCtor, getCompiledPattern, getIndexKey, getCandidates, isParameterizedPattern, } from "./url-pattern-utils.js";
+import { URLPatternUnavailableError, InvalidRoutePatternError } from "./errors.js";
+/**
+ * Canonical stateId key: the bare form with any leading `#` stripped.
+ *
+ * `RouteMap` accepts stateIds in both `"#stateId"` and `"stateId"` form on insert
+ * and on lookup. Internally every stateId is keyed on this canonical bare form so
+ * consumers never need to re-implement dual-form handling. The *registered* form
+ * is preserved and returned by `getStateIdByPath` so the map is transparent about
+ * how routes were declared.
+ */
+function canonicalStateIdKey(stateId) {
+    return stateId.startsWith("#") ? stateId.slice(1) : stateId;
+}
 /**
  * Shared bidirectional route map base class.
  *
- * All framework adapter `RouteMap` classes extend this — they add no logic of their
+ * All framework adapters use this class as their route map — they add no logic of their
  * own and inherit the full public API from here.
  *
  * **Lookup strategy:**
  * - Static paths (no `:param`) → O(1) `Map` lookup
- * - Dynamic paths → O(k) bucket-indexed scan using `RegExp`, where `k` is the number
+ * - Dynamic paths → O(k) bucket-indexed scan using `URLPattern`, where `k` is the number
  *   of routes sharing the same first path segment
- * - Results are cached after the first match
+ * - Results are cached after the first match in an LRU cache (default 500 entries,
+ *   configurable via the `cacheSize` constructor option)
  *
- * **Pattern syntax** (`:param` / `:param?`):
+ * **Pattern syntax** (`:param` / `:param?` / `*`):
  * - `:param` — required segment, matches exactly one non-`/` segment
  * - `:param?` — optional segment, matches zero or one non-`/` segment
+ * - `*` — wildcard, matches any number of segments (URLPattern semantics)
+ *
+ * **StateId forms:** stateIds may be registered and looked up in either
+ * `"#stateId"` or `"stateId"` form — `RouteMap` canonicalizes internally.
+ * `getStateIdByPath` returns the stateId exactly as registered;
+ * `getPathByStateId` accepts both forms. Registering the same stateId in both
+ * forms refers to one entry (the later registration wins for reverse lookup).
  *
  * @example
  * ```typescript
- * import { BaseRouteMap } from "@xmachines/play-router";
+ * import { RouteMap } from "@xmachines/play-router";
  *
- * const map = new BaseRouteMap([
+ * const map = new RouteMap([
  *   { stateId: "home",     path: "/" },
  *   { stateId: "profile",  path: "/profile/:userId" },
  *   { stateId: "settings", path: "/settings/:section?" },
@@ -43,7 +66,8 @@ import QuickLRU from "quick-lru";
  * map.getPathByStateId("missing");         // null
  * ```
  */
-export class BaseRouteMap {
+export class RouteMap {
+    /** Keyed on the canonical (bare, `#`-stripped) stateId form. */
     stateIdToPath;
     pathToStateId;
     patternBuckets;
@@ -52,29 +76,45 @@ export class BaseRouteMap {
      * Build a route map from an array of state ID ↔ path mappings.
      *
      * Static paths (no `:param`) are indexed in an O(1) `Map`.
-     * Parameterized paths are compiled to `RegExp` and grouped into first-segment
+     * Parameterized paths are compiled to `URLPattern` and grouped into first-segment
      * buckets for efficient candidate selection.
      *
      * @param mappings - Array of `{ stateId, path }` entries. Order determines
      *   priority when multiple patterns could match the same path.
+     * @param options - Optional configuration.
+     *   `options.cacheSize`: Maximum number of resolved parameterized path lookups
+     *   to cache. Defaults to `500`. Increase for applications with many unique
+     *   parameterized URL values (e.g. user profile pages with thousands of distinct IDs).
+     *   After eviction the path falls back to the O(k) bucket pattern scan — correct
+     *   but slower. Minimum effective value is `1` (QuickLRU constraint).
      */
-    constructor(mappings) {
+    constructor(mappings, { cacheSize = 500 } = {}) {
         this.stateIdToPath = new Map();
         this.pathToStateId = new Map();
         this.patternBuckets = new Map();
-        this.pathMatchCache = new QuickLRU({ maxSize: 500 });
+        this.pathMatchCache = new QuickLRU({ maxSize: Math.max(1, cacheSize) });
         let patternOrder = 0;
         for (const { stateId, path } of mappings) {
-            this.stateIdToPath.set(stateId, path);
-            if (path.includes(":")) {
-                const pattern = path.replace(/\/:[^/]+\??/g, (segment) => segment.endsWith("?") ? "(?:/([^/]+))?" : "/([^/]+)");
-                const bucketKey = this.getIndexKey(path);
+            // Key on the canonical (bare) form so getPathByStateId accepts both
+            // "#stateId" and "stateId". The registered form is kept for returns.
+            this.stateIdToPath.set(canonicalStateIdKey(stateId), path);
+            if (isParameterizedPattern(path)) {
+                const URLPatternCtorFn = getURLPatternCtor();
+                if (!URLPatternCtorFn) {
+                    throw new URLPatternUnavailableError();
+                }
+                const bucketKey = getIndexKey(path);
                 const bucket = this.patternBuckets.get(bucketKey) ?? [];
-                bucket.push({
-                    pattern: new RegExp(`^${pattern}$`),
-                    stateId,
-                    order: patternOrder++,
-                });
+                try {
+                    bucket.push({
+                        pattern: getCompiledPattern(path, URLPatternCtorFn),
+                        stateId,
+                        order: patternOrder++,
+                    });
+                }
+                catch (err) {
+                    throw new InvalidRoutePatternError(path, { cause: err });
+                }
                 this.patternBuckets.set(bucketKey, bucket);
             }
             else {
@@ -107,9 +147,10 @@ export class BaseRouteMap {
         const cachedMatch = this.pathMatchCache.get(cleanPath);
         if (cachedMatch !== undefined)
             return cachedMatch;
-        const candidates = this.getCandidates(this.getIndexKey(cleanPath));
+        const candidates = getCandidates(this.patternBuckets, getIndexKey(cleanPath));
         for (const { pattern, stateId } of candidates) {
-            if (pattern.test(cleanPath)) {
+            const match = pattern.exec({ pathname: cleanPath });
+            if (match) {
                 this.pathMatchCache.set(cleanPath, stateId);
                 return stateId;
             }
@@ -120,56 +161,22 @@ export class BaseRouteMap {
     /**
      * Look up the path pattern registered for a state ID.
      *
+     * Accepts the stateId in either `"#stateId"` or `"stateId"` form regardless of
+     * which form was used at registration — lookups are canonicalized internally,
+     * so consumers never need to try both forms.
+     *
      * @param stateId - State machine state ID (e.g., `"profile"`, `"#settings"`)
      * @returns The registered path pattern, or `null` if the state ID is unknown
      *
      * @example
      * ```typescript
      * map.getPathByStateId("profile");   // "/profile/:userId"
+     * map.getPathByStateId("#profile");  // "/profile/:userId" (same entry)
      * map.getPathByStateId("missing");   // null
      * ```
      */
     getPathByStateId(stateId) {
-        return this.stateIdToPath.get(stateId) ?? null;
-    }
-    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;
-    }
-    getCandidates(indexKey) {
-        const bucket = this.patternBuckets.get(indexKey) ?? [];
-        const wildcardBucket = this.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;
+        return this.stateIdToPath.get(canonicalStateIdKey(stateId)) ?? null;
     }
 }
 //# sourceMappingURL=base-route-map.js.map

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

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

package/dist/build-tree.d.ts

@@ -6,8 +6,15 @@ import type { RouteInfo, RouteTree } from "./types.js";
  * Absolute routes become top-level, relative routes nest under parents.
  * Creates bidirectional maps for state ID ↔ path lookup.
  *
+ * Duplicate detection runs here — after relative routes are resolved against
+ * their parent's full path — so two relative routes with the same raw string
+ * under different parents are valid, while distinct raw strings that resolve to
+ * the same full path (which would silently overwrite each other in `byPath`)
+ * are rejected.
+ *
  * @param routes - Flat list of RouteInfo from extraction
  * @returns RouteTree with root, byStateId map, and byPath map
+ * @throws {DuplicateRoutePathError} If two states resolve to the same full path
  */
 export declare const buildRouteTree: (routes: RouteInfo[]) => RouteTree;
 //# sourceMappingURL=build-tree.d.ts.map

package/dist/build-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,SAAS,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,EAAE,KAAG,SAgEpD,CAAC"}
+{"version":3,"file":"build-tree.d.ts","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA4B,SAAS,EAAE,MAAM,YAAY,CAAC;AAGjF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,EAAE,KAAG,SAwEpD,CAAC"}

package/dist/build-tree.js

@@ -1,3 +1,4 @@
+import { detectDuplicateRoutes } from "./validate-routes.js";
 /**
  * Build hierarchical route tree from flat route list
  *
@@ -5,8 +6,15 @@
  * Absolute routes become top-level, relative routes nest under parents.
  * Creates bidirectional maps for state ID ↔ path lookup.
  *
+ * Duplicate detection runs here — after relative routes are resolved against
+ * their parent's full path — so two relative routes with the same raw string
+ * under different parents are valid, while distinct raw strings that resolve to
+ * the same full path (which would silently overwrite each other in `byPath`)
+ * are rejected.
+ *
  * @param routes - Flat list of RouteInfo from extraction
  * @returns RouteTree with root, byStateId map, and byPath map
+ * @throws {DuplicateRoutePathError} If two states resolve to the same full path
  */
 export const buildRouteTree = (routes) => {
     // 1. Create root node
@@ -18,20 +26,23 @@ export const buildRouteTree = (routes) => {
         routable: false, // Root is not a routable state
         children: [],
         parent: null,
-        metadata: {},
+        metadata: "", // Synthetic non-routable root — no real route metadata
     };
     // 2. Initialize maps
     const byStateId = new Map([[root.stateId, root]]);
     const byPath = new Map([[root.fullPath, root]]);
     // 3. Sort routes by depth (shallowest first for proper parent linking)
+    // oxlint-disable-next-line unicorn/no-array-sort
     const sorted = routes.slice().sort((a, b) => a.statePath.length - b.statePath.length);
-    // 4. Build tree
+    // 4. Build tree, collecting inserted nodes for resolved-path duplicate detection
+    const insertedNodes = [];
     for (const route of sorted) {
-        // Find parent by walking up state path
+        // Find parent by walking up state path.
+        // Each entry in statePath is a full dotted stateId (e.g., "chain.app.section"),
+        // so we check each ancestor stateId directly from the end of the list.
         let parentNode = root;
-        for (let i = route.statePath.length - 1; i >= 0; i--) {
-            const parentPath = route.statePath.slice(0, i);
-            const parentStateId = parentPath.join(".");
+        for (let i = route.statePath.length - 2; i >= 0; i--) {
+            const parentStateId = route.statePath[i]; // nosemgrep: gitlab.eslint.detect-object-injection
             if (byStateId.has(parentStateId)) {
                 parentNode = byStateId.get(parentStateId);
                 break;
@@ -61,7 +72,11 @@ export const buildRouteTree = (routes) => {
         // Add to maps for bidirectional lookup
         byStateId.set(node.stateId, node);
         byPath.set(node.fullPath, node);
+        insertedNodes.push(node);
     }
+    // 5. Reject resolved full-path collisions — a silent byPath overwrite would
+    // leave one state unreachable by URL.
+    detectDuplicateRoutes(insertedNodes);
     return { root, byStateId, byPath };
 };
 //# sourceMappingURL=build-tree.js.map

package/dist/build-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAmB,EAAa,EAAE;IAChE,sBAAsB;IACtB,MAAM,IAAI,GAAc;QACvB,EAAE,EAAE,UAAU;QACd,IAAI,EAAE,GAAG;QACT,QAAQ,EAAE,GAAG;QACb,OAAO,EAAE,UAAU;QACnB,QAAQ,EAAE,KAAK,EAAE,+BAA+B;QAChD,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,EAAE;KACZ,CAAC;IAEF,qBAAqB;IACrB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAoB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAoB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAEnE,uEAAuE;IACvE,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAEtF,gBAAgB;IAChB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,uCAAuC;QACvC,IAAI,UAAU,GAAG,IAAI,CAAC;QACtB,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACtD,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC/C,MAAM,aAAa,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3C,IAAI,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;gBAClC,UAAU,GAAG,SAAS,CAAC,GAAG,CAAC,aAAa,CAAE,CAAC;gBAC3C,MAAM;YACP,CAAC;QACF,CAAC;QAED,kBAAkB;QAClB,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU;YAChC,CAAC,CAAC,KAAK,CAAC,SAAS;YACjB,CAAC,CAAC,GAAG,UAAU,CAAC,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAEpE,cAAc;QACd,MAAM,IAAI,GAAc;YACvB,EAAE,EAAE,KAAK,CAAC,OAAO;YACjB,IAAI,EAAE,KAAK,CAAC,SAAS;YACrB,QAAQ;YACR,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,QAAQ,EAAE,EAAE;YACZ,MAAM,EAAE,UAAU;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACxB,CAAC;QAEF,2BAA2B;QAC3B,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACnB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,CAAC;QAED,iBAAiB;QACjB,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/B,uCAAuC;QACvC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACpC,CAAC,CAAC"}
+{"version":3,"file":"build-tree.js","sourceRoot":"","sources":["../src/build-tree.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,33 @@
+import type { RouteTree } from "./types.js";
+import { RouteMap } from "./base-route-map.js";
+import type { RouteMapOptions } from "./create-route-map.js";
+/**
+ * Create a `RouteMap` from a `RouteTree` node structure.
+ *
+ * Used by framework-router adapters that pass a
+ * `RouteTree` produced by `extractMachineRoutes()` rather than calling
+ * `createRouteMap()` directly.
+ *
+ * Traverses all nodes collecting `{ stateId: node.id, path: node.fullPath }` pairs.
+ * `node.fullPath` is always the absolute resolved path (e.g. `"/dashboard/overview"`),
+ * which is what `RouteMap` needs for browser URL matching. This matches the
+ * behaviour of `createRouteMap(machine)`, which also uses `node.fullPath`.
+ *
+ * @param routeTree - A `RouteTree` as returned by `extractMachineRoutes()`.
+ * @param options - Optional configuration (e.g. `{ cacheSize }` to override the LRU cache size).
+ * @returns A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
+ *
+ * @example
+ * ```typescript
+ * // Preferred — single call for XState machines:
+ * import { createRouteMap } from '@xmachines/play-router';
+ * const routeMap = createRouteMap(machine); // takes AnyStateMachine
+ *
+ * // Two-step form used by framework adapters that work with route trees:
+ * import { extractMachineRoutes, createRouteMapFromTree } from '@xmachines/play-router';
+ * const routeTree = extractMachineRoutes(machine);
+ * const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
+ * ```
+ */
+export declare function createRouteMapFromTree(routeTree: RouteTree, options?: RouteMapOptions): RouteMap;
+//# sourceMappingURL=create-route-map-from-tree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map-from-tree.d.ts","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CAchG"}

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

@@ -0,0 +1,43 @@
+import { RouteMap } from "./base-route-map.js";
+/**
+ * Create a `RouteMap` from a `RouteTree` node structure.
+ *
+ * Used by framework-router adapters that pass a
+ * `RouteTree` produced by `extractMachineRoutes()` rather than calling
+ * `createRouteMap()` directly.
+ *
+ * Traverses all nodes collecting `{ stateId: node.id, path: node.fullPath }` pairs.
+ * `node.fullPath` is always the absolute resolved path (e.g. `"/dashboard/overview"`),
+ * which is what `RouteMap` needs for browser URL matching. This matches the
+ * behaviour of `createRouteMap(machine)`, which also uses `node.fullPath`.
+ *
+ * @param routeTree - A `RouteTree` as returned by `extractMachineRoutes()`.
+ * @param options - Optional configuration (e.g. `{ cacheSize }` to override the LRU cache size).
+ * @returns A `RouteMap` for use with any `RouterBridgeBase`-based adapter.
+ *
+ * @example
+ * ```typescript
+ * // Preferred — single call for XState machines:
+ * import { createRouteMap } from '@xmachines/play-router';
+ * const routeMap = createRouteMap(machine); // takes AnyStateMachine
+ *
+ * // Two-step form used by framework adapters that work with route trees:
+ * import { extractMachineRoutes, createRouteMapFromTree } from '@xmachines/play-router';
+ * const routeTree = extractMachineRoutes(machine);
+ * const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
+ * ```
+ */
+export function createRouteMapFromTree(routeTree, options) {
+    const routes = [];
+    function traverse(node) {
+        if (node.id && node.fullPath) {
+            routes.push({ stateId: node.id, path: node.fullPath });
+        }
+        if (node.children) {
+            node.children.forEach(traverse);
+        }
+    }
+    traverse(routeTree.root);
+    return new RouteMap(routes, options);
+}
+//# sourceMappingURL=create-route-map-from-tree.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-route-map-from-tree.js","sourceRoot":"","sources":["../src/create-route-map-from-tree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAoB,EAAE,OAAyB;IACrF,MAAM,MAAM,GAA6C,EAAE,CAAC;IAE5D,SAAS,QAAQ,CAAC,IAAe;QAChC,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;IAED,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC"}

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

@@ -1,66 +1,42 @@
-import type { RouteTree } from "./types.js";
+import type { AnyStateMachine } from "xstate";
+import { RouteMap } from "./base-route-map.js";
 /**
- * Bidirectional route resolution interface returned by `createRouteMap()`.
- *
- * Resolves incoming URL paths to state IDs (with `#` prefix) and extracts
- * route parameters. Used by `RouterBridgeBase` to translate router navigation
- * events into `play.route` actor events.
- *
- * @see {@link createRouteMap} for the factory function
- * @see {@link BaseRouteMap} for direct state ID ↔ path lookups without params extraction
+ * Options for `createRouteMap` and `createRouteMapFromTree`.
  */
-export interface RouteMap {
+export interface RouteMapOptions {
     /**
-     * Resolve a URL path to a state ID and params.
-     *
-     * @param path - URL pathname (e.g., "/settings/account")
-     * @returns Object with `to` (state ID with # prefix) and `params`
+     * Maximum number of resolved parameterized path lookups to cache.
      *
-     * Example:
-     * ```typescript
-     * const { to, params } = routeMap.resolve('/settings/account');
-     * // { to: "#settings", params: { section: "account" } }
+     * `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g.
+     * `/profile/:userId`) via URLPattern on every call. Frequently visited
+     * paths are cached in an LRU so subsequent lookups are O(1).
      *
-     * if (to) {
-     *   actor.send({ type: 'play.route', to, params });
-     * }
-     * ```
+     * Increase this value for applications with large parameterized route sets
+     * or high navigation frequency. Default: `500`.
      */
-    resolve(path: string): {
-        to: string | null;
-        params: Record<string, string>;
-    };
+    cacheSize?: number;
 }
 /**
- * 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 declare function createRouteMap(routeTree: RouteTree): RouteMap;
+export declare function createRouteMap(machine: AnyStateMachine, options?: RouteMapOptions): RouteMap;
 //# sourceMappingURL=create-route-map.d.ts.map