@xmachines/docs 3.0.0 → 5.0.0

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/v5.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/v5.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?` | [`RouterBridgeOptions`](../../play-router/index/interfaces/RouterBridgeOptions.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:282](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L282)
 
 The resolved URL prefix that the machine of this bridge is mounted under, or `""`
 when the machine owns the complete router.
@@ -83,7 +84,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePath`](../../play-router/classes/RouterBridgeBase.md#basepath)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`basePath`](../../play-router/index/classes/RouterBridgeBase.md#basepath)
 
 ---
 
@@ -95,7 +96,7 @@ The resolved URL prefix of the mount, or `""` when the machine owns the complete
 get basePathParams(): Readonly<Record<string, string>>;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:284](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L284)
+Defined in: [play-router/src/router-bridge-base.ts:311](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L311)
 
 The resolved values of the `:param` segments of the mount, or `{}` for a prefix
 without a param.
@@ -136,7 +137,7 @@ mount while the machine stays on the same route, and no event goes out.
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/classes/RouterBridgeBase.md#basepathparams)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`basePathParams`](../../play-router/index/classes/RouterBridgeBase.md#basepathparams)
 
 ## Methods
 
@@ -146,11 +147,11 @@ mount while the machine stays on the same route, and no event goes out.
 connect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:506](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L506)
+Defined in: [play-router/src/router-bridge-base.ts:533](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L533)
 
 Connects the router bridge to the Actor.
 
-The method installs the TC39 Signal watcher of the direction from the actor to the
+The method installs the atom watcher of the direction from the actor to the
 router. It then starts the watch of the router changes, which each framework does
 in its own way.
 
@@ -170,7 +171,7 @@ An adapter that needs a different behavior of the first synchronization override
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`connect`](../../play-router/classes/RouterBridgeBase.md#connect)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`connect`](../../play-router/index/classes/RouterBridgeBase.md#connect)
 
 ---
 
@@ -180,11 +181,11 @@ An adapter that needs a different behavior of the first synchronization override
 disconnect(): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:728](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L728)
+Defined in: [play-router/src/router-bridge-base.ts:791](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L791)
 
 Disconnects the router bridge from the Actor.
 
-The method stops the watch of the signal, and it removes the router listener of the
+The method stops the watch of the atom, and it removes the router listener of the
 framework.
 
 #### Returns
@@ -193,7 +194,7 @@ framework.
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/classes/RouterBridgeBase.md#disconnect)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`disconnect`](../../play-router/index/classes/RouterBridgeBase.md#disconnect)
 
 ---
 
@@ -203,7 +204,7 @@ framework.
 setBasePath(basePath?, basePathParams?): void;
 ```
 
-Defined in: [play-router/src/router-bridge-base.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L324)
+Defined in: [play-router/src/router-bridge-base.ts:351](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/router-bridge-base.ts#L351)
 
 Moves the machine to a different mount point, while it stays connected.
 
@@ -255,4 +256,4 @@ bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });
 
 #### Inherited from
 
-[`RouterBridgeBase`](../../play-router/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/classes/RouterBridgeBase.md#setbasepath)
+[`RouterBridgeBase`](../../play-router/index/classes/RouterBridgeBase.md).[`setBasePath`](../../play-router/index/classes/RouterBridgeBase.md#setbasepath)

package/api/@xmachines/play-dom-router/{interfaces → classes}/RouteMap.md

@@ -1,8 +1,8 @@
 [API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / RouteMap
 
-# Interface: 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:177](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L177)
 
 The shared base class of the route map for both directions.
 
@@ -14,15 +14,22 @@ of its own, and it inherits the complete public API from here.
 - A static path, without a `:param` → a `Map` lookup in O(1)
 - A dynamic path → a scan of the bucket index in O(k), with `URLPattern`, where
   `k` is the number of the routes with the same first path segment
-- The class keeps each result of a first match in an LRU cache. The default size
-  is 500 entries, and the `cacheSize` constructor option changes it
+- The class keeps each result of a first match in an LRU cache. The default cache
+  holds between 500 and 1000 entries, and the `pathCache` constructor option
+  replaces it
 
-**The syntax of a pattern** (`:param`, `:param?`, and `*`):
+**The syntax of a pattern:** the whole URLPattern pathname grammar. The forms used most
+often are:
 
 - `:param` — a necessary segment. It matches exactly one segment without a `/`
 - `:param?` — an optional segment. It matches zero segments or one segment without a `/`
 - `*` — a wildcard. It matches each number of segments, as URLPattern defines
 
+A `{…}` group, a `:param(\d+)` constraint, a `+` modifier and a `\:` escape are read
+too. The [routing guide](../../../../guides/routing.md) states every form, the prefix
+rule, and the one divergence from the standard: a param name of this library can hold a
+hyphen.
+
 **The forms of a stateId:** you can register a stateId, and you can look one up,
 in the form `"#stateId"` or in the form `"stateId"`. `RouteMap` makes the
 canonical form itself. `getStateIdByPath` returns the stateId exactly as you
@@ -50,6 +57,34 @@ map.getPathByStateId("profile"); // "/profile/:userId"
 map.getPathByStateId("missing"); // null
 ```
 
