@xmachines/docs 3.0.0 → 4.0.0

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

@@ -4,18 +4,18 @@
 
 TanStack Router (React) adapter for XMachines Play. It keeps the browser URL and the actor state in step through passive infrastructure.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-3.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-tanstack-react-router)
 
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-tanstack-react-router
+pnpm add @xmachines/play-tanstack-react-router @xmachines/play-router
 ```
 
 **Peer dependencies.** Install them separately:
 
 ```bash
-pnpm add @tanstack/react-router react react-dom xstate
+pnpm add @tanstack/react-router react react-dom
 ```
 
 The adapter requires:
@@ -23,7 +23,6 @@ The adapter requires:
 - `@tanstack/react-router` `^1.168.8`
 - `react` `^18.0.0` or `^19.0.0`
 - `react-dom` `^18.0.0` or `^19.0.0`
-- `xstate` `^5.31.0`
 
 ## Usage
 
@@ -35,8 +34,11 @@ The adapter requires:
 import { useMemo, useEffect, useState } from "react";
 import { createMachine } from "xstate";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
-import { PlayRouterProvider, createRouteMap } from "@xmachines/play-tanstack-react-router";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { PlayRouterProvider } from "@xmachines/play-tanstack-react-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { withRouting } from "@xmachines/play-xstate/routing";
 import { useSignalEffect } from "@xmachines/play-react";
 
 // Any machine whose states declare `meta.route` (plus an explicit `id`) is routable.
@@ -53,7 +55,7 @@ const machine = createMachine(
 	}),
 );
 
-const createPlayer = definePlayer({ machine });
+const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRouting) });
 type AppActor = ReturnType<typeof createPlayer>;
 
 // Minimal shell: mirrors the actor's route signal into React state. A full app
@@ -101,12 +103,15 @@ Use the bridge directly when you do not need the React wrapper, or when you inte
 
 ```typescript
 import { createRouter, createRootRoute } from "@tanstack/react-router";
-import { definePlayer } from "@xmachines/play-xstate";
-import { TanStackReactRouterBridge, createRouteMap } from "@xmachines/play-tanstack-react-router";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { TanStackReactRouterBridge } from "@xmachines/play-tanstack-react-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
 import { machine } from "./machine.js"; // the routable machine from the example above
 
 const router = createRouter({ routeTree: createRootRoute() });
-const actor = definePlayer({ machine })();
+// The bridge needs the routing capability
+const actor = definePlayer({ machine, actor: compose(PlayerActor, withRouting) })();
 actor.start();
 const routeMap = createRouteMap(machine);
 
@@ -164,25 +169,15 @@ type TanStackRouterLike = {
 };
 ```
 
-### `RouteNavigateEvent`
-
-The event that the bridge sends to the actor when the browser navigates:
-
-```typescript
-interface RouteNavigateEvent {
-	readonly type: "route.navigate";
-	readonly path: string; // e.g. "/dashboard" or "/posts/123"
-}
-```
-
 ### Re-exported from `@xmachines/play-router`
 
 ```typescript
 // Route map construction
 RouteMap
-createRouteMap(machine, options?): RouteMap
 createRouteMapFromTree(routeTree): RouteMap
-extractMachineRoutes(machine): RouteTree
+
+// `createRouteMap` and `extractMachineRoutes` read a state machine. This barrel names
+// none, so import them from `@xmachines/play-router/xstate`.
 
 // Types
 type RouteMapOptions
@@ -201,22 +196,6 @@ The bridge implements the **Passive Infrastructure** invariant from the XMachine
 4. **Deep-link and restore:** on `connect()`, the bridge reads `router.history.location.pathname`. That value shows `window.location` at once, before `router.load()` runs. The bridge then makes a decision: it sets the actor state from the URL (a deep link), or it writes the restored route of the actor to the URL (a snapshot restore).
 5. **Corrective navigation under a mounted `<RouterProvider>`:** for every history event, the bridge calls `router.load()` and waits for the promise before it synchronizes the actor. A mounted `<RouterProvider>` defers the refresh of `router.latestLocation`, and without the wait TanStack drops the corrective navigation for a refused URL. See the [`@xmachines/play-tanstack-router` README](../play-tanstack-router/README.md) for the details.
 
