@xmachines/docs 1.0.0-beta.25 → 1.0.0-beta.26

package/api/@xmachines/play-react-router/functions/createRouteMapFromTree.md

@@ -6,30 +6,40 @@
 function createRouteMapFromTree(routeTree): RouteMap;
 ```
 
-Defined in: [play-react-router/src/route-map.ts:73](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/route-map.ts#L73)
+Defined in: [play-router/src/create-route-map-from-tree.ts:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/create-route-map-from-tree.ts#L31)
 
-Create RouteMap from RouteTree
+Create a `BaseRouteMap` from a `RouteTree` node structure.
 
-Converts XMachines route tree to RouteMap for use with router adapters.
+Used by framework-router adapters (React Router, TanStack Router) that pass a
+`RouteTree` produced by `extractMachineRoutes()` rather than calling
+`createRouteMapFromMachine()` 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 `BaseRouteMap` needs for browser URL matching. This matches the
+behaviour of `createRouteMapFromMachine`, which also uses `node.fullPath`.
 
 ## Parameters
 
-| Parameter   | Type                                                     | Description                            |
-| ----------- | -------------------------------------------------------- | -------------------------------------- |
-| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | Route tree from extractMachineRoutes() |
+| Parameter   | Type                                                     | Description                                            |
+| ----------- | -------------------------------------------------------- | ------------------------------------------------------ |
+| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | A `RouteTree` as returned by `extractMachineRoutes()`. |
 
 ## Returns
 
-[`RouteMap`](../classes/RouteMap.md)
+[`RouteMap`](../../play-dom-router/interfaces/RouteMap.md)
 
-RouteMap instance
+A `BaseRouteMap` for use with any `RouterBridgeBase`-based adapter.
 
 ## Example
 
 ```typescript
-import { extractMachineRoutes } from "@xmachines/play-router";
-import { createRouteMapFromTree } from "@xmachines/play-react-router";
+// Preferred — single call for XState machines:
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+const routeMap = createRouteMapFromMachine(machine);
 
+// Equivalent two-step form used by framework adapters:
+import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
 const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
