@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -2,21 +2,23 @@
 
 # Interface: RouterBridge
 
-Defined in: [play-router/src/types.ts:360](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L360)
+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:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L376)
+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:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-router/src/types.ts#L392)
+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-react-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -6,9 +6,9 @@
 type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap) => RouterBridge;
 ```
 
-Defined in: [play-react-router/src/create-play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/create-play-router-provider.tsx#L20)
+Defined in: [play-react-router/src/create-play-router-provider.tsx:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/create-play-router-provider.tsx#L20)
 
-Constructor shape a bridge class must satisfy to be used with
+The constructor shape that a bridge class must satisfy for
 `createPlayRouterProvider`: `(router, actor, routeMap) → RouterBridge`.
 
 ## Type Parameters

package/api/@xmachines/play-react-router/variables/PlayRouterProvider.md

@@ -6,14 +6,15 @@
 const PlayRouterProvider: <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-react-router/src/play-router-provider.tsx:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-react-router/src/play-router-provider.tsx#L38)
+Defined in: [play-react-router/src/play-router-provider.tsx:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-react-router/src/play-router-provider.tsx#L40)
 
-Connects a `PlayerActor` to React Router, keeping actor state and browser URL
-in sync bidirectionally.
+Connects a `PlayerActor` to React Router. It keeps the actor state and the browser
+URL in step, in both directions.
 
-The bridge is created once on mount and torn down on unmount. It is also
-rebuilt if `actor`, `router`, or `routeMap` change identity — so all three
-props must be **stable references** (created outside JSX or memoized).
+The component creates the bridge one time, on mount, and it disconnects the bridge
+on unmount. It also builds the bridge again on a change of the identity of `actor`,
+of `router`, or of `routeMap`. Therefore all three props must be **stable
+references**: create them outside the JSX, or hold them with `useMemo`.
 
 ## Type Parameters
 

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

@@ -1,31 +1,29 @@
 [API](../../README.md) / @xmachines/play-router
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-router
 
-Route tree extraction from XState v6 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
+Route tree extraction from XState v5 state machines. Part of [@xmachines/play](../play/README.md) Universal Player Architecture.
 
-Graph-based route extraction and bidirectional lookup enabling Actor Authority over navigation.
+[![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-router)
 
-Part of the [xmachines-js monorepo](../../README.md).
+This package extracts the routes from a machine graph and looks them up in both directions. The Actor therefore keeps the authority over the navigation.
 
 ## Installation
 
 ```bash
-pnpm add xstate@^6.0.0-alpha.19
+pnpm add xstate@^5.31.0
 pnpm add @xmachines/play-router
 ```
 
 **Peer dependencies:**
 
-- `xstate` ^6.0.0-alpha.19 — XState v6 state machine runtime
+- `xstate` ^5.31.0 — XState v5 state machine runtime
 
 **URLPattern polyfill (Node.js < 24 / older browsers):**
 
-`@xmachines/play-router` uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for dynamic route matching. URLPattern is available natively on Node.js 24+ and modern browsers (Chrome 95+, Firefox 117+, Safari 16.4+).
+`@xmachines/play-router` matches each dynamic route with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern). URLPattern is native in Node.js 24+ and in a modern browser (Chrome 95+, Firefox 117+, Safari 16.4+).
 
-On environments without native support, load a polyfill **before** importing this package:
+In an environment without the native API, load a polyfill **before** you import this package:
 
 ```typescript
 // Entry point — must run before any @xmachines/play-router import
@@ -38,23 +36,17 @@ Install the polyfill:
 pnpm add urlpattern-polyfill
 ```
 
-`urlpattern-polyfill` is declared as an optional peer dependency. Package managers will not install it automatically — consumers must install and load it when their runtime lacks native URLPattern support.
+`urlpattern-polyfill` is an optional peer dependency. A package manager does not install it for you. Install it and load it yourself when your runtime has no native URLPattern.
 
 ## Usage
 
 ### Extract routes from a machine
 
 ```typescript
-import { setup, types } from "xstate";
+import { createMachine } from "xstate";
 import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router";
 
