@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.48

package/api/@xmachines/play-sveltekit-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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.
 

package/api/@xmachines/play-sveltekit-router/functions/connectRouter.md

@@ -6,7 +6,7 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [play-sveltekit-router/src/connect-router.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-sveltekit-router/src/connect-router.ts#L29)
+Defined in: [play-sveltekit-router/src/connect-router.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-sveltekit-router/src/connect-router.ts#L29)
 
 Connect SvelteKit router to actor.
 

package/api/@xmachines/play-sveltekit-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.46/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.48/packages/play-router/src/create-route-map.ts#L45)
 
 Create a `RouteMap` from an XState state machine.
 

package/api/@xmachines/play-sveltekit-router/interfaces/ConnectRouterOptions.md

@@ -2,12 +2,12 @@
 
 # Interface: ConnectRouterOptions
 
-Defined in: [play-sveltekit-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-sveltekit-router/src/connect-router.ts#L6)
+Defined in: [play-sveltekit-router/src/connect-router.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-sveltekit-router/src/connect-router.ts#L6)
 
 ## Properties
 
 | Property                                   | Modifier   | Type                                                                                                                                                                                                                                                             | 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) | -                                                                                                                                  | [play-sveltekit-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-sveltekit-router/src/connect-router.ts#L7)   |
-| <a id="property-location"></a> `location?` | `readonly` | [`LocationLike`](LocationLike.md) \| `null`                                                                                                                                                                                                                      | Location-like object for initial URL reads. Defaults to `globalThis.location`. Pass a mock in tests or a stub in SSR environments. | [play-sveltekit-router/src/connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-sveltekit-router/src/connect-router.ts#L13) |
-| <a id="property-routemap"></a> `routeMap`  | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                             | -                                                                                                                                  | [play-sveltekit-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-sveltekit-router/src/connect-router.ts#L8)   |
+| <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) | -                                                                                                                                  | [play-sveltekit-router/src/connect-router.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-sveltekit-router/src/connect-router.ts#L7)   |
+| <a id="property-location"></a> `location?` | `readonly` | [`LocationLike`](LocationLike.md) \| `null`                                                                                                                                                                                                                      | Location-like object for initial URL reads. Defaults to `globalThis.location`. Pass a mock in tests or a stub in SSR environments. | [play-sveltekit-router/src/connect-router.ts:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-sveltekit-router/src/connect-router.ts#L13) |
+| <a id="property-routemap"></a> `routeMap`  | `readonly` | [`RouteMap`](../classes/RouteMap.md)                                                                                                                                                                                                                             | -                                                                                                                                  | [play-sveltekit-router/src/connect-router.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-sveltekit-router/src/connect-router.ts#L8)   |

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

@@ -2,7 +2,7 @@
 
 # Interface: LocationLike
 
-Defined in: [play-router/src/types.ts:344](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L344)
+Defined in: [play-router/src/types.ts:344](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L344)
 
 Minimal location interface required by adapters that read the current URL at
 `connect()` time. Injectable for SSR and testing — pass a mock instead of the
@@ -23,5 +23,5 @@ connectRouter({ actor, routeMap, location: mockLoc });
 
 | Property                                  | Modifier   | Type     | Defined in                                                                                                                              |
 | ----------------------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [play-router/src/types.ts:345](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L345) |
-| <a id="property-search"></a> `search`     | `readonly` | `string` | [play-router/src/types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L346) |
+| <a id="property-pathname"></a> `pathname` | `readonly` | `string` | [play-router/src/types.ts:345](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L345) |
+| <a id="property-search"></a> `search`     | `readonly` | `string` | [play-router/src/types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L346) |

package/api/@xmachines/play-sveltekit-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.46/packages/play-router/src/types.ts#L223)
+Defined in: [play-router/src/types.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L223)
 
 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.46/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.46/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.46/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.46/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.46/packages/play-router/src/types.ts#L224) |
+| <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.48/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.48/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.48/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.48/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.48/packages/play-router/src/types.ts#L224) |

package/api/@xmachines/play-sveltekit-router/interfaces/RouteMapOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/create-route-map.ts#L9)
+Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/create-route-map.ts#L9)
 
 Options for `createRouteMap` and `createRouteMapFromTree`.
 
@@ -10,4 +10,4 @@ Options for `createRouteMap` and `createRouteMapFromTree`.
 
 | Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                | Defined in                                                                                                                                                  |
 | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/create-route-map.ts#L20) |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | Maximum number of resolved parameterized path lookups to cache. `RouteMap.getStateIdByPath()` resolves parameterized patterns (e.g. `/profile/:userId`) via URLPattern on every call. Frequently visited paths are cached in an LRU so subsequent lookups are O(1). Increase this value for applications with large parameterized route sets or high navigation frequency. Default: `500`. | [play-router/src/create-route-map.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/create-route-map.ts#L20) |

package/api/@xmachines/play-sveltekit-router/interfaces/RouteMapping.md

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

package/api/@xmachines/play-sveltekit-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L271)
+Defined in: [play-router/src/types.ts:271](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L271)
 
 RouterBridge interface for runtime infrastructure adapters
 
@@ -54,7 +54,7 @@ class TanStackRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L287)
+Defined in: [play-router/src/types.ts:287](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L287)
 
 Connect the router bridge to the Actor
 
@@ -83,7 +83,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-router/src/types.ts#L303)
+Defined in: [play-router/src/types.ts:303](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-router/src/types.ts#L303)
 
 Disconnect the router bridge from the Actor
 

package/api/@xmachines/play-sveltekit-router/type-aliases/RoutableActor.md

@@ -6,4 +6,4 @@
 type RoutableActor = AbstractActor<AnyActorLogic> & Routable;
 ```
 
-Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-sveltekit-router/src/types.ts#L10)
+Defined in: [play-sveltekit-router/src/types.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.48/packages/play-sveltekit-router/src/types.ts#L10)

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

@@ -1,199 +1,224 @@
 [API](../../README.md) / @xmachines/play-tanstack-react-router
 
-# @xmachines/play-tanstack-react-router
+<!-- generated-by: gsd-doc-writer -->
 
-**TanStack React Router adapter for XMachines Play using the RouterBridge pattern.**
+# @xmachines/play-tanstack-react-router
 
-## Overview
+TanStack Router (React) adapter for XMachines Play — synchronizes browser URL with actor state through passive infrastructure.
 
-`@xmachines/play-tanstack-react-router` connects a Play actor to TanStack Router through `TanStackReactRouterBridge`.
+Part of the [xmachines-js monorepo](../../README.md).
 
-The bridge extends `RouterBridgeBase` from, so adapter behavior stays consistent across frameworks:
+## Installation
 
-- Actor route signal (`actor.currentRoute`) drives router navigation.
-- Router history events send `play.route` intents back to the actor.
-- Guarded state transitions remain actor-owned (Actor Authority).
+```bash
+npm install @xmachines/play-tanstack-react-router
+```
 
-## Installation
+**Peer dependencies** (install separately):
 
 ```bash
-npm install @tanstack/react-router react
-npm install @xmachines/play-tanstack-react-router @xmachines/play-router @xmachines/play-react
+npm install @tanstack/react-router react react-dom xstate
 ```
 
-## Current Exports
+Requires:
 
-- `TanStackReactRouterBridge`
-- `RouteMap`, `createRouteMapFromTree`, `RouteMapping` (type)
-- `extractParams`, `extractQueryParams`
-- `PlayRouterProvider` + `PlayRouterProviderProps`
-- re-exports: `extractMachineRoutes`, `createRouteMap`, `RouterBridge`, `PlayRouteEvent`
+- `@tanstack/react-router` `^1.168.8`
+- `react` `^18.0.0` or `^19.0.0`
+- `react-dom` `^18.0.0` or `^19.0.0`
+- `xstate` `^5.30.0`
 
-Peer dependencies:
+## Usage
 
-- `@tanstack/react-router` `^1.166.7`
-- `react` `^18 || ^19`
-- `xstate` `^5.0.0`
+### `PlayRouterProvider` — React component (recommended)
 
-## URLPattern Support
+`PlayRouterProvider` is the primary integration point. It creates a `TanStackReactRouterBridge` on mount, keeps it connected for the component lifetime, and tears it down on unmount.
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via.
+```tsx
+import { useMemo, useEffect } from "react";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
+import {
+	PlayRouterProvider,
+	createRouteMapFromTree,
+	extractMachineRoutes,
+} from "@xmachines/play-tanstack-react-router";
+import { definePlayer } from "@xmachines/play-xstate";
 
-URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+). On older environments, load a polyfill **before** importing this package — see [`@xmachines/play-router`](../play-router/README.md) for details.
+function createAppRuntime() {
+	const actor = definePlayer({ machine, catalog })();
+	actor.start();
 
-## Quick Start
+	const routeTree = extractMachineRoutes(machine);
+	const routeMap = createRouteMapFromTree(routeTree);
+	const rootRoute = createRootRoute();
+	const router = createRouter({ routeTree: rootRoute });
 
-```tsx
+	return { actor, routeMap, router };
+}
+
+export function App() {
+	// All three props must be stable references — memoize to avoid reconnecting on every render
+	const { actor, routeMap, router } = useMemo(createAppRuntime, []);
+
+	useEffect(() => () => actor.stop(), [actor]);
+
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor, currentRouter) => (
+				<Shell actor={currentActor} router={currentRouter} />
+			)}
+		/>
+	);
+}
+```
+
+> **Stable references:** `actor`, `router`, and `routeMap` must be stable across renders. If any prop changes identity, the bridge disconnects and reconnects. Use `useMemo` to create them once.
+
+### `TanStackReactRouterBridge` — headless class
+
+Use the bridge directly when you don't need the React wrapper, or when integrating with a custom lifecycle:
+
+```typescript
 import { createRouter } from "@tanstack/react-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import { extractMachineRoutes } from "@xmachines/play-router";
 import {
 	TanStackReactRouterBridge,
 	createRouteMapFromTree,
+	extractMachineRoutes,
 } from "@xmachines/play-tanstack-react-router";
 
-const routeTree = extractMachineRoutes(machine);
-const routeMap = createRouteMapFromTree(routeTree);
-
-const router = createRouter({ routeTree: tanstackRouteTree });
-
+const router = createRouter({ routeTree });
 const actor = definePlayer({ machine, catalog })();
-actor.start();
+const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
 
 const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
 
-// later
+// Cleanup when done
 bridge.disconnect();
 ```
 
-### React convenience wrapper
-
-Use `PlayRouterProvider` when you want bridge lifecycle wiring in a component:
-
-```tsx
-import { PlayRenderer } from "@xmachines/play-react";
-
-<PlayRouterProvider
-	actor={actor}
-	router={router}
-	routeMap={routeMap}
-	renderer={(currentActor, currentRouter) => (
-		<PlayRenderer actor={currentActor} registry={registry} actions={{ login: "auth.login" }} />
-	)}
-/>;
-```
-
-## API
+## API Summary
 
 ### `TanStackReactRouterBridge`
 
-Primary adapter class.
+Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements bidirectional sync between actor state signals and TanStack Router history.
 
-```ts
-class TanStackReactRouterBridge implements RouterBridge {
+```typescript
+class TanStackReactRouterBridge extends RouterBridgeBase {
 	constructor(
 		router: TanStackRouterLike,
 		actor: AbstractActor<AnyActorLogic> & Routable,
 		routeMap: RouteMap,
-	);
-	connect(): void;
-	disconnect(): void;
+	): void;
+
+	connect(): void; // Start sync; subscribe to router.history and actor signals
+	disconnect(): void; // Stop sync; unsubscribe all listeners
 }
 ```
 
-### `RouteMap` and `createRouteMapFromTree`
+Subscribes to `router.history` (not `router.subscribe("onBeforeLoad")`) so that back/forward browser navigation (popstate events) are captured even without a `<RouterProvider>` mounted.
 
-Map state IDs to URL paths and resolve URLs back to state IDs.
-
-`RouteMap` extends `BaseRouteMap` from, inheriting bucket-indexed
-bidirectional route matching. No routing logic lives in the adapter itself.
-
-```ts
-// RouteMap is a thin subclass of BaseRouteMap — no extra methods
-class RouteMap extends BaseRouteMap {}
+### `PlayRouterProvider`
 
-// Inherited API:
-routeMap.getStateIdByPath(path: string): string | null
-routeMap.getPathByStateId(stateId: string): string | null
+React component that wraps `TanStackReactRouterBridge` in a `useEffect` lifecycle.
 
-// Factory from a machine route tree:
-function createRouteMapFromTree(routeTree: RouteTree): RouteMap
+```typescript
+interface PlayRouterProviderProps<TActor> {
+	actor: TActor; // Must be stable
+	router: TanStackRouterInstance; // Must be stable
+	routeMap: RouteMap; // Must be stable
+	renderer: (actor: TActor, router: TanStackRouterInstance) => ReactNode;
+}
 ```
 
-`getStateIdByPath` returns `null` (not `undefined`) for unmatched paths.
+### `TanStackRouterLike`
+
+Structural type for the router instance — accepts any object with the required `navigate` and `history` shape, making it testable without creating a full TanStack Router:
+
+```typescript
+type TanStackRouterLike = {
+	navigate(args: { to: string }): void;
+	load?(): void | Promise<void>;
+	history: {
+		location: { pathname: string; search?: string };
+		subscribe(
+			handler: (event: { location: { pathname: string; search?: string } }) => void,
+		): () => void;
+	};
+};
+```
 
-`createRouteMapFromTree` uses `node.fullPath` (the fully resolved absolute path) for all
-route entries. This is correct for both flat routes (e.g. `"/login"`) and nested relative
-routes (e.g. `meta.route: "overview"` under `"/dashboard"` resolves to `"/dashboard/overview"`).
+### `RouteNavigateEvent`
 
-```ts
-const routeMap = new RouteMap([
-	{ stateId: "home", path: "/" },
-	{ stateId: "profile", path: "/profile/:userId" },
-	{ stateId: "settings", path: "/settings/:section?" },
-]);
+Event sent to the actor when the browser navigates:
 
-routeMap.getStateIdByPath("/profile/123"); // "profile"
-routeMap.getPathByStateId("home"); // "/"
-routeMap.getStateIdByPath("/unknown"); // null
+```typescript
+interface RouteNavigateEvent {
+	readonly type: "route.navigate";
+	readonly path: string; // e.g. "/dashboard" or "/posts/123"
+}
 ```
 
-### `PlayRouterProvider`
+### Re-exported from `@xmachines/play-router`
 
-React wrapper around `TanStackReactRouterBridge`.
+```typescript
+// Route map construction
+RouteMap
+createRouteMap(mappings: RouteMapping[]): RouteMap
+createRouteMapFromTree(routeTree): RouteMap
+extractMachineRoutes(machine): RouteTree
 
-```ts
-interface PlayRouterProviderProps {
-	actor: AbstractActor<AnyActorLogic> & Routable & Viewable;
-	router: TanStackRouterLike;
-	routeMap: RouteMap;
-	renderer: (
-		actor: AbstractActor<AnyActorLogic> & Routable & Viewable,
-		router: TanStackRouterLike,
-	) => ReactNode;
-}
+// Types
+type RouteMapOptions
+type RouteMapping
+type RouterBridge
+type PlayRouteEvent
 ```
 
-### Utilities and re-exports
+## How It Works
 
-- `extractParams`, `extractQueryParams`
-- `extractMachineRoutes`, `createRouteMap` (re-exported from)
-- `RouterBridge`, `PlayRouteEvent` types
+The bridge implements the **Passive Infrastructure** invariant from the XMachines RFC:
 
-## Examples
+1. **Actor → Router:** When `actor.currentRoute` signal changes, the bridge calls `router.navigate({ to: path })`. The URL updates to reflect the new actor state.
+2. **Router → Actor:** When `router.history.subscribe` fires (link clicks, `back`/`forward` buttons, `history.pushState`), the bridge sends a `play.route` event to the actor. The actor's guards decide whether navigation is valid — the router never enforces business logic.
+3. **Circular update prevention:** A `lastSyncedPath` guard suppresses round-trip updates so an actor → router navigation does not trigger a redundant router → actor send.
+4. **Deep-link and restore:** On `connect()`, the bridge reads `router.history.location.pathname` (which reflects `window.location` immediately, before `router.load()` runs) and determines whether to sync the actor from the URL (deep-link) or push the actor's restored route to the URL (snapshot restore).
 
-- Multi-router integration guide: `docs/examples/multi-router-integration.md`
-- Routing patterns guide: `docs/examples/routing-patterns.md`
+## Testing
+
+Run tests for this package in isolation:
+
+```bash
+npm test -w @xmachines/play-tanstack-react-router
+```
 
-## Architecture
+From the monorepo root:
 
-Bridge-first flow:
+```bash
+npm test
+```
 
-1. `RouterBridgeBase.connect()` performs initial actor/router synchronization — both pathname and query string from `router.history.location` are forwarded to the actor on first connect.
-2. Actor route updates call TanStack navigation (`router.navigate({ to })`).
-3. TanStack history updates are subscribed and translated to `play.route` events.
-4. Actor guards accept or reject transitions; infrastructure reflects resulting state.
+Tests cover RouterBridge protocol compliance, actor ↔ router bidirectional sync, circular update prevention, deep-link and snapshot-restore scenarios, and `PlayRouterProvider` lifecycle (mount/unmount/reconnect).
 
-This keeps routing infrastructure passive while preserving business-logic control.
+## Demo
 
-## Related Packages
+A runnable React + TanStack Router integration demo is available under `examples/demo/`. To run it from the repository root:
 
-- [@xmachines/play-router](../play-router/README.md)
-- [@xmachines/play-xstate](../play-xstate/README.md)
-- [@xmachines/play-react](../play-react/README.md)
+```bash
+npm install
+npm run dev -w @xmachines/play-tanstack-react-router-demo
+```
 
-## Learn More
+Then open `http://localhost:3000`.
 
-- [Demo](../../../examples/@xmachines/play-tanstack-react-router-demo/README.md)
-- [React renderer](../play-react/README.md)
+The demo shows actor-authoritative routing with a shared auth machine: TanStack Router updates the URL, `PlayRouterProvider` translates it to a `play.route` event, and the actor's guards decide whether access is permitted.
 
 ## License
 
-Copyright (c) 2016 [Mikael Karon](mailto:mikael@karon.se). All rights reserved.
-
-This work is licensed under the terms of the MIT license.  
-For a copy, see <https://opensource.org/licenses/MIT>.
+MIT — see [LICENSE](./LICENSE).
 
 @xmachines/play-tanstack-react-router
 

package/api/@xmachines/play-tanstack-react-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.46/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.48/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.46/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.48/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.46/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.48/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.46/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.48/packages/play-router/src/base-route-map.ts#L174)
 
 Resolve a URL path to its mapped state ID.