@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,57 +2,62 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L225)
+Defined in: [play-router/src/types.ts:237](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L237)
 
-Enhanced routing event with parameter and query support
+The routing event, with its parameters and its query
 
-Unified routing event used throughout the Play architecture. Supports parameter-aware
-navigation patterns (e.g., `/profile/:userId`) for dynamic route segments.
+This is the one routing event of the complete Play architecture. It supports a
+navigation that knows the parameters, for example `/profile/:userId`, for a dynamic
+route segment.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by representing
-user navigation intent that the Actor evaluates through guards. Infrastructure proposes
-via `play.route` events, Actor decides via state machine transitions.
+**Architectural context:** the event implements **Passive Infrastructure
+(INV-04)**, because it holds the navigation intent of the user, and the Actor then
+evaluates that intent with its guards. The infrastructure makes a request with a
+`play.route` event, and the Actor decides with a transition of its state machine.
 
-**Browser Navigation Flow:**
+**The flow of a browser navigation:**
 
-1. Browser fires `popstate`
-2. Router adapter resolves URL to route target
-3. Adapter sends `PlayRouteEvent` to Actor
-4. Actor validates transition via state machine guards
+1. The browser fires `popstate`
+2. The router adapter resolves the URL to a route target
+3. The adapter sends a `PlayRouteEvent` to the Actor
+4. The Actor checks the transition with the guards of its state machine
 
 ## Param
 
 **type**
 
-Event discriminator (always "play.route")
+The discriminator of the event. It is always "play.route"
 
 ## Param
 
 **to**
 
-Target state ID with # prefix (e.g., '#home', '#profile')
+The target state ID, with a # prefix, for example '#home' or '#profile'
 
 ## Param
 
 **params**
 
-Path-only route parameters extracted from the URL path (e.g., `{ userId: '123' }` from `/profile/123`). Query parameters are kept separate in `query`.
+The route parameters of the path only, from the URL path, for
+example `{ userId: '123' }` of `/profile/123`. The `query` field holds the query
+parameters separately.
 
 ## Param
 
 **query**
 
-Query parameters only (isolated from path params)
+The query parameters only. They stay separate from the params of the path
 
 ## Param
 
 **match**
 
-Full URLPattern match result for debugging/observability (optional)
+The complete match result of URLPattern, for the debug work and for
+the observability. It is optional
 
 ## Examples
 
-Combining base and routing events
+The base event and the routing event together
 
 ```typescript
 import type { PlayEvent } from "@xmachines/play";
@@ -61,7 +66,7 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 type AppEvent = PlayEvent | PlayRouteEvent;
 ```
 
