@xmachines/docs 3.0.0 → 4.0.0

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

@@ -4,22 +4,28 @@
 
 **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-3.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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom-router)
 
 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
 
 ```bash
-pnpm add @xmachines/play-dom-router @xmachines/play-router @xmachines/play-actor
+pnpm add @xmachines/play-dom-router @xmachines/play-router
 ```
 
-Peer dependency:
+**Peer dependency.** Install it with the package:
 
 ```bash
-pnpm add xstate@^5.31.0
+pnpm add @xmachines/play
 ```
 
+- `@xmachines/play` — the release protocol. This barrel re-exports `asCleanup`, `DISPOSE` and `Cleanup` from it.
+
+`@xmachines/play-router` is a dependency of this package already. Install it directly to
+reach `@xmachines/play-router/xstate`, which holds `createRouteMap` and
+`extractMachineRoutes`.
+
 ## Overview
 
 [`@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)):
@@ -33,35 +39,55 @@ pnpm add xstate@^5.31.0
 
 | Export                                        | Description                                                                                                        |
 | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `createBrowserHistory(options)`               | Wraps `window.history`. It returns a `DisposableBrowserHistory`                                                    |
-| `createRouter(options)`                       | Creates a `DisposableVanillaRouter` from a `BrowserHistory` and a `RouteTree`, which `using` releases              |
-| `connectRouter(options)`                      | Connects a `VanillaRouter` to a `Routable` actor — returns a `RouterConnection`, which `using` releases            |
+| `createBrowserHistory(options)`               | Wraps `window.history`. It returns a `BrowserHistory`, which `using` releases                                      |
+| `createRouter(options)`                       | Creates a `VanillaRouter` from a `BrowserHistory` and a `RouteTree`, which `using` releases                        |
+| `connectRouter(options)`                      | Connects a history to a `Routable` actor — returns a `RouterConnection`, which `using` releases                    |
 | `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. Implement it to inject a history of your own                                    |
-| `DisposableBrowserHistory`                    | What `createBrowserHistory` returns: `subscribe` hands a `Cleanup` back, and the history itself is a `Disposable`  |
+| `BrowserHistory`                              | Interface for the history wrapper. Implement it to inject a history of your own — see the note below               |
 | `BrowserWindow`                               | Structural window interface (accepts `Window`, JSDOM, or any test double)                                          |
-| `VanillaRouter<History>`                      | The router wrapper. `History` carries the history of the caller, so a `DisposableBrowserHistory` stays one         |
-| `DisposableVanillaRouter<History>`            | What `createRouter` returns: a `VanillaRouter` that carries the dispose key, so a `using` scope holds it           |
+| `VanillaRouter`                               | The router wrapper: a history, a route tree, and the release of the history under two keys                         |
 | `ConnectRouterOptions`                        | Options type for `connectRouter`                                                                                   |
 | `RouteLookupContract`                         | Structural interface for bidirectional route lookup                                                                |
 | `RoutableActor`                               | Minimal actor interface from `@xmachines/play-router` — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)` |
 | `RouterBridge`, `PlayRouteEvent`              | Types re-exported from `@xmachines/play-router`                                                                    |
-| `RouteMap`, `RouteMapping`, `RouteMapOptions` | Types re-exported from `@xmachines/play-router`                                                                    |
-| `DISPOSE`, `Cleanup`                          | The release protocol that `subscribe` and `DisposableBrowserHistory` name, re-exported from `@xmachines/play`      |
+| `RouteMap`, `RouteMapping`, `RouteMapOptions` | The route map class and its types, re-exported from `@xmachines/play-router`                                       |
+| `asCleanup`, `DISPOSE`, `Cleanup`             | The release protocol that `BrowserHistory` names, re-exported from `@xmachines/play`                               |
+
+### Implementing `BrowserHistory`
+
+`subscribe` returns a `Cleanup`, and the history carries the dispose key. A history that you inject for a test or for SSR therefore writes two things that a plain object does not:
+
+```typescript
+import { asCleanup, DISPOSE, type BrowserHistory } from "@xmachines/play-dom-router";
+
+const history: BrowserHistory = {
+	// ...
+	subscribe(listener) {
+		listeners.add(listener);
+		return asCleanup(() => void listeners.delete(listener));
+	},
+	destroy() {
+		listeners.clear();
+	},
+	[DISPOSE]() {
+		this.destroy();
+	},
+};
+```
+
+`asCleanup` gives the function back as itself, with the dispose key added, so a caller that runs the release keeps that code. A caller that writes `using` releases at the end of the scope, and after an exception too.
+
+Of this interface `connectRouter` reads three members — `location`, `push` and `subscribe` — and it releases the history never. The type asks for the whole of it, because that is the type of a history, and a test that stands in for one builds it from a factory rather than from a narrower type.
 
 ## Quick Start
 
 ```typescript
 import { createMachine } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions, withRouting } from "@xmachines/play-xstate/routing";
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap } from "@xmachines/play-router/xstate";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 // 1. Define a routable machine — states carry meta.route
 const machine = createMachine(
@@ -85,8 +111,8 @@ const history = createBrowserHistory({ window });
 // 4. Create router
 const router = createRouter({ routeTree, history });
 
-// 5. Start actor and connect
-const actor = definePlayer({ machine })();
+// 5. Start actor and connect — `connectRouter` needs the routing capability
+const actor = definePlayer({ machine, actor: compose(PlayerActor, withRouting) })();
 actor.start();
 
 const disconnect = connectRouter({ actor, router, routeMap });
@@ -142,7 +168,7 @@ The interface accepts `window`, a JSDOM window, or every other object that imple
 
 ### `createRouter(options)`
 
-This function creates a `DisposableVanillaRouter` around a `history` and a `routeTree`. Its setup flow is the same as the setup flow of TanStack Router.
+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
@@ -158,8 +184,8 @@ Or let a scope release it, which also releases the history on an exception:
 using router = createRouter({ routeTree, history });
 ```
 
-The return is a `DisposableVanillaRouter`. The dispose key and `destroy()` run the same
-body, and the release is idempotent, so a caller that keeps `destroy()` keeps it.
+The dispose key and `destroy()` run the same body, and the release is idempotent, so a
+caller that keeps `destroy()` keeps it.
 
 **The release covers the history alone.** `connectRouter` hands back its own
 `RouterConnection`, and a scope that ends releases no connection for you. Release the
@@ -167,7 +193,7 @@ connection first, then the router.
 
 ### `connectRouter(options)`
 
-This function connects a `VanillaRouter` to a `Routable` actor. It does all the work in both directions:
+This function connects a history to a `Routable` actor. It does all the work in both directions:
 
 - 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.
@@ -175,8 +201,8 @@ This function connects a `VanillaRouter` to a `Routable` actor. It does all the
 
 ```typescript
 const disconnect = connectRouter({
-	actor, // RoutableActor — any AbstractActor subclass satisfies this structurally
-	router, // VanillaRouter from createRouter()
+	actor, // RoutableActor — an actor of the `PlayActor` contract that adds `Routable` satisfies this structurally
+	router, // the router from createRouter(), or any { history }
 	routeMap, // RouteLookupContract — any object with getStateIdByPath / getPathByStateId
 });
 
@@ -186,11 +212,11 @@ disconnect();
 
 **`ConnectRouterOptions`:**
 
-| 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           |
+| Option     | Type                  | Description                                                                                                        |
+| ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `actor`    | `RoutableActor`       | The actor to keep in step with the browser URL                                                                     |
+| `router`   | `{ history }`         | The router from `createRouter()`, or any `{ history }`. Of the history it reads `location`, `push` and `subscribe` |
+| `routeMap` | `RouteLookupContract` | Bidirectional path ↔ state ID lookup                                                                               |
 
 **`RouteLookupContract`:**
 
@@ -203,44 +229,18 @@ interface RouteLookupContract {
 
 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)
+### `createRouteMap` — from `@xmachines/play-router/xstate`
 
-This function comes from `@xmachines/play-router`. It builds a bidirectional `RouteMap` from an XState machine:
+This package re-exports it never: the barrel names no state machine. The function builds a bidirectional `RouteMap` from an XState machine:
 
 ```typescript
-import { createRouteMap } from "@xmachines/play-dom-router";
-
+import { createRouteMap } from "@xmachines/play-router/xstate";
 // machine from the Quick Start above (states carry meta.route)
 const routeMap = createRouteMap(machine);
 routeMap.getStateIdByPath("/dashboard"); // "dashboard"
 routeMap.getPathByStateId("dashboard"); // "/dashboard"
 ```
 
-## URLPattern Support
-
-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
-
-Run tests in isolation:
-
-```bash
-pnpm test
-# or from monorepo root:
-pnpm --filter @xmachines/play-dom-router test
-```
-
-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:
-
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 80%       |
-| Functions  | 80%       |
-| Branches   | 75%       |
-| Statements | 80%       |
-
 ## Architecture
 
 The bridge-first data flow:
@@ -269,10 +269,12 @@ Browser URL
 
 ## Related Packages
 
-- [@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-router](../play-router/README.md) — `RouterBridgeBase`, `RouteMap`, `Routable`
+- [@xmachines/play-router/xstate](../play-router/README.md) — `createRouteMap`, `extractMachineRoutes`
+- [@xmachines/play-actor](../play-actor/README.md) — `PlayActor`; an actor that adds `Routable` satisfies `RoutableActor` structurally
 - [@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`
+- [Routing guide](../../../guides/routing.md) — the URLPattern language that a `meta.route` path declares
 
 ## License
 
@@ -281,6 +283,7 @@ MIT — see [LICENSE](LICENSE).
 ## Classes
 
 - [DomRouterBridge](classes/DomRouterBridge.md)
+- [RouteMap](classes/RouteMap.md)
 
 ## Interfaces
 
@@ -288,12 +291,9 @@ MIT — see [LICENSE](LICENSE).
 - [BrowserHistory](interfaces/BrowserHistory.md)
 - [BrowserWindow](interfaces/BrowserWindow.md)
 - [ConnectRouterOptions](interfaces/ConnectRouterOptions.md)
-- [DisposableBrowserHistory](interfaces/DisposableBrowserHistory.md)
-- [DisposableVanillaRouter](interfaces/DisposableVanillaRouter.md)
 - [PlayRouteEvent](interfaces/PlayRouteEvent.md)
 - [RoutableActor](interfaces/RoutableActor.md)
 - [RouteLookupContract](interfaces/RouteLookupContract.md)
-- [RouteMap](interfaces/RouteMap.md)
 - [RouteMapOptions](interfaces/RouteMapOptions.md)
 - [RouteMapping](interfaces/RouteMapping.md)
 - [RouterBridge](interfaces/RouterBridge.md)
@@ -310,7 +310,7 @@ MIT — see [LICENSE](LICENSE).
 
 ## Functions
 
+- [asCleanup](functions/asCleanup.md)
 - [connectRouter](functions/connectRouter.md)
 - [createBrowserHistory](functions/createBrowserHistory.md)
-- [createRouteMap](functions/createRouteMap.md)
 - [createRouter](functions/createRouter.md)

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

@@ -2,7 +2,7 @@
 
 # Class: DomRouterBridge
 
-Defined in: [play-dom-router/src/dom-router-bridge.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L27)
+Defined in: [play-dom-router/src/dom-router-bridge.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L27)
 
 The DOM router bridge — it puts a BrowserHistory from `createBrowserHistory`
 behind the `RouterBridgeBase` protocol.
@@ -27,7 +27,7 @@ full control of the connection lifecycle.
 
 ## Extends
 
-- [`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md)
+- [`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md)
 
 ## Constructors
 
@@ -38,19 +38,20 @@ new DomRouterBridge(
    actor,
    routeMap,
    history,
-   options?): DomRouterBridge;
+   options?
+): DomRouterBridge;
 ```
 
-Defined in: [play-dom-router/src/dom-router-bridge.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L35)
+Defined in: [play-dom-router/src/dom-router-bridge.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom-router/src/dom-router-bridge.ts#L40)
 
 #### 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`.                                                                             |
-| `options?` | [`BasePathOptions`](../interfaces/BasePathOptions.md)         | -                                                                                                                                    |
+| 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 history to read. `createBrowserHistory` builds one. Of the interface this class touches three members — `location`, `push` and `subscribe` — and it releases the history never, because the owner of the history does that. The parameter still asks for the WHOLE interface, because that is the type of a history: a stand-in for one writes `destroy()` and `[DISPOSE]()` beside the three, and the README of this package shows the shape. |
+| `options?` | [`BasePathOptions`](../interfaces/BasePathOptions.md)         | -                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 #### Returns
 
@@ -58,7 +59,7 @@ Defined in: [play-dom-router/src/dom-router-bridge.ts:35](https://gitlab.com/xma
 
 #### 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-dom-router/src/dom-router-bridge.ts:35](https://gitlab.com/xma
 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.
@@ -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: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.
@@ -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,7 +147,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.
 
@@ -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,7 +181,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.
 
@@ -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: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.
 
@@ -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-vue-router → play-dom-router}/classes/RouteMap.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play-vue-router](../README.md) / RouteMap
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / RouteMap
 
 # 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-dom-router/functions/asCleanup.md

@@ -0,0 +1,78 @@
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / asCleanup
+
+# Function: asCleanup()
+
+```ts
+function asCleanup<R>(release): Cleanup;
+```
+
+Defined in: [play/src/disposable.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L150)
+
+Makes one release function serve as a [Cleanup](../type-aliases/Cleanup.md).
+
+The function comes back as itself, with [DISPOSE](../variables/DISPOSE.md) added. Nothing wraps it, so
+the identity of the release holds: a caller that compares two releases, or that puts
+one in a `Set`, sees what it saw before this protocol existed.
+
+The release therefore must be idempotent. A scope releases the value one time, but a
+caller that runs the function AND lets the scope end runs it two times. Every release
+of this workspace already accepts that, because a teardown that runs two times is
+older than this protocol.
+
+The release must be synchronous. `Disposable` and not `AsyncDisposable`: a
+`Disposable` serves `using` AND `await using`, because `await using` falls back to
+`Symbol.dispose`, while an `AsyncDisposable` raises a TypeError under a plain `using`
+and forces every holder into an async function. Nothing in this workspace releases
+asynchronously. An `AsyncCleanup` can arrive the day something does.
+
+The `R extends void | undefined` bound is what holds that line. A plain `() => void`
+parameter would ACCEPT `async () => {}`, because TypeScript lets a function that
+returns a value stand where one returning `void` is wanted. The promise would then go
+on the floor: the scope releases, the release looks finished, and the work runs later
+with nobody able to await it. The bound rejects that at the call, and it rejects a
+release that returns any other value as well.
+
+The bound holds where the compiler knows the return type. It cannot hold where the
+caller erased it: `R` infers `any` for a release typed `any`, such as a bare
+`vi.fn()`, and `any` satisfies every constraint. A release declared `() => void` whose
+body is async passes for the same reason — the declaration, and not the body, is what
+the call site sees. Write the release inline, or type it, and the bound applies.
+
+The release lands under [DISPOSE](../variables/DISPOSE.md) and, when the two differ, under the
+`Symbol.dispose` that exists at the CALL. `DISPOSE` resolves when the module evaluates,
+so a polyfill that installs the well-known symbol later would otherwise leave the
+release on the registered key while a downlevelled `using` reads the well-known one.
+Writing both closes that window for every release this function publishes.
+
+## Type Parameters
+
+| Type Parameter                      |
+| ----------------------------------- |
+| `R` _extends_ `void` \| `undefined` |
+
+## Parameters
+
+| Parameter | Type      | Description                                                                                                                                                                                                         |
+| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `release` | () => `R` | The release to publish. It must return nothing. The function is changed in place, so pass a function that this release owns: a shared or module-level function becomes a `Disposable` for every other holder of it. |
+
+## Returns
+
+[`Cleanup`](../type-aliases/Cleanup.md)
+
+The same function, now also a `Disposable`.
+
+## Throws
+
+TypeError - When the release is frozen or is otherwise not extensible. The
+protocol adds a property, and a sealed function accepts none.
+
+## Example
+
+```ts
+export function watchSignal<T>(signal: Signal.State<T>, onValue: (v: T) => void): Cleanup {
+	const watcher = new Signal.subtle.Watcher(() => {});
+	watcher.watch(signal);
+	return asCleanup(() => watcher.unwatch(signal));
+}
+```

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

@@ -6,7 +6,7 @@
 function connectRouter(options): RouterConnection;
 ```
 
-Defined in: [play-dom-router/src/connect-router.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/connect-router.ts#L54)
+Defined in: [play-dom-router/src/connect-router.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom-router/src/connect-router.ts#L64)
 
 Connects the vanilla router to an actor. This is a pure browser integration.
 
@@ -27,13 +27,8 @@ before. The handle also carries the mount — `basePath`, `basePathParams` and
 ## Example
 
 ```typescript
-import {
-	createBrowserHistory,
-	createRouter,
-	connectRouter,
-	createRouteMap,
-} from "@xmachines/play-dom-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { createRouteMap, extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMap(machine);

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

@@ -3,10 +3,10 @@
 # Function: createBrowserHistory()
 
 ```ts
-function createBrowserHistory(options): DisposableBrowserHistory;
+function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:167](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L167)
+Defined in: [play-dom-router/src/create-browser-history.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-dom-router/src/create-browser-history.ts#L172)
 
 Creates a browser history that wraps window.history
 
@@ -36,6 +36,12 @@ unsubscribe();
 history.destroy();
 ```
 
+Or let a scope do it, which releases the history on an exception too:
+
+```typescript
+using history = createBrowserHistory({ window });
+```
+
 `destroy()` is idempotent, and it cooperates with each other wrapper of the same
 `window` instance.
 
@@ -54,4 +60,4 @@ teardown.
 
 ## Returns
 
-[`DisposableBrowserHistory`](../interfaces/DisposableBrowserHistory.md)
+[`BrowserHistory`](../interfaces/BrowserHistory.md)