@xmachines/docs 3.0.0 → 5.0.0

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

@@ -2,22 +2,22 @@
 
 # `@xmachines/play-react-router`
 
-> React Router v7 adapter for the XMachines Play Universal Player Architecture. It keeps the actor state and the browser URL in step, in both directions, through the `createBrowserRouter` data API.
+> React Router 7 and 8 adapter for the XMachines Play Universal Player Architecture. It keeps the actor state and the browser URL in step, in both directions, through the `createBrowserRouter` data API.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-react-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-react-router)
 
 ---
 
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-react-router
+pnpm add @xmachines/play-react-router @xmachines/play-router
 ```
 
 **Peer dependencies.** Install them if they are not present:
 
 ```bash
-pnpm add react@"^18 || ^19" react-router@"^7.0.0" xstate@"^5.31.0"
+pnpm add react@"^18 || ^19" react-router@"^7 || ^8"
 ```
 
 ---
@@ -33,11 +33,13 @@ pnpm add react@"^18 || ^19" react-router@"^7.0.0" xstate@"^5.31.0"
 ```tsx
 import { useMemo, useEffect } from "react";
 import { createBrowserRouter, RouterProvider } from "react-router";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-react-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-react-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 import { myMachine } from "./machine.js";
 
-const createPlayer = definePlayer({ machine: myMachine });
+const createPlayer = definePlayer({ machine: myMachine, actor: compose(PlayerActor, withRouting) });
 const routeMap = createRouteMap(myMachine);
 
 // Minimal app shell stub — a real app renders PlayUIProvider + PlayRenderer from
@@ -77,11 +79,14 @@ Use `ReactRouterBridge` directly when you need imperative lifecycle control outs
 
 ```typescript
 import { createBrowserRouter } from "react-router";
-import { ReactRouterBridge, createRouteMap } from "@xmachines/play-react-router";
-import { definePlayer } from "@xmachines/play-xstate";
+import { ReactRouterBridge } from "@xmachines/play-react-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
 import { myMachine } from "./machine.js";
 
-const actor = definePlayer({ machine: myMachine })();
+// The bridge needs the routing capability
+const actor = definePlayer({ machine: myMachine, actor: compose(PlayerActor, withRouting) })();
 actor.start();
 
 const router = createBrowserRouter([/* routes */]);
@@ -119,7 +124,7 @@ interface PlayRouterProviderProps<TActor> {
 
 ### `ReactRouterBridge`
 
-Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements the `RouterBridge` protocol.
+Extends `RouterBridgeBase` from [`@xmachines/play-router`](../play-router/README.md). Implements the `RouterBridge` protocol.
 
 | Method         | Description                                                                    |
 | -------------- | ------------------------------------------------------------------------------ |
@@ -131,63 +136,31 @@ Extends `RouterBridgeBase` from `@xmachines/play-router`. Implements the `Router
 | Export                    | Description                                                                      |
 | ------------------------- | -------------------------------------------------------------------------------- |
 | `PlayRouterProviderProps` | Props interface for `PlayRouterProvider`                                         |
-| `PlayActor`               | The constraint type for an actor that `PlayRouterProvider` and the bridge accept |
+| `RoutableActor`           | The constraint type for an actor that `PlayRouterProvider` and the bridge accept |
 
 ### Route map utilities (re-exported from `@xmachines/play-router`)
 
+This barrel names no state machine. `createRouteMap` and `extractMachineRoutes` read one,
+so import them from [`@xmachines/play-router/xstate`](../play-router/README.md).
+
 | Export                         | Description                                                               |
 | ------------------------------ | ------------------------------------------------------------------------- |
 | `RouteMap`                     | Bidirectional state ID ↔ URL path map                                     |
-| `createRouteMap(machine)`      | Build a `RouteMap` directly from an XState machine definition             |
 | `createRouteMapFromTree(tree)` | Build a `RouteMap` from a `RouteTree` object                              |
