@xmachines/docs 2.1.1 → 3.0.0

package/api/@xmachines/play-router/interfaces/RouteTree.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteTree
 
-Defined in: [types.ts:122](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L122)
+Defined in: [play-router/src/types.ts:123](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L123)
 
 The complete route tree, with its lookup maps
 
@@ -13,9 +13,9 @@ It gives you the map between a state ID and a URL path, in both directions:
 
 ## Properties
 
-| Property                                    | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                      |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a complete path to its route node. It gives you the state ID of a URL path, for the target of a play.route event                                                                                                                                                                                                                                                                       | [types.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L134) |
-| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a state ID to its route node. It gives you the URL path of a state ID, for the update of the browser URL                                                                                                                                                                                                                                                                               | [types.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L129) |
-| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | The graph of the state machine, for an advanced query. extractMachineRoutes() fills it. Use it for a query of the hierarchy, for a test of the reachability, and for a navigation that knows the transitions, through the algorithms of @statelyai/graph. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [types.ts:147](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L147) |
-| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | The root node of the routes                                                                                                                                                                                                                                                                                                                                                                         | [types.ts:124](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L124) |
+| Property                                    | Type                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                         | Defined in                                                                                                                      |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-bypath"></a> `byPath`       | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a complete path to its route node. It gives you the state ID of a URL path, for the target of a play.route event                                                                                                                                                                                                                                                                       | [play-router/src/types.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L135) |
+| <a id="property-bystateid"></a> `byStateId` | `Map`\<`string`, [`RouteNode`](RouteNode.md)\>                                                            | The map from a state ID to its route node. It gives you the URL path of a state ID, for the update of the browser URL                                                                                                                                                                                                                                                                               | [play-router/src/types.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L130) |
+| <a id="property-graph"></a> `graph?`        | `Graph`\<[`MachineNodeData`](MachineNodeData.md), [`MachineEdgeData`](MachineEdgeData.md), `any`, `any`\> | The graph of the state machine, for an advanced query. extractMachineRoutes() fills it. Use it for a query of the hierarchy, for a test of the reachability, and for a navigation that knows the transitions, through the algorithms of @statelyai/graph. **Example** `import { getSuccessors, hasPath } from "@statelyai/graph"; const successors = getSuccessors(tree.graph!, "myMachine.home");` | [play-router/src/types.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L148) |
+| <a id="property-root"></a> `root`           | [`RouteNode`](RouteNode.md)                                                                               | The root node of the routes                                                                                                                                                                                                                                                                                                                                                                         | [play-router/src/types.ts:125](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L125) |

package/api/@xmachines/play-router/interfaces/RouteWatcherHandle.md

@@ -2,7 +2,7 @@
 
 # Interface: RouteWatcherHandle
 
-Defined in: [router-bridge-base.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L72)
+Defined in: [play-router/src/router-bridge-base.ts:79](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L79)
 
 The narrow interface of the TC39 Signal watcher. `RouterBridgeBase` uses it to
 observe each change of `actor.currentRoute`.
@@ -24,7 +24,7 @@ it and manages it internally.
 unwatch(): void;
 ```
 
-Defined in: [router-bridge-base.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L76)
+Defined in: [play-router/src/router-bridge-base.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L83)
 
 Stops the observation and frees the watcher.
 
@@ -40,7 +40,7 @@ Stops the observation and frees the watcher.
 watch(signal): void;
 ```
 
