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

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

@@ -0,0 +1,136 @@
+/**
+ * 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 `RouteMap`.
+ * Adapter packages re-export a structurally compatible `RouteMapping` type under
+ * their own name. This type is published from `@xmachines/play-router` as
+ * `RouteMapping` to avoid name collisions with those adapter-local types.
+ *
+ * @example
+ * ```typescript
+ * 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 {
+    /** State machine state ID (e.g., `"home"`, `"#profile"`) */
+    readonly stateId: string;
+    /** URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) */
+    readonly path: string;
+}
+/**
+ * Shared bidirectional route map base class.
+ *
+ * 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 `URLPattern`, where `k` is the number
+ *   of routes sharing the same first path segment
+ * - Results are cached after the first match in an LRU cache (default 500 entries,
+ *   configurable via the `cacheSize` constructor option)
+ *
+ * **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 { RouteMap } from "@xmachines/play-router";
+ *
+ * const map = new RouteMap([
+ *   { stateId: "home",     path: "/" },
+ *   { stateId: "profile",  path: "/profile/:userId" },
+ *   { stateId: "settings", path: "/settings/:section?" },
+ * ]);
+ *
+ * map.getStateIdByPath("/");               // "home"
+ * map.getStateIdByPath("/profile/123");    // "profile"
+ * map.getStateIdByPath("/settings");       // "settings"
+ * map.getStateIdByPath("/unknown");        // null
+ *
+ * map.getPathByStateId("profile");         // "/profile/:userId"
+ * map.getPathByStateId("missing");         // null
+ * ```
+ */
+export declare class RouteMap {
+    /** Keyed on the canonical (bare, `#`-stripped) stateId form. */
+    private stateIdToPath;
+    private pathToStateId;
+    private patternBuckets;
+    private pathMatchCache;
+    /**
+     * 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 `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[], { cacheSize }?: {
+        cacheSize?: number;
+    });
+    /**
+     * Resolve a URL path to its mapped state ID.
+     *
+     * Strips query strings and hash fragments before matching. Tries an O(1) exact
+     * lookup first, then falls back to bucket-indexed pattern matching. Results are
+     * cached after the first pattern match.
+     *
+     * @param path - URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`)
+     * @returns The mapped state ID, or `null` if no route matches
+     *
+     * @example
+     * ```typescript
+     * map.getStateIdByPath("/profile/123");  // "profile"
+     * map.getStateIdByPath("/unknown");      // null
+     * ```
+     */
+    getStateIdByPath(path: string): string | null;
+    /**
+     * 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;
+}
+//# sourceMappingURL=base-route-map.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,182 @@
+/**
+ * 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 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 `URLPattern`, where `k` is the number
+ *   of routes sharing the same first path segment
+ * - Results are cached after the first match in an LRU cache (default 500 entries,
+ *   configurable via the `cacheSize` constructor option)
+ *
+ * **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 { RouteMap } from "@xmachines/play-router";
+ *
+ * const map = new RouteMap([
+ *   { stateId: "home",     path: "/" },
+ *   { stateId: "profile",  path: "/profile/:userId" },
+ *   { stateId: "settings", path: "/settings/:section?" },
+ * ]);
+ *
+ * map.getStateIdByPath("/");               // "home"
+ * map.getStateIdByPath("/profile/123");    // "profile"
+ * map.getStateIdByPath("/settings");       // "settings"
+ * map.getStateIdByPath("/unknown");        // null
+ *
+ * map.getPathByStateId("profile");         // "/profile/:userId"
+ * map.getPathByStateId("missing");         // null
+ * ```
+ */
+export class RouteMap {
+    /** Keyed on the canonical (bare, `#`-stripped) stateId form. */
+    stateIdToPath;
+    pathToStateId;
+    patternBuckets;
+    pathMatchCache;
+    /**
+     * 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 `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, { cacheSize = 500 } = {}) {
+        this.stateIdToPath = new Map();
+        this.pathToStateId = new Map();
+        this.patternBuckets = new Map();
+        this.pathMatchCache = new QuickLRU({ maxSize: Math.max(1, cacheSize) });
+        let patternOrder = 0;
+        for (const { stateId, path } of mappings) {
+            // 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) ?? [];
+                try {
+                    bucket.push({
+                        pattern: getCompiledPattern(path, URLPatternCtorFn),
+                        stateId,
+                        order: patternOrder++,
+                    });
+                }
+                catch (err) {
+                    throw new InvalidRoutePatternError(path, { cause: err });
+                }
+                this.patternBuckets.set(bucketKey, bucket);
+            }
+            else {
+                this.pathToStateId.set(path, stateId);
+            }
+        }
+    }
+    /**
+     * Resolve a URL path to its mapped state ID.
+     *
+     * Strips query strings and hash fragments before matching. Tries an O(1) exact
+     * lookup first, then falls back to bucket-indexed pattern matching. Results are
+     * cached after the first pattern match.
+     *
+     * @param path - URL pathname, optionally including query/hash (e.g., `"/profile/123?ref=nav"`)
+     * @returns The mapped state ID, or `null` if no route matches
+     *
+     * @example
+     * ```typescript
+     * map.getStateIdByPath("/profile/123");  // "profile"
+     * map.getStateIdByPath("/unknown");      // null
+     * ```
+     */
+    getStateIdByPath(path) {
+        // Strip query string and hash fragment for matching
+        const cleanPath = path.split("?")[0].split("#")[0];
+        const exactMatch = this.pathToStateId.get(cleanPath);
+        if (exactMatch !== undefined)
+            return exactMatch;
+        const cachedMatch = this.pathMatchCache.get(cleanPath);
+        if (cachedMatch !== undefined)
+            return cachedMatch;
+        const candidates = getCandidates(this.patternBuckets, getIndexKey(cleanPath));
+        for (const { pattern, stateId } of candidates) {
+            const match = pattern.exec({ pathname: cleanPath });
+            if (match) {
+                this.pathMatchCache.set(cleanPath, stateId);
+                return stateId;
+            }
+        }
+        this.pathMatchCache.set(cleanPath, null);
+        return null;
+    }
+    /**
+     * 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(canonicalStateIdKey(stateId)) ?? null;
+    }
+}
+//# sourceMappingURL=base-route-map.js.map

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

@@ -0,0 +1 @@
+{"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,46 +1,42 @@
-import type { RouteTree } from "./types.js";
-export interface RouteMap {
+import type { AnyStateMachine } from "xstate";
+import { RouteMap } from "./base-route-map.js";
+/**
+ * Options for `createRouteMap` and `createRouteMapFromTree`.
+ */
+export interface RouteMapOptions {
     /**
-     * Resolve a URL path to a state ID and params.
+     * Maximum number of resolved parameterized path lookups to cache.
      *
-     * @param path - URL pathname (e.g., "/settings/account")
-     * @returns Object with `to` (state ID with # prefix) and `params`
+     * `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).
      *
-     * Example:
-     * ```typescript
-     * const { to, params } = routeMap.resolve('/settings/account');
-     * // { to: "#settings", params: { section: "account" } }
-     *
-     * 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.
+ *
+ * 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.
  *
- * 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
+ * @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

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,EAAE,MAAM,YAAY,CAAC;AAG5C,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;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,CAyD7D"}
+{"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"}