@xmachines/docs 1.0.0-beta.21 → 1.0.0-beta.23

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

@@ -2,7 +2,7 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L82)
+Defined in: [router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L87)
 
 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:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L96)
+Defined in: [router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L101)
 
 #### Parameters
 
@@ -49,15 +49,15 @@ Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-j
 
 | 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:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L97)   |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L85)   |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L84)   |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                | [router-bridge-base.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L87)   |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L86)   |
-| <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:98](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L98)   |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L100) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                | [router-bridge-base.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L99)   |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                | [router-bridge-base.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L88)   |
+| <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.23/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.23/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.23/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.23/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.23/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.23/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.23/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.23/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.23/packages/play-router/src/router-bridge-base.ts#L93)   |
 
 ## Methods
 
@@ -67,13 +67,22 @@ Defined in: [router-bridge-base.ts:96](https://gitlab.com/xmachin-es/xmachines-j
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L116)
+Defined in: [router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L129)
 
 Connect the router bridge to the Actor.
 
 Sets up the TC39 Signal watcher for actor → router direction and
 starts watching router changes (framework-specific).
 
+Ordering here is part of the bridge contract:
+
+- `lastSyncedPath` is seeded in the constructor from `actor.currentRoute`
+- the actor watcher is installed before adapter router subscriptions
+- initial sync then resolves deep-link vs restore using `actor.initialRoute`
+
+Adapters that need custom initial-sync behavior should override
+`getInitialRouterPath()` rather than reordering `connect()` steps.
+
 #### Returns
 
 `void`
@@ -90,7 +99,7 @@ starts watching router changes (framework-specific).
 disconnect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:184](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L184)
+Defined in: [router-bridge-base.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L197)
 
 Disconnect the router bridge from the Actor.
 
@@ -112,7 +121,7 @@ Stops signal watching and unregisters framework-specific router listener.
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:283](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L283)
+Defined in: [router-bridge-base.ts:300](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L300)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -142,7 +151,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:310](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L310)
+Defined in: [router-bridge-base.ts:321](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L321)
 
 Extract query parameters from URL search string.
 
@@ -166,7 +175,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L357)
+Defined in: [router-bridge-base.ts:368](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L368)
 
 Return the router's current pathname at connect() time.
 
@@ -198,7 +207,7 @@ bridges that have not yet implemented this hook.
 abstract protected navigateRouter(path): void;
 ```
 
-Defined in: [router-bridge-base.ts:322](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L322)
+Defined in: [router-bridge-base.ts:333](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L333)
 
 Navigate the framework router to the given path.
 
@@ -223,7 +232,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [router-bridge-base.ts:231](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L231)
+Defined in: [router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L248)
 
 Sync actor state when router location changes.
 
@@ -249,13 +258,17 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [router-bridge-base.ts:211](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L211)
+Defined in: [router-bridge-base.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L228)
 
 Sync router location when actor route signal changes.
 
 Calls navigateRouter() for framework-specific navigation.
 Prevents circular updates via isProcessingNavigation flag.
 
+`lastSyncedPath` is updated before `navigateRouter()` and the processing flag is
+released in a microtask so synchronous router callbacks triggered by navigation are
+suppressed as circular echoes.
+
 #### Parameters
 
 | Parameter | Type      |
@@ -274,7 +287,7 @@ Prevents circular updates via isProcessingNavigation flag.
 abstract protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:337](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L337)
+Defined in: [router-bridge-base.ts:348](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L348)
 
 Stop watching for router location changes.
 
@@ -292,7 +305,7 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 abstract protected watchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:330](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/router-bridge-base.ts#L330)
+Defined in: [router-bridge-base.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-bridge-base.ts#L341)
 
 Start watching for router location changes.
 

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

@@ -0,0 +1,32 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / buildPlayRouteEvent
+
+# Function: buildPlayRouteEvent()
+
+```ts
+function buildPlayRouteEvent(options): {
+	event: PlayRouteEvent;
+	pathname: string;
+} | null;
+```
+
+Defined in: [router-sync.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-sync.ts#L93)
+
+Build a normalized `play.route` event from raw router/browser input.
+
+Both `connectRouter()` (from `@xmachines/play-dom-router`) and `RouterBridgeBase`
+use this helper so low-level and framework adapters share the same pathname
+sanitization, route resolution, and query extraction behavior.
+
+## Parameters
+
+| Parameter | Type                                                                        |
+| --------- | --------------------------------------------------------------------------- |
+| `options` | [`BuildPlayRouteEventOptions`](../interfaces/BuildPlayRouteEventOptions.md) |
+
+## Returns
+
+\| \{
+`event`: [`PlayRouteEvent`](../interfaces/PlayRouteEvent.md);
+`pathname`: `string`;
+\}
+\| `null`

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.21/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.23/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:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/create-route-map.ts#L121)
+Defined in: [create-route-map.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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/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.21/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.23/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.21/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.23/packages/play-router/src/extract-routes.ts#L93)
 
 Extract complete route tree from state machine graph
 

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

@@ -0,0 +1,22 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / extractQuery
+
+# Function: extractQuery()
+
+```ts
+function extractQuery(search): Record<string, string>;
+```
+
+Defined in: [router-sync.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-sync.ts#L74)
+
+Parse a URL search string into the plain object shape expected by
+`play.route` events.
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `search`  | `string` |
+
+## Returns
+
+`Record`\<`string`, `string`\>

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

@@ -6,7 +6,7 @@
 function findRouteById(tree, id): RouteNode | undefined;
 ```
 
