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

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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/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.27/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

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

@@ -2,7 +2,7 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L87)
+Defined in: [router-bridge-base.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L84)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -30,7 +30,7 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L101)
+Defined in: [router-bridge-base.ts:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L98)
 
 #### Parameters
 
@@ -49,15 +49,15 @@ Defined in: [router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-
 
 | Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                      | Defined in                                                                                                                                        |
 | --------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L102) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L90)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L89)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L92)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L91)   |
-| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L103) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L105) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L93)   |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`AbstractActor`](../../play-actor/classes/AbstractActor.md)\<[`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic), [`EventObject`](https://www.jsdocs.io/package/xstate#EventObject)\> & [`Routable`](../../play-actor/interfaces/Routable.md) | `undefined`   | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                           | [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L99)   |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L87)   |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L86)   |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L89)   |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <a id="property-routemap"></a> `routeMap`                             | `readonly`  | `object`                                                                                                                                                                                                                                                         | `undefined`   | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap()` or an equivalent. | [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L100) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L102) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L101) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L90)   |
 
 ## Methods
 
@@ -67,7 +67,7 @@ Defined in: [router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L129)
+Defined in: [router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L126)
 
 Connect the router bridge to the Actor.
 
@@ -99,7 +99,7 @@ Adapters that need custom initial-sync behavior should override
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L197)
+Defined in: [router-bridge-base.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L209)
 
 Disconnect the router bridge from the Actor.
 
@@ -121,14 +121,14 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:300](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L300)
+Defined in: [router-bridge-base.ts:318](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L318)
 
 Extract path parameters from URL using the URLPattern API.
 
 Accesses `globalThis.URLPattern` at runtime — no polyfill is imported by this
-library. If `URLPattern` is unavailable (Node.js < 24, older browsers without a
-polyfill), this method returns `{}` silently (graceful degradation — routing still
-works, params will be empty).
+library. If `URLPattern` is unavailable and the matched route has parameterized
+segments, a `URLPatternUnavailableError` is thrown — callers must provide a polyfill
+for environments without native URLPattern support (Node.js < 24, older browsers).
 
 #### Parameters
 
@@ -141,7 +141,11 @@ works, params will be empty).
 
 `Record`\<`string`, `string`\>
 
-Extracted path parameters, or empty object if URLPattern is unavailable or no match
+Extracted path parameters, or empty object if no match
+
+#### Throws
+
+When URLPattern is absent and the route is parameterized
 
 ---
 
@@ -151,7 +155,7 @@ Extracted path parameters, or empty object if URLPattern is unavailable or no ma
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:321](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L321)
+Defined in: [router-bridge-base.ts:355](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L355)
 
 Extract query parameters from URL search string.
 
@@ -175,7 +179,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:368](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L368)
+Defined in: [router-bridge-base.ts:412](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L412)
 
 Return the router's current pathname at connect() time.
 
@@ -201,13 +205,39 @@ bridges that have not yet implemented this hook.
 
 ---
 
+### getInitialRouterSearch()
+
+```ts
+protected getInitialRouterSearch(): string | undefined;
+```
+
+Defined in: [router-bridge-base.ts:429](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L429)
+
+Return the router's current search string at connect() time.
+
+Paired with `getInitialRouterPath()` — called once during connect() to pass
+the initial URL query string to `syncActorFromRouter()`. If the router's current
+URL has no search (or the subclass doesn't override this), returns `undefined`
+and `syncActorFromRouter` will produce an empty `query: {}` in the event.
+
+Subclasses that override `getInitialRouterPath()` and have a query string
+available should also override this method.
+
+#### Returns
+
+`string` \| `undefined`
+
+URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
+
+---
+
 ### navigateRouter()
 
 ```ts
 abstract protected navigateRouter(path): void;
 ```
 
-Defined in: [router-bridge-base.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L333)
+Defined in: [router-bridge-base.ts:367](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L367)
 
 Navigate the framework router to the given path.
 
@@ -226,13 +256,48 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 
 ---
 
+### resolveNavigationPath()
+
+```ts
+protected resolveNavigationPath(route): string | null;
+```
+
+Defined in: [router-bridge-base.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L340)
+
+Resolve an actor route value to a concrete URL path for navigation.
+
+Bridges that receive raw `actor.currentRoute` values in `navigateRouter`
+can call this to normalize stateIds (with or without `#` prefix) to paths.
+Returns `null` when navigation is not possible:
+
+- unknown stateId with no route map entry
+- parameterized pattern (e.g. `/profile/:id`) — no concrete values available
+- non-path string that isn't a known stateId
+
+Route maps may store stateIds with or without the `#` prefix; both forms
+are tried automatically.
+
+#### Parameters
+
+| Parameter | Type     | Description                                                    |
+| --------- | -------- | -------------------------------------------------------------- |
+| `route`   | `string` | Raw actor route value (stateId, `#`-stateId, or concrete path) |
+
+#### Returns
+
+`string` \| `null`
+
+Concrete URL path, or `null` if navigation should be skipped
+
+---
+
 ### syncActorFromRouter()
 
 ```ts
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L248)
+Defined in: [router-bridge-base.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L260)
 
 Sync actor state when router location changes.
 
@@ -258,7 +323,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [router-bridge-base.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L228)
+Defined in: [router-bridge-base.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L240)
 
 Sync router location when actor route signal changes.
 
@@ -287,7 +352,7 @@ suppressed as circular echoes.
 abstract protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:348](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L348)
+Defined in: [router-bridge-base.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L392)
 
 Stop watching for router location changes.
 
@@ -305,13 +370,23 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 abstract protected watchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-bridge-base.ts#L341)
+Defined in: [router-bridge-base.ts:385](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-bridge-base.ts#L385)
 
 Start watching for router location changes.
 
 Called by connect(). Should set up the framework-specific subscription
 for location changes and call syncActorFromRouter() on each change.
 
+**Implementations that call `syncActorFromRouter`** get `sanitizePathname`
+applied automatically — no extra work needed.
+
+**Implementations that bypass `syncActorFromRouter`** (e.g. `VueRouterBridge`,
+which builds the `play.route` event directly from `afterEach` params) MUST
+apply `sanitizePathname(path)` manually before processing the path. Skipping
+this allows oversized or malformed paths through without the length/content
+guards that protect the route-map lookup. Import `sanitizePathname` from
+`@xmachines/play-router`.
+
 #### Returns
 
 `void`

package/api/@xmachines/play-router/functions/buildPlayRouteEvent.md

@@ -9,7 +9,7 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-Defined in: [router-sync.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L93)
+Defined in: [router-sync.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/router-sync.ts#L140)
 
 Build a normalized `play.route` event from raw router/browser input.
 

package/api/@xmachines/play-router/functions/buildRouteTree.md

@@ -6,7 +6,7 @@
 function buildRouteTree(routes): RouteTree;
 ```
 
-Defined in: [build-tree.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/build-tree.ts#L13)
+Defined in: [build-tree.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.27/packages/play-router/src/build-tree.ts#L13)
 
 Build hierarchical route tree from flat route list