@xmachines/docs 2.0.0 → 2.1.0

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

@@ -4,9 +4,9 @@
 
 **Vanilla DOM router (Browser History API) for XMachines Play Architecture.**
 
-[![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-dom-router)
+[![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-dom-router)
 
-Framework-agnostic router integration that synchronizes a Play actor's `currentRoute` TC39 Signal with the browser's `window.history` API — no framework required. Implements the same [`RouterBridgeBase`](../play-router/README.md) pattern as all other router adapters in the XMachines ecosystem.
+This framework-agnostic router integration keeps the `currentRoute` TC39 Signal of a Play actor and the `window.history` API of the browser in step. It needs no framework. It implements the same [`RouterBridgeBase`](../play-router/README.md) pattern as every other router adapter in the XMachines ecosystem.
 
 ## Installation
 
@@ -24,19 +24,20 @@ pnpm add xstate@^5.31.0
 
 [`@xmachines/play-dom-router`](README.md) connects a Play actor to the browser URL through the `DomRouterBridge` (extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md)):
 
-- Actor route signal (`actor.currentRoute`) drives `history.push()` — actor is authoritative.
-- Browser navigation events (`popstate`, `pushState`, `replaceState`) send `play.route` intents back to the actor.
-- Guarded state transitions remain actor-owned (Actor Authority).
-- Circular update prevention via `isProcessingNavigation` flag — inherited from `RouterBridgeBase`.
+- The actor route signal (`actor.currentRoute`) drives `history.push()`. The actor is the authority.
+- Each browser navigation event (`popstate`, `pushState`, `replaceState`) sends a `play.route` intent to the actor.
+- The actor keeps the ownership of each guarded state transition (Actor Authority).
+- The `isProcessingNavigation` flag stops a circular update. The bridge inherits the flag from `RouterBridgeBase`.
 
 ## Key Exports
 
 | Export                                        | Description                                                                                                        |
 | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | `createBrowserHistory(options)`               | Wraps `window.history` with a subscribable `BrowserHistory` interface                                              |
-| `createRouter(options)`                       | Creates a `VanillaRouter` combining `BrowserHistory` and `RouteTree`                                               |
+| `createRouter(options)`                       | Creates a `VanillaRouter` from a `BrowserHistory` and a `RouteTree`                                                |
 | `connectRouter(options)`                      | Connects a `VanillaRouter` to a `Routable` actor — returns a `disconnect` cleanup function                         |
-| `createRouteMap`                              | Re-exported from `@xmachines/play-router` — builds bidirectional path ↔ state ID map                               |
+| `DomRouterBridge`                             | The low-level bridge class. It extends `RouterBridgeBase`. Use it directly for full lifecycle control              |
+| `createRouteMap`                              | It comes from `@xmachines/play-router`. It builds the bidirectional path ↔ state ID map                            |
 | `BrowserHistory`                              | Interface for the history wrapper                                                                                  |
 | `BrowserWindow`                               | Structural window interface (accepts `Window`, JSDOM, or any test double)                                          |
 | `VanillaRouter`                               | Interface for the router wrapper                                                                                   |
@@ -49,6 +50,8 @@ pnpm add xstate@^5.31.0
 ## Quick Start
 
 ```typescript
+import { createMachine } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
 import {
 	createBrowserHistory,
 	createRouter,
@@ -57,18 +60,30 @@ import {
 } from "@xmachines/play-dom-router";
 import { extractMachineRoutes } from "@xmachines/play-router";
 
-// 1. Extract route tree and build route map from your XState machine
+// 1. Define a routable machine — states carry meta.route
+const machine = createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+		},
+	}),
+);
+
+// 2. Extract route tree and build route map from the machine
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMap(machine);
 
-// 2. Create browser history wrapper (accepts window or any BrowserWindow-compatible object)
+// 3. Create browser history wrapper (accepts window or any BrowserWindow-compatible object)
 const history = createBrowserHistory({ window });
 
-// 3. Create router
+// 4. Create router
 const router = createRouter({ routeTree, history });
 
-// 4. Start actor and connect
-const actor = definePlayer({ machine, catalog })();
+// 5. Start actor and connect
+const actor = definePlayer({ machine })();
 actor.start();
 
 const disconnect = connectRouter({ actor, router, routeMap });
@@ -84,7 +99,7 @@ window.addEventListener("beforeunload", () => {
 
 ### `createBrowserHistory(options)`
 
-Wraps `window.history` to provide a subscribable history interface. Patches `pushState`/`replaceState` to detect programmatic navigations in addition to `popstate` events for back/forward.
+This function wraps `window.history`, and it gives you a history interface with a subscription. It patches `pushState` and `replaceState`. Therefore the wrapper also detects a navigation from the code, not only a `popstate` event from the BACK or FORWARD button.
 
 ```typescript
 const history = createBrowserHistory({ window });
@@ -106,27 +121,28 @@ history.destroy();
 
 **`BrowserHistory` interface:**
 
-| Method                  | Description                                                                |
-| ----------------------- | -------------------------------------------------------------------------- |
-| `location`              | Read-only `{ pathname, search, hash, state }`                              |
-| `push(path, state?)`    | Push a new entry to history                                                |
-| `replace(path, state?)` | Replace the current history entry                                          |
-| `go(delta)`             | Navigate relative to current position                                      |
-| `back()`                | Navigate backward                                                          |
-| `forward()`             | Navigate forward                                                           |
-| `subscribe(listener)`   | Subscribe to location changes — returns unsubscribe function               |
-| `createHref(path)`      | Create an href from a path                                                 |
-| `destroy()`             | Cleanup — removes listeners and restores patched methods when last wrapper |
+| Method                  | Description                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `location`              | Read-only `{ pathname, search, hash, state }`                                                        |
+| `push(path, state?)`    | Push a new entry to history                                                                          |
+| `replace(path, state?)` | Replace the current history entry                                                                    |
+| `go(delta)`             | Navigate relative to current position                                                                |
+| `back()`                | Navigate backward                                                                                    |
+| `forward()`             | Navigate forward                                                                                     |
+| `subscribe(listener)`   | Subscribe to location changes — returns unsubscribe function                                         |
+| `createHref(path)`      | Create an href from a path                                                                           |
+| `destroy()`             | Cleans up. It removes the listeners, and it restores the patched methods when it is the last wrapper |
 
 **`BrowserWindow` interface:**
 
-Accepts `window`, a JSDOM window, or any object implementing the structural interface. Covers only properties actually used — avoids coupling to `Window & typeof globalThis`.
+The interface accepts `window`, a JSDOM window, or every other object that implements it. It holds only the properties that the package uses. Therefore the package does not depend on `Window & typeof globalThis`.
 
 ### `createRouter(options)`
 
-Creates a `VanillaRouter` wrapping `history` and `routeTree`. Designed for parity with TanStack Router's setup flow.
+This function creates a `VanillaRouter` around a `history` and a `routeTree`. Its setup flow is the same as the setup flow of TanStack Router.
 
 ```typescript
+// routeTree and history from the Quick Start above
 const router = createRouter({ routeTree, history });
 // router.history — the BrowserHistory instance
 // router.routeTree — for structure reference
@@ -135,10 +151,10 @@ const router = createRouter({ routeTree, history });
 
 ### `connectRouter(options)`
 
-Connects a `VanillaRouter` to a `Routable` actor. Handles all bidirectional synchronization:
+This function connects a `VanillaRouter` to a `Routable` actor. It does all the work in both directions:
 
-- On connect: syncs initial URL → actor or actor route → browser (restore vs. deep-link detection).
-- While connected: actor route changes push to history; browser navigations send `play.route` events.
+- On connect: it sets the actor state from the initial URL, or it writes the actor route to the browser. The bridge detects a restore and a deep link.
+- While it is connected: each actor route change goes to the history, and each browser navigation sends a `play.route` event.
 - Returns a cleanup function that disconnects the bridge.
 
 ```typescript
@@ -154,11 +170,11 @@ disconnect();
 
 **`ConnectRouterOptions`:**
 
-| Option     | Type                  | Description                               |
-| ---------- | --------------------- | ----------------------------------------- |
-| `actor`    | `RoutableActor`       | Actor to synchronize with the browser URL |
-| `router`   | `VanillaRouter`       | Router from `createRouter()`              |
-| `routeMap` | `RouteLookupContract` | Bidirectional path ↔ state ID lookup      |
+| Option     | Type                  | Description                                    |
+| ---------- | --------------------- | ---------------------------------------------- |
+| `actor`    | `RoutableActor`       | The actor to keep in step with the browser URL |
+| `router`   | `VanillaRouter`       | Router from `createRouter()`                   |
+| `routeMap` | `RouteLookupContract` | Bidirectional path ↔ state ID lookup           |
 
 **`RouteLookupContract`:**
 
@@ -169,15 +185,16 @@ interface RouteLookupContract {
 }
 ```
 
-Any object satisfying this structural interface is accepted — including `RouteMap` instances from `@xmachines/play-router`, subclasses, or test doubles.
+The bridge accepts every object that implements this structural interface. A `RouteMap` instance from `@xmachines/play-router`, a subclass, and a test double all work.
 
 ### `createRouteMap` (re-export)
 
-Re-exported from `@xmachines/play-router`. Builds a bidirectional `RouteMap` from an XState machine:
+This function comes from `@xmachines/play-router`. It builds a bidirectional `RouteMap` from an XState machine:
 
 ```typescript
 import { createRouteMap } from "@xmachines/play-dom-router";
 
+// machine from the Quick Start above (states carry meta.route)
 const routeMap = createRouteMap(machine);
 routeMap.getStateIdByPath("/dashboard"); // "dashboard"
 routeMap.getPathByStateId("dashboard"); // "/dashboard"
@@ -185,7 +202,7 @@ routeMap.getPathByStateId("dashboard"); // "/dashboard"
 
 ## URLPattern Support
 
-This package uses the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) for route pattern matching via [`@xmachines/play-router`](../play-router/README.md). 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.
+This package matches each route pattern with the [URLPattern API](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern), through [`@xmachines/play-router`](../play-router/README.md). URLPattern is native in Node.js 24+ and in a modern browser (Chrome 95+, Firefox 117+, Safari 16.4+). In an older environment, load a polyfill **before** you import this package. See [`@xmachines/play-router`](../play-router/README.md) for the details.
 
 ## Testing
 