+## Constructors
+
+### Constructor
+
+```ts
+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.0/packages/play-router/src/base-route-map.ts#L210)
+
+Builds a route map from an array of the mappings between a state ID and a path.
+
+The constructor puts each static path, which holds no `:param`, into a `Map` for a
+lookup in O(1). It compiles each parameterized path to a `URLPattern`, and it
+groups the patterns into the buckets of the first segment. The selection of the
+candidates is therefore efficient.
+
+#### Parameters
+
+| Parameter  | Type                                                  | Description                                                                                                                                               |
+| ---------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mappings` | [`RouteMapping`](../interfaces/RouteMapping.md)[]     | The array of the `{ stateId, path }` entries. The order gives the priority when more than one pattern can match the same path.                            |
+| `options`  | [`RouteMapOptions`](../interfaces/RouteMapOptions.md) | See [RouteMapOptions](../interfaces/RouteMapOptions.md). A map holds TWO caches, so no option is named `cache`: each one names the cache that it carries. |
+
+#### Returns
+
+`RouteMap`
+
 ## Methods
 
 ### getPathByStateId()
@@ -58,7 +93,7 @@ map.getPathByStateId("missing"); // null
 getPathByStateId(stateId): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:229](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L229)
+Defined in: [play-router/src/base-route-map.ts:324](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L324)
 
 Returns the path pattern of a state ID.
 
@@ -94,7 +129,7 @@ map.getPathByStateId("missing"); // null
 getStateIdByPath(path): string | null;
 ```
 
-Defined in: [play-router/src/base-route-map.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-route-map.ts#L189)
+Defined in: [play-router/src/base-route-map.ts:279](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-router/src/base-route-map.ts#L279)
 
 Resolves a URL path to its state ID.
 

package/api/@xmachines/{play → play-dom-router}/functions/asCleanup.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / asCleanup
+[API](../../../README.md) / [@xmachines/play-dom-router](../README.md) / asCleanup
 
 # Function: asCleanup()
 
@@ -6,7 +6,7 @@
 function asCleanup<R>(release): Cleanup;
 ```
 
-Defined in: [packages/play/src/disposable.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L150)
+Defined in: [play/src/disposable.ts:149](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/disposable.ts#L149)
 
 Makes one release function serve as a [Cleanup](../type-aliases/Cleanup.md).
 
@@ -70,9 +70,8 @@ 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));
+export function watchAtom<T>(atom: Readable<T>, onValue: (v: T) => void): Cleanup {
+	const subscription = atom.subscribe(() => onValue(atom.get()));
+	return asCleanup(() => subscription.unsubscribe());
 }
 ```

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/v5.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/v5.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)

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

@@ -3,10 +3,10 @@
 # Function: createRouter()
 
 ```ts
-function createRouter<History>(options): DisposableVanillaRouter<History>;
+function createRouter(options): VanillaRouter;
 ```
 
-Defined in: [play-dom-router/src/create-router.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-router.ts#L101)
+Defined in: [play-dom-router/src/create-router.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-router.ts#L80)
 
 Creates the vanilla router for a framework-agnostic routing.
 
@@ -47,20 +47,14 @@ Or let a scope do it, which releases the history on an exception too:
 using router = createRouter({ routeTree, history });
 ```
 
-## Type Parameters
-
-| Type Parameter                                                          |
-| ----------------------------------------------------------------------- |
-| `History` _extends_ [`BrowserHistory`](../interfaces/BrowserHistory.md) |
-
 ## Parameters
 