-Defined in: [find-route.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/find-route.ts#L91)
+Defined in: [find-route.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/find-route.ts#L116)
+Defined in: [find-route.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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.21/packages/play-router/src/query.ts#L22)
+Defined in: [query.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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.21/packages/play-router/src/query.ts#L67)
+Defined in: [query.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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.21/packages/play-router/src/query.ts#L113)
+Defined in: [query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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.21/packages/play-router/src/query.ts#L149)
+Defined in: [query.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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.21/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.23/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.21/packages/play-router/src/query.ts#L89)
+Defined in: [query.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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.21/packages/play-router/src/router-sync.ts#L63)
+Defined in: [router-sync.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-sync.ts#L63)
 
 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.21/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.23/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.21/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.23/packages/play-router/src/validate-routes.ts#L32)
 
 Validate state exists in state ID set
 

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

@@ -2,7 +2,7 @@
 
 # Interface: BaseRouteMapping
 
-Defined in: [base-route-map.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/base-route-map.ts#L64)
+Defined in: [base-route-map.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/base-route-map.ts#L57)
 
 A single state ID ↔ path mapping entry.
 
@@ -23,5 +23,5 @@ const optionalMapping: BaseRouteMapping = { stateId: "settings", path: "/setting
 
 | Property                                | Modifier   | Type     | Description                                                                   | Defined in                                                                                                                              |
 | --------------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/base-route-map.ts#L68) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [base-route-map.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/base-route-map.ts#L66) |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | URL path pattern (e.g., `"/"`, `"/profile/:userId"`, `"/settings/:section?"`) | [base-route-map.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/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"`)                         | [base-route-map.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/base-route-map.ts#L59) |

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

@@ -0,0 +1,13 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / BuildPlayRouteEventOptions
+
+# Interface: BuildPlayRouteEventOptions
+
+Defined in: [router-sync.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-sync.ts#L8)
+
+## 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.23/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.23/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.23/packages/play-router/src/router-sync.ts#L10) |

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

@@ -2,7 +2,7 @@
 
 # Interface: MachineEdgeData
 
-Defined in: [types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L22)
+Defined in: [types.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L22)
 
 Data attached to each edge in the machine graph representation.
 Captures transition event and guard information.
@@ -11,5 +11,5 @@ Captures transition event and guard information.
 
 | Property                                     | Type     | Description                                  | Defined in                                                                                                            |
 | -------------------------------------------- | -------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-eventtype"></a> `eventType`  | `string` | The event type that triggers this transition | [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L24) |
-| <a id="property-guardtype"></a> `guardType?` | `string` | String representation of guard (if any)      | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L26) |
+| <a id="property-eventtype"></a> `eventType`  | `string` | The event type that triggers this transition | [types.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L24) |
+| <a id="property-guardtype"></a> `guardType?` | `string` | String representation of guard (if any)      | [types.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L26) |

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

@@ -2,7 +2,7 @@
 
 # Interface: MachineNodeData
 
-Defined in: [types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L7)
+Defined in: [types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L7)
 
 Data attached to each node in the machine graph representation.
 Captures the essential state metadata needed for route extraction and queries.
@@ -11,7 +11,7 @@ Captures the essential state metadata needed for route extraction and queries.
 
 | Property                                | Type                                                                   | Description                                        | Defined in                                                                                                            |
 | --------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | Original state meta object                         | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L13) |
-| <a id="property-route"></a> `route?`    | `string`                                                               | Extracted route path from meta.route (string form) | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L15) |
-| <a id="property-stateid"></a> `stateId` | `string`                                                               | XState state ID (e.g., "test.dashboard.overview")  | [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L9)   |
-| <a id="property-type"></a> `type`       | `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` \| `"history"` | State type from XState                             | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L11) |
+| <a id="property-meta"></a> `meta?`      | `Record`\<`string`, `unknown`\>                                        | Original state meta object                         | [types.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L13) |
+| <a id="property-route"></a> `route?`    | `string`                                                               | Extracted route path from meta.route (string form) | [types.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L15) |
+| <a id="property-stateid"></a> `stateId` | `string`                                                               | XState state ID (e.g., "test.dashboard.overview")  | [types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L9)   |
+| <a id="property-type"></a> `type`       | `"atomic"` \| `"compound"` \| `"parallel"` \| `"final"` \| `"history"` | State type from XState                             | [types.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L11) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [types.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L216)
+Defined in: [types.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L216)
 
 Enhanced routing event with parameter and query support
 
@@ -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`                      | [types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L221) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L219) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L220) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L218) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:217](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L217) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [types.ts:221](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L221) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [types.ts:219](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L219) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [types.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L220) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [types.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L218) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [types.ts:217](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L217) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteInfo
 
-Defined in: [types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L54)
+Defined in: [types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L54)
 
 Extracted route information from a state node
 
@@ -10,10 +10,10 @@ Extracted route information from a state node
 
 | Property                                      | Type                                                | Description                                                                                          | Defined in                                                                                                            |
 | --------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L64) |
-| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L71) |
-| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L62) |
-| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L69) |
-| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L60) |
-| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L56) |
-| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/types.ts#L58) |
+| <a id="property-isabsolute"></a> `isAbsolute` | `boolean`                                           | Whether route path is absolute (starts with /)                                                       | [types.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L64) |
+| <a id="property-metadata"></a> `metadata`     | [`RouteMetadata`](../type-aliases/RouteMetadata.md) | Original route metadata                                                                              | [types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L71) |
+| <a id="property-pattern"></a> `pattern?`      | `string`                                            | Route pattern with parameters (e.g., /profile/:userId) if routePath contains params                  | [types.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L62) |
+| <a id="property-routable"></a> `routable`     | `boolean`                                           | Whether this state is routable (has meta.route) true = has meta.route, can receive play.route events | [types.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L69) |
+| <a id="property-routepath"></a> `routePath`   | `string`                                            | Route path extracted from meta.route                                                                 | [types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L60) |
+| <a id="property-stateid"></a> `stateId`       | `string`                                            | State identifier (node.id or path.join('.'))                                                         | [types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L56) |
+| <a id="property-statepath"></a> `statePath`   | `string`[]                                          | State path segments from root                                                                        | [types.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/types.ts#L58) |

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

@@ -2,7 +2,7 @@
 
 # Interface: RouteMap
 
-Defined in: [create-route-map.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/create-route-map.ts#L28)
+Defined in: [create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/create-route-map.ts#L20)
 
 Bidirectional route resolution interface returned by `createRouteMap()`.
 
@@ -23,7 +23,7 @@ events into `play.route` actor events.
 resolve(path): object;
 ```
 
-Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [create-route-map.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/create-route-map.ts#L37)
 
 Resolve a URL path to a state ID and params.
 
@@ -52,5 +52,5 @@ if (to) {
 
 | Name     | Type                           | Defined in                                                                                                                                  |
 | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `params` | `Record`\<`string`, `string`\> | [create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/create-route-map.ts#L47) |
-| `to`     | `string` \| `null`             | [create-route-map.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.21/packages/play-router/src/create-route-map.ts#L46) |
+| `params` | `Record`\<`string`, `string`\> | [create-route-map.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/create-route-map.ts#L39) |
+| `to`     | `string` \| `null`             | [create-route-map.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/create-route-map.ts#L38) |

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

@@ -0,0 +1,12 @@
+[Documentation](../../../README.md) / [@xmachines/play-router](../README.md) / RouteMatch
+
+# Interface: RouteMatch
+
+Defined in: [router-sync.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-sync.ts#L3)
+
+## Properties
+
+| Property                               | Type                              | Defined in                                                                                                                      |
+| -------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-params"></a> `params?` | `Record`\<`string`, `string`\>    | [router-sync.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-sync.ts#L5) |
+| <a id="property-to"></a> `to`          | `string` \| `null` \| `undefined` | [router-sync.ts:4](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.23/packages/play-router/src/router-sync.ts#L4) |