@@ -197,7 +214,7 @@ pnpm test
 pnpm --filter @xmachines/play-dom-router test
 ```
 
-Tests run in Node.js environment with `URLPattern` polyfill setup. Browser-specific tests are in `test/browser/` and run separately via `vitest.browser.config.ts`.
+The tests run in a Node.js environment with the `URLPattern` polyfill setup. The browser tests are in `test/browser/`. They run separately, through `vitest.browser.config.ts`.
 
 Coverage thresholds:
 
@@ -212,11 +229,11 @@ Coverage thresholds:
 
 The bridge-first data flow:
 
-1. `connectRouter` instantiates `DomRouterBridge` (extends `RouterBridgeBase`) and calls `bridge.connect()`.
-2. On connect, `RouterBridgeBase` performs initial sync: if browser URL differs from actor route, a `play.route` event is sent; if actor route differs and browser is at the machine's initial route (restore scenario), the actor wins and history is updated.
-3. Actor route changes (via `currentRoute` Signal) trigger `history.push(path)`.
-4. Browser URL changes (popstate, patched pushState/replaceState) call `syncActorFromRouter(pathname, search)`, which sends a `play.route` event.
-5. Circular updates are prevented by the `isProcessingNavigation` flag in `RouterBridgeBase`.
+1. `connectRouter` creates a `DomRouterBridge`, which extends `RouterBridgeBase`, and calls `bridge.connect()`.
+2. On connect, `RouterBridgeBase` does the first synchronization. If the browser URL is different from the actor route, the bridge sends a `play.route` event. If the actor route is different and the browser is at the initial route of the machine (a restore), the actor wins, and the bridge updates the history.
+3. Each actor route change, through the `currentRoute` Signal, calls `history.push(path)`.
+4. Each browser URL change (a `popstate` event, or a patched `pushState` or `replaceState` call) calls `syncActorFromRouter(pathname, search)`, which sends a `play.route` event.
+5. The `isProcessingNavigation` flag in `RouterBridgeBase` stops a circular update.
 
 ```
 Browser URL