-Basic navigation to a route
+A basic navigation to a route
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -73,7 +78,7 @@ const event: PlayRouteEvent = {
 actor.send(event);
 ```
 
-Navigation with route parameters
+A navigation with route parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -84,10 +89,10 @@ const event: PlayRouteEvent = {
 	params: { userId: "123" },
 };
 actor.send(event);
-// Resolves to route: /profile/123
+// It resolves to the route /profile/123
 ```
 
-Navigation with query parameters
+A navigation with query parameters
 
 ```typescript
 import type { PlayRouteEvent } from "@xmachines/play-router";
@@ -95,11 +100,11 @@ import type { PlayRouteEvent } from "@xmachines/play-router";
 const event: PlayRouteEvent = {
 	type: "play.route",
 	to: "#settings",
-	params: { section: "profile" }, // Path-only route parameter
-	query: { tab: "security" }, // Query-only
+	params: { section: "profile" }, // a route parameter of the path only
+	query: { tab: "security" }, // the query only
 };
 actor.send(event);
-// Resolves to route: /settings/profile?tab=security
+// It resolves to the route /settings/profile?tab=security
 ```
 
 ## See
@@ -108,9 +113,10 @@ actor.send(event);
 
 ## Remarks
 
-Use `play.route` when you need parameter-aware navigation with the `route: {}`
-config pattern on your state machine nodes. The `match` field exposes the full
-URLPatternResult for advanced use cases (debugging, pattern analysis).
+Use `play.route` when you need a navigation that knows the parameters, with the
+`route: {}` config pattern on the nodes of your state machine. The `match` field
+gives you the complete URLPatternResult, for an advanced use such as a debug or an
+analysis of the pattern.
 
 ## Indexable
 
@@ -122,8 +128,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:230](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/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/v2.0.0/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/v2.0.0/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/v2.0.0/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/v2.0.0/packages/play-router/src/types.ts#L226) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L242) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L240) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L241) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L239) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L238) |

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

@@ -2,12 +2,12 @@
 
 # Interface: RouteMapOptions
 
-Defined in: [play-router/src/create-route-map.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/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/v2.1.0/packages/play-router/src/create-route-map.ts#L9)
 
-Options for `createRouteMap` and `createRouteMapFromTree`.
+The options of `createRouteMap` and of `createRouteMapFromTree`.
 
 ## Properties
 
-| 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/v2.0.0/packages/play-router/src/create-route-map.ts#L20) |
+| Property                                     | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                                          |
+| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-cachesize"></a> `cacheSize?` | `number` | The maximum number of the resolved parameterized path lookups in the cache. `RouteMap.getStateIdByPath()` resolves a parameterized pattern, for example `/profile/:userId`, with URLPattern on each call. The map keeps each path of a frequent visit in an LRU cache, and a later lookup of that path is therefore O(1). Raise this value for an application with a large set of parameterized routes, or with a high frequency of the navigation. The default is `500`. | [play-router/src/create-route-map.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L21) |

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

@@ -2,14 +2,15 @@
 
 # Interface: RouteMapping
 
-Defined in: [play-router/src/base-route-map.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L51)
+Defined in: [play-router/src/base-route-map.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L54)
 
-A single state ID ↔ path mapping entry.
+One entry of the map between a state ID and a path.
 
-Both fields are `readonly` — mappings are immutable once passed to `RouteMap`.
-Adapter packages re-export a structurally compatible `RouteMapping` type under
-their own name. This type is published from `@xmachines/play-router` as
-`RouteMapping` to avoid name collisions with those adapter-local types.
+Both fields are `readonly`, because a mapping is immutable after the caller gives
+it to `RouteMap`. An adapter package re-exports a structurally compatible
+`RouteMapping` type under its own name. `@xmachines/play-router` publishes this
+type as `RouteMapping`, and its name therefore does not collide with such a local
+type of an adapter.
 
 ## Example
 
@@ -21,7 +22,7 @@ const optionalMapping: RouteMapping = { stateId: "settings", path: "/settings/:s
 
 ## Properties
 
-| 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:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L55) |
-| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | State machine state ID (e.g., `"home"`, `"#profile"`)                         | [play-router/src/base-route-map.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/base-route-map.ts#L53) |
+| Property                                | Modifier   | Type     | Description                                                                                      | Defined in                                                                                                                                      |
+| --------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-path"></a> `path`       | `readonly` | `string` | The pattern of the URL path, for example `"/"`, `"/profile/:userId"`, or `"/settings/:section?"` | [play-router/src/base-route-map.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L58) |
+| <a id="property-stateid"></a> `stateId` | `readonly` | `string` | The state ID of the state machine, for example `"home"` or `"#profile"`                          | [play-router/src/base-route-map.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/base-route-map.ts#L56) |

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

@@ -2,21 +2,23 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:341](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L341)
+Defined in: [play-router/src/types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L358)
 
-RouterBridge interface for runtime infrastructure adapters
+The RouterBridge interface of a runtime infrastructure adapter
 
-Defines the lifecycle connection between Infrastructure (e.g., a framework router) and
-the Actor. Infrastructure "bridges" to the Actor by observing its signals and
-managing its own lifecycle accordingly.
+The interface defines the connection of the lifecycle between the infrastructure,
+for example a framework router, and the Actor. The infrastructure builds a "bridge"
+to the Actor: it observes the signals of the Actor, and it manages its own
+lifecycle accordingly.
 
-**Architectural Context:** Implements **Passive Infrastructure (INV-04)** by establishing
-a unidirectional observation pattern. Infrastructure connects to observe Actor signals
-(currentRoute, currentView, state) and reflects changes without making state decisions.
+**Architectural context:** the interface implements **Passive Infrastructure
+(INV-04)**, because it gives an observation in one direction. The infrastructure
+connects to observe the signals of the Actor (currentRoute, currentView, and
+state), and it reflects each change. It makes no decision about the state.
 
 ## Example
 
-Framework router bridge implementation
+The implementation of a framework router bridge
 
 ```typescript
 import type { RouterBridge } from "@xmachines/play-router";
@@ -26,7 +28,7 @@ class MyRouterBridge implements RouterBridge {
 	private watcher: Signal.Watcher | null = null;
 
 	async connect(): Promise<void> {
-		// Start observing actor.currentRoute signal
+		// Start the observation of the actor.currentRoute signal
 		this.watcher = new Signal.subtle.Watcher(() => {
 			const route = actor.currentRoute.get();
 			if (route) router.navigate(route);
@@ -35,7 +37,7 @@ class MyRouterBridge implements RouterBridge {
 	}
 
 	async disconnect(): Promise<void> {
-		// Stop observing, cleanup watchers
+		// Stop the observation, and clean the watchers up
 		this.watcher?.unwatch(actor.currentRoute);
 		this.watcher = null;
 	}
@@ -44,7 +46,7 @@ class MyRouterBridge implements RouterBridge {
 
 ## See
 
-[Play RFC](../../../../rfc/play.md) - Invariant INV-04
+[Play RFC](../../../../rfc/play.md) - invariant INV-04
 
 ## Methods
 
@@ -54,25 +56,26 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:357](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L357)
+Defined in: [play-router/src/types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L375)
 
-Connect the router bridge to the Actor
+Connects the router bridge to the Actor
 
-Called when Infrastructure should begin observing Actor signals and
-synchronizing its state (e.g., browser URL) with Actor state.
+The infrastructure calls it when it must start the observation of the Actor
+signals, and when it must bring its own state, for example the browser URL, in line
+with the Actor state.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when connection is established, or void for synchronous connection
+The promise that resolves after the connection, or void for a synchronous connection
 
 #### Example
 
 ```typescript
 const bridge: RouterBridge = createBridge(actor, router);
 await bridge.connect();
-// Bridge now observing actor.currentRoute signal
+// The bridge observes the actor.currentRoute signal now
 ```
 
 ---
@@ -83,22 +86,22 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [play-router/src/types.ts:373](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/types.ts#L373)
+Defined in: [play-router/src/types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/types.ts#L391)
 
-Disconnect the router bridge from the Actor
+Disconnects the router bridge from the Actor
 
-Called when Infrastructure should stop observing and clean up resources
-(e.g., signal watchers, event listeners).
+The infrastructure calls it when it must stop the observation and free its
+resources, for example a signal watcher and an event listener.
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
-Promise that resolves when disconnection is complete, or void for synchronous disconnection
+The promise that resolves after the disconnection, or void for a synchronous disconnection
 
 #### Example
 
 ```typescript
 await bridge.disconnect();
-// Bridge stopped observing, resources cleaned up
+// The bridge stopped its observation, and it freed its resources
 ```

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/v2.0.0/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/v2.1.0/packages/play-sveltekit-router/src/types.ts#L10)

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

@@ -2,11 +2,9 @@
 
 # @xmachines/play-tanstack-react-router
 
-TanStack Router (React) adapter for XMachines Play — synchronizes browser URL with actor state through passive infrastructure.
+TanStack Router (React) adapter for XMachines Play. It keeps the browser URL and the actor state in step through passive infrastructure.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-react-router)
-
-Part of the [xmachines-js monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-react-router)
 
 ## Installation
 
@@ -14,13 +12,13 @@ Part of the [xmachines-js monorepo](../../README.md).
 pnpm add @xmachines/play-tanstack-react-router
 ```
 
-**Peer dependencies** (install separately):
+**Peer dependencies.** Install them separately:
 
 ```bash
 pnpm add @tanstack/react-router react react-dom xstate
 ```
 
-Requires:
+The adapter requires:
 
 - `@tanstack/react-router` `^1.168.8`
 - `react` `^18.0.0` or `^19.0.0`
@@ -31,24 +29,47 @@ Requires:
 
 ### `PlayRouterProvider` — React component (recommended)
 
-`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.
+`PlayRouterProvider` is the primary integration point. It creates a `TanStackReactRouterBridge` on mount. It keeps the bridge connected for the life of the component. It disconnects the bridge on unmount.
 
 ```tsx
-import { useMemo, useEffect } from "react";
+import { useMemo, useEffect, useState } from "react";
+import { createMachine } from "xstate";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
-import {
-	PlayRouterProvider,
-	createRouteMapFromTree,
-	extractMachineRoutes,
-} from "@xmachines/play-tanstack-react-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-react-router";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { useSignalEffect } from "@xmachines/play-react";
+
+// Any machine whose states declare `meta.route` (plus an explicit `id`) is routable.
+// formatPlayRouteTransitions() generates the root-level `play.route` handlers that
+// let the bridge drive the machine from URL changes.
+const machine = createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+		},
+	}),
+);
+
+const createPlayer = definePlayer({ machine });
+type AppActor = ReturnType<typeof createPlayer>;
+
+// Minimal shell: mirrors the actor's route signal into React state. A full app
+// renders <PlayUIProvider> + <PlayRenderer> from @xmachines/play-react here
+// instead — see examples/demo for the complete Shell.
+function Shell({ actor }: { actor: AppActor }) {
+	const [route, setRoute] = useState(actor.currentRoute.get());
+	useSignalEffect(() => setRoute(actor.currentRoute.get()), [actor]);
+	return <p>Current route: {route}</p>;
+}
 
 function createAppRuntime() {
-	const actor = definePlayer({ machine, catalog })();
+	const actor = createPlayer();
 	actor.start();
 
-	const routeTree = extractMachineRoutes(machine);
-	const routeMap = createRouteMapFromTree(routeTree);
+	const routeMap = createRouteMap(machine);
 	const rootRoute = createRootRoute();
 	const router = createRouter({ routeTree: rootRoute });
 
@@ -66,32 +87,28 @@ export function App() {
 			actor={actor}
 			router={router}
 			routeMap={routeMap}
-			renderer={(currentActor, currentRouter) => (
-				<Shell actor={currentActor} router={currentRouter} />
-			)}
+			renderer={(currentActor) => <Shell actor={currentActor} />}
 		/>
 	);
 }
 ```
 
-> **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.
+> **Stable references:** `actor`, `router`, and `routeMap` must stay stable across the renders. If one prop gets a new identity, the bridge disconnects, then it connects again. Use `useMemo` to create each prop one time.
 
-### `TanStackReactRouterBridge` — headless class
+### `TanStackReactRouterBridge` — the bridge class
 
-Use the bridge directly when you don't need the React wrapper, or when integrating with a custom lifecycle:
+Use the bridge directly when you do not need the React wrapper, or when you integrate it with a custom lifecycle:
 
 ```typescript