+const routeMap = createRouteMapFromTree(routeTree); // uses node.fullPath (absolute)
 ```

package/api/@xmachines/play-react-router/interfaces/PlayRouteEvent.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L216)
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L223)
 
 Enhanced routing event with parameter and query support
 
@@ -30,7 +30,7 @@ Target state ID with # prefix (e.g., '#home', '#profile')
 
 ## Param
 
-Merged path + query parameters (path parameters win conflicts)
+Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
 
 ## Param
 
@@ -85,7 +85,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Merged: path + query
+	params: { section: "profile" }, // Path-only route parameter
 	query: { tab: "security" }, // Query-only
 };
 actor.send(event);
@@ -112,8 +112,8 @@ URLPatternResult for advanced use cases (debugging, pattern analysis).
 
 | Property                               | Modifier   | Type                           | Defined in                                                                                                                              |
 | -------------------------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L221) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L219) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L220) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L218) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:217](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L217) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L228) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L226) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L227) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L225) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L224) |

package/api/@xmachines/play-react-router/interfaces/PlayRouterProviderProps.md

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-react-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/play-router-provider.tsx#L10)
+Defined in: [play-react-router/src/play-router-provider.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-react-router/src/play-router-provider.tsx#L10)
 
 ## Type Parameters
 
@@ -12,9 +12,9 @@ Defined in: [play-react-router/src/play-router-provider.tsx:10](https://gitlab.c
 
 ## Properties
 
-| Property                                  | Type                                 | Description                                                                 | Defined in                                                                                                                                                                        |
-| ----------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`       | `TActor`                             | -                                                                           | [play-react-router/src/play-router-provider.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/play-router-provider.tsx#L14) |
-| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in. | [play-react-router/src/play-router-provider.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/play-router-provider.tsx#L18) |
-| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | -                                                                           | [play-react-router/src/play-router-provider.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/play-router-provider.tsx#L16) |
-| <a id="property-router"></a> `router`     | `Router`                             | -                                                                           | [play-react-router/src/play-router-provider.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/play-router-provider.tsx#L15) |
+| Property                                  | Type                                 | Description                                                                                                                                                                                                                                                                                                                                                                                              | Defined in                                                                                                                                                                        |
+| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`       | `TActor`                             | The actor to sync with React Router. Must be a stable reference — pass the same actor instance across renders. Creating the actor inline or re-creating it on every render will cause the bridge to disconnect and reconnect each time.                                                                                                                                                                  | [play-react-router/src/play-router-provider.tsx:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-react-router/src/play-router-provider.tsx#L19) |
+| <a id="property-renderer"></a> `renderer` | (`actor`, `router`) => `ReactNode`   | Renderer callback receives the same concrete actor type that was passed in.                                                                                                                                                                                                                                                                                                                              | [play-react-router/src/play-router-provider.tsx:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-react-router/src/play-router-provider.tsx#L36) |
+| <a id="property-routemap"></a> `routeMap` | [`RouteMap`](../classes/RouteMap.md) | Bidirectional route map for state ID ↔ URL path lookups. **Must be a stable reference.** The bridge is rebuilt whenever `routeMap` changes identity. If constructed inline (e.g. `createRouteMap(routeTree)` in JSX), a new object is produced on every render and the bridge reconnects every render. Memoize with `useMemo`: `const routeMap = useMemo(() => createRouteMap(routeTree), [routeTree]);` | [play-react-router/src/play-router-provider.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-react-router/src/play-router-provider.tsx#L34) |
+| <a id="property-router"></a> `router`     | `Router`                             | The React Router instance returned by `createBrowserRouter`.                                                                                                                                                                                                                                                                                                                                             | [play-react-router/src/play-router-provider.tsx:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-react-router/src/play-router-provider.tsx#L21) |

package/api/@xmachines/play-react-router/interfaces/RouteMapping.md

@@ -2,16 +2,26 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-react-router/src/route-map.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/route-map.ts#L22)
+Defined in: [play-router/src/base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L57)
 
-Mapping between state machine state ID and router path.
+A single state ID ↔ path mapping entry.
 
-Structurally compatible with `BaseRouteMapping` from `@xmachines/play-router`.
-Fields are `readonly` — entries are immutable once passed to `RouteMap`.
+Both fields are `readonly` — mappings are immutable once passed to `BaseRouteMap`.
+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.
+
+## Example
+
+```typescript
+const mapping: BaseRouteMapping = { stateId: "home", path: "/" };
+const paramMapping: BaseRouteMapping = { stateId: "profile", path: "/profile/:userId" };
+const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/settings/:section?" };
+```
 
 ## Properties
 
-| Property                                | Modifier   | Type     | Description                                                          | Defined in                                                                                                                                                |
-| --------------------------------------- | ---------- | -------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | Router path with optional parameters (e.g., `"/settings/:section?"`) | [play-react-router/src/route-map.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/route-map.ts#L26) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State ID from state machine (e.g., `"home"`, `"settings.profile"`)   | [play-react-router/src/route-map.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-react-router/src/route-map.ts#L24) |
+| Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                                              |
+| --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [play-router/src/base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L61) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L59) |

package/api/@xmachines/play-react-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:264](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L264)
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:280](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L280)
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:296](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/types.ts#L296)
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

package/api/@xmachines/play-router/README.md

@@ -239,9 +239,16 @@ import { extractMachineRoutes } from "@xmachines/play-router";
 
 const tree = extractMachineRoutes(authMachine);
 
-// Query routes
+// Query routes — use fullPath for URL matching (path is the raw meta.route segment)
 const loginRoute = tree.byStateId.get("login");
-console.log(loginRoute?.path); // "/login"
+console.log(loginRoute?.fullPath); // "/login"
+console.log(loginRoute?.path); // "/login" (same for absolute routes)
+
+// For nested relative routes the distinction matters:
+// meta.route: "overview" under "/dashboard" → path: "overview", fullPath: "/dashboard/overview"
+const overviewRoute = tree.byStateId.get("overview");
+console.log(overviewRoute?.path); // "overview"  (raw segment — relative)
+console.log(overviewRoute?.fullPath); // "/dashboard/overview"  (resolved — use this)
 
 const dashboardRoute = tree.byPath.get("/dashboard");
 console.log(dashboardRoute?.id); // "dashboard"
@@ -286,6 +293,25 @@ const successors = getSuccessors(tree.graph!, "myMachine.home");
 - `eventType: string` — event type triggering this transition
 - `guardType?: string` — guard name/description (if transition is guarded)
 
+### createRouteMapFromMachine() / createRouteMapFromTree()
+
+Both build a `BaseRouteMap` using `node.fullPath` (absolute resolved paths) for browser URL matching.
+
+```typescript
+// Single-call form — preferred for XState machines:
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+const routeMap = createRouteMapFromMachine(machine);
+
+// Two-step form — used by framework adapter packages:
+import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+const routeTree = extractMachineRoutes(machine);
+const routeMap = createRouteMapFromTree(routeTree);
+```
+
+Both forms produce identical results. `createRouteMapFromTree` is exposed for framework adapters (React Router, TanStack Router) that need to hold the `RouteTree` separately for other purposes (e.g. graph queries).
+
+**`node.path` vs `node.fullPath`:** Every `RouteNode` carries both fields. `path` is the raw `meta.route` segment as declared in the machine — it may be relative (e.g. `"overview"`). `fullPath` is the resolved absolute path (e.g. `"/dashboard/overview"`). Route maps always use `fullPath`. Only use `path` if you specifically need the declared segment.
+
 ### Query Utilities
 
 ```typescript
@@ -341,9 +367,9 @@ const machine = createMachine({
 
 const tree = extractMachineRoutes(machine);
 
-// Bidirectional mapping
+// Bidirectional mapping — use fullPath for URLs; path is the raw meta.route segment
 const profileById = tree.byStateId.get("profile");
-console.log(profileById?.path); // "/profile/:userId"
+console.log(profileById?.fullPath); // "/profile/:userId"
 
 const profileByPath = findRouteByPath(tree, "/profile/user123");
 console.log(profileByPath?.id); // "profile"
@@ -581,19 +607,21 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 
 ## Interfaces
 
-- [BaseRouteMapping](interfaces/BaseRouteMapping.md)
 - [BuildPlayRouteEventOptions](interfaces/BuildPlayRouteEventOptions.md)
+- [LocationLike](interfaces/LocationLike.md)
 - [MachineEdgeData](interfaces/MachineEdgeData.md)
 - [MachineNodeData](interfaces/MachineNodeData.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RouteInfo](interfaces/RouteInfo.md)
 - [RouteMap](interfaces/RouteMap.md)
+- [RouteMapping](interfaces/RouteMapping.md)
 - [RouteMatch](interfaces/RouteMatch.md)
 - [RouteNode](interfaces/RouteNode.md)
 - [RouteObject](interfaces/RouteObject.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 - [RouteTree](interfaces/RouteTree.md)
 - [RouteWatcherHandle](interfaces/RouteWatcherHandle.md)
+- [WindowLike](interfaces/WindowLike.md)
 
 ## Type Aliases
 
@@ -605,9 +633,12 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 - [buildPlayRouteEvent](functions/buildPlayRouteEvent.md)
 - [buildRouteTree](functions/buildRouteTree.md)
 - [createRouteMap](functions/createRouteMap.md)
+- [createRouteMapFromMachine](functions/createRouteMapFromMachine.md)
+- [createRouteMapFromTree](functions/createRouteMapFromTree.md)
 - [detectDuplicateRoutes](functions/detectDuplicateRoutes.md)
 - [extractMachineRoutes](functions/extractMachineRoutes.md)
 - [extractQuery](functions/extractQuery.md)
+- [extractRouteParams](functions/extractRouteParams.md)
 - [findRouteById](functions/findRouteById.md)
 - [findRouteByPath](functions/findRouteByPath.md)
 - [getNavigableRoutes](functions/getNavigableRoutes.md)
@@ -619,3 +650,9 @@ For a copy, see <https://opensource.org/licenses/MIT>.
 - [sanitizePathname](functions/sanitizePathname.md)
 - [validateRouteFormat](functions/validateRouteFormat.md)
 - [validateStateExists](functions/validateStateExists.md)
+
+## References
+
+### BaseRouteMapping
+
+Renames and re-exports [RouteMapping](interfaces/RouteMapping.md)

package/api/@xmachines/play-router/classes/BaseRouteMap.md

@@ -2,7 +2,7 @@
 
 # Class: BaseRouteMap
 
-Defined in: [base-route-map.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L99)
+Defined in: [base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -14,7 +14,8 @@ own and inherit the full public API from here.
 - 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
+- Results are cached after the first match in an LRU cache (default 500 entries,
+  configurable via the `cacheSize` constructor option)
 
 **Pattern syntax** (`:param` / `:param?`):
 
@@ -41,25 +42,15 @@ map.getPathByStateId("profile"); // "/profile/:userId"
 map.getPathByStateId("missing"); // null
 ```
 
-## Extended by
-
-- [`RouteMap`](../../play-react-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-solid-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-sveltekit-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-svelte-spa-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-tanstack-react-router/classes/RouteMap.md)
-- [`RouteMap`](../../play-tanstack-solid-router/classes/RouteMap.md)
-- [`VueBaseRouteMap`](../../play-vue-router/classes/VueBaseRouteMap.md)
-
 ## Constructors
 
 ### Constructor
 
 ```ts
-new BaseRouteMap(mappings): BaseRouteMap;
+new BaseRouteMap(mappings, options?): BaseRouteMap;
 ```
 
-Defined in: [base-route-map.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L118)
+Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -69,9 +60,11 @@ buckets for efficient candidate selection.
 
 #### Parameters
 
-| Parameter  | Type                                                      | Description                                                                                                       |
-| ---------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `mappings` | [`BaseRouteMapping`](../interfaces/BaseRouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path. |
+| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | Array of `{ stateId, path }` entries. Order determines priority when multiple patterns could match the same path.                                                                                                                                                                                                                                                                                            |
+| `options`            | \{ `cacheSize?`: `number`; \}                     | 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). |
+| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
@@ -85,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L202)
+Defined in: [base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -116,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/base-route-map.ts#L167)
+Defined in: [base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.