@@ -238,17 +255,17 @@ Browser URL
 
 - [@xmachines/play-router](../play-router/README.md) — `RouterBridgeBase`, `createRouteMap`, `extractMachineRoutes`
 - [@xmachines/play-actor](../play-actor/README.md) — `AbstractActor`, `Routable`, `Viewable`; all subclasses satisfy `RoutableActor` structurally
-- [@xmachines/play-dom](../play-dom/README.md) — Vanilla DOM renderer for view rendering alongside routing
+- [@xmachines/play-dom](../play-dom/README.md) — the vanilla DOM renderer, for the view beside the routing
 - [@xmachines/play-xstate](../play-xstate/README.md) — `definePlayer`, `PlayerActor`
 
-## Part of the XMachines monorepo
-
-This package is part of the [xmachines-js](../../README.md) monorepo.
-
 ## License
 
 MIT — see [LICENSE](LICENSE).
 
+## Classes
+
+- [DomRouterBridge](classes/DomRouterBridge.md)
+
 ## Interfaces
 
 - [BrowserHistory](interfaces/BrowserHistory.md)

package/api/@xmachines/play-dom-router/classes/DomRouterBridge.md

@@ -0,0 +1,116 @@
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / DomRouterBridge
+
+# Class: DomRouterBridge
+
+Defined in: [play-dom-router/src/dom-router-bridge.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/dom-router-bridge.ts#L26)
+
+The DOM router bridge — it puts a BrowserHistory from `createBrowserHistory`
+behind the `RouterBridgeBase` protocol.
+
+It implements the three abstract methods:
+
+- `navigateRouter` → `history.push(path)`
+- `watchRouterChanges` → `history.subscribe(...)`, and it keeps the unsubscribe handle
+- `unwatchRouterChanges` → it calls the handle that it kept
+
+It overrides two optional hooks:
+
+- `getInitialRouterPath` → `history.location.pathname`
+- `getInitialRouterSearch` → `history.location.search`
+
+The bridge inherits the prevention of a circular update, the
+restore-or-deeplink detection, and the `lastSyncedPath` deduplication from
+`RouterBridgeBase`.
+
+Use `connectRouter` for the usual case. Use this class directly when you need
+full control of the connection lifecycle.
+
+## Extends
+
+- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new DomRouterBridge(
+   actor,
+   routeMap,
+   history): DomRouterBridge;
+```
+
+Defined in: [play-dom-router/src/dom-router-bridge.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/dom-router-bridge.ts#L34)
+
+#### Parameters
+
+| Parameter  | Type                                                          | Description                                                                                                                          |
+| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `actor`    | [`RoutableActor`](../interfaces/RoutableActor.md)             | A `Routable` actor with `currentRoute` and `send`.                                                                                   |
+| `routeMap` | [`RouteLookupContract`](../interfaces/RouteLookupContract.md) | The route lookup for both directions. Every object that satisfies [RouteLookupContract](../interfaces/RouteLookupContract.md) works. |
+| `history`  | [`BrowserHistory`](../interfaces/BrowserHistory.md)           | The BrowserHistory instance from `createBrowserHistory`.                                                                             |
+
+#### Returns
+
+`DomRouterBridge`
+
+#### Overrides
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+
+## Methods
+
+### connect()
+
+```ts
+connect(): void;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:158](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L158)
+
+Connects the router bridge to the Actor.
+
+The method installs the TC39 Signal watcher of the direction from the actor to the
+router. It then starts the watch of the router changes, which each framework does
+in its own way.
+
+The order of these steps is part of the contract of the bridge:
+
+- The constructor seeds `lastSyncedPath` from `actor.currentRoute`
+- The method installs the actor watcher before the router subscriptions of the adapter
+- The first synchronization then separates a deep link from a restore, with `actor.initialRoute`
+
+An adapter that needs a different behavior of the first synchronization overrides
+`getInitialRouterPath()`. It does not change the order of the steps of
+`connect()`.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: [play-router/src/router-bridge-base.ts:270](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/router-bridge-base.ts#L270)
+
+Disconnects the router bridge from the Actor.
+
+The method stops the watch of the signal, and it removes the router listener of the
+framework.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)

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