-Defined in: [router-bridge-base.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/router-bridge-base.ts#L74)
+Defined in: [play-router/src/router-bridge-base.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/router-bridge-base.ts#L81)
 
 Arms the watcher on the given signal.
 

package/api/@xmachines/play-router/interfaces/RouterBridge.md

@@ -2,7 +2,7 @@
 
 # Interface: RouterBridge
 
-Defined in: [types.ts:358](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L358)
+Defined in: [play-router/src/types.ts:359](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L359)
 
 The RouterBridge interface of a runtime infrastructure adapter
 
@@ -48,6 +48,10 @@ class MyRouterBridge implements RouterBridge {
 
 [Play RFC](../../../../rfc/play.md) - invariant INV-04
 
+## Extended by
+
+- [`MountableRouterBridge`](MountableRouterBridge.md)
+
 ## Methods
 
 ### connect()
@@ -56,7 +60,7 @@ class MyRouterBridge implements RouterBridge {
 connect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:375](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L375)
+Defined in: [play-router/src/types.ts:376](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L376)
 
 Connects the router bridge to the Actor
 
@@ -86,7 +90,7 @@ await bridge.connect();
 disconnect(): void | Promise<void>;
 ```
 
-Defined in: [types.ts:391](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L391)
+Defined in: [play-router/src/types.ts:392](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L392)
 
 Disconnects the router bridge from the Actor
 

package/api/@xmachines/play-router/interfaces/RouterConnection.md

@@ -0,0 +1,105 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / RouterConnection
+
+# Interface: RouterConnection()
+
+Defined in: [play-router/src/provider-lifecycle.ts:265](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L265)
+
+What `connectRouter` of an adapter returns.
+
+The value is CALLABLE, so `const disconnect = connectRouter(…); disconnect();` keeps
+working exactly as it did. It also carries the mount API, because a host that gives a
+`basePath` needs the two things [MountableRouterBridge](MountableRouterBridge.md) promises: the resolved
+mount to read back, and a way to move it. The bridge itself lives inside
+`connectRouter`, so without this handle a host had to rebuild the actor and the bridge
+to move a mount — which throws away the LRU cache of the route map, the very thing
+`setBasePath` exists to keep.
+
+`basePath` and `basePathParams` are GETTERS on the live bridge, so they cannot go
+stale.
+
+```ts
+RouterConnection(): void;
+```
+
+Defined in: [play-router/src/provider-lifecycle.ts:267](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L267)
+
+Stops the synchronization. The same call as [RouterConnection.disconnect](#disconnect).
+
+## Returns
+
+`void`
+
+## Properties
+
+| Property                                              | Modifier   | Type                                         | Description                                                                       | Defined in                                                                                                                                                |
+| ----------------------------------------------------- | ---------- | -------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath`             | `readonly` | `string`                                     | The resolved prefix of the mount, or `""` when the machine owns the whole router. | [play-router/src/provider-lifecycle.ts:288](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L288) |
+| <a id="property-basepathparams"></a> `basePathParams` | `readonly` | `Readonly`\<`Record`\<`string`, `string`\>\> | The values of the `:param` segments of the mount. They travel in no event.        | [play-router/src/provider-lifecycle.ts:290](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L290) |
+
+## Methods
+
+### \[dispose\]()
+
+```ts
+dispose: void;
+```
+
+Defined in: [play-router/src/provider-lifecycle.ts:286](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L286)
+
+Stops the synchronization when the scope of a `using` declaration ends.
+
+This value IS the release of `connectRouter`, and all eight router adapters return
+it, so it carries the protocol of `@xmachines/play` like every other release of the
+ecosystem:
+
+```ts
+{
+	using connection = connectRouter({ actor, router, routeMap });
+	// disconnect() runs at the end of the scope, and after an exception too
+}
+```
+
+The release is [RouterConnection.disconnect](#disconnect), which is idempotent.
+
+#### Returns
+
+`void`
+
+---
+
+### disconnect()
+
+```ts
+disconnect(): void;
+```
+
+Defined in: [play-router/src/provider-lifecycle.ts:269](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L269)
+
+Stops the synchronization.
+
+#### Returns
+
+`void`
+
+---
+
+### setBasePath()
+
+```ts
+setBasePath(basePath?, basePathParams?): void;
+```
+
+Defined in: [play-router/src/provider-lifecycle.ts:292](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L292)
+
+Moves the mount of the live bridge, with no teardown.
+
+#### Parameters
+
+| Parameter         | Type                                       |
+| ----------------- | ------------------------------------------ |
+| `basePath?`       | `string`                                   |
+| `basePathParams?` | `Record`\<`string`, `string` \| `number`\> |
+
+#### Returns
+
+`void`

package/api/@xmachines/play-router/interfaces/WindowLike.md

@@ -2,7 +2,7 @@
 
 # Interface: WindowLike
 
-Defined in: [types.ts:412](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L412)
+Defined in: [play-router/src/types.ts:460](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L460)
 
 The minimal window interface of an adapter that subscribes to a DOM event, for
 example to `hashchange`. You can inject it for SSR and for a test: give a mock in
@@ -30,7 +30,7 @@ connectRouter({ actor, routeMap, window: mockWin });
 addEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L413)
+Defined in: [play-router/src/types.ts:461](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L461)
 
 #### Parameters
 
@@ -51,7 +51,7 @@ Defined in: [types.ts:413](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.
 removeEventListener(type, listener): void;
 ```
 
-Defined in: [types.ts:414](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L414)
+Defined in: [play-router/src/types.ts:462](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L462)
 
 #### Parameters
 

package/api/@xmachines/play-router/type-aliases/BaseRouteMapping.md

@@ -6,7 +6,7 @@
 type BaseRouteMapping = RouteMapping;
 ```
 
-Defined in: [index.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/index.ts#L61)
+Defined in: [play-router/src/index.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/index.ts#L103)
 
 ## Deprecated
 

package/api/@xmachines/play-router/type-aliases/MachineGraph.md

@@ -6,7 +6,7 @@
 type MachineGraph = Graph<MachineNodeData, MachineEdgeData>;
 ```
 
-Defined in: [machine-to-graph.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/machine-to-graph.ts#L19)
+Defined in: [play-router/src/machine-to-graph.ts:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/machine-to-graph.ts#L19)
 
 The typed Graph of @statelyai/graph that represents a state machine.
 It gives you the queries of the hierarchy, the algorithms of a walk, and the tests

package/api/@xmachines/play-router/type-aliases/PlayRouterBridgeConstructor.md

@@ -0,0 +1,36 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / PlayRouterBridgeConstructor
+
+# Type Alias: PlayRouterBridgeConstructor\<TRouter\>
+
+```ts
+type PlayRouterBridgeConstructor<TRouter> = (router, actor, routeMap, options?) => RouterBridge;
+```
+
+Defined in: [play-router/src/provider-lifecycle.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/provider-lifecycle.ts#L103)
+
+The constructor shape that a bridge class must satisfy for a provider factory: `(router, actor, routeMap, options?) → RouterBridge`.
+
+The return type is `RouterBridge`, the published contract of a bridge, so a
+consumer bridge of its own keeps compiling. Every bridge on `RouterBridgeBase` also
+satisfies `MountableRouterBridge`, and the provider finds that mount API at run
+time: a bridge without it ignores `basePath`, exactly as it did before the option
+existed.
+
+## Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `TRouter`      |
+
+## Parameters
+
+| Parameter  | Type                                                  |
+| ---------- | ----------------------------------------------------- |
+| `router`   | `TRouter`                                             |
+| `actor`    | [`PlayActor`](../interfaces/PlayActor.md)             |
+| `routeMap` | [`RouteMap`](../classes/RouteMap.md)                  |
+| `options?` | [`BasePathOptions`](../interfaces/BasePathOptions.md) |
+
+## Returns
+
+[`RouterBridge`](../interfaces/RouterBridge.md)

package/api/@xmachines/play-router/type-aliases/RouteMetadata.md

@@ -6,6 +6,6 @@
 type RouteMetadata = string | RouteObject;
 ```
 
-Defined in: [types.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-router/src/types.ts#L55)
+Defined in: [play-router/src/types.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/types.ts#L56)
 
 The route metadata of the `meta.route` field of a state machine.

package/api/@xmachines/play-router/variables/DISPOSE.md

@@ -0,0 +1,34 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / DISPOSE
+
+# Variable: DISPOSE
+
+```ts
+const DISPOSE: DisposeKey;
+```
+
+Defined in: [play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L94)
+
+The key that a release is stored under.
+
+`Symbol.dispose` where the runtime has it, and `Symbol.for("Symbol.dispose")` where it
+does not. This is not a convenience — it is the difference between a `using` that
+releases and one that raises.
+
+A bundler that downlevels `using` for a target below Chrome 134 emits a helper that
+reads `object[Symbol.dispose || Symbol.for("Symbol.dispose")]`. A release stored under
+a bare `[Symbol.dispose]` lands on the string key `"undefined"` in that runtime,
+because the well-known symbol is absent and the computed key takes the value
+`undefined`. The helper then looks up the registered symbol, finds nothing, and throws
+`TypeError: Object is not disposable`. Storing under the same fallback closes the gap.
+
+The type assertion states what the fallback IS. `Symbol.for` returns a plain `symbol`,
+TypeScript declares `Symbol.dispose` as a `unique symbol`, and no expression produces
+a `unique symbol` other than the declaration itself.
+
+This binding resolves ONE time, when the module evaluates. [asCleanup](../../play/functions/asCleanup.md) therefore
+reads `Symbol.dispose` again at each call and stores the release under both keys, so a
+polyfill that installs the well-known symbol after this module evaluates still finds
+the release. A class or an object literal that writes `[DISPOSE]()` has no such second
+chance: it carries the key that existed when it was defined. Install an Explicit
+Resource Management polyfill before the first import of `@xmachines/play`, which is the
+ordinary contract of a polyfill.

package/api/@xmachines/play-router/variables/NO_BASE_PATH.md

@@ -0,0 +1,18 @@
+[API](../../../README.md) / [@xmachines/play-router](../README.md) / NO\_BASE\_PATH
+
+# Variable: NO\_BASE\_PATH
+
+```ts
+const NO_BASE_PATH: ResolvedBasePath;
+```
+
+Defined in: [play-router/src/base-path.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-router/src/base-path.ts#L102)
+
+The base path of a bridge that has no `basePath` option.
+
+The object is FROZEN, and both levels of it: [resolveBasePath](../functions/resolveBasePath.md) returns this
+exact instance for every bridge with no mount, and
+`RouterBridgeBase.basePathParams` hands its `params` to the caller.
+`Readonly<Record<string, string>>` is gone at run time, so without the freeze one
+write in consumer code would leak that key into every other unmounted bridge in
+the process.

package/api/@xmachines/play-signals/README.md

@@ -4,7 +4,7 @@
 
 TC39 Signals polyfill for XMachines. It gives the Play Architecture fine-grained reactive state primitives. The primitives propagate state without a glitch and without a subscription.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.1-blue)](https://www.npmjs.com/package/@xmachines/play-signals)
+[![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-signals)
 
 ## Installation
 
@@ -117,13 +117,14 @@ person.set({ name: "Alice", age: 30 });
 | Export                         | Kind      | Description                                                                                            |
 | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------ |
 | `Signal`                       | namespace | Full TC39 Signals namespace (`State`, `Computed`, `subtle.Watcher`) re-exported from `signal-polyfill` |
-| `watchSignal(signal, onValue)` | function  | The memory-safe subscription helper. It returns a cleanup function                                     |
+| `watchSignal(signal, onValue)` | function  | The memory-safe subscription helper. It returns a `Cleanup`                                            |
 | `SignalState<T>`               | interface | Shape of `Signal.State<T>` (`.get()`, `.set()`)                                                        |
 | `SignalComputed<T>`            | interface | Shape of `Signal.Computed<T>` (`.get()`)                                                               |
 | `SignalWatcher`                | interface | Shape of `Signal.subtle.Watcher` (`.watch()`, `.unwatch()`, `.getPending()`)                           |
 | `SignalOptions<T>`             | interface | The options object for the `Signal.State` constructor (`equals?`)                                      |
 | `ComputedOptions<T>`           | interface | The options object for the `Signal.Computed` constructor (`equals?`)                                   |
 | `WatcherNotify`                | type      | The callback signature of the `Signal.subtle.Watcher` notify function                                  |
+| `Cleanup`                      | type      | The release that `watchSignal` returns, re-exported from `@xmachines/play`                             |
 
 ## Testing
 
@@ -222,6 +223,7 @@ the code from a change of the Stage 1 API.
 
 ## Type Aliases
 
+- [Cleanup](type-aliases/Cleanup.md)
 - [WatcherNotify](type-aliases/WatcherNotify.md)
 
 ## Functions

package/api/@xmachines/play-signals/functions/watchSignal.md

@@ -3,10 +3,10 @@
 # Function: watchSignal()
 
 ```ts
-function watchSignal<T>(signal, onValue): () => void;
+function watchSignal<T>(signal, onValue): Cleanup;
 ```
 
-Defined in: [packages/play-signals/src/watch-signal.ts:21](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/watch-signal.ts#L21)
+Defined in: [packages/play-signals/src/watch-signal.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/watch-signal.ts#L45)
 
 Subscribes to one signal, with the canonical one-shot watcher lifecycle.
 
@@ -21,6 +21,29 @@ that is detached already.
   once when the cleanup runs before the microtask fires.
 - The `needsEnqueue` guard removes the duplicates of rapid synchronous signal
   changes: one batch of synchronous changes queues one microtask only.
+- The watcher arms again BEFORE the callback: a callback that THROWS keeps the watch, a
+  callback that RELEASES the watch leaves no watcher attached to the signal, and a
+  callback that WRITES the signal reaches the caller with the value that it wrote.
+- The watcher arms with NO argument: `watch(signal)` records the edge a second time on
+  every emission, so the edge list of the watcher and the consumer list of the signal
+  grow by one for each change, for the life of the watch.
+
+A CAUTION for a callback that writes the signal that it watches: the write reaches the
+callback, so a callback that writes a NEW value on every call runs again for ever, and
+the microtask queue drains never. That is the loop of the caller, and this function
+bounds it not — a bound here would drop the write of a caller that repairs its state
+one time, which is the case that the order above exists to serve. A caller that repairs
+from a failure must repair to a state that succeeds, or it must stop after one attempt.
+A write of the SAME value ends the sequence by itself, because a signal notifies for a
+value that it holds already never.
+
+The return is a [Cleanup](../type-aliases/Cleanup.md): a function, and a `Disposable`. A caller that keeps
+the release in a field and runs it from a teardown keeps that code. A caller inside one
+scope writes `using` and writes no teardown:
+
+```ts
+using stop = watchSignal(count, render);
+```
 
 ## Type Parameters
 
@@ -37,6 +60,6 @@ that is detached already.
 
 ## Returns
 
-The cleanup function. It removes the watcher.
+[`Cleanup`](../type-aliases/Cleanup.md)
 
-() => `void`
+The release. It removes the watcher.

package/api/@xmachines/play-signals/interfaces/ComputedOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: ComputedOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L85)
+Defined in: [packages/play-signals/src/types.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L85)
 
 The options of a Signal.Computed
 
@@ -33,4 +33,4 @@ const options: ComputedOptions<string> = {
 
 | Property                               | Type                    | Description                                            | Defined in                                                                                                                               |
 | -------------------------------------- | ----------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own, for the memoization | [packages/play-signals/src/types.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L89) |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own, for the memoization | [packages/play-signals/src/types.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L89) |

package/api/@xmachines/play-signals/interfaces/SignalComputed.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalComputed\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L112)
+Defined in: [packages/play-signals/src/types.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L112)
 
 The computed signal. It evaluates late, and it memoizes the result
 
@@ -38,7 +38,7 @@ console.log(doubled.get()); // 10 (from the memory, with no new computation)
 get(): T;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L118)
+Defined in: [packages/play-signals/src/types.ts:118](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L118)
 
 Reads the computed value. It computes the value again only after a dependency changed
 

package/api/@xmachines/play-signals/interfaces/SignalOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalOptions\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L27)
+Defined in: [packages/play-signals/src/types.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L27)
 
 The options of a Signal.State
 
@@ -34,4 +34,4 @@ const count = new Signal.State(0, options);
 
 | Property                               | Type                    | Description                                                        | Defined in                                                                                                                               |
 | -------------------------------------- | ----------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own. It decides if the value changed | [packages/play-signals/src/types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L34) |
+| <a id="property-equals"></a> `equals?` | (`a`, `b`) => `boolean` | The equality function of your own. It decides if the value changed | [packages/play-signals/src/types.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L34) |

package/api/@xmachines/play-signals/interfaces/SignalState.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalState\<T\>
 
-Defined in: [packages/play-signals/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L54)
+Defined in: [packages/play-signals/src/types.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L54)
 
 The writable state signal. It holds one reactive value
 
@@ -35,7 +35,7 @@ console.log(name.get()); // 'Bob'
 get(): T;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L60)
+Defined in: [packages/play-signals/src/types.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L60)
 
 Reads the current value, and tracks the signal as a dependency
 
@@ -53,7 +53,7 @@ The current value of the signal
 set(value): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L67)
+Defined in: [packages/play-signals/src/types.ts:67](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L67)
 
 Writes a new value, and notifies the watchers when the value changed
 

package/api/@xmachines/play-signals/interfaces/SignalWatcher.md

@@ -2,7 +2,7 @@
 
 # Interface: SignalWatcher
 
-Defined in: [packages/play-signals/src/types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L169)
+Defined in: [packages/play-signals/src/types.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L169)
 
 The watcher. It observes each signal change and schedules an effect
 
@@ -40,7 +40,7 @@ getPending(): (
   | SignalComputed<unknown>)[];
 ```
 
-Defined in: [packages/play-signals/src/types.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L189)
+Defined in: [packages/play-signals/src/types.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L189)
 
 Returns the signals that changed after the last check
 
@@ -60,7 +60,7 @@ The array of the signals with an update that waits
 unwatch(signal): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L182)
+Defined in: [packages/play-signals/src/types.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L182)
 
 Stops the watch of one signal
 
@@ -82,7 +82,7 @@ Stops the watch of one signal
 watch(signal): void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L175)
+Defined in: [packages/play-signals/src/types.ts:175](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L175)
 
 Starts the watch of one signal
 

package/api/@xmachines/play-signals/type-aliases/Cleanup.md

@@ -0,0 +1,38 @@
+[API](../../../README.md) / [@xmachines/play-signals](../README.md) / Cleanup
+
+# Type Alias: Cleanup
+
+```ts
+type Cleanup = () => void & { [Key in DisposeKey]: () => void };
+```
+
+Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L66)
+
+The release of a subscription. A caller runs it, or a scope releases it.
+
+The type is a function AND a `Disposable`, so one value serves both forms. A caller
+that holds the release in a field and runs it from a teardown keeps that code. A
+caller inside one scope writes `using` and writes no teardown at all:
+
+```ts
+// The explicit form. It stays correct.
+const stop = watchSignal(count, render);
+stop();
+
+// The scoped form. The scope releases it, and an exception releases it too.
+{
+	using stop = watchSignal(count, render);
+	render(count.get());
+}
+```
+
+`using` needs Node 24 or a browser with Explicit Resource Management, and it needs
+`"lib": ["ESNext"]` of the consumer. The publishable packages build at
+`target: "esnext"` and pass the syntax through, so the bundler of the consumer decides
+how to emit it. The `Cleanup` VALUE needs neither: a runtime without `Symbol.dispose`
+still calls it as a function, and a consumer that declares a lower `lib` still reads
+the type. See [DisposeKey](../../play/type-aliases/DisposeKey.md) for the second half of that.
+
+## See
+
+[Play RFC](../../../../rfc/play.md)

package/api/@xmachines/play-signals/type-aliases/WatcherNotify.md

@@ -6,7 +6,7 @@
 type WatcherNotify = () => void;
 ```
 
-Defined in: [packages/play-signals/src/types.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.1/packages/play-signals/src/types.ts#L141)
+Defined in: [packages/play-signals/src/types.ts:141](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-signals/src/types.ts#L141)
 
 The notification callback of a Signal.subtle.Watcher