@xmachines/docs 1.0.0-beta.50 → 1.0.0-beta.52

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

@@ -13,13 +13,13 @@ Part of the [xmachines-js monorepo](../../README.md).
 ## Installation
 
 ```bash
-npm install xstate@^5.30.0
+npm install xstate@^5.31.0
 npm install @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `xstate` ^5.30.0 — XState v5 state machine runtime
+- `xstate` ^5.31.0 — XState v5 state machine runtime
 
 **URLPattern polyfill (Node.js < 24 / older browsers):**
 
@@ -128,15 +128,14 @@ Extend `RouterBridgeBase` and implement the three abstract methods for your fram
 
 ```typescript
 import { RouterBridgeBase } from "@xmachines/play-router";
-import type { AbstractActor, Routable } from "@xmachines/play-actor";
-import type { AnyActorLogic } from "xstate";
+import type { RoutableActor } from "@xmachines/play-router";
 
 export class MyRouterBridge extends RouterBridgeBase {
 	private unsubscribe: (() => void) | null = null;
 
 	constructor(
 		private readonly myRouter: MyRouter,
-		actor: AbstractActor<AnyActorLogic> & Routable,
+		actor: RoutableActor,
 		routeMap: ReturnType<typeof createRouteMap>,
 	) {
 		super(actor, routeMap);
@@ -225,18 +224,20 @@ bridge.disconnect();
 
 ### Key Types
 
-| Export                             | Description                                                                            |
-| ---------------------------------- | -------------------------------------------------------------------------------------- |
-| `RouterBridge`                     | Interface for `connect()` / `disconnect()` lifecycle                                   |
-| `RouteTree`                        | Hierarchical tree with `root`, `byStateId`, `byPath`, and optional `graph`             |
-| `RouteNode`                        | Single node in the tree with `id`, `path`, `fullPath`, `stateId`, `children`, `parent` |
-| `RouteInfo`                        | Flat route descriptor extracted from a state node                                      |
-| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                            |
-| `RouteMapping`                     | `{ stateId, path }` pair used to build a `RouteMap`                                    |
-| `RouteMapping as BaseRouteMapping` | Alias for `RouteMapping` (backwards-compat re-export)                                  |
-| `MachineGraph`                     | Typed `@statelyai/graph` Graph with `MachineNodeData` / `MachineEdgeData`              |
-| `WindowLike`                       | Injectable minimal `window` interface for SSR / testing                                |
-| `LocationLike`                     | Injectable minimal `location` interface for SSR / testing                              |
+| Export                             | Description                                                                                                            |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `RouterBridge`                     | Interface for `connect()` / `disconnect()` lifecycle                                                                   |
+| `RouteTree`                        | Hierarchical tree with `root`, `byStateId`, `byPath`, and optional `graph`                                             |
+| `RouteNode`                        | Single node in the tree with `id`, `path`, `fullPath`, `stateId`, `children`, `parent`                                 |
+| `RouteInfo`                        | Flat route descriptor extracted from a state node                                                                      |
+| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                                                            |
+| `RoutableActor`                    | Minimal actor interface required by `RouterBridgeBase` — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)`    |
+| `PlayActor`                        | Full actor interface used by `PlayRouterProvider` — extends `RoutableActor` with `currentView` (`Routable + Viewable`) |
+| `RouteMapping`                     | `{ stateId, path }` pair used to build a `RouteMap`                                                                    |
+| `RouteMapping as BaseRouteMapping` | Alias for `RouteMapping` (backwards-compat re-export)                                                                  |
+| `MachineGraph`                     | Typed `@statelyai/graph` Graph with `MachineNodeData` / `MachineEdgeData`                                              |
+| `WindowLike`                       | Injectable minimal `window` interface for SSR / testing                                                                |
+| `LocationLike`                     | Injectable minimal `location` interface for SSR / testing                                                              |
 
 ### Errors (subpath `@xmachines/play-router/errors`)
 
@@ -347,7 +348,7 @@ runBridgeContractTests({
 ## Related Packages
 
 - **[@xmachines/play](../play/README.md)** — Core protocol types (`PlayEvent`, `PlayError`)
-- **[@xmachines/play-actor](../play-actor/README.md)** — Abstract actor base class (`AbstractActor`, `Routable`)
+- **[@xmachines/play-actor](../play-actor/README.md)** — Abstract actor base class (`AbstractActor`, `Routable`); all `AbstractActor` subclasses satisfy `RoutableActor` structurally
 - **[@xmachines/play-signals](../play-signals/README.md)** — TC39 Signals polyfill used for actor route observation
 - **[@xmachines/play-xstate](../play-xstate/README.md)** — XState v5 logic adapter that integrates with route trees
 - **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md)** — TanStack Router adapter (React)
@@ -371,7 +372,9 @@ MIT — see [LICENSE](LICENSE).
 - [LocationLike](interfaces/LocationLike.md)
 - [MachineEdgeData](interfaces/MachineEdgeData.md)
 - [MachineNodeData](interfaces/MachineNodeData.md)
+- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
+- [RoutableActor](interfaces/RoutableActor.md)
 - [RouteInfo](interfaces/RouteInfo.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L100)
 
 Shared bidirectional route map base class.
 
@@ -50,7 +50,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L125)
 
 Build a route map from an array of state ID ↔ path mappings.
 
@@ -78,7 +78,7 @@ buckets for efficient candidate selection.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L209)
 
 Look up the path pattern registered for a state ID.
 
@@ -109,7 +109,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

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

@@ -2,7 +2,7 @@
 
 # Abstract Class: RouterBridgeBase
 
-Defined in: [router-bridge-base.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L101)
+Defined in: [router-bridge-base.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L100)
 
 Abstract base class for all `@xmachines` router adapter bridges.
 
@@ -15,7 +15,7 @@ between frameworks.
 - [`ReactRouterBridge`](../../play-react-router/classes/ReactRouterBridge.md)
 - [`SolidRouterBridge`](../../play-solid-router/classes/SolidRouterBridge.md)
 - [`TanStackReactRouterBridge`](../../play-tanstack-react-router/classes/TanStackReactRouterBridge.md)
-- [`SolidRouterBridge`](../../play-tanstack-solid-router/classes/SolidRouterBridge.md)
+- [`TanStackSolidRouterBridge`](../../play-tanstack-solid-router/classes/TanStackSolidRouterBridge.md)
 - [`VueRouterBridge`](../../play-vue-router/classes/VueRouterBridge.md)
 
 ## Implements
@@ -30,16 +30,16 @@ between frameworks.
 new RouterBridgeBase(actor, routeMap): RouterBridgeBase;
 ```
 
-Defined in: [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L125)
+Defined in: [router-bridge-base.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L124)
 
 #### Parameters
 
-| Parameter                   | Type                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                             |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `actor`                     | [`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) | A `Routable` actor exposing `currentRoute` and `send`.                                                                                                                                                  |
-| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \}                                                                                                                                              | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent. |
-| `routeMap.getPathByStateId` | -                                                                                                                                                                                                                                                                |
-| `routeMap.getStateIdByPath` | -                                                                                                                                                                                                                                                                |
+| Parameter                   | Type                                                                                                                | Description                                                                                                                                                                                             |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actor`                     | [`RoutableActor`](../interfaces/RoutableActor.md)                                                                   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                  |
+| `routeMap`                  | \{ `getPathByStateId`: `string` \| `null` \| `undefined`; `getStateIdByPath`: `string` \| `null` \| `undefined`; \} | Bidirectional route map for `stateId ↔ path` resolution. Provide `getStateIdByPath` and `getPathByStateId`. Framework adapters typically wrap the result of `createRouteMap(machine)` or an equivalent. |
+| `routeMap.getPathByStateId` | -                                                                                                                   |
+| `routeMap.getStateIdByPath` | -                                                                                                                   |
 
 #### Returns
 
@@ -47,17 +47,17 @@ Defined in: [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-
 
 ## Properties
 
-| 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:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L126) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L103) |
-| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L116) |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L105) |
-| <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(machine)` or an equivalent.                                                                                                                                                                                                                                                                                                | [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L127) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L129) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L128) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                                            | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L117) |
+| Property                                                              | Modifier    | Type                                                                  | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Defined in                                                                                                                                        |
+| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../interfaces/RoutableActor.md)                     | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L125) |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L103) |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                             | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L102) |
+| <a id="property-isprocessingnavigation"></a> `isProcessingNavigation` | `protected` | `boolean`                                                             | `false`       | Guards `syncActorFromRouter` against re-entrant calls triggered by the actor's own guard redirects (router→actor send → signal fires → actor→router push → another syncActorFromRouter before the first one returns). NOT used for actor→router echo suppression — that is handled exclusively by `lastSyncedPath`, which is updated before `navigateRouter()` is called so any router callback for the same path short-circuits at the `sanitized === lastSyncedPath` check in `syncActorFromRouter`. | [router-bridge-base.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L115) |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                    | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L104) |
+| <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(machine)` or an equivalent.                                                                                                                                                                                                                                                                                                | [router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L126) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L128) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                     | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L127) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | [`RouteWatcherHandle`](../interfaces/RouteWatcherHandle.md) \| `null` | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L116) |
 
 ## Methods
 
