@xmachines/docs 5.0.1 → 6.0.0

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

@@ -4,23 +4,17 @@
 
 **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-5.0.1-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-6.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-dom-router)
 
 This framework-agnostic router integration keeps the `currentRoute` atom 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
+pnpm add @xmachines/play-dom-router @xmachines/play-router @xmachines/core @xmachines/play @xmachines/play-atom
 ```
 
-**Peer dependency.** Install it with the package:
-
-```bash
-pnpm add @xmachines/play
-```
-
-- [`@xmachines/play`](../play/README.md) — the release protocol. This barrel re-exports `asCleanup`, `DISPOSE` and `Cleanup` from it.
+[`@xmachines/play-router`](../play-router/README.md) names [`@xmachines/core`](../core/README.md), [`@xmachines/play`](../play/README.md) and [`@xmachines/play-atom`](../play-atom/README.md) as peers, so the command installs them with this package. To release a history, a router or a connection with `using`, your code imports it itself, so declare it in your own manifest. The `asDisposable` of its `utils` subpath publishes each of them for a scope.
 
 [`@xmachines/play-router`](../play-router/README.md) is a dependency of this package already. Install it directly to
 reach [`@xmachines/play-router/xstate`](../play-router/README.md), which holds `createRouteMap` and
@@ -39,43 +33,39 @@ reach [`@xmachines/play-router/xstate`](../play-router/README.md), which holds `
 
 | Export                                        | Description                                                                                                                                    |
 | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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                                                |
+| `createBrowserHistory(options)`               | Wraps `window.history`. It returns a `BrowserHistory`                                                                                          |
+| `createRouter(options)`                       | Creates a `VanillaRouter` from a `BrowserHistory` and a `RouteTree`                                                                            |
+| `connectRouter(options)`                      | Connects a history to a `Routable` actor — returns a `RouterConnection`                                                                        |
 | `DomRouterBridge`                             | The low-level bridge class. It extends `RouterBridgeBase`. Use it directly for full lifecycle control                                          |
 | `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`                               | The router wrapper: a history, a route tree, and the release of the history under two keys                                                     |
+| `VanillaRouter`                               | The router wrapper: a history, a route tree, and `destroy()`                                                                                   |
 | `ConnectRouterOptions`                        | Options type for `connectRouter`                                                                                                               |
 | `RouteLookupContract`                         | Structural interface for bidirectional route lookup                                                                                            |
 | `RoutableActor`                               | Minimal actor interface from [`@xmachines/play-router`](../play-router/README.md) — `currentRoute`, `initialRoute`, and `send(PlayRouteEvent)` |
 | `RouterBridge`, `PlayRouteEvent`              | Types re-exported from [`@xmachines/play-router`](../play-router/README.md)                                                                    |
 | `RouteMap`, `RouteMapping`, `RouteMapOptions` | The route map class and its types, re-exported from [`@xmachines/play-router`](../play-router/README.md)                                       |
-| `asCleanup`, `DISPOSE`, `Cleanup`             | The release protocol that `BrowserHistory` names, re-exported from [`@xmachines/play`](../play/README.md)                                      |
 
 ### 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:
+A history that you inject for a test or for SSR is a plain object. `subscribe` returns a plain function:
 
 ```typescript
-import { asCleanup, DISPOSE, type BrowserHistory } from "@xmachines/play-dom-router";
+import type { BrowserHistory } from "@xmachines/play-dom-router";
 
 const history: BrowserHistory = {
 	// ...
 	subscribe(listener) {
 		listeners.add(listener);
-		return asCleanup(() => void listeners.delete(listener));
+		return () => 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.
+A spread copies `location` as a value, and the copy then shows a stale location. To wrap a history, build the wrapper as its own object.
 
 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.
 
@@ -117,11 +107,14 @@ actor.start();
 
 const disconnect = connectRouter({ actor, router, routeMap });
 
-// Cleanup (e.g. on page unload)
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnect();
 	router.destroy();
-});
+}
 ```
 
 ## API
@@ -150,17 +143,17 @@ history.destroy();
 
 **`BrowserHistory` interface:**
 