-// meta.route on state nodes needs a declared meta schema —
-// without it, XState v6 types `meta` as `never`.
-const machine = setup({
-	schemas: {
-		meta: types<{ route?: string }>(),
-	},
-}).createMachine({
+const machine = createMachine({
 	id: "app",
 	initial: "home",
 	states: {
@@ -103,8 +95,13 @@ routeMap.getPathByStateId("profile"); // "/profile/:userId"
 ### Sending `play.route` events
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
 import type { PlayRouteEvent } from "@xmachines/play-router";
 
+// machine: your routable machine (states carry meta.route)
+const actor = definePlayer({ machine })();
+actor.start();
+
 // Navigate to a state by ID
 const event: PlayRouteEvent = {
 	type: "play.route",
@@ -128,14 +125,21 @@ actor.send({
 });
 ```
 
-### Implementing a `RouterBridgeBase` adapter
+### How to write a `RouterBridgeBase` adapter
 
-Extend `RouterBridgeBase` and implement the three abstract methods for your framework:
+Extend `RouterBridgeBase`, then implement the three abstract methods for your framework:
 
 ```typescript
-import { RouterBridgeBase } from "@xmachines/play-router";
+import { RouterBridgeBase, createRouteMap } from "@xmachines/play-router";
 import type { RoutableActor } from "@xmachines/play-router";
 
+// Shape of your framework's router — adjust to its real API
+type MyRouter = {
+	navigate(path: string): void;
+	subscribe(handler: (location: { pathname: string; search: string }) => void): () => void;
+	state: { location: { pathname: string } };
+};
+
 export class MyRouterBridge extends RouterBridgeBase {
 	private unsubscribe: (() => void) | null = null;
 
@@ -171,7 +175,8 @@ export class MyRouterBridge extends RouterBridgeBase {
 	}
 }
 
-// Usage
+// Usage — myRouter: your framework's router instance;
+// machine/actor: your routable machine and its started actor
 const routeMap = createRouteMap(machine);
 const bridge = new MyRouterBridge(myRouter, actor, routeMap);
 bridge.connect();
@@ -183,81 +188,79 @@ bridge.disconnect();
 
 ### Route Extraction
 
-| Export                                   | Description                                                                        |
-| ---------------------------------------- | ---------------------------------------------------------------------------------- |
-| `extractMachineRoutes(machine)`          | Convert an XState machine to a `RouteTree` with bidirectional state ID ↔ path maps |
-| `createRouteMap(machine, options?)`      | Build a `RouteMap` directly from a machine (preferred form for adapters)           |
-| `createRouteMapFromTree(tree, options?)` | Build a `RouteMap` from an already-extracted `RouteTree`                           |
-| `buildRouteTree(routes)`                 | Build a `RouteTree` from an array of `RouteInfo` objects                           |
-| `machineToGraph(machine)`                | Convert a machine to a typed `@statelyai/graph` `Graph` for graph algorithm access |
-
-> **Graph shape under XState v6:** machines wired by `formatPlayRouteTransitions` expose their route navigation as statically-targeted `xstate.route` edges (one per routed state) plus a single dynamic `play.route` forwarder edge — tooling that previously filtered for per-route `play.route` edges should query `xstate.route` instead. Edge data marks guard presence with `guarded: true`; guard _names_ are unrecoverable under v6 (`guardType` is never populated).
+| Export                                   | Description                                                                       |
+| ---------------------------------------- | --------------------------------------------------------------------------------- |
+| `extractMachineRoutes(machine)`          | Converts an XState machine into a `RouteTree` with the state ID ↔ path maps       |
+| `createRouteMap(machine, options?)`      | Builds a `RouteMap` directly from a machine. An adapter uses this form            |
+| `createRouteMapFromTree(tree, options?)` | Builds a `RouteMap` from a `RouteTree` that you extracted before                  |
+| `buildRouteTree(routes)`                 | Builds a `RouteTree` from an array of `RouteInfo` objects                         |
+| `machineToGraph(machine)`                | Converts a machine into a typed `@statelyai/graph` `Graph`, for a graph algorithm |
 
 ### Route Matching
 
-| Export                        | Description                                                                                |
-| ----------------------------- | ------------------------------------------------------------------------------------------ |
-| `RouteMap`                    | Bidirectional `stateId ↔ path` lookup class; supports O(1) exact and O(k) pattern matching |
-| `findRouteById(tree, id)`     | Look up a `RouteNode` by state ID                                                          |
-| `findRouteByPath(tree, path)` | Look up a `RouteNode` by URL path (supports dynamic patterns)                              |
+| Export                        | Description                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `RouteMap`                    | The `stateId ↔ path` lookup class for both directions. It matches an exact path in O(1) and a pattern in O(k) |
+| `findRouteById(tree, id)`     | Finds a `RouteNode` by its state ID                                                                           |
+| `findRouteByPath(tree, path)` | Finds a `RouteNode` by its URL path. It also matches a dynamic pattern                                        |
 
 ### Query Utilities
 
-| Export                                            | Description                                                               |
-| ------------------------------------------------- | ------------------------------------------------------------------------- |
-| `getRoutableRoutes(tree)`                         | All routable `RouteNode`s as a flat array                                 |
-| `getNavigableRoutes(tree, stateId)`               | Child routes reachable from a state (hierarchical + transition-reachable) |
-| `routeExists(tree, path)`                         | Check whether a path is registered in the tree                            |
-| `getTransitionReachableRoutes(graph, stateId)`    | Route paths reachable via XState transitions from a state                 |
-| `isRouteReachable(graph, fromStateId, toStateId)` | Check whether a transition path exists between two states                 |
+| Export                                            | Description                                                                                     |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `getRoutableRoutes(tree)`                         | Returns every routable `RouteNode` in one flat array                                            |
+| `getNavigableRoutes(tree, stateId)`               | Returns the child routes that a state can reach, through the hierarchy and through a transition |
+| `routeExists(tree, path)`                         | Tells you if the tree holds a path                                                              |
+| `getTransitionReachableRoutes(graph, stateId)`    | Returns the route paths that a state can reach through an XState transition                     |
+| `isRouteReachable(graph, fromStateId, toStateId)` | Tells you if a transition path is present between two states                                    |
 
 ### Router Bridge
 
-| Export                                  | Description                                                                           |
-| --------------------------------------- | ------------------------------------------------------------------------------------- |
-| `RouterBridgeBase`                      | Abstract base class for framework router adapters; implements `RouterBridge` protocol |
-| `sanitizePathname(path)`                | Normalize a raw pathname; returns `null` for paths > 2048 chars or malformed input    |
-| `buildPlayRouteEvent(options)`          | Build a `PlayRouteEvent` from a pathname + route-map match result                     |
-| `extractRouteParams(pathname, pattern)` | Extract path parameters from a URL using URLPattern                                   |
-| `extractQuery(search)`                  | Extract query parameters from a URL search string                                     |
+| Export                                  | Description                                                                                                   |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `RouterBridgeBase`                      | The abstract base class of each framework router adapter. It implements the `RouterBridge` protocol           |
+| `sanitizePathname(path)`                | Normalizes a raw pathname. It returns `null` for a path of more than 2048 characters, and for malformed input |
+| `buildPlayRouteEvent(options)`          | Builds a `PlayRouteEvent` from a pathname and a route-map match result                                        |
+| `extractRouteParams(pathname, pattern)` | Reads the path parameters of a URL with URLPattern                                                            |
+| `extractQuery(search)`                  | Reads the query parameters of a URL search string                                                             |
 
 ### Validation
 
-| Export                                   | Description                                           |
-| ---------------------------------------- | ----------------------------------------------------- |
-| `validateRouteFormat(route, stateId)`    | Assert route path is non-empty                        |
-| `validateStateExists(stateId, stateIds)` | Assert a state ID is present in the machine graph     |
-| `detectDuplicateRoutes(routes)`          | Throw if any two states resolve to the same full path |
+| Export                                   | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `validateRouteFormat(route, stateId)`    | Asserts that the route path is not empty             |
+| `validateStateExists(stateId, stateIds)` | Asserts that the machine graph holds the state ID    |
+| `detectDuplicateRoutes(routes)`          | Throws when two states resolve to the same full path |
 
 ### Key Types
 
-| Export                             | Description                                                                                                            |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `RouterBridge`                     | Interface for `connect()` / `disconnect()` lifecycle                                                                   |
-| `RouteTree`                        | Hierarchical tree with `root`, `byStateId`, `byPath`, and optional `graph`                                             |
-| `RouteNode`                        | Single node in the tree with `id`, `path`, `fullPath`, `stateId`, `children`, `parent`                                 |
-| `RouteInfo`                        | Flat route descriptor extracted from a state node                                                                      |
-| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                                                            |
-| `RoutableActor`                    | Minimal actor interface required by `RouterBridgeBase` — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)`    |
-| `PlayActor`                        | Full actor interface used by `PlayRouterProvider` — extends `RoutableActor` with `currentView` (`Routable + Viewable`) |
-| `RouteMapping`                     | `{ stateId, path }` pair used to build a `RouteMap`                                                                    |
-| `RouteMapping as BaseRouteMapping` | Alias for `RouteMapping` (backwards-compat re-export)                                                                  |
-| `MachineGraph`                     | Typed `@statelyai/graph` Graph with `MachineNodeData` / `MachineEdgeData`                                              |
-| `WindowLike`                       | Injectable minimal `window` interface for SSR / testing                                                                |
-| `LocationLike`                     | Injectable minimal `location` interface for SSR / testing                                                              |
+| Export                             | Description                                                                                                                        |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `RouterBridge`                     | The interface of the `connect()` and `disconnect()` lifecycle                                                                      |
+| `RouteTree`                        | The hierarchical tree, with `root`, `byStateId`, `byPath`, and an optional `graph`                                                 |
+| `RouteNode`                        | One node of the tree, with `id`, `path`, `fullPath`, `stateId`, `children`, and `parent`                                           |
+| `RouteInfo`                        | The flat route descriptor that comes from a state node                                                                             |
+| `PlayRouteEvent`                   | Routing event `{ type: "play.route", to, params?, query? }`                                                                        |
+| `RoutableActor`                    | The minimal actor interface that `RouterBridgeBase` requires: `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)`           |
+| `PlayActor`                        | The complete actor interface that `PlayRouterProvider` uses. It extends `RoutableActor` with `currentView` (`Routable + Viewable`) |
+| `RouteMapping`                     | The `{ stateId, path }` pair that builds a `RouteMap`                                                                              |
+| `RouteMapping as BaseRouteMapping` | The alias of `RouteMapping`, for compatibility with an earlier version                                                             |
+| `MachineGraph`                     | The typed `@statelyai/graph` Graph, with `MachineNodeData` and `MachineEdgeData`                                                   |
+| `WindowLike`                       | The minimal `window` interface that you can inject for SSR and for a test                                                          |
+| `LocationLike`                     | The minimal `location` interface that you can inject for SSR and for a test                                                        |
 
 ### Errors (subpath `@xmachines/play-router/errors`)
 
-| Class                        | Code                                    | When thrown                                                       |
-| ---------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
-| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` fails to send a `play.route` event        |
-| `DuplicateBridgeError`       | `PLAY_ROUTER_DUPLICATE_BRIDGE`          | A second bridge tries to connect to an actor that already has one |
-| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | URLPattern API is absent and no polyfill is loaded                |
-| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | A route pattern string is rejected by the URLPattern constructor  |
-| `EmptyRoutePathError`        | `PLAY_ROUTE_EMPTY_PATH`                 | A state declares `meta.route: ""`                                 |
-| `InvalidStateIdError`        | `PLAY_ROUTE_INVALID_STATE_ID`           | A route references a state ID not in the machine graph            |
-| `DuplicateRoutePathError`    | `PLAY_ROUTE_DUPLICATE_PATH`             | Two or more states share the same URL path                        |
-| `UnknownStateTypeError`      | `PLAY_ROUTE_UNKNOWN_STATE_TYPE`         | A state node has an unrecognised XState `.type` value             |
+| Class                        | Code                                    | When thrown                                                             |
+| ---------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
+| `RouterSyncError`            | `PLAY_ROUTER_SYNC_FAILED`               | `syncActorFromRouter()` cannot send a `play.route` event                |
+| `DuplicateBridgeError`       | `PLAY_ROUTER_DUPLICATE_BRIDGE`          | A second bridge tries to connect to an actor that already has one       |
+| `URLPatternUnavailableError` | `PLAY_ROUTE_MAP_URLPATTERN_UNAVAILABLE` | The URLPattern API is absent, and no polyfill is loaded                 |
+| `InvalidRoutePatternError`   | `PLAY_ROUTE_MAP_INVALID_PATTERN`        | The URLPattern constructor refuses a route pattern string               |
+| `EmptyRoutePathError`        | `PLAY_ROUTE_EMPTY_PATH`                 | A state declares `meta.route: ""`                                       |
+| `InvalidStateIdError`        | `PLAY_ROUTE_INVALID_STATE_ID`           | A route names a state ID that the machine graph does not hold           |
+| `DuplicateRoutePathError`    | `PLAY_ROUTE_DUPLICATE_PATH`             | Two or more states share the same URL path                              |
+| `UnknownStateTypeError`      | `PLAY_ROUTE_UNKNOWN_STATE_TYPE`         | A state node has an XState `.type` value that the package does not know |
 
 ```typescript
 import {
@@ -266,6 +269,7 @@ import {
 	URLPatternUnavailableError,
 } from "@xmachines/play-router/errors";
 
+// bridge from the adapter example above
 try {
 	bridge.connect();
 } catch (err) {
@@ -281,7 +285,7 @@ try {
 
 ### `meta.route` patterns
 
-Routes are declared on XState state nodes via the `meta.route` field. The machine's `setup({ schemas })` must declare a matching `meta` schema (e.g. `meta: types<{ route?: string | { path: string; title?: string } }>()`) — without one, XState v6 types state `meta` as `never`:
+Declare the route of an XState state node in its `meta.route` field:
 
 ```typescript
 states: {
@@ -306,7 +310,7 @@ states: {
 
 ### Relative vs absolute paths
 
-Child routes with a leading `/` are absolute (do not inherit the parent path). Without a leading `/`, they resolve relative to their nearest routable ancestor:
+A child route that starts with `/` is absolute, and it does not inherit the path of its parent. A child route without the first `/` is relative to its nearest routable ancestor:
 
 ```typescript
 states: {
@@ -327,7 +331,7 @@ states: {
 }
 ```
 
-Always use `node.fullPath` (never `node.path`) for browser URL matching and route map construction.
+Always use `node.fullPath` to match a browser URL and to build a route map. Never use `node.path` for this.
 
 ## Testing
 
@@ -339,10 +343,11 @@ pnpm --filter @xmachines/play-router test
 pnpm --filter @xmachines/play-router run test:watch
 ```
 
-A router bridge contract test suite for adapter authors lives in
-`@xmachines/play-router-shared` (it drives a real actor, so it sits one layer
-above this package to keep `@xmachines/play-router` free of an actor-runtime
-dependency):
+`@xmachines/play-router-shared` holds a contract test suite of the router bridge, for the
+author of an adapter. That suite drives a real actor. Therefore it is one layer above this
+package, and `@xmachines/play-router` keeps no dependency on an actor runtime.
+`@xmachines/play-router-shared` is a private workspace package. Thus only an adapter author
+in this repository can use the suite:
 
 ```typescript
 import { runBridgeContractTests } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
@@ -352,15 +357,19 @@ runBridgeContractTests({
 	createHarness(initialPath) {
 		// return ContractHarness with bridge, actor, simulateNavigation, getLastNavigatedPath
 	},
+	createRestoredHarness(routedPath) {
+		// return ContractHarness whose actor is restored to routedPath
+		// while the mock router starts at the machine's initial route
+	},
 });
 ```
 
 ## Related Packages
 
 - **[@xmachines/play](../play/README.md)** — Core protocol types (`PlayEvent`, `PlayError`)
-- **[@xmachines/play-actor](../play-actor/README.md)** — Abstract actor base class (`AbstractActor`, `Routable`); all `AbstractActor` subclasses satisfy `RoutableActor` structurally
-- **[@xmachines/play-signals](../play-signals/README.md)** — TC39 Signals polyfill used for actor route observation
-- **[@xmachines/play-xstate](../play-xstate/README.md)** — XState v6 logic adapter that integrates with route trees
+- **[@xmachines/play-actor](../play-actor/README.md)** — the abstract actor base class (`AbstractActor`, `Routable`). Every `AbstractActor` subclass satisfies `RoutableActor` structurally
+- **[@xmachines/play-signals](../play-signals/README.md)** — the TC39 Signals polyfill that observes the actor route
+- **[@xmachines/play-xstate](../play-xstate/README.md)** — the XState v5 logic adapter, which works with a route tree
 - **[@xmachines/play-tanstack-router](../play-tanstack-router/README.md)** — Shared TanStack Router bridge base (framework-agnostic)
 - **[@xmachines/play-tanstack-react-router](../play-tanstack-react-router/README.md)** — TanStack Router adapter (React)
 - **[@xmachines/play-tanstack-solid-router](../play-tanstack-solid-router/README.md)** — TanStack Router adapter (SolidJS)
@@ -400,6 +409,7 @@ MIT — see [LICENSE](LICENSE).
 
 ## Type Aliases
 
+- [~~BaseRouteMapping~~](type-aliases/BaseRouteMapping.md)
 - [MachineGraph](type-aliases/MachineGraph.md)
 - [RouteMetadata](type-aliases/RouteMetadata.md)
 
@@ -424,9 +434,3 @@ MIT — see [LICENSE](LICENSE).
 - [sanitizePathname](functions/sanitizePathname.md)
 - [validateRouteFormat](functions/validateRouteFormat.md)
 - [validateStateExists](functions/validateStateExists.md)
-
-## References
-
-### BaseRouteMapping
-
-Renames and re-exports [RouteMapping](interfaces/RouteMapping.md)