-import { createRouter } from "@tanstack/react-router";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { definePlayer } from "@xmachines/play-xstate";
-import {
-	TanStackReactRouterBridge,
-	createRouteMapFromTree,
-	extractMachineRoutes,
-} from "@xmachines/play-tanstack-react-router";
+import { TanStackReactRouterBridge, createRouteMap } from "@xmachines/play-tanstack-react-router";
+import { machine } from "./machine.js"; // the routable machine from the example above
 
-const router = createRouter({ routeTree });
-const actor = definePlayer({ machine, catalog })();
-const routeMap = createRouteMapFromTree(extractMachineRoutes(machine));
+const router = createRouter({ routeTree: createRootRoute() });
+const actor = definePlayer({ machine })();
+actor.start();
+const routeMap = createRouteMap(machine);
 
 const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
@@ -104,7 +121,7 @@ bridge.disconnect();
 
 ### `TanStackReactRouterBridge`
 
-Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements bidirectional sync between actor state signals and TanStack Router history.
+This class extends `RouterBridgeBase` from `@xmachines/play-router`. It keeps the actor state signals and the TanStack Router history in step, in both directions.
 
 ```typescript
 class TanStackReactRouterBridge extends RouterBridgeBase {
@@ -115,11 +132,11 @@ class TanStackReactRouterBridge extends RouterBridgeBase {
 }
 ```
 