-## Testing
-
-Run tests for this package in isolation:
-
-```bash
-pnpm --filter @xmachines/play-tanstack-react-router test
-```
-
-From the monorepo root:
-
-```bash
-pnpm test
-```
-
-Tests cover RouterBridge protocol compliance, actor ↔ router bidirectional sync, circular update prevention, deep-link and snapshot-restore scenarios, and `PlayRouterProvider` lifecycle (mount/unmount/reconnect).
-
 ## Demo
 
 `examples/demo/` holds a runnable demo of the React and TanStack Router integration. Run it from the repository root:
@@ -247,12 +226,11 @@ infrastructure.
 
 ## 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)
-- [~~RouteNavigateEvent~~](interfaces/RouteNavigateEvent.md)
 - [RouterBridge](interfaces/RouterBridge.md)
 
 ## Type Aliases
@@ -269,6 +247,4 @@ infrastructure.
 ## Functions
 
 - [createPlayRouterProvider](functions/createPlayRouterProvider.md)
-- [createRouteMap](functions/createRouteMap.md)
 - [createRouteMapFromTree](functions/createRouteMapFromTree.md)
-- [extractMachineRoutes](functions/extractMachineRoutes.md)

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts: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:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L111)
 
 The shared base class of the route map for both directions.
 
@@ -17,12 +17,18 @@ of its own, and it inherits the complete public API from here.
 - 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 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 +64,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:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L139)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -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:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L242)
 
 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:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/base-route-map.ts#L197)
 
 Resolves a URL path to its state ID.
 

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

@@ -2,7 +2,7 @@
 
 # Class: TanStackReactRouterBridge
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L133)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:133](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L133)
 
 The shared TanStack Router adapter. It implements the RouterBridge protocol through RouterBridgeBase
 
@@ -29,7 +29,7 @@ Architectural invariants:
 
 The class is concrete. You can create an instance of it directly. Each framework
 package re-exports it, or makes a subclass of it, only to bind the public name of
-the adapter. The Solid package also adds the `dispose()` alias.
+the adapter.
 
 ## Example
 
@@ -41,7 +41,7 @@ return () => bridge.disconnect();
 
 ## Extends
 
-- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+- [`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md)
 
 ## Constructors
 
@@ -52,10 +52,11 @@ new TanStackReactRouterBridge(
    router,
    actor,
    routeMap,
-   options?): TanStackRouterBridgeBase;
+   options?
+): TanStackRouterBridgeBase;
 ```
 
-Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L151)
+Defined in: [play-tanstack-router/src/tanstack-router-bridge-base.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-router/src/tanstack-router-bridge-base.ts#L151)
 
 Creates a TanStack Router bridge
 
@@ -64,7 +65,7 @@ Creates a TanStack Router bridge
 | Parameter  | Type                                                                                      | Description                                               |
 | ---------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- |
 | `router`   | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md)                             | The TanStack Router instance from `createRouter`          |
-| `actor`    | [`RoutableActor`](../../play-dom-router/interfaces/RoutableActor.md)                      | The XMachines actor instance                              |
+| `actor`    | [`RoutableActor`](../interfaces/RoutableActor.md)                                         | The XMachines actor instance                              |
 | `routeMap` | [`TanStackRouteMapLike`](../../play-tanstack-router/type-aliases/TanStackRouteMapLike.md) | The bidirectional map between the state IDs and the paths |
 | `options?` | [`BasePathOptions`](../../play-dom-router/interfaces/BasePathOptions.md)                  | -                                                         |
 
@@ -74,7 +75,7 @@ Creates a TanStack Router bridge
 
 #### 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
 