@@ -6,11 +6,12 @@
 function connectRouter(options): () => void;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:51](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/connect-router.ts#L51)
+Defined in: [play-dom-router/src/connect-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/connect-router.ts#L52)
 
-Connect vanilla router to actor (pure browser integration).
+Connects the vanilla router to an actor. This is a pure browser integration.
 
-Returns a cleanup function. Calls `bridge.disconnect()` to stop sync.
+The function returns a cleanup function. That function calls
+`bridge.disconnect()` to stop the synchronization.
 
 ## Parameters
 

package/api/@xmachines/play-dom-router/functions/createBrowserHistory.md

@@ -6,20 +6,21 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-browser-history.ts#L120)
+Defined in: [play-dom-router/src/create-browser-history.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-browser-history.ts#L122)
 
-Create browser history that wraps window.history
+Creates a browser history that wraps window.history
 
-Aligned with TanStack Router's history interface for API parallelism.
+The interface is the same as the history interface of TanStack Router, so that
+the two APIs stay parallel.
 
 Architecture:
 
-- Patches window.history.pushState/replaceState to detect changes
-- Listens to popstate for browser back/forward
-- Provides subscribe() for listeners (like PlayRouterProvider)
-- Testable (accepts window object)
+- It patches window.history.pushState and window.history.replaceState, to detect a change
+- It listens for popstate, for the browser BACK and FORWARD buttons
+- It gives you subscribe() for a listener, such as PlayRouterProvider
+- It accepts a window object, so a test can give a double
 
-Usage:
+Use:
 
 ```typescript
 const history = createBrowserHistory({ window });
@@ -35,13 +36,14 @@ unsubscribe();
 history.destroy();
 ```
 
-`destroy()` is idempotent and cooperates with other wrappers created for the
-same `window` instance.
+`destroy()` is idempotent, and it cooperates with each other wrapper of the same
+`window` instance.
 
-**Warning**: `createBrowserHistory()` mutates global `window.history` methods
-(`pushState` and `replaceState`) and coordinates wrappers with shared ref-count state.
-To mitigate leakage, create one history wrapper per browser window at the application
-boundary and always pair it with `destroy()` during teardown.
+**Warning**: `createBrowserHistory()` changes the global `window.history` methods
+(`pushState` and `replaceState`), and it coordinates the wrappers with a shared
+reference count. Therefore create one history wrapper for each browser window, at
+the boundary of the application, and always call `destroy()` during the
+teardown.
 
 ## Parameters
 

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

@@ -6,27 +6,28 @@
 function createRouteMap(machine, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-router/src/create-route-map.ts#L45)
+Defined in: [play-router/src/create-route-map.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-router/src/create-route-map.ts#L47)
 
-Create a `RouteMap` from an XState state machine.
+Creates a `RouteMap` from an XState state machine.
 
-Extracts all routable states (those with `meta.route`) and builds a bidirectional
-path ↔ stateId lookup structure. The returned map is used by `RouterBridgeBase`
-subclasses to translate browser URL changes into `play.route` actor events and
-vice-versa.
+The function reads every state with a route, which means each state with a
+`meta.route` field. It then builds the lookup structure between a path and a
+stateId, for both directions. A subclass of `RouterBridgeBase` uses the map: it
+converts each change of the browser URL into a `play.route` actor event, and each
+actor route into a URL.
 
 ## Parameters
 
-| Parameter  | Type                                                                      | Description                                                                                                         |
-| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v5 state machine with `meta.route` annotations on states.                                                    |
-| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | Optional configuration. Pass `{ cacheSize }` to override the default LRU cache size for parameterized path lookups. |
+| Parameter  | Type                                                                      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `machine`  | [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The XState v5 state machine, with a `meta.route` annotation on each state with a route.                                         |
+| `options?` | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)                     | The optional configuration. Give `{ cacheSize }` to change the default size of the LRU cache of the parameterized path lookups. |
 
 ## Returns
 
 [`RouteMap`](../interfaces/RouteMap.md)
 
-A `RouteMap` for passing to any `RouterBridgeBase`-based adapter.
+A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ## Example
 

package/api/@xmachines/play-dom-router/functions/createRouter.md

@@ -6,37 +6,37 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play-dom-router/src/create-router.ts#L52)
+Defined in: [play-dom-router/src/create-router.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-dom-router/src/create-router.ts#L52)
 
-Create vanilla router for framework-agnostic routing.
+Creates the vanilla router for a framework-agnostic routing.
 
 Architecture:
 
-- Just wraps history and routeTree
-- Does NOT embed routeMap (providers need it as prop)
-- Framework-agnostic history management only
+- The router wraps a history and a routeTree, and it does nothing more
+- It does NOT hold the routeMap, because a provider needs the routeMap as a prop
+- It manages the history only, and it knows no framework
 
-Why no routeMap:
+The reason for no routeMap:
 
-- Router doesn't know about state IDs (that's Play-specific)
-- RouteMap is the bridge between router and actor
-- Provider receives routeMap as prop to do path → state ID resolution
+- The router knows nothing about a state ID, because a state ID belongs to Play
+- The RouteMap is the bridge between the router and the actor
+- The provider receives the routeMap as a prop, and it resolves a path to a state ID
 
-Usage (parallel to TanStack mode):
+Use, parallel to the TanStack mode:
 
 ```typescript
-// Both modes: identical setup
+// Both modes: the same setup
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree);
 const history = createBrowserHistory({ window });
 
-// Vanilla router
+// The vanilla router
 const router = createRouter({ routeTree, history });
 
-// Connect router to actor (handles all bidirectional sync)
+// Connect the router to the actor. This does all the work in both directions
 const disconnect = connectRouter({ actor, router, routeMap });
 
-// Later: cleanup
+// Later: clean up
 disconnect();
 router.destroy();
 ```