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

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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/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.26/packages/play-router/src/build-tree.ts#L13)
 
 Build hierarchical route tree from flat route list
 

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

@@ -6,7 +6,7 @@
 function createRouteMap(routeTree): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/create-route-map.ts#L74)
+Defined in: [create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/create-route-map.ts#L74)
 
 Create a RouteMap from a RouteTree for efficient path lookups.
 

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

@@ -0,0 +1,38 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMapFromMachine
+
+# Function: createRouteMapFromMachine()
+
+```ts
+function createRouteMapFromMachine(machine): BaseRouteMap;
+```
+
+Defined in: [create-route-map-from-machine.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/create-route-map-from-machine.ts#L26)
+
+Create a `BaseRouteMap` 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.
+
+## Parameters
+
+| Parameter | Type                                                                      | Description                                                      |
+| --------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `machine` | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states. |
+
+## Returns
+
+[`BaseRouteMap`](../classes/BaseRouteMap.md)
+
+A `BaseRouteMap` for passing to any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+import { createRouteMapFromMachine } from "@xmachines/play-router";
+import { connectRouter } from "@xmachines/play-dom-router";
+
+const routeMap = createRouteMapFromMachine(myMachine);
+const disconnect = connectRouter({ actor, router, routeMap });
+```

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

@@ -0,0 +1,45 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / createRouteMapFromTree
+
+# Function: createRouteMapFromTree()
+
+```ts
+function createRouteMapFromTree(routeTree): BaseRouteMap;
+```
+
+Defined in: [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 a `BaseRouteMap` from a `RouteTree` node structure.
+
+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`](../interfaces/RouteTree.md) | A `RouteTree` as returned by `extractMachineRoutes()`. |
+
+## Returns
+
+[`BaseRouteMap`](../classes/BaseRouteMap.md)
+
+A `BaseRouteMap` for use with any `RouterBridgeBase`-based adapter.
+
+## Example
+
+```typescript
+// 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); // uses node.fullPath (absolute)
+```

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

@@ -6,7 +6,7 @@
 function detectDuplicateRoutes(routes): void;
 ```
 
-Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/validate-routes.ts#L51)
+Defined in: [validate-routes.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/validate-routes.ts#L51)
 
 Detect duplicate route paths
 

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

@@ -6,7 +6,7 @@
 function extractMachineRoutes(machine): RouteTree;
 ```
 
-Defined in: [extract-routes.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/extract-routes.ts#L93)
+Defined in: [extract-routes.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/extract-routes.ts#L93)
 
 Extract complete route tree from state machine graph
 

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

@@ -6,7 +6,7 @@
 function extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-sync.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L74)
+Defined in: [router-sync.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-sync.ts#L121)
 
 Parse a URL search string into the plain object shape expected by
 `play.route` events.

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

@@ -0,0 +1,46 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / extractRouteParams
+
+# Function: extractRouteParams()
+
+```ts
+function extractRouteParams(pathname, pattern): Record<string, string>;
+```
+
+Defined in: [router-sync.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-sync.ts#L101)
+
+Extract named path parameters from a URL using the URLPattern API.
+
+Takes the pattern string directly — use this when the pattern is already known.
+For extraction via a state ID lookup, see `RouterBridgeBase.extractParams`.
+
+Undefined values (unmatched optional segments, e.g. `/settings` against
+`/settings/:section?`) are omitted from the returned object.
+
+## Parameters
+
+| Parameter  | Type     | Description                                          |
+| ---------- | -------- | ---------------------------------------------------- |
+| `pathname` | `string` | The concrete URL pathname (e.g. `/profile/alice`)    |
+| `pattern`  | `string` | The URL pattern template (e.g. `/profile/:username`) |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+A record of extracted parameter values, or `{}` for static patterns.
+
+## Throws
+
+When `URLPattern` is absent and the pattern is parameterized.
+
+## Example
+
+```typescript
+import { extractRouteParams } from "@xmachines/play-router";
+
+extractRouteParams("/profile/alice", "/profile/:username");
+// → { username: "alice" }
+
+extractRouteParams("/settings", "/settings/:section?");
+// → {}  (optional param absent — not included)
+```

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

@@ -6,7 +6,7 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/find-route.ts#L52)
+Defined in: [find-route.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/find-route.ts#L52)
 
 Find route node by state ID
 

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

@@ -6,7 +6,7 @@
 function findRouteByPath(tree, path): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/find-route.ts#L77)
+Defined in: [find-route.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/find-route.ts#L77)
 
 Find route node by URL path
 

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

@@ -6,7 +6,7 @@
 function getNavigableRoutes(tree, stateId): RouteNode[];
 ```
 
-Defined in: [query.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L22)
+Defined in: [query.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/query.ts#L22)
 
 Get all routes navigable from given state
 

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

@@ -6,7 +6,7 @@
 function getRoutableRoutes(tree): RouteNode[];
 ```
 
-Defined in: [query.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L67)
+Defined in: [query.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/query.ts#L67)
 
 Get all routable routes from tree as flat array
 

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

@@ -6,7 +6,7 @@
 function getTransitionReachableRoutes(graph, stateId): string[];
 ```
 
-Defined in: [query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L113)
+Defined in: [query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/query.ts#L113)
 
 Get routes reachable via transitions from current state
 

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

@@ -6,7 +6,7 @@
 function isRouteReachable(graph, fromStateId, toStateId): boolean;
 ```
 
-Defined in: [query.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L149)
+Defined in: [query.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/query.ts#L149)
 
 Check if a route is reachable from current state via transitions
 

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

@@ -6,7 +6,7 @@
 function machineToGraph(machine): MachineGraph;
 ```
 
-Defined in: [machine-to-graph.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/machine-to-graph.ts#L70)
+Defined in: [machine-to-graph.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/machine-to-graph.ts#L70)
 
 ## Parameters
 

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

@@ -6,7 +6,7 @@
 function routeExists(tree, path): boolean;
 ```
 
-Defined in: [query.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/query.ts#L89)
+Defined in: [query.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/query.ts#L89)
 
 Validate route path exists in tree
 

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

@@ -6,7 +6,7 @@
 function sanitizePathname(pathname): string | null;
 ```
 
-Defined in: [router-sync.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L63)
+Defined in: [router-sync.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-sync.ts#L69)
 
 Normalize a pathname before route-map lookup.
 

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

@@ -6,7 +6,7 @@
 function validateRouteFormat(routePath, stateId): void;
 ```
 
-Defined in: [validate-routes.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/validate-routes.ts#L14)
+Defined in: [validate-routes.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/validate-routes.ts#L14)
 
 Validate route path format
 

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

@@ -6,7 +6,7 @@
 function validateStateExists(stateId, stateIds): void;
 ```
 
-Defined in: [validate-routes.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/validate-routes.ts#L32)
+Defined in: [validate-routes.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/validate-routes.ts#L32)
 
 Validate state exists in state ID set
 

package/api/@xmachines/play-router/interfaces/BuildPlayRouteEventOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: BuildPlayRouteEventOptions
 
-Defined in: [router-sync.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L8)
+Defined in: [router-sync.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-sync.ts#L14)
 
 ## Properties
 
 | Property                                  | Type                                                   | Defined in                                                                                                                        |
 | ----------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L9)   |
-| <a id="property-resolve"></a> `resolve`   | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L11) |
-| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.25/packages/play-router/src/router-sync.ts#L10) |
+| <a id="property-pathname"></a> `pathname` | `string`                                               | [router-sync.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-sync.ts#L15) |
+| <a id="property-resolve"></a> `resolve`   | (`sanitizedPathname`) => [`RouteMatch`](RouteMatch.md) | [router-sync.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-sync.ts#L17) |
+| <a id="property-search"></a> `search?`    | `string`                                               | [router-sync.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/router-sync.ts#L16) |

package/api/@xmachines/play-router/interfaces/LocationLike.md

@@ -0,0 +1,27 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / LocationLike
+
+# Interface: LocationLike
+
+Defined in: [types.ts:344](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L344)
+
+Minimal location interface required by adapters that read the current URL at
+`connect()` time. Injectable for SSR and testing — pass a mock instead of the
+global `location` when the DOM is unavailable.
+
+Defined structurally (no `Location` reference) so this package compiles without
+the DOM lib.
+
+## Example
+
+```typescript
+// SSR / test — injected mock
+const mockLoc: LocationLike = { pathname: "/dashboard", search: "?tab=posts" };
+connectRouter({ actor, routeMap, location: mockLoc });
+```
+
+## Properties
+
+| Property                                  | Modifier   | Type     | Defined in                                                                                                              |
+| ----------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [types.ts:345](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L345) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.26/packages/play-router/src/types.ts#L346) |