@@ -86,7 +87,7 @@ Creates a TanStack Router bridge
 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:256](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L256)
 
 The resolved URL prefix that the machine of this bridge is mounted under, or `""`
 when the machine owns the complete router.
@@ -99,7 +100,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)
 
 ---
 
@@ -111,7 +112,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:285](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L285)
 
 The resolved values of the `:param` segments of the mount, or `{}` for a prefix
 without a param.
@@ -152,7 +153,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
 
@@ -162,7 +163,7 @@ 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:507](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L507)
 
 Connects the router bridge to the Actor.
 
@@ -186,7 +187,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)
 
 ---
 
@@ -196,7 +197,7 @@ 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:765](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L765)
 
 Disconnects the router bridge from the Actor.
 
@@ -209,7 +210,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)
 
 ---
 
@@ -219,7 +220,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:325](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/router-bridge-base.ts#L325)
 
 Moves the machine to a different mount point, while it stays connected.
 
@@ -271,4 +272,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-tanstack-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-tanstack-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-react-router/src/create-play-router-provider.tsx#L52)
+Defined in: [play-tanstack-react-router/src/create-play-router-provider.tsx:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-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-tanstack-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/v4.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 `{ cacheSize }` to change the size of the LRU cache. |
 
 ## 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-tanstack-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/v4.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/v4.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/v4.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/v4.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/v4.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/v4.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/v4.0.0/packages/play-router/src/types.ts#L337) |

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

@@ -2,7 +2,7 @@
 
 # Interface: PlayRouterProviderProps\<TActor\>
 
-Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L45)
+Defined in: [play-tanstack-react-router/src/play-router-provider.tsx:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-tanstack-react-router/src/play-router-provider.tsx#L45)
 
 The props of the `PlayRouterProvider` of TanStack React Router.
 
@@ -16,17 +16,17 @@ The props of the `PlayRouterProvider` of TanStack React Router.
 
 ## Type Parameters
 
-| Type Parameter                                 | Default type                |
-| ---------------------------------------------- | --------------------------- |
-| `TActor` _extends_ [`PlayActor`](PlayActor.md) | [`PlayActor`](PlayActor.md) |
+| Type Parameter                                         | Default type                        |
+| ------------------------------------------------------ | ----------------------------------- |
+| `TActor` _extends_ [`RoutableActor`](RoutableActor.md) | [`RoutableActor`](RoutableActor.md) |
 
 ## Properties
 
 | Property                                               | Type                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Inherited from                               | Defined in                                                                                                                                              |
 | ------------------------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor`                    | `TActor`                                                      | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `PlayRouterProviderBaseProps.actor`          | [play-router/src/provider-lifecycle.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L42) |
-| <a id="property-basepath"></a> `basePath?`             | `string`                                                      | Mounts the routes of the machine under a URL prefix that the host owns, so that the routes of the host and the routes of the machine share one router. `actor`, `router`, and `routeMap` each need a stable reference. This prop needs none, and it rebuilds the bridge never: a change moves the live bridge with `setBasePath()`, so a host route that renders again with a new prefix keeps the actor, the route map, and its cache. The prefix says WHERE an actor is mounted, and never WHICH actor is mounted. An actor never changes identity, so a prefix segment that IDENTIFIES the actor gives a different `actor` prop instead, and THAT rebuilds the bridge — which is correct, because one actor takes one bridge. A location outside the prefix belongs completely to the host: the bridge sends no event there, and it corrects no URL there. Every `:param` needs a value. An unresolved one throws a `MissingBasePathParamError` out of the mount effect, because the bridge writes no URL without it. Render this component only after the host holds the value, which a route loader or a `useParams()` call does already. | `PlayRouterProviderBaseProps.basePath`       | [play-router/src/provider-lifecycle.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L80) |
-| <a id="property-basepathparams"></a> `basePathParams?` | `Record`\<`string`, `string` \| `number`\>                    | The values of the `:param` segments of [PlayRouterProviderBaseProps.basePath](../../play-react-router/interfaces/PlayRouterProviderProps.md#property-basepath), for example `{ machineId }` for `basePath="/:machineId/play"`. An inline object literal is correct here: the provider compares this prop by value, and a move to the same prefix does nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `PlayRouterProviderBaseProps.basePathParams` | [play-router/src/provider-lifecycle.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L89) |
-| <a id="property-renderer"></a> `renderer`              | (`actor`, `router`) => `ReactNode`                            | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `PlayRouterProviderBaseProps.renderer`       | [play-router/src/provider-lifecycle.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L91) |
-| <a id="property-routemap"></a> `routeMap`              | [`RouteMap`](../classes/RouteMap.md)                          | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `PlayRouterProviderBaseProps.routeMap`       | [play-router/src/provider-lifecycle.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L57) |
-| <a id="property-router"></a> `router`                  | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `PlayRouterProviderBaseProps.router`         | [play-router/src/provider-lifecycle.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L44) |
+| <a id="property-actor"></a> `actor`                    | `TActor`                                                      | The actor to keep in step with the router. It must be a stable reference: give the same actor instance on every render. An actor in the JSX, or a new actor on each render, makes the bridge disconnect and connect again each time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `PlayRouterProviderBaseProps.actor`          | [play-router/src/provider-lifecycle.ts:42](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L42) |
+| <a id="property-basepath"></a> `basePath?`             | `string`                                                      | Mounts the routes of the machine under a URL prefix that the host owns, so that the routes of the host and the routes of the machine share one router. `actor`, `router`, and `routeMap` each need a stable reference. This prop needs none, and it rebuilds the bridge never: a change moves the live bridge with `setBasePath()`, so a host route that renders again with a new prefix keeps the actor, the route map, and its cache. The prefix says WHERE an actor is mounted, and never WHICH actor is mounted. An actor never changes identity, so a prefix segment that IDENTIFIES the actor gives a different `actor` prop instead, and THAT rebuilds the bridge — which is correct, because one actor takes one bridge. A location outside the prefix belongs completely to the host: the bridge sends no event there, and it corrects no URL there. Every `:param` needs a value. An unresolved one throws a `MissingBasePathParamError` out of the mount effect, because the bridge writes no URL without it. Render this component only after the host holds the value, which a route loader or a `useParams()` call does already. | `PlayRouterProviderBaseProps.basePath`       | [play-router/src/provider-lifecycle.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L80) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `Record`\<`string`, `string` \| `number`\>                    | The values of the `:param` segments of [PlayRouterProviderBaseProps.basePath](../../play-react-router/interfaces/PlayRouterProviderProps.md#property-basepath), for example `{ machineId }` for `basePath="/:machineId/play"`. An inline object literal is correct here: the provider compares this prop by value, and a move to the same prefix does nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `PlayRouterProviderBaseProps.basePathParams` | [play-router/src/provider-lifecycle.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L89) |
+| <a id="property-renderer"></a> `renderer`              | (`actor`, `router`) => `ReactNode`                            | The renderer callback receives the same concrete actor type as the prop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `PlayRouterProviderBaseProps.renderer`       | [play-router/src/provider-lifecycle.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L91) |
+| <a id="property-routemap"></a> `routeMap`              | [`RouteMap`](../classes/RouteMap.md)                          | The route map of both directions, for the lookup between a state ID and a URL path. **It must be a stable reference.** The provider builds the bridge again on each change of the identity of `routeMap`. A value in the JSX, for example `createRouteMapFromTree(routeTree)`, makes a new object on every render, and the bridge therefore connects again on every render. Hold the value with `useMemo`: `const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `PlayRouterProviderBaseProps.routeMap`       | [play-router/src/provider-lifecycle.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L57) |
+| <a id="property-router"></a> `router`                  | [`TanStackRouterLike`](../type-aliases/TanStackRouterLike.md) | The router instance that the bridge keeps in step with the actor. It must be a stable reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `PlayRouterProviderBaseProps.router`         | [play-router/src/provider-lifecycle.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-router/src/provider-lifecycle.ts#L44) |