@@ -67,7 +67,7 @@ Defined in: [router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-
 connect(): void;
 ```
 
-Defined in: [router-bridge-base.ts:153](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L153)
+Defined in: [router-bridge-base.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L152)
 
 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:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L249)
+Defined in: [router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L248)
 
 Disconnect the router bridge from the Actor.
 
@@ -121,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:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L373)
+Defined in: [router-bridge-base.ts:402](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L402)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -155,7 +155,7 @@ When URLPattern is absent and the route is parameterized
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [router-bridge-base.ts:410](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L410)
+Defined in: [router-bridge-base.ts:439](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L439)
 
 Extract query parameters from URL search string.
 
@@ -179,7 +179,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:467](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L467)
+Defined in: [router-bridge-base.ts:512](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L512)
 
 Return the router's current pathname at connect() time.
 
@@ -211,7 +211,7 @@ bridges that have not yet implemented this hook.
 protected getInitialRouterSearch(): string | undefined;
 ```
 
-Defined in: [router-bridge-base.ts:484](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L484)
+Defined in: [router-bridge-base.ts:529](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L529)
 
 Return the router's current search string at connect() time.
 
@@ -237,11 +237,8 @@ URL search string (e.g. `"?tab=security"`), or `undefined` if not available.
 abstract protected navigateRouter(path): void;
 ```
 
-Defined in: [router-bridge-base.ts:422](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L422)
+Defined in: [router-bridge-base.ts:448](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L448)
 
-Navigate the framework router to the given path.
-
-Called when actor's currentRoute signal changes to a new path.
 Must trigger the framework router's navigation (e.g., router.navigate(path)).
 
 #### Parameters
@@ -262,7 +259,7 @@ Must trigger the framework router's navigation (e.g., router.navigate(path)).
 protected resolveNavigationPath(route): string | null;
 ```
 
-Defined in: [router-bridge-base.ts:395](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L395)
+Defined in: [router-bridge-base.ts:424](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L424)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -291,18 +288,62 @@ Concrete URL path, or `null` if navigation should be skipped
 
 ---
 
+### sanitizePath()
+
+```ts
+protected sanitizePath(pathname): string | null;
+```
+
+Defined in: [router-bridge-base.ts:466](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L466)
+
+Sanitize and validate a raw URL pathname received from the router.
+
+Applies the path-length cap (2048 chars), strips query strings and fragments
+that may have been included in the pathname segment, and normalises
+consecutive slashes.
+
+Implementations that bypass `syncActorFromRouter()` (e.g. when using
+framework-native reactive watchers that receive pre-parsed route objects)
+MUST call this method before passing the path to any route-map lookup.
+`syncActorFromRouter()` calls this internally, so bridges that delegate
+to it do not need to call `sanitizePath` themselves.
+
+#### Parameters
+
+| Parameter  | Type     | Description                                 |
+| ---------- | -------- | ------------------------------------------- |
+| `pathname` | `string` | Raw URL pathname from the framework router. |
+
+#### Returns
+
+`string` \| `null`
+
+Sanitized pathname, or `null` if the path is invalid / too long.
+
+---
+
 ### syncActorFromRouter()
 
 ```ts
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [router-bridge-base.ts:315](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L315)
+Defined in: [router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L324)
 
 Sync actor state when router location changes.
 
-Sends play.route event to actor with matched stateId, params, and query.
-Prevents circular updates via isProcessingNavigation flag.
+**Known path:** sends a `play.route` event to the actor with the matched
+stateId, params, and query. Prevents circular updates via the
+`isProcessingNavigation` flag.
+
+**Unknown/unmapped path:** does NOT send a `play.route` event (actor state
+is unchanged). Instead, actively corrects the browser URL by calling
+`navigateRouter(actor.currentRoute.get())` — keeping the URL in sync with
+actor state even when the user types an invalid path into the address bar
+or pushes one programmatically mid-session. `lastSyncedPath` is set to the
+resolved concrete path before calling `navigateRouter` so the router's own
+callback for that navigation short-circuits the echo-suppression guard and
+sends no spurious event.
 
 #### Parameters
 
@@ -323,7 +364,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [router-bridge-base.ts:290](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L290)
+Defined in: [router-bridge-base.ts:289](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L289)
 
 Sync router location when actor route signal changes.
 
@@ -356,7 +397,7 @@ no event regardless of whether the callback fires synchronously or asynchronousl
 abstract protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:447](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L447)
+Defined in: [router-bridge-base.ts:492](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L492)
 
 Stop watching for router location changes.
 
@@ -374,22 +415,21 @@ Called by disconnect(). Should clean up the framework-specific subscription.
 abstract protected watchRouterChanges(): void;
 ```
 
-Defined in: [router-bridge-base.ts:440](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-bridge-base.ts#L440)
+Defined in: [router-bridge-base.ts:485](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-bridge-base.ts#L485)
 
 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`
+**Implementations that call `syncActorFromRouter`** get path sanitization
 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`.
+which builds the `play.route` event directly from framework-native route params)
+MUST call `this.sanitizePath(path)` and return early when it returns `null`.
+Skipping this allows oversized or malformed paths through without the length
+and content guards that protect the route-map lookup.
 
 #### Returns
 

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

@@ -9,7 +9,7 @@ function buildPlayRouteEvent(options): {
 } | null;
 ```
 
-Defined in: [router-sync.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-sync.ts#L140)
+Defined in: [router-sync.ts:140](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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.50/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.52/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(machine, options?): RouteMap;
 ```
 
-Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map.ts#L45)
 
 Create a `RouteMap` from an XState state machine.
 

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

@@ -6,7 +6,7 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-map-from-tree.ts#L33)
 
 Create a `RouteMap` from a `RouteTree` node structure.
 

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

@@ -6,7 +6,7 @@
 function createRouteMatcher(routeTree): RouteMatcher;
 ```
 
-Defined in: [create-route-matcher.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/create-route-matcher.ts#L74)
+Defined in: [create-route-matcher.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/create-route-matcher.ts#L74)
 
 Create a URL pattern matcher 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:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/validate-routes.ts#L50)
+Defined in: [validate-routes.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/validate-routes.ts#L50)
 
 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.50/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.52/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:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-sync.ts#L121)
+Defined in: [router-sync.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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

@@ -6,7 +6,7 @@
 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.50/packages/play-router/src/router-sync.ts#L101)
+Defined in: [router-sync.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-sync.ts#L101)
 
 Extract named path parameters from a URL using the URLPattern API.
 

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.50/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.52/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.50/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.52/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.50/packages/play-router/src/query.ts#L22)
+Defined in: [query.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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.50/packages/play-router/src/query.ts#L67)
+Defined in: [query.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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.50/packages/play-router/src/query.ts#L113)
+Defined in: [query.ts:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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.50/packages/play-router/src/query.ts#L149)
+Defined in: [query.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/machine-to-graph.ts#L71)
+Defined in: [machine-to-graph.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/machine-to-graph.ts#L71)
 
 ## 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.50/packages/play-router/src/query.ts#L89)
+Defined in: [query.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/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:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-router/src/router-sync.ts#L69)
+Defined in: [router-sync.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.52/packages/play-router/src/router-sync.ts#L69)
 
 Normalize a pathname before route-map lookup.