-| `RouteMapOptions`              | Options type for `createRouteMap`                                         |
+| `RouteMapOptions`              | Options type for the `RouteMap` construction                              |
 | `RouteMapping`                 | Type for a single `{ stateId, path }` entry                               |
 | `RouterBridge`                 | Interface that `ReactRouterBridge` satisfies                              |
 | `PlayRouteEvent`               | The `play.route` event type that a router sends to an actor on navigation |
 
 ---
 
-## Testing
-
-Run tests for this package in isolation:
-
-```bash
-pnpm --filter @xmachines/play-react-router test
-```
-
-Or from inside the package directory:
-
-```bash
-pnpm test
-```
-
-Tests use [Vitest](https://vitest.dev/). Component tests (`*.test.tsx`) run in a `jsdom` environment via `@testing-library/react`. Unit tests (`*.test.ts`) run in Node.
-
-**Browser tests** (`test/browser/**/*.browser.test.ts`) run in real Chromium through Playwright. They cover the asynchronous sequences that jsdom cannot reproduce: BACK and FORWARD navigation, the callback order of `router.subscribe`, echo suppression under real microtask timing, and subscriber teardown on `disconnect()`.
-
-```bash
-# Run browser tests only
-pnpm exec vitest --config vitest.browser.config.ts --project play-react-router-browser
-```
-
-Coverage thresholds (v8 provider):
-
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 80%       |
-| Functions  | 80%       |
-| Branches   | 80%       |
-| Statements | 80%       |
-
----
-
 ## License
 
 [MIT](./LICENSE)
 
 @xmachines/play-react-router
 
-React Router v7 adapter for the XMachines Play architecture.
+React Router 7/8 adapter for the XMachines Play architecture.
 It keeps the browser URL and the actor state in step through the
 createBrowserRouter data API.
 
@@ -198,9 +171,9 @@ createBrowserRouter data API.
 
 ## Interfaces
 
-- [PlayActor](interfaces/PlayActor.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [PlayRouterProviderProps](interfaces/PlayRouterProviderProps.md)
+- [RoutableActor](interfaces/RoutableActor.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
@@ -217,5 +190,4 @@ createBrowserRouter data API.
 ## Functions
 
 - [createPlayRouterProvider](functions/createPlayRouterProvider.md)
-- [createRouteMap](functions/createRouteMap.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)

package/api/@xmachines/play-react-router/classes/ReactRouterBridge.md

@@ -2,7 +2,7 @@
 
 # Class: ReactRouterBridge
 
-Defined in: [play-react-router/src/react-router-bridge.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-react-router/src/react-router-bridge.ts#L30)
+Defined in: [play-react-router/src/react-router-bridge.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react-router/src/react-router-bridge.ts#L30)
 
 A `RouterBridge` whose machine is mounted at a URL prefix that can MOVE while the
 bridge stays connected.
@@ -27,7 +27,7 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 
 ## Extends
 
-- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+- [`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md)
 
 ## Constructors
 
@@ -38,19 +38,20 @@ new ReactRouterBridge(
    router,
    actor,
    routeMap,
-   options?): ReactRouterBridge;
+   options?
+): ReactRouterBridge;
 ```
 
-Defined in: [play-react-router/src/react-router-bridge.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-react-router/src/react-router-bridge.ts#L33)
+Defined in: [play-react-router/src/react-router-bridge.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react-router/src/react-router-bridge.ts#L33)
 
 #### Parameters
 
-| Parameter  | Type                                                                     |
-| ---------- | ------------------------------------------------------------------------ |
-| `router`   | `Router`                                                                 |
-| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)     |
-| `routeMap` | [`RouteMap`](RouteMap.md)                                                |
-| `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md) |
+| Parameter  | Type                                                                               |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `router`   | `Router`                                                                           |
+| `actor`    | [`RoutableActor`](../interfaces/RoutableActor.md)                                  |
+| `routeMap` | [`RouteMap`](RouteMap.md)                                                          |
+| `options?` | [`RouterBridgeOptions`](../../play-router/index/interfaces/RouterBridgeOptions.md) |
 
 #### Returns
 
@@ -58,7 +59,7 @@ Defined in: [play-react-router/src/react-router-bridge.ts:33](https://gitlab.com
 
 #### Overrides
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`constructor`](../../play-router/classes/RouterBridgeBase.md#constructor)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`constructor`](../../play-router/index/classes/RouterBridgeBase.md#constructor)
 
 ## Accessors
 
@@ -70,7 +71,7 @@ Defined in: [play-react-router/src/react-router-bridge.ts:33](https://gitlab.com
 get basePath(): string;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:255](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L255)
+Defined in: [play-router/src/router-bridge-base.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L282)
 
 The resolved URL prefix that the machine of this bridge is mounted under, or `""`
 when the machine owns the complete router.
@@ -83,7 +84,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePath`](../../play-router/classes/RouterBridgeBase.md#basepath)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`basePath`](../../play-router/index/classes/RouterBridgeBase.md#basepath)
 
 ---
 
@@ -95,7 +96,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 get basePathParams(): Readonly<Record<string, string>>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L284)
+Defined in: [play-router/src/router-bridge-base.ts:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L311)
 
 The resolved values of the `:param` segments of the mount, or `{}` for a prefix
 without a param.
@@ -136,7 +137,7 @@ mount while the machine stays on the same route, and no event goes out.
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/classes/RouterBridgeBase.md#basepathparams)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/index/classes/RouterBridgeBase.md#basepathparams)
 
 ## Methods
 
@@ -146,11 +147,11 @@ mount while the machine stays on the same route, and no event goes out.
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:506](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L506)
+Defined in: [play-router/src/router-bridge-base.ts:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L533)
 
 Connects the router bridge to the Actor.
 
-The method installs the TC39 Signal watcher of the direction from the actor to the
+The method installs the atom 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.
 
@@ -170,7 +171,7 @@ An adapter that needs a different behavior of the first synchronization override
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`connect`](../../play-router/index/classes/RouterBridgeBase.md#connect)
 
 ---
 
@@ -180,11 +181,11 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:728](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L728)
+Defined in: [play-router/src/router-bridge-base.ts:791](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L791)
 
 Disconnects the router bridge from the Actor.
 
-The method stops the watch of the signal, and it removes the router listener of the
+The method stops the watch of the atom, and it removes the router listener of the
 framework.
 
 #### Returns
@@ -193,7 +194,7 @@ framework.
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/index/classes/RouterBridgeBase.md#disconnect)
 
 ---
 
@@ -203,7 +204,7 @@ framework.
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L324)
+Defined in: [play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L351)
 
 Moves the machine to a different mount point, while it stays connected.
 
@@ -255,4 +256,4 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/classes/RouterBridgeBase.md#setbasepath)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/index/classes/RouterBridgeBase.md#setbasepath)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:105](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L105)
+Defined in: [play-router/src/base-route-map.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L177)
 
 The shared base class of the route map for both directions.
 
@@ -14,15 +14,22 @@ of its own, and it inherits the complete public API from here.
 - A static path, without a `:param` → a `Map` lookup in O(1)
 - A dynamic path → a scan of the bucket index in O(k), with `URLPattern`, where
   `k` is the number of the routes with the same first path segment
-- The class keeps each result of a first match in an LRU cache. The default size
-  is 500 entries, and the `cacheSize` constructor option changes it
+- The class keeps each result of a first match in an LRU cache. The default cache
+  holds between 500 and 1000 entries, and the `pathCache` constructor option
+  replaces it
 
-**The syntax of a pattern** (`:param`, `:param?`, and `*`):
+**The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
+often are:
 
 - `:param` — a necessary segment. It matches exactly one segment without a `/`
 - `:param?` — an optional segment. It matches zero segments or one segment without a `/`
 - `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
+A `{…}` group, a `:param(\d+)` constraint, a `+` modifier and a `\:` escape are read
+too. The [routing guide](../../../../guides/routing.md) states every form, the prefix
+rule, and the one divergence from the standard: a param name of this library can hold a
+hyphen.
+
 **The forms of a stateId:** you can register a stateId, and you can look one up,
 in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
 canonical form itself. `getStateIdByPath` returns the stateId exactly as you
@@ -58,7 +65,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L133)
+Defined in: [play-router/src/base-route-map.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L210)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -69,11 +76,10 @@ candidates is therefore efficient.
 
 #### Parameters
 
-| Parameter            | Type                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| -------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mappings`           | [`RouteMapping`](../interfaces/RouteMapping.md)[] | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                                                                                                                                                                                                                                                                                                                                                     |
-| `options`            | \{ `cacheSize?`: `number`; \}                     | The optional configuration. `options.cacheSize`: the maximum number of the resolved parameterized path lookups in the cache. The default is `500`. Raise it for an application with many different values in a parameterized URL, for example a page of a user profile with thousands of different IDs. After an eviction, the path goes to the bucket pattern scan in O(k) again, which is correct but slower. The smallest effective value is `1`, because QuickLRU requires it. |
-| `options.cacheSize?` | `number`                                          | -                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Parameter  | Type                                                  | Description                                                                                                                                               |
+| ---------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mappings` | [`RouteMapping`](../interfaces/RouteMapping.md)[]     | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                            |
+| `options`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | See [RouteMapOptions](../interfaces/RouteMapOptions.md). A map holds TWO caches, so no option is named `cache`: each one names the cache that it carries. |
 
 #### Returns
 
@@ -87,7 +93,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L229)
+Defined in: [play-router/src/base-route-map.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L324)
 
 Returns the path pattern of a state ID.
 
@@ -123,7 +129,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L189)
+Defined in: [play-router/src/base-route-map.ts:279](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L279)
 
 Resolves a URL path to its state ID.
 

package/api/@xmachines/play-react-router/functions/createPlayRouterProvider.md

@@ -3,24 +3,27 @@
 # Function: createPlayRouterProvider()
 
 ```ts
-function createPlayRouterProvider<TRouter>(BridgeCtor): <TActor>(__namedParameters) => Element;
+function createPlayRouterProvider<TRouter, TActorBase>(
+	BridgeCtor,
+): <TActor>(__namedParameters) => Element;
 ```
 
-Defined in: [play-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-react-router/src/create-play-router-provider.tsx#L52)
+Defined in: [play-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-react-router/src/create-play-router-provider.tsx#L52)
 
 Builds a `PlayRouterProvider` for one React bridge class.
 
 ## Type Parameters
 
-| Type Parameter |
-| -------------- |
-| `TRouter`      |
+| Type Parameter                                                           | Default type                                      |
+| ------------------------------------------------------------------------ | ------------------------------------------------- |
+| `TRouter`                                                                | -                                                 |
+| `TActorBase` _extends_ [`RoutableActor`](../interfaces/RoutableActor.md) | [`RoutableActor`](../interfaces/RoutableActor.md) |
 
 ## Parameters
 
-| Parameter    | Type                                                                                         | Description                                                                    |
-| ------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`\> | The bridge class, built as `new BridgeCtor(router, actor, routeMap, options)`. |
+| Parameter    | Type                                                                                                       | Description                                                                    |
+| ------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `BridgeCtor` | [`PlayRouterBridgeConstructor`](../type-aliases/PlayRouterBridgeConstructor.md)\<`TRouter`, `TActorBase`\> | The bridge class, built as `new BridgeCtor(router, actor, routeMap, options)`. |
 
 ## Returns
 

package/api/@xmachines/play-react-router/functions/createRouteMapFromTree.md

@@ -6,12 +6,13 @@
 function createRouteMapFromTree(routeTree, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/create-route-map-from-tree.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/create-route-map-from-tree.ts#L33)
+Defined in: [play-router/src/create-route-map-from-tree.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/create-route-map-from-tree.ts#L40)
 
 Creates a `RouteMap` from the node structure of a `RouteTree`.
 
-A framework router adapter uses this function when it gives a `RouteTree` from
-`extractMachineRoutes()`, and not when it calls `createRouteMap()` directly.
+A framework router adapter uses this function when it holds a `RouteTree`, for example
+from `extractMachineRoutes()` of `@xmachines/play-router/xstate`, and not when it calls
+`createRouteMap()` of that package directly.
 
 The function walks every node, and it collects the pairs
 `{ stateId: node.id, path: node.fullPath }`. `node.fullPath` is always the
@@ -19,12 +20,17 @@ absolute resolved path, for example `"/dashboard/overview"`, and `RouteMap` need
 that path for the match of a browser URL. `createRouteMap(machine)` behaves in the
 same way, because it also uses `node.fullPath`.
 
+The walk SKIPS the synthetic root node. `buildRouteTree` makes that node to hold each
+absolute route, and no state of a machine declares it. `createRouteMap` skips it as
+well, through `getRoutableRoutes`, and the two functions therefore answer the same map
+for the same tree.
+
 ## Parameters
 
-| Parameter   | Type                                                     | Description                                                                                  |
-| ----------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md) | A `RouteTree`, as `extractMachineRoutes()` returns it.                                       |
-| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)    | The optional configuration, for example `{ cacheSize }` to change the size of the LRU cache. |
+| Parameter   | Type                                                           | Description                                                                                             |
+| ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `routeTree` | [`RouteTree`](../../play-router/index/interfaces/RouteTree.md) | A `RouteTree`, as `extractMachineRoutes()` returns it.                                                  |
+| `options?`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md)          | The optional configuration, for example `{ pathCache }` to replace the LRU cache of the resolved paths. |
 
 ## Returns
 
@@ -36,11 +42,12 @@ A `RouteMap` for each adapter on `RouterBridgeBase`.
 
 ```typescript
 // The preferred form — one call for an XState machine:
-import { createRouteMap } from "@xmachines/play-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 const routeMap = createRouteMap(machine); // it takes an AnyStateMachine
 
 // The two-step form, for a framework adapter that works with a route tree:
-import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+import { createRouteMapFromTree } from "@xmachines/play-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree); // it uses node.fullPath, which is absolute
 ```

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouteEvent
 
-Defined in: [play-router/src/types.ts:238](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L238)
+Defined in: [play-router/src/types.ts:336](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L336)
 
 The routing event, with its parameters and its query
 
@@ -118,18 +118,13 @@ Use `play.route` when you need a navigation that knows the parameters, with the
 gives you the complete URLPatternResult, for an advanced use such as a debug or an
 analysis of the pattern.
 
-## Indexable
-
-```ts
-[key: string]: unknown
-```
-
 ## Properties
 
-| Property                               | Modifier   | Type                           | Defined in                                                                                                                      |
-| -------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                      | [play-router/src/types.ts:243](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L243) |
-| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:241](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L241) |
-| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\> | [play-router/src/types.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L242) |
-| <a id="property-to"></a> `to`          | `readonly` | `string`                       | [play-router/src/types.ts:240](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L240) |
-| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                 | [play-router/src/types.ts:239](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L239) |
+| Property                               | Modifier   | Type                                                             | Description                                                                                                                                                                                                                                                                           | Defined in                                                                                                                      |
+| -------------------------------------- | ---------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-data"></a> `data?`     | `readonly` | [`RouteData`](../../play-router/index/type-aliases/RouteData.md) | The extra data that the SENDER of this event supplies: a router bridge, or the code of an application. It is not what the target state declares — that is [RouteObject.data](../../play-router/index/interfaces/RouteObject.md#property-data), and a resolver there reads this field. | [play-router/src/types.ts:346](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L346) |
+| <a id="property-match"></a> `match?`   | `readonly` | `unknown`                                                        | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:347](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L347) |
+| <a id="property-params"></a> `params?` | `readonly` | `Record`\<`string`, `string`\>                                   | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:339](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L339) |
+| <a id="property-query"></a> `query?`   | `readonly` | `Record`\<`string`, `string`\>                                   | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:340](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L340) |
+| <a id="property-to"></a> `to`          | `readonly` | `string`                                                         | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:338](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L338) |
+| <a id="property-type"></a> `type`      | `readonly` | `"play.route"`                                                   | -                                                                                                                                                                                                                                                                                     | [play-router/src/types.ts:337](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/types.ts#L337) |