-Subscribes to `router.history` (not `router.subscribe("onBeforeLoad")`) so that back/forward browser navigation (popstate events) are captured even without a `<RouterProvider>` mounted.
+The bridge subscribes to `router.history`, not to `router.subscribe("onBeforeLoad")`. Therefore the bridge also receives a browser BACK or FORWARD navigation (a popstate event) when no `<RouterProvider>` is mounted.
 
 ### `PlayRouterProvider`
 
-React component that wraps `TanStackReactRouterBridge` in a `useEffect` lifecycle.
+This React component wraps `TanStackReactRouterBridge` in a `useEffect` lifecycle.
 
 ```typescript
 interface PlayRouterProviderProps<TActor> {
@@ -132,7 +149,7 @@ interface PlayRouterProviderProps<TActor> {
 
 ### `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:
+The structural type of the router instance. It accepts every object that has the necessary `navigate` and `history` shape. A test can therefore use a stub in place of a complete TanStack Router:
 
 ```typescript
 type TanStackRouterLike = {
@@ -149,7 +166,7 @@ type TanStackRouterLike = {
 
 ### `RouteNavigateEvent`
 
-Event sent to the actor when the browser navigates:
+The event that the bridge sends to the actor when the browser navigates:
 
 ```typescript
 interface RouteNavigateEvent {
@@ -163,7 +180,7 @@ interface RouteNavigateEvent {
 ```typescript
 // Route map construction
 RouteMap
-createRouteMap(mappings: RouteMapping[]): RouteMap
+createRouteMap(machine, options?): RouteMap
 createRouteMapFromTree(routeTree): RouteMap
 extractMachineRoutes(machine): RouteTree
 
@@ -178,10 +195,10 @@ type PlayRouteEvent
 
 The bridge implements the **Passive Infrastructure** invariant from the XMachines RFC:
 
-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).
+1. **Actor → Router:** when the `actor.currentRoute` signal changes, the bridge calls `router.navigate({ to: path })`. The URL then shows the new actor state.
+2. **Router → Actor:** when `router.history.subscribe` fires, the bridge sends a `play.route` event to the actor. A link click, a BACK or FORWARD button, and a call to `history.pushState` each cause this. The guards of the actor decide if the navigation is valid. The router never enforces the business logic.
+3. **Circular update prevention:** the `lastSyncedPath` guard stops a return update. An actor-to-router navigation therefore does not cause an unnecessary router-to-actor send.
+4. **Deep-link and restore:** on `connect()`, the bridge reads `router.history.location.pathname`. That value shows `window.location` at once, before `router.load()` runs. The bridge then makes a decision: it sets the actor state from the URL (a deep link), or it writes the restored route of the actor to the URL (a snapshot restore).
 
 ## Testing
 
@@ -201,16 +218,16 @@ Tests cover RouterBridge protocol compliance, actor ↔ router bidirectional syn
 
 ## Demo
 
-A runnable React + TanStack Router integration demo is available under `examples/demo/`. To run it from the repository root:
+`examples/demo/` holds a runnable demo of the React and TanStack Router integration. Run it from the repository root:
 
 ```bash
 pnpm install
 pnpm --filter @xmachines/play-tanstack-react-router-demo run dev
 ```
 
-Then open `http://localhost:3000`.
+Then open `http://localhost:3011`.
 
-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.
+The demo shows actor-authoritative routing with a shared auth machine. TanStack Router updates the URL. `PlayRouterProvider` converts the update into a `play.route` event. The guards of the actor then permit the access, or they refuse it.
 
 ## License
 
@@ -218,8 +235,9 @@ MIT — see [LICENSE](./LICENSE).
 
 @xmachines/play-tanstack-react-router
 
-TanStack Router adapter for XMachines Play architecture.
-Synchronizes browser URL with actor state through passive infrastructure.
+TanStack Router adapter for the XMachines Play architecture.
+It keeps the browser URL and the actor state in step through passive
+infrastructure.
 
 ## Classes
 
@@ -234,7 +252,7 @@ Synchronizes browser URL with actor state through passive infrastructure.
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
-- [RouteNavigateEvent](interfaces/RouteNavigateEvent.md)
+- [~~RouteNavigateEvent~~](interfaces/RouteNavigateEvent.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
 ## Type Aliases