@xmachines/docs 1.0.0-beta.51 → 1.0.0-beta.53

package/api/@xmachines/play-tanstack-react-router/type-aliases/TanStackRouterLike.md

@@ -6,7 +6,7 @@
 type TanStackRouterLike = object;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L42)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L41)
 
 ## Properties
 
@@ -16,7 +16,7 @@ Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https:
 history: object;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L45)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L44)
 
 #### location
 
@@ -64,7 +64,7 @@ subscribe(handler): () => void;
 optional load(): void | Promise<void>;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L44)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L43)
 
 #### Returns
 
@@ -78,7 +78,7 @@ Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:44](https:
 navigate(args): void;
 ```
 
-Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:43](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L43)
+Defined in: [play-tanstack-react-router/src/tanstack-router-bridge.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-react-router/src/tanstack-router-bridge.ts#L42)
 
 #### Parameters
 

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

@@ -12,7 +12,7 @@ Part of the [xmachines-js](../../README.md) monorepo.
 
 ## Overview
 
-[`@xmachines/play-tanstack-solid-router`](README.md) connects a Play actor to TanStack Solid Router through `SolidRouterBridge`.
+[`@xmachines/play-tanstack-solid-router`](README.md) connects a Play actor to TanStack Solid Router through `TanStackSolidRouterBridge`.
 
 The bridge extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md), keeping adapter behavior consistent across frameworks:
 
@@ -32,13 +32,15 @@ npm install @xmachines/play-tanstack-solid-router @xmachines/play-router
 
 - `@tanstack/solid-router` `^1.168.7`
 - `solid-js` `^1.8.0`
-- `xstate` `^5.30.0`
+- `xstate` `^5.31.0`
 
 ## Current Exports
 
-- `SolidRouterBridge` — primary adapter class
+- `TanStackSolidRouterBridge` — primary adapter class
 - `PlayRouterProvider` — Solid component wrapper for bridge lifecycle
-- `PlayRouterProviderProps`, `RoutableActor`, `TanStackRouterInstance` (types)
+- `PlayRouterProviderProps`, `TanStackRouterInstance` (types)
+- `PlayActor` — canonical actor shape (`AbstractActor & Routable & Viewable`) from `@xmachines/play-router`; use when constructing a typed renderer callback for `PlayRouterProvider`
+- `RoutableActor` — deprecated alias for `PlayActor`; use `PlayActor` from `@xmachines/play-router` instead
 - `RouteMap`, `createRouteMap`, `RouteMapping`, `RouteMapOptions` (re-exported from `@xmachines/play-router`)
 - `TanStackRouterLike` (type)
 - `RouterBridge`, `PlayRouteEvent` (types)
@@ -55,7 +57,7 @@ URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+,
 import { createRouter } from "@tanstack/solid-router";
 import { definePlayer } from "@xmachines/play-xstate";
 import { extractMachineRoutes } from "@xmachines/play-router";
-import { SolidRouterBridge, createRouteMap } from "@xmachines/play-tanstack-solid-router";
+import { TanStackSolidRouterBridge, createRouteMap } from "@xmachines/play-tanstack-solid-router";
 
 const routeMap = createRouteMap(machine);
 const router = createRouter({ routeTree: tanstackRouteTree });
@@ -63,7 +65,7 @@ const router = createRouter({ routeTree: tanstackRouteTree });
 const actor = definePlayer({ machine })();
 actor.start();
 
-const bridge = new SolidRouterBridge(router, actor, routeMap);
+const bridge = new TanStackSolidRouterBridge(router, actor, routeMap);
 bridge.connect();
 
 // later
@@ -90,17 +92,13 @@ import { RouterProvider } from "@tanstack/solid-router";
 
 ## API
 
-### `SolidRouterBridge`
+### `TanStackSolidRouterBridge`
 
 Primary adapter class extending `RouterBridgeBase`.
 
 ```ts
-class SolidRouterBridge {
-	constructor(
-		router: TanStackRouterLike,
-		actor: AbstractActor<AnyActorLogic> & Routable,
-		routeMap: RouteMap,
-	);
+class TanStackSolidRouterBridge {
+	constructor(router: TanStackRouterLike, actor: RoutableActor, routeMap: RouteMap);
 	connect(): void;
 	disconnect(): void;
 	dispose(): void; // alias for disconnect()
@@ -116,10 +114,10 @@ class SolidRouterBridge {
 
 ### `PlayRouterProvider`
 
-Solid component that instantiates, connects, and cleans up a `SolidRouterBridge` automatically.
+Solid component that instantiates, connects, and cleans up a `TanStackSolidRouterBridge` automatically.
 
 ```ts
-interface PlayRouterProviderProps<TActor extends RoutableActor = RoutableActor> {
+interface PlayRouterProviderProps<TActor extends PlayActor = PlayActor> {
 	/** The actor to sync with TanStack Solid Router. */
 	actor: TActor;
 	/** The TanStack Router instance returned by `createRouter`. */
@@ -269,6 +267,13 @@ Or from the package directory:
 npm test
 ```
 
+**Browser tests** (`test/browser/**/*.browser.test.ts`) run against real Chromium via Playwright, covering async sequencing that jsdom cannot faithfully reproduce: BACK/FORWARD navigation via `router.history.subscribe`, echo suppression under real microtask timing, `navigate({ to })` call verification, and subscriber teardown on `disconnect()` and `dispose()`.
+
+```bash
+# Run browser tests only
+npx vitest --config vitest.browser.config.ts --project play-tanstack-solid-router-browser
+```
+
 Coverage thresholds: lines 80%, functions 80%, branches 70%, statements 80%.
 
 ## Related Packages
@@ -291,10 +296,11 @@ MIT — see [LICENSE](LICENSE).
 ## Classes
 
 - [RouteMap](classes/RouteMap.md)
-- [SolidRouterBridge](classes/SolidRouterBridge.md)
+- [TanStackSolidRouterBridge](classes/TanStackSolidRouterBridge.md)
 
 ## Interfaces
 
+- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
@@ -303,7 +309,7 @@ MIT — see [LICENSE](LICENSE).
 
 ## Type Aliases
 
-- [RoutableActor](type-aliases/RoutableActor.md)
+- [~~RoutableActor~~](type-aliases/RoutableActor.md)
 - [TanStackRouterInstance](type-aliases/TanStackRouterInstance.md)
 - [TanStackRouterLike](type-aliases/TanStackRouterLike.md)
 

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/base-route-map.ts#L100)
+Defined in: [play-router/src/base-route-map.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/base-route-map.ts#L125)
+Defined in: [play-router/src/base-route-map.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/base-route-map.ts#L209)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/base-route-map.ts#L174)
+Defined in: [play-router/src/base-route-map.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

package/api/@xmachines/play-tanstack-solid-router/classes/{SolidRouterBridge.md → TanStackSolidRouterBridge.md}

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / SolidRouterBridge
+[API](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / TanStackSolidRouterBridge
 
-# Class: SolidRouterBridge
+# Class: TanStackSolidRouterBridge
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L48)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L47)
 
 TanStack Solid Router integration bridge extending RouterBridgeBase
 
@@ -19,27 +19,27 @@ public router events API instead of the internal \_\_store.
 ### Constructor
 
 ```ts
-new SolidRouterBridge(
+new TanStackSolidRouterBridge(
    router,
    actor,
-   routeMap): SolidRouterBridge;
+   routeMap): TanStackSolidRouterBridge;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L58)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L57)
 
 Create a TanStack Solid Router bridge.
 
 #### Parameters
 
-| Parameter  | Type                                                                                                                                                                                                                                                             | Description                                     |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                                                                                                                                                                                                    | TanStack Router instance (from `createRouter`). |
-| `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) | XMachines actor instance.                       |
-| `routeMap` | [`RouteMap`](RouteMap.md)                                                                                                                                                                                                                                        | Bidirectional state ID ↔ path mapping.          |
+| Parameter  | Type                                                                 | Description                                     |
+| ---------- | -------------------------------------------------------------------- | ----------------------------------------------- |
+| `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)        | TanStack Router instance (from `createRouter`). |
+| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md) | XMachines actor instance.                       |
+| `routeMap` | [`RouteMap`](RouteMap.md)                                            | Bidirectional state ID ↔ path mapping.          |
 
 #### Returns
 
-`SolidRouterBridge`
+`TanStackSolidRouterBridge`
 
 #### Overrides
 
@@ -47,17 +47,17 @@ Create a TanStack Solid Router bridge.
 
 ## Properties
 
-| Property                                                              | Modifier    | Type                                                                                                                                                                                                                                                             | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Inherited from                                                                                                                                                                | 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L126) |
-| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L104) |
-| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                                                                                                                                                                                                        | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/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`. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L116) |
-| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                                                                                                                                                                                               | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/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.                                                                                                                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L127) |
-| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L129) |
-| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                                                                                                                                                                                                | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L128) |
-| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null`                                                                                                                                                                          | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L117) |
+| Property                                                              | Modifier    | Type                                                                                    | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Inherited from                                                                                                                                                                | Defined in                                                                                                                                                        |
+| --------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                                   | `readonly`  | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                    | `undefined`   | A `RoutableActor` exposing `currentRoute`, `initialRoute`, and `send`.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`actor`](../../play-router/classes/RouterBridgeBase.md#property-actor)                                   | [play-router/src/router-bridge-base.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L125) |
+| <a id="property-hasconnectedonce"></a> `hasConnectedOnce`             | `protected` | `boolean`                                                                               | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`hasConnectedOnce`](../../play-router/classes/RouterBridgeBase.md#property-hasconnectedonce)             | [play-router/src/router-bridge-base.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L103) |
+| <a id="property-isconnected"></a> `isConnected`                       | `protected` | `boolean`                                                                               | `false`       | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isConnected`](../../play-router/classes/RouterBridgeBase.md#property-isconnected)                       | [play-router/src/router-bridge-base.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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`. | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`isProcessingNavigation`](../../play-router/classes/RouterBridgeBase.md#property-isprocessingnavigation) | [play-router/src/router-bridge-base.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L115) |
+| <a id="property-lastsyncedpath"></a> `lastSyncedPath`                 | `protected` | `string` \| `null`                                                                      | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`lastSyncedPath`](../../play-router/classes/RouterBridgeBase.md#property-lastsyncedpath)                 | [play-router/src/router-bridge-base.ts:104](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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.                                                                                                                                                                                                                                                                                                | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeMap`](../../play-router/classes/RouterBridgeBase.md#property-routemap)                             | [play-router/src/router-bridge-base.ts:126](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L126) |
+| `routeMap.getPathByStateId`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L128) |
+| `routeMap.getStateIdByPath`                                           | `public`    | `string` \| `null` \| `undefined`                                                       | `undefined`   | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                                                                                                                                                             | [play-router/src/router-bridge-base.ts:127](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L127) |
+| <a id="property-routewatcher"></a> `routeWatcher`                     | `protected` | \| [`RouteWatcherHandle`](../../play-router/interfaces/RouteWatcherHandle.md) \| `null` | `null`        | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`routeWatcher`](../../play-router/classes/RouterBridgeBase.md#property-routewatcher)                     | [play-router/src/router-bridge-base.ts:116](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L116) |
 
 ## Methods
 
@@ -67,7 +67,7 @@ Create a TanStack Solid Router bridge.
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:153](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L153)
+Defined in: [play-router/src/router-bridge-base.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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: [play-router/src/router-bridge-base.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L249)
+Defined in: [play-router/src/router-bridge-base.ts:248](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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.
 dispose(): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L130)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L129)
 
 Dispose the bridge (alias for disconnect).
 
