@xmachines/docs 2.2.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Documentation, guides, RFCs, and generated API reference for XMachines.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/docs)
+[![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/docs)
 
 ## Overview
 

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

@@ -4,7 +4,7 @@
 
 > Core protocol layer for the Universal Player Architecture. It defines `PlayEvent`, `PlayError`, and the contracts that keep the business logic loosely coupled to the runtime adapters.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play)
+[![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)
 
 ---
 
@@ -26,6 +26,7 @@ pnpm add @xmachines/play
 - **`PlayError`** — the typed base class for all `@xmachines/*` runtime errors
 - **`NonNullableError`** — the error that a package throws when a required value is `null` or `undefined`
 - **`assertNonNullable()`** — the assertion utility that narrows `T | null | undefined` to `T`
+- **`Cleanup`**, **`asCleanup()`**, **`DISPOSE`** — the release protocol that every subscription of the ecosystem hands back
 
 These protocols implement the architectural invariants that the Play RFC defines:
 
@@ -111,18 +112,77 @@ import { assertNonNullable } from "@xmachines/play";
 const el = assertNonNullable(document.getElementById("app"), "#app");
 ```
 
+### `Cleanup`, `asCleanup(release)`, and `DISPOSE`
+
+Every subscription of the ecosystem hands one value back: the release. `Cleanup` is that
+type. It is a function AND a `Disposable`, so one value serves both forms — the caller
+that keeps the release in a field, and the caller that gives it to a scope.
+
+```ts
+import { asCleanup, type Cleanup } from "@xmachines/play";
+
+// 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());
+}
+```
+
+`asCleanup` publishes a release. It gives the SAME function back with the dispose key
+added, and wraps nothing, so a caller that compares two releases or holds one in a `Set`
+sees what it saw before.
+
+```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));
+}
+```
+
+`DISPOSE` is the key that the release sits under, and a class implements the protocol
+with it:
+
+```ts
+import { DISPOSE } from "@xmachines/play";
+
+class Session {
+	close(): void {}
+	[DISPOSE](): void {
+		this.close();
+	}
+}
+```
+
+Use `DISPOSE` and not a bare `Symbol.dispose`. A bundler that downlevels `using` for a
+target below Chrome 134 emits a helper that reads
+`object[Symbol.dispose || Symbol.for("Symbol.dispose")]`, and `DISPOSE` is that same
+pair.
+
+> **The `using` FORM needs `"lib": ["ESNext"]`, and the `Cleanup` VALUE needs nothing.**
+> A consumer on a lower `lib` reads `Cleanup` as the plain `() => void` that these
+> functions returned before the protocol existed, and every call site keeps compiling.
+
 ---
 
 ## API Summary
 
 ### Exported from `@xmachines/play`
 
-| Export                | Kind       | Description                                                         |
-| --------------------- | ---------- | ------------------------------------------------------------------- |
-| `PlayEvent<TPayload>` | `type`     | Universal event contract — `{ type: string } & TPayload`            |
-| `PlayError`           | `class`    | Base class for all `@xmachines/*` typed errors                      |
-| `NonNullableError`    | `class`    | `assertNonNullable` throws it when a value is `null` or `undefined` |
-| `assertNonNullable`   | `function` | Asserts that the value is not null. It returns the narrowed value   |
+| Export                | Kind       | Description                                                          |
+| --------------------- | ---------- | -------------------------------------------------------------------- |
+| `PlayEvent<TPayload>` | `type`     | Universal event contract — `{ type: string } & TPayload`             |
+| `PlayError`           | `class`    | Base class for all `@xmachines/*` typed errors                       |
+| `NonNullableError`    | `class`    | `assertNonNullable` throws it when a value is `null` or `undefined`  |
+| `assertNonNullable`   | `function` | Asserts that the value is not null. It returns the narrowed value    |
+| `Cleanup`             | `type`     | The release of a subscription — `(() => void) & Disposable`          |
+| `asCleanup`           | `function` | Publishes one release as a `Cleanup`. It changes the function itself |
+| `DISPOSE`             | `const`    | The symbol key that a release sits under                             |
+| `DisposeKey`          | `type`     | The type of that key, and `never` where the consumer omits the lib   |
 
 ### Exported from `@xmachines/play/errors`
 
@@ -237,8 +297,15 @@ These protocols enforce the invariants below:
 
 ## Type Aliases
 
+- [Cleanup](type-aliases/Cleanup.md)
+- [DisposeKey](type-aliases/DisposeKey.md)
 - [PlayEvent](type-aliases/PlayEvent.md)
 
+## Variables
+
+- [DISPOSE](variables/DISPOSE.md)
+
 ## Functions
 
+- [asCleanup](functions/asCleanup.md)
 - [assertNonNullable](functions/assertNonNullable.md)

package/api/@xmachines/play/classes/NonNullableError.md

@@ -2,7 +2,7 @@
 
 # Class: NonNullableError
 
-Defined in: [packages/play/src/errors.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L110)
+Defined in: [packages/play/src/errors.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L110)
 
 [assertNonNullable](../functions/assertNonNullable.md) throws this error when a value is `null` or `undefined`.
 
@@ -35,7 +35,7 @@ try {
 new NonNullableError(message, options?): NonNullableError;
 ```
 
-Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L111)
+Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L111)
 
 #### Parameters
 
@@ -57,10 +57,10 @@ Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmac
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                         | Defined in                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`cause`](PlayError.md#property-cause)                     | -                                                                                                                          |
-| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `PLAY_<PACKAGE>_<DESCRIPTION>`. It stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                                                                                  | [`PlayError`](PlayError.md).[`code`](PlayError.md#property-code)                       | [packages/play/src/errors.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L74) |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `PLAY_<PACKAGE>_<DESCRIPTION>`. It stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                                                                                  | [`PlayError`](PlayError.md).[`code`](PlayError.md#property-code)                       | [packages/play/src/errors.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L74) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`message`](PlayError.md#property-message)                 | -                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`name`](PlayError.md#property-name)                       | -                                                                                                                          |
-| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](PlayError.md).[`scope`](PlayError.md#property-scope)                     | [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L64) |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](PlayError.md).[`scope`](PlayError.md#property-scope)                     | [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L64) |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](PlayError.md).[`stack`](PlayError.md#property-stack)                     | -                                                                                                                          |
 | <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | [`PlayError`](PlayError.md).[`stackTraceLimit`](PlayError.md#property-stacktracelimit) | -                                                                                                                          |
 

package/api/@xmachines/play/classes/PlayError.md

@@ -2,7 +2,7 @@
 
 # Class: PlayError
 
-Defined in: [packages/play/src/errors.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L62)
+Defined in: [packages/play/src/errors.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L62)
 
 The base class of every typed runtime error of an `@xmachines/*` package.
 
@@ -85,7 +85,7 @@ new PlayError(
    options?): PlayError;
 ```
 
-Defined in: [packages/play/src/errors.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L82)
+Defined in: [packages/play/src/errors.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L82)
 
 #### Parameters
 
@@ -111,10 +111,10 @@ Error.constructor;
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from          | Defined in                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.cause`           | -                                                                                                                          |
-| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `PLAY_<PACKAGE>_<DESCRIPTION>`. It stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                                                                                  | -                       | [packages/play/src/errors.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L74) |
+| <a id="property-code"></a> `code`                       | `readonly` | `string`  | A stable, machine-readable identifier of the error. An error code follows the naming convention `PLAY_<PACKAGE>_<DESCRIPTION>`. It stays the same across each patch release and each minor release of one major version. Never match on `.message`. Always match on `.code`, or on the subclass.                                                                                                                                                  | -                       | [packages/play/src/errors.ts:74](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L74) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.message`         | -                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.name`            | -                                                                                                                          |
-| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | -                       | [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/errors.ts#L64) |
+| <a id="property-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | -                       | [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/errors.ts#L64) |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `Error.stack`           | -                                                                                                                          |
 | <a id="property-stacktracelimit"></a> `stackTraceLimit` | `static`   | `number`  | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` | -                                                                                                                          |
 

package/api/@xmachines/play/functions/asCleanup.md

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

package/api/@xmachines/play/functions/assertNonNullable.md

@@ -6,7 +6,7 @@
 function assertNonNullable<V>(value, name?): NonNullable<V>;
 ```
 
-Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/utils.ts#L39)
+Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/utils.ts#L39)
 
 Asserts that `value` is not `null` and not `undefined`, then returns it with the
 type `NonNullable<V>`. One expression therefore holds the guard and the narrowed

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

@@ -0,0 +1,38 @@
+[API](../../../README.md) / [@xmachines/play](../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](DisposeKey.md) for the second half of that.
+
+## See
+
+[Play RFC](../../../../rfc/play.md)

package/api/@xmachines/play/type-aliases/DisposeKey.md

@@ -0,0 +1,32 @@
+[API](../../../README.md) / [@xmachines/play](../README.md) / DisposeKey
+
+# Type Alias: DisposeKey
+
+```ts
+type DisposeKey = SymbolConstructor extends object ? Key : never;
+```
+
+Defined in: [packages/play/src/disposable.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L34)
+
+The dispose key of the ambient library, and `never` where the consumer omits it.
+
+`Symbol.dispose` and the `Disposable` interface arrive with `lib.esnext.disposable`. A
+consumer gets that library from `"lib": ["ESNext"]`, and NOT from `"lib": ["ES2022"]`
+or `["ES2023"]`. A published `.d.ts` that names either one therefore refuses to
+type-check for every consumer of the second kind, and this package cannot ask for the
+library on their behalf: TypeScript copies no `/// <reference lib="..." />` into
+declaration output.
+
+The conditional asks the compiler instead of naming the key. Where the library is
+present the key resolves to `typeof Symbol.dispose`, and [Cleanup](Cleanup.md) is a
+`Disposable` that a `using` declaration accepts. Where the library is absent the key
+resolves to `never`, the mapped type of [Cleanup](Cleanup.md) adds no member, and `Cleanup`
+IS the plain `() => void` that these functions returned before this protocol existed.
+That consumer loses nothing, because `using` is syntax that the same library gates: a
+compiler that cannot name `Symbol.dispose` cannot compile the form either.
+
+The runtime is not involved. [asCleanup](../functions/asCleanup.md) stores the release under [DISPOSE](../variables/DISPOSE.md)
+whatever the consumer declares, so one build serves both.
+
+The type is exported because the published `.d.ts` names it, and a reader who asks why
+[Cleanup](Cleanup.md) carries no dispose member needs to reach the answer.

package/api/@xmachines/play/type-aliases/PlayEvent.md

@@ -6,7 +6,7 @@
 type PlayEvent<TPayload> = object & TPayload;
 ```
 
-Defined in: [packages/play/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/types.ts#L71)
+Defined in: [packages/play/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/types.ts#L71)
 
 The generic event type of the Play Architecture
 
@@ -35,7 +35,7 @@ and of the other state machine libraries.
 
 | Name   | Type     | Defined in                                                                                                               |
 | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `type` | `string` | [packages/play/src/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play/src/types.ts#L72) |
+| `type` | `string` | [packages/play/src/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/types.ts#L72) |
 
 ## Type Parameters
 

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

@@ -0,0 +1,34 @@
+[API](../../../README.md) / [@xmachines/play](../README.md) / DISPOSE
+
+# Variable: DISPOSE
+
+```ts
+const DISPOSE: DisposeKey;
+```
+
+Defined in: [packages/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](../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-actor/README.md

@@ -4,7 +4,7 @@
 
 Abstract Actor base class 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-2.2.0-blue)](https://www.npmjs.com/package/@xmachines/play-actor)
+[![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-actor)
 
 ## Installation
 
@@ -268,10 +268,14 @@ communication with the infrastructure layer.
 
 - [BaseActorProviderProps](interfaces/BaseActorProviderProps.md)
 - [BaseViewContextValue](interfaces/BaseViewContextValue.md)
+- [FailureLatch](interfaces/FailureLatch.md)
 - [PlaySpec](interfaces/PlaySpec.md)
+- [ReportGuard](interfaces/ReportGuard.md)
+- [ReportGuardMessages](interfaces/ReportGuardMessages.md)
 - [ResolveViewStoreOptions](interfaces/ResolveViewStoreOptions.md)
 - [Routable](interfaces/Routable.md)
 - [Viewable](interfaces/Viewable.md)
+- [ViewInputs](interfaces/ViewInputs.md)
 - [ViewStoreLifecycle](interfaces/ViewStoreLifecycle.md)
 - [ViewStoreResolution](interfaces/ViewStoreResolution.md)
 
@@ -283,10 +287,13 @@ communication with the infrastructure layer.
 
 - [attachRenderErrorHandler](functions/attachRenderErrorHandler.md)
 - [composePlayState](functions/composePlayState.md)
+- [createFailureLatch](functions/createFailureLatch.md)
+- [createReportGuard](functions/createReportGuard.md)
 - [createViewStoreLifecycle](functions/createViewStoreLifecycle.md)
 - [guardContextWrites](functions/guardContextWrites.md)
 - [refreshContextSubtree](functions/refreshContextSubtree.md)
 - [reuseComposedState](functions/reuseComposedState.md)
+- [sameViewInputs](functions/sameViewInputs.md)
 - [shallowEqualExcept](functions/shallowEqualExcept.md)
 - [toAtomState](functions/toAtomState.md)
 - [typedSpec](functions/typedSpec.md)

package/api/@xmachines/play-actor/classes/AbstractActor.md

@@ -2,7 +2,7 @@
 
 # Abstract Class: AbstractActor\<TLogic, TEvent\>
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/abstract-actor.ts#L197)
+Defined in: [packages/play-actor/src/abstract-actor.ts:197](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/abstract-actor.ts#L197)
 
 The abstract base class of an actor of the Play Architecture.
 
@@ -74,7 +74,7 @@ Actor<TLogic>.constructor
 | <a id="property-ref"></a> `ref`             | `public`   | [`ActorRef`](https://www.jsdocs.io/package/xstate#ActorRef)\<[`SnapshotFrom`](https://www.jsdocs.io/package/xstate#SnapshotFrom)\<`TLogic`\>, [`EventFromLogic`](https://www.jsdocs.io/package/xstate#EventFromLogic)\<`TLogic`\>, [`EmittedFrom`](https://www.jsdocs.io/package/xstate#EmittedFrom)\<`TLogic`\>\> | -                                                                                                                                                                                                         | `Actor.ref`       | -                                                                                                                                                        |
 | <a id="property-sessionid"></a> `sessionId` | `public`   | `string`                                                                                                                                                                                                                                                                                                           | The globally unique process ID for this invocation.                                                                                                                                                       | `Actor.sessionId` | -                                                                                                                                                        |
 | <a id="property-src"></a> `src`             | `public`   | \| `string` \| [`AnyActorLogic`](https://www.jsdocs.io/package/xstate#AnyActorLogic)                                                                                                                                                                                                                               | -                                                                                                                                                                                                         | `Actor.src`       | -                                                                                                                                                        |
-| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | The reactive snapshot of the current actor state. The infrastructure observes this signal, and it reacts to each state change. It therefore holds no coupling to the internal state machine of the actor. | -                 | [packages/play-actor/src/abstract-actor.ts:207](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/abstract-actor.ts#L207) |
+| <a id="property-state"></a> `state`         | `abstract` | [`State`](../../play-signals/namespaces/Signal/classes/State.md)\<`unknown`\>                                                                                                                                                                                                                                      | The reactive snapshot of the current actor state. The infrastructure observes this signal, and it reacts to each state change. It therefore holds no coupling to the internal state machine of the actor. | -                 | [packages/play-actor/src/abstract-actor.ts:207](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/abstract-actor.ts#L207) |
 | <a id="property-system"></a> `system`       | `public`   | [`AnyActorSystem`](https://www.jsdocs.io/package/xstate#AnyActorSystem)                                                                                                                                                                                                                                            | The system to which this actor belongs.                                                                                                                                                                   | `Actor.system`    | -                                                                                                                                                        |
 | <a id="property-systemid"></a> `systemId`   | `public`   | `string` \| `undefined`                                                                                                                                                                                                                                                                                            | -                                                                                                                                                                                                         | `Actor.systemId`  | -                                                                                                                                                        |
 
@@ -245,7 +245,7 @@ Actor.select;
 abstract send(event): void;
 ```
 
-Defined in: [packages/play-actor/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/abstract-actor.ts#L223)
+Defined in: [packages/play-actor/src/abstract-actor.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/abstract-actor.ts#L223)
 
 Sends an event to the Actor.
 

package/api/@xmachines/play-actor/functions/attachRenderErrorHandler.md

@@ -6,7 +6,7 @@
 function attachRenderErrorHandler<TRegistry>(registry, handler): TRegistry;
 ```
 
-Defined in: [packages/play-actor/src/provider-guards.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/provider-guards.ts#L68)
+Defined in: [packages/play-actor/src/provider-guards.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/provider-guards.ts#L68)
 
 Copies a component registry, and puts an `onRenderError` handler into the copy.
 

package/api/@xmachines/play-actor/functions/composePlayState.md

@@ -6,7 +6,7 @@
 function composePlayState(authoredState, slice): Record<string, unknown> | undefined;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/context-projection.ts#L228)
+Defined in: [packages/play-actor/src/context-projection.ts:228](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/context-projection.ts#L228)
 
 Composes the effective state of a view: the authored `spec.state` and the
 `/context` slice.

package/api/@xmachines/play-actor/functions/createFailureLatch.md

@@ -0,0 +1,20 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / createFailureLatch
+
+# Function: createFailureLatch()
+
+```ts
+function createFailureLatch(): FailureLatch;
+```
+
+Defined in: [packages/play-actor/src/failure-latch.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/failure-latch.ts#L202)
+
+Makes a [FailureLatch](../interfaces/FailureLatch.md).
+
+The latch holds the three inputs BESIDE the flag. Clearing on each emission would be
+enough for a provider that can hook every emission, and the identity check covers the
+one that cannot: a render that runs again with nothing changed reports nothing, whether
+or not the provider noticed that it ran.
+
+## Returns
+
+[`FailureLatch`](../interfaces/FailureLatch.md)

package/api/@xmachines/play-actor/functions/createReportGuard.md

@@ -0,0 +1,26 @@
+[API](../../../README.md) / [@xmachines/play-actor](../README.md) / createReportGuard
+
+# Function: createReportGuard()
+
+```ts
+function createReportGuard(messages): ReportGuard;
+```
+
+Defined in: [packages/play-actor/src/failure-latch.ts:134](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/failure-latch.ts#L134)
+
+Makes a [ReportGuard](../interfaces/ReportGuard.md).
+
+The flag SAVES and restores, and it is no plain `false` at the end: a handler of the
+host can start a second contained failure inside the first — a fallback that throws, a
+write of the store that drives another emission — and a bare reset in the inner
+`finally` would clear the guard while the outer report still runs.
+
+## Parameters
+
+| Parameter  | Type                                                          | Description                                                                                                                                                                       |
+| ---------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `messages` | [`ReportGuardMessages`](../interfaces/ReportGuardMessages.md) | See [ReportGuardMessages](../interfaces/ReportGuardMessages.md). The two messages say what the guard writes to `console.error`, and the absence of one says what it lets through. |
+
+## Returns
+
+[`ReportGuard`](../interfaces/ReportGuard.md)

package/api/@xmachines/play-actor/functions/createViewStoreLifecycle.md

@@ -6,7 +6,7 @@
 function createViewStoreLifecycle(createStore): ViewStoreLifecycle;
 ```
 
-Defined in: [packages/play-actor/src/view-store-lifecycle.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/view-store-lifecycle.ts#L94)
+Defined in: [packages/play-actor/src/view-store-lifecycle.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/view-store-lifecycle.ts#L94)
 
 Creates a coordinator of the lifecycle.
 

package/api/@xmachines/play-actor/functions/guardContextWrites.md

@@ -6,7 +6,7 @@
 function guardContextWrites(store): StateStore;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/context-projection.ts#L151)
+Defined in: [packages/play-actor/src/context-projection.ts:151](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/context-projection.ts#L151)
 
 Wraps a StateStore, and the wrapper refuses each write under `/context`.
 

package/api/@xmachines/play-actor/functions/refreshContextSubtree.md

@@ -6,7 +6,7 @@
 function refreshContextSubtree(store, view): void;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/context-projection.ts#L210)
+Defined in: [packages/play-actor/src/context-projection.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/context-projection.ts#L210)
 
 Refreshes the `/context` subtree of a live store from the composed state of a
 derived view. An emission with the same `viewKey` means that only the projection

package/api/@xmachines/play-actor/functions/reuseComposedState.md

@@ -6,7 +6,7 @@
 function reuseComposedState(prev, next): PlaySpec | null;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-actor/src/context-projection.ts#L92)
+Defined in: [packages/play-actor/src/context-projection.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/context-projection.ts#L92)
 
 Reuses the composed `state` of the previous emission, or the complete previous
 spec, when the value of the projection did not change.