-| Parameter           | Type                                                                                               |
-| ------------------- | -------------------------------------------------------------------------------------------------- |
-| `options`           | \{ `history`: `History`; `routeTree`: [`RouteTree`](../../play-router/interfaces/RouteTree.md); \} |
-| `options.history`   | `History`                                                                                          |
-| `options.routeTree` | [`RouteTree`](../../play-router/interfaces/RouteTree.md)                                           |
+| Parameter           | Type                                                                                                                                               |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`           | \{ `history`: [`BrowserHistory`](../interfaces/BrowserHistory.md); `routeTree`: [`RouteTree`](../../play-router/index/interfaces/RouteTree.md); \} |
+| `options.history`   | [`BrowserHistory`](../interfaces/BrowserHistory.md)                                                                                                |
+| `options.routeTree` | [`RouteTree`](../../play-router/index/interfaces/RouteTree.md)                                                                                     |
 
 ## Returns
 
-[`DisposableVanillaRouter`](../interfaces/DisposableVanillaRouter.md)\<`History`\>
+[`VanillaRouter`](../interfaces/VanillaRouter.md)

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

@@ -2,7 +2,7 @@
 
 # Interface: BasePathOptions
 
-Defined in: [play-router/src/base-path.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L44)
+Defined in: [play-url/src/base-path.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-url/src/base-path.ts#L48)
 
 The base-path options that every router bridge, `connectRouter` function, and
 `PlayRouterProvider` component accepts.
@@ -20,13 +20,9 @@ connectRouter({
 });
 ```
 
-## Extended by
-
-- [`ConnectRouterOptions`](ConnectRouterOptions.md)
-
 ## Properties
 
-| 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-router/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L58) |
-| <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-router/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L72) |
+| 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.0/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.0/packages/play-url/src/base-path.ts#L76) |

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

@@ -2,31 +2,63 @@
 
 # Interface: BrowserHistory
 
-Defined in: [play-dom-router/src/create-browser-history.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L3)
-
-## Extended by
-
-- [`DisposableBrowserHistory`](DisposableBrowserHistory.md)
+Defined in: [play-dom-router/src/create-browser-history.ts:3](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L3)
 
 ## 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/v3.0.0/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/v3.0.0/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/v3.0.0/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/v3.0.0/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/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L11) |
+| <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.0/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.0/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.0/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.0/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.0/packages/play-dom-router/src/create-browser-history.ts#L11) |
 
 ## 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.0/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/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L28)
+Defined in: [play-dom-router/src/create-browser-history.ts:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L28)
 
 #### Returns
 
@@ -40,7 +72,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:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L46)
+Defined in: [play-dom-router/src/create-browser-history.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L58)
 
 Creates an href from a path
 
@@ -62,7 +94,7 @@ Creates an href from a path
 destroy(): void;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L54)
+Defined in: [play-dom-router/src/create-browser-history.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L66)
 
 Cleans up.
 
@@ -81,7 +113,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/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L29)
+Defined in: [play-dom-router/src/create-browser-history.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L29)
 
 #### Returns
 
@@ -95,7 +127,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/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L27)
+Defined in: [play-dom-router/src/create-browser-history.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L27)
 
 Moves back or forward in the history
 
@@ -117,7 +149,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/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L17)
+Defined in: [play-dom-router/src/create-browser-history.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L17)
 
 Pushes a new URL to the history
 
@@ -140,7 +172,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/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L22)
+Defined in: [play-dom-router/src/create-browser-history.ts:22](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L22)
 
 Replaces the current URL in the history
 
@@ -160,19 +192,31 @@ Replaces the current URL in the history
 ### subscribe()
 
 ```ts
-subscribe(listener): () => void;
+subscribe(listener): Cleanup;
 ```
 
-Defined in: [play-dom-router/src/create-browser-history.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-dom-router/src/create-browser-history.ts#L41)
+Defined in: [play-dom-router/src/create-browser-history.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-dom-router/src/create-browser-history.ts#L53)
 
 Subscribes to the history changes.
-It returns a function that cancels the subscription.
+It returns the release of the subscription.
 
-The return is a plain function here, because a consumer IMPLEMENTS this interface
-to inject its own history for a test or for SSR. A `Cleanup` return would refuse
-every implementation that hands a plain function back.
-[DisposableBrowserHistory](DisposableBrowserHistory.md) narrows it for the value that
-[createBrowserHistory](../functions/createBrowserHistory.md) builds, which nothing implements.
+A caller runs the release, or a scope releases it:
+
+```ts
+using stop = 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
 
@@ -182,4 +226,4 @@ every implementation that hands a plain function back.
 
 #### Returns
 
-() => `void`
+[`Cleanup`](../type-aliases/Cleanup.md)