@@ -137,7 +137,7 @@ Dispose the bridge (alias for disconnect).
 protected extractParams(pathname, stateId): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L373)
+Defined in: [play-router/src/router-bridge-base.ts:402](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L402)
 
 Extract path parameters from URL using the URLPattern API.
 
@@ -175,7 +175,7 @@ When URLPattern is absent and the route is parameterized
 protected extractQuery(search): Record<string, string>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:410](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L410)
+Defined in: [play-router/src/router-bridge-base.ts:439](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L439)
 
 Extract query parameters from URL search string.
 
@@ -203,7 +203,7 @@ Extracted query parameters or empty object
 protected getInitialRouterPath(): string | null;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L83)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L82)
 
 Get the current pathname at connect() time for deep-link / restore detection.
 
@@ -227,7 +227,7 @@ used by `TanStackReactRouterBridge`.
 protected getInitialRouterSearch(): string | undefined;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L92)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L91)
 
 Return the initial URL search string for query-param forwarding on `connect()`.
 
@@ -249,7 +249,7 @@ Reads `router.history.location.search` — same source as `getInitialRouterPath(
 protected navigateRouter(path): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L72)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L71)
 
 Navigate TanStack Solid Router to the given path.
 
@@ -275,7 +275,7 @@ Navigate TanStack Solid Router to the given path.
 protected resolveNavigationPath(route): string | null;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:395](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L395)
+Defined in: [play-router/src/router-bridge-base.ts:424](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L424)
 
 Resolve an actor route value to a concrete URL path for navigation.
 
@@ -308,18 +308,66 @@ Concrete URL path, or `null` if navigation should be skipped
 
 ---
 
+### sanitizePath()
+
+```ts
+protected sanitizePath(pathname): string | null;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:466](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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.
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`sanitizePath`](../../play-router/classes/RouterBridgeBase.md#sanitizepath)
+
+---
+
 ### syncActorFromRouter()
 
 ```ts
 protected syncActorFromRouter(pathname, search?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:315](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L315)
+Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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
 
@@ -344,7 +392,7 @@ Prevents circular updates via isProcessingNavigation flag.
 protected syncRouterFromActor(route): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:290](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/router-bridge-base.ts#L290)
+Defined in: [play-router/src/router-bridge-base.ts:289](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/router-bridge-base.ts#L289)
 
 Sync router location when actor route signal changes.
 
@@ -381,7 +429,7 @@ no event regardless of whether the callback fires synchronously or asynchronousl
 protected unwatchRouterChanges(): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L122)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L121)
 
 Stop watching TanStack Router changes.
 
@@ -401,7 +449,7 @@ Stop watching TanStack Router changes.
 protected watchRouterChanges(): void;
 ```
 
-Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L111)
+Defined in: [play-tanstack-solid-router/src/solid-router-bridge.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/solid-router-bridge.ts#L110)
 
 Subscribe to ALL navigation events via router.history.
 

package/api/@xmachines/play-tanstack-solid-router/functions/PlayRouterProvider.md

@@ -6,7 +6,7 @@
 function PlayRouterProvider<TActor>(props): any;
 ```
 
-Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L31)
+Defined in: [play-tanstack-solid-router/src/play-router-provider.tsx:31](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-tanstack-solid-router/src/play-router-provider.tsx#L31)
 
 Connects a `PlayerActor` to TanStack Solid Router, keeping actor state and
 browser URL in sync bidirectionally.
@@ -18,9 +18,9 @@ already reactive and the bridge is created once per component instance.
 
 ## Type Parameters
 
-| Type Parameter                                                         |
-| ---------------------------------------------------------------------- |
-| `TActor` _extends_ [`RoutableActor`](../type-aliases/RoutableActor.md) |
+| Type Parameter                                               |
+| ------------------------------------------------------------ |
+| `TActor` _extends_ [`PlayActor`](../interfaces/PlayActor.md) |
 
 ## Parameters
 

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

@@ -6,7 +6,7 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/create-route-map.ts#L45)
 
 Create a `RouteMap` from an XState state machine.
 

package/api/@xmachines/play-tanstack-solid-router/interfaces/PlayActor.md

@@ -0,0 +1,68 @@
+[API](../../../README.md) / [@xmachines/play-tanstack-solid-router](../README.md) / PlayActor
+
+# Interface: PlayActor
+
+Defined in: [play-router/src/types.ts:297](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L297)
+
+Full actor shape used by `PlayRouterProvider` components across all framework
+adapters (`play-solid-router`, `play-tanstack-solid-router`, `play-vue-router`,
+`play-tanstack-react-router`, `play-react-router`).
+
+Extends `RoutableActor` with `currentView` — the provider renders the current
+view spec in addition to synchronizing routes, so it needs both capabilities.
+
+- Use `RoutableActor` when only routing is needed (e.g. `RouterBridgeBase` subclasses,
+  `connectRouter`).
+- Use `PlayActor` when the component also renders the current view spec
+  (e.g. `PlayRouterProvider` renderer callback parameter, `PlayRenderer`).
+
+All `AbstractActor` subclasses that implement both `Routable` and `Viewable`
+satisfy this interface structurally.
+
+## Example
+
+```typescript
+import type { PlayActor } from "@xmachines/play-router";
+
+function MyRouterProvider({ actor }: { actor: PlayActor }) {
+	// access actor.currentRoute (routing) and actor.currentView (rendering)
+}
+```
+
+## Extends
+
+- [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)
+
+## Properties
+
+| Property                                          | Modifier   | Type                                                                                                                                | Description                                                                                                                                                                                                   | Inherited from                                                                                                                                                 | Defined in                                                                                                                              |
+| ------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-currentroute"></a> `currentRoute` | `readonly` | [`Computed`](../../play-signals/namespaces/Signal/classes/Computed.md)\<`string` \| `null`\>                                        | TC39 Signal exposing the actor's current URL path (or state ID).                                                                                                                                              | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`currentRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-currentroute) | [play-router/src/types.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L261) |
+| <a id="property-currentview"></a> `currentView`   | `readonly` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<[`PlaySpec`](../../play-actor/interfaces/PlaySpec.md) \| `null`\> | TC39 Signal exposing the actor's current view spec, or `null` when inactive.                                                                                                                                  | -                                                                                                                                                              | [play-router/src/types.ts:299](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L299) |
+| <a id="property-initialroute"></a> `initialRoute` | `readonly` | `string` \| `null`                                                                                                                  | The route derived from the machine's initial state — fixed at construction. Router bridges compare this against the browser URL to distinguish a deep-link (router wins) from a session restore (actor wins). | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`initialRoute`](../../play-dom-router/interfaces/RoutableActor.md#property-initialroute) | [play-router/src/types.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L267) |
+
+## Methods
+
+### send()
+
+```ts
+send(event): void;
+```
+
+Defined in: [play-router/src/types.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L269)
+
+Send a route navigation event to the actor.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `event`   | [`PlayRouteEvent`](PlayRouteEvent.md) |
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md).[`send`](../../play-dom-router/interfaces/RoutableActor.md#send)

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/types.ts#L223)
+Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L225)
 
 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`                      | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/types.ts#L228) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/types.ts#L226) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/types.ts#L227) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/types.ts#L225) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:224](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-router/src/types.ts#L224) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L230) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L228) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L229) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L227) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:226](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/packages/play-router/src/types.ts#L226) |