-| Method                  | Description                                                                                              |
-| ----------------------- | -------------------------------------------------------------------------------------------------------- |
-| `location`              | Read-only `{ pathname, search, hash, state }`                                                            |
-| `push(path, state?)`    | Push a new entry to history                                                                              |
-| `replace(path, state?)` | Replace the current history entry                                                                        |
-| `go(delta)`             | Navigate relative to current position                                                                    |
-| `back()`                | Navigate backward                                                                                        |
-| `forward()`             | Navigate forward                                                                                         |
-| `subscribe(listener)`   | Subscribe to location changes — returns an unsubscribe function, a `Cleanup` from `createBrowserHistory` |
-| `createHref(path)`      | Create an href from a path                                                                               |
-| `destroy()`             | Cleans up. It removes the listeners, and it restores the patched methods when it is the last wrapper     |
+| Method                  | Description                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `location`              | Read-only `{ pathname, search, hash, state }`                                                        |
+| `push(path, state?)`    | Push a new entry to history                                                                          |
+| `replace(path, state?)` | Replace the current history entry                                                                    |
+| `go(delta)`             | Navigate relative to current position                                                                |
+| `back()`                | Navigate backward                                                                                    |
+| `forward()`             | Navigate forward                                                                                     |
+| `subscribe(listener)`   | Subscribe to location changes — returns an unsubscribe function                                      |
+| `createHref(path)`      | Create an href from a path                                                                           |
+| `destroy()`             | Cleans up. It removes the listeners, and it restores the patched methods when it is the last wrapper |
 
 **`BrowserWindow` interface:**
 
@@ -178,14 +171,16 @@ const router = createRouter({ routeTree, history });
 // router.destroy() — calls history.destroy()
 ```
 
-Or let a scope release it, which also releases the history on an exception:
+Or let a scope release it, which also releases the history on an exception. Publish the router with `asDisposable` of [`@xmachines/core/utils`](../core/README.md), and name `destroy` as the release:
 
 ```typescript
-using router = createRouter({ routeTree, history });
+import { asDisposable } from "@xmachines/core/utils";
+
+const plain = createRouter({ routeTree, history });
+using router = asDisposable(plain, () => plain.destroy());
 ```
 
-The dispose key and `destroy()` run the same body, and the release is idempotent, so a
-caller that keeps `destroy()` keeps it.
+`destroy()` is idempotent, so a caller that calls it before the scope ends is safe.
 
 **The release covers the history alone.** `connectRouter` hands back its own
 `RouterConnection`, and a scope that ends releases no connection for you. Release the
@@ -278,7 +273,7 @@ Browser URL
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](../../../LICENSE).
 
 ## Classes
 
@@ -300,17 +295,8 @@ MIT — see [LICENSE](LICENSE).
 - [RouterConnection](interfaces/RouterConnection.md)
 - [VanillaRouter](interfaces/VanillaRouter.md)
 
-## Type Aliases
-
-- [Cleanup](type-aliases/Cleanup.md)
-
-## Variables
-
-- [DISPOSE](variables/DISPOSE.md)
-
 ## Functions
 
-- [asCleanup](functions/asCleanup.md)
 - [connectRouter](functions/connectRouter.md)
 - [createBrowserHistory](functions/createBrowserHistory.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/v5.0.1/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/v6.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.
@@ -42,16 +42,16 @@ new DomRouterBridge(
 ): DomRouterBridge;
 ```
 
-Defined in: [play-dom-router/src/dom-router-bridge.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/dom-router-bridge.ts#L40)
+Defined in: [play-dom-router/src/dom-router-bridge.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.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 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?` | [`RouterBridgeOptions`](../../play-router/index/interfaces/RouterBridgeOptions.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()` beside the three. The README of this package shows the shape. |
+| `options?` | [`RouterBridgeOptions`](../../play-router/index/interfaces/RouterBridgeOptions.md) | -                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 #### Returns
 
@@ -71,7 +71,7 @@ Defined in: [play-dom-router/src/dom-router-bridge.ts:40](https://gitlab.com/xma
 get basePath(): string;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/router-bridge-base.ts#L282)
+Defined in: [play-router/src/router-bridge-base.ts:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.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.
@@ -96,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:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/router-bridge-base.ts#L311)
+Defined in: [play-router/src/router-bridge-base.ts:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.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.
@@ -147,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:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/router-bridge-base.ts#L533)
+Defined in: [play-router/src/router-bridge-base.ts:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L533)
 
 Connects the router bridge to the Actor.
 
@@ -181,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:791](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/router-bridge-base.ts#L791)
+Defined in: [play-router/src/router-bridge-base.ts:791](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L791)
 
 Disconnects the router bridge from the Actor.
 
@@ -204,7 +204,7 @@ framework.
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/router-bridge-base.ts#L351)
+Defined in: [play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/router-bridge-base.ts#L351)
 
 Moves the machine to a different mount point, while it stays connected.
 

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

@@ -2,7 +2,7 @@
 
 # Class: RouteMap
 
-Defined in: [play-router/src/base-route-map.ts:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/base-route-map.ts#L177)
+Defined in: [play-router/src/base-route-map.ts:176](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L176)
 
 The shared base class of the route map for both directions.
 
@@ -15,8 +15,7 @@ of its own, and it inherits the complete public API from here.
 - 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 cache
-  holds between 500 and 1000 entries, and the `pathCache` constructor option
-  replaces it
+  holds 1001 entries at most, and the `pathCache` constructor option replaces it
 
 **The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
 often are:
@@ -65,7 +64,7 @@ map.getPathByStateId("missing"); // null
 new RouteMap(mappings, options?): RouteMap;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/base-route-map.ts#L210)
+Defined in: [play-router/src/base-route-map.ts:209](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L209)
 
 Builds a route map from an array of the mappings between a state ID and a path.
 
@@ -93,7 +92,7 @@ candidates is therefore efficient.
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/base-route-map.ts#L324)
+Defined in: [play-router/src/base-route-map.ts:322](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L322)
 
 Returns the path pattern of a state ID.
 
@@ -129,7 +128,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:279](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-router/src/base-route-map.ts#L279)
+Defined in: [play-router/src/base-route-map.ts:277](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-router/src/base-route-map.ts#L277)
 
 Resolves a URL path to its state ID.
 

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:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/connect-router.ts#L64)
+Defined in: [play-dom-router/src/connect-router.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/connect-router.ts#L64)
 
 Connects the vanilla router to an actor. This is a pure browser integration.
 

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

@@ -6,7 +6,7 @@
 function createBrowserHistory(options): BrowserHistory;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:172](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L172)
+Defined in: [play-dom-router/src/create-browser-history.ts:137](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L137)
 
 Creates a browser history that wraps window.history
 
@@ -36,10 +36,12 @@ unsubscribe();
 history.destroy();
 ```
 
-Or let a scope do it, which releases the history on an exception too:
+Or let a scope do it, which releases the history on an exception too. Publish the
+history with `asDisposable` of `@xmachines/core/utils`, and name `destroy` as the release:
 
 ```typescript
-using history = createBrowserHistory({ window });
+const plain = createBrowserHistory({ window });
+using history = asDisposable(plain, () => plain.destroy());
 ```
 
 `destroy()` is idempotent, and it cooperates with each other wrapper of the same

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

@@ -6,7 +6,7 @@
 function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-router.ts#L80)
+Defined in: [play-dom-router/src/create-router.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-router.ts#L79)
 
 Creates the vanilla router for a framework-agnostic routing.
 
@@ -41,10 +41,12 @@ disconnect();
 router.destroy();
 ```
 
-Or let a scope do it, which releases the history on an exception too:
+Or let a scope do it, which releases the history on an exception too. Publish the
+router with `asDisposable` of `@xmachines/core/utils`:
 
 ```typescript
-using router = createRouter({ routeTree, history });
+const plain = createRouter({ routeTree, history });
+using router = asDisposable(plain, () => plain.destroy());
 ```
 
 ## Parameters

package/api/@xmachines/play-dom-router/interfaces/BasePathOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: BasePathOptions
 
-Defined in: [play-url/src/base-path.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-url/src/base-path.ts#L48)
+Defined in: [play-url/src/base-path.ts:49](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-url/src/base-path.ts#L49)
 
 The base-path options that every router bridge, `connectRouter` function, and
 `PlayRouterProvider` component accepts.
@@ -24,5 +24,5 @@ connectRouter({
 
 | Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Defined in                                                                                                                      |
 | ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](ConnectRouterOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [play-url/src/base-path.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-url/src/base-path.ts#L62) |
-| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](ConnectRouterOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [play-url/src/base-path.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-url/src/base-path.ts#L76) |
+| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](ConnectRouterOptions.md#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [play-url/src/base-path.ts:63](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-url/src/base-path.ts#L63) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](ConnectRouterOptions.md#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [play-url/src/base-path.ts:77](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-url/src/base-path.ts#L77) |

package/api/@xmachines/play-dom-router/interfaces/BrowserHistory.md

@@ -2,63 +2,27 @@
 
 # Interface: BrowserHistory
 
-Defined in: [play-dom-router/src/create-browser-history.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L3)
+Defined in: [play-dom-router/src/create-browser-history.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L1)
 
 ## Properties
 
-| Property                                  | Modifier   | Type      | Description                               | Defined in                                                                                                                                                              |
-| ----------------------------------------- | ---------- | --------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-location"></a> `location` | `readonly` | `object`  | Returns the state of the current location | [play-dom-router/src/create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L7)   |
-| `location.hash`                           | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L10) |
-| `location.pathname`                       | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L8)   |
-| `location.search`                         | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L9)   |
-| `location.state`                          | `public`   | `unknown` | -                                         | [play-dom-router/src/create-browser-history.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L11) |
+| Property                                  | Modifier   | Type      | Description                               | Defined in                                                                                                                                                            |
+| ----------------------------------------- | ---------- | --------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-location"></a> `location` | `readonly` | `object`  | Returns the state of the current location | [play-dom-router/src/create-browser-history.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L5) |
+| `location.hash`                           | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L8) |
+| `location.pathname`                       | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L6) |
+| `location.search`                         | `public`   | `string`  | -                                         | [play-dom-router/src/create-browser-history.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L7) |
+| `location.state`                          | `public`   | `unknown` | -                                         | [play-dom-router/src/create-browser-history.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L9) |
 
 ## Methods
 
-### \[dispose\]()
-
-```ts
-dispose: void;
-```
-
-Defined in: [play-dom-router/src/create-browser-history.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L91)
-
-Releases the history with [BrowserHistory.destroy](#destroy). It is idempotent.
-
-`destroy()` unpatches `history.pushState` and `history.replaceState` of the window,
-so a scope that drops the history without it leaves the global patched. The key lets
-a scope do that work:
-
-```ts
-{
-	using history = createBrowserHistory({ window });
-	history.push("/first");
-	// destroy() runs at the end of the scope, and after an exception too
-}
-```
-
-An implementation writes it as one line beside `destroy`, and the two therefore
-release the same work:
-
-```ts
-destroy() { ... },
-[DISPOSE]() { this.destroy(); },
-```
-
-#### Returns
-
-`void`
-
----
-
 ### back()
 
 ```ts
 back(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L28)
+Defined in: [play-dom-router/src/create-browser-history.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L26)
 
 #### Returns
 
@@ -72,7 +36,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:28](https://gitlab.co
 createHref(path): string;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L58)
+Defined in: [play-dom-router/src/create-browser-history.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L46)
 
 Creates an href from a path
 
@@ -94,7 +58,7 @@ Creates an href from a path
 destroy(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L66)
+Defined in: [play-dom-router/src/create-browser-history.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L54)
 
 Cleans up.
 
@@ -113,7 +77,7 @@ A second call is safe. When more than one wrapper shares the same
 forward(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L29)
+Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L27)
 
 #### Returns
 
@@ -127,7 +91,7 @@ Defined in: [play-dom-router/src/create-browser-history.ts:29](https://gitlab.co
 go(delta): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L27)
+Defined in: [play-dom-router/src/create-browser-history.ts:25](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L25)
 
 Moves back or forward in the history
 
@@ -149,7 +113,7 @@ Moves back or forward in the history
 push(path, state?): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L17)
+Defined in: [play-dom-router/src/create-browser-history.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L15)
 
 Pushes a new URL to the history
 
@@ -172,7 +136,7 @@ Pushes a new URL to the history
 replace(path, state?): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L22)
+Defined in: [play-dom-router/src/create-browser-history.ts:20](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L20)
 
 Replaces the current URL in the history
 
@@ -192,32 +156,22 @@ Replaces the current URL in the history
 ### subscribe()
 
 ```ts
-subscribe(listener): Cleanup;
+subscribe(listener): () => void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom-router/src/create-browser-history.ts#L53)
+Defined in: [play-dom-router/src/create-browser-history.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom-router/src/create-browser-history.ts#L41)
 
 Subscribes to the history changes.
 It returns the release of the subscription.
 
-A caller runs the release, or a scope releases it:
+The release is a plain function. A caller runs it, or it publishes the release with
+`asDisposable` of `@xmachines/core/utils`, and a scope releases it:
 
 ```ts
-using stop = history.subscribe((location) => render(location));
+using stop = asDisposable(history.subscribe((location) => render(location)));
 // stop() runs at the end of the scope, and after an exception too
 ```
 
-A `Cleanup` IS a `() => void`, so a caller that runs it keeps that code. An
-implementation of this interface builds one with `asCleanup` of `@xmachines/play`,
-which this package re-exports:
-
-```ts
-subscribe(listener) {
-  listeners.add(listener);
-  return asCleanup(() => listeners.delete(listener));
-}
-```
-
 #### Parameters
 
 | Parameter  | Type                   |
@@ -226,4 +180,4 @@ subscribe(listener) {
 
 #### Returns
 
-[`Cleanup`](../type-aliases/Cleanup.md)
+() => `void`