@xmachines/docs 2.2.0 → 4.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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/docs)
 
 ## Overview
 
@@ -78,7 +78,8 @@ Concept guides and tutorials that show how to use XMachines:
 
 - **[Getting Started](guides/getting-started.md)** — `setup().createMachine()` → `definePlayer()` → `actor.start()` → TC39 Signals
 - **[Understanding State Machines](guides/state-machines.md)** — `meta.route`, `meta.view`, and why machines replace boolean flags
-- **[Understanding the Actor Model](guides/actor-model.md)** — Actor/infrastructure split, `AbstractActor`, and the reset invariant
+- **[Understanding the Actor Model](guides/actor-model.md)** — Actor/infrastructure split, `PlayActor`, and the reset invariant
+- **[Understanding Routing](guides/routing.md)** — The URLPattern grammar of `meta.route`, the prefix rule, and the routing invariants
 - **[Understanding TC39 Signals](guides/signals.md)** — Signal primitives and the five architectural invariants they enforce
 
 **Tooling:**
@@ -112,25 +113,16 @@ TypeDoc generates the API reference for every public package. See [`api/README.m
 The documented packages:
 
 - [`@xmachines/play`](../play/README.md) — Core protocols (`PlayEvent`, `PlayError`)
-- [`@xmachines/play-actor`](../play-actor/README.md) — `AbstractActor`, `Routable`, `Viewable`
+- [`@xmachines/play-actor`](../play-actor/README.md) — `PlayActor`
+- [`@xmachines/play-view`](../play-view/README.md) — `Viewable`, `PlaySpec`, the view store lifecycle
 - [`@xmachines/play-signals`](../play-signals/README.md) — TC39 Signals polyfill, `watchSignal`
-- [`@xmachines/play-router`](../play-router/README.md) — `extractMachineRoutes`, `RouterBridgeBase`
+- [`@xmachines/play-router`](../play-router/README.md) — `RouterBridgeBase`, `RouteMap`, `Routable`
+- [`@xmachines/play-router/xstate`](../play-router/README.md) — `extractMachineRoutes`, `createRouteMap`
+- [`@xmachines/play-url`](../play-url/README.md) — the URLPattern grammar, a base path, the params of a framework router
 - [`@xmachines/play-xstate`](../play-xstate/README.md) — `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor`
 - [`@xmachines/play-dom`](../play-dom/README.md), [`play-react`](../play-react/README.md), [`play-solid`](../play-solid/README.md), [`play-svelte`](../play-svelte/README.md), [`play-vue`](../play-vue/README.md) — View renderers
 - [`@xmachines/play-dom-router`](../play-dom-router/README.md), [`play-tanstack-router`](../play-tanstack-router/README.md), [`play-react-router`](../play-react-router/README.md), [`play-tanstack-react-router`](../play-tanstack-react-router/README.md), [`play-solid-router`](../play-solid-router/README.md), [`play-tanstack-solid-router`](../play-tanstack-solid-router/README.md), [`play-vue-router`](../play-vue-router/README.md), [`play-svelte-spa-router`](../play-svelte-spa-router/README.md), [`play-sveltekit-router`](../play-sveltekit-router/README.md) — Router adapters
 
-## Testing
-
-Run the docs package tests in isolation:
-
-```bash
-# From the monorepo root
-pnpm --filter @xmachines/docs test
-
-# Or from within the package directory
-pnpm test
-```
-
 ## Regenerating API Docs
 
 TypeDoc generates the `api/` directory. Never edit it by hand. Generate it again from the monorepo root:

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-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play)
 
 ---
 
@@ -14,7 +14,7 @@
 pnpm add @xmachines/play
 ```
 
-> **This package requires Node.js `>= 22.0.0`.** Every package is an ES module (`"type": "module"`).
+> **This package requires Node.js `>= 24.0.0`.** Every package is an ES module (`"type": "module"`).
 
 ---
 
@@ -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:
 
@@ -68,8 +69,8 @@ const invalid: LoginEvent = { type: "auth.login" }; // Error!
 Base class for every `@xmachines/*` runtime error. Each error has a stable `scope` (the class or the module that throws it) and a stable `code` (a machine-readable identifier). Always branch on `.code` or on the subclass. Never branch on `.message`.
 
 ```typescript
-import { PlayError, assertNonNullable } from "@xmachines/play";
-import { NonNullableError } from "@xmachines/play/errors";
+import { assertNonNullable } from "@xmachines/play";
+import { NonNullableError, PlayError } from "@xmachines/play/errors";
 
 try {
 	assertNonNullable(document.getElementById("app"), "#app");
@@ -90,7 +91,7 @@ try {
 Extend `PlayError` in your own `@xmachines/*`-compatible packages:
 
 ```typescript
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 
 export class MyPackageError extends PlayError {
 	constructor(message: string, options?: ErrorOptions) {
@@ -111,24 +112,81 @@ 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`             |
+| `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`
 
 | Export             | Kind    | Description                                               |
 | ------------------ | ------- | --------------------------------------------------------- |
-| `PlayError`        | `class` | The base error class, re-exported                         |
+| `PlayError`        | `class` | The base class of every `@xmachines/*` typed error        |
 | `NonNullableError` | `class` | `scope: "assertNonNullable"`, `code: "PLAY_NON_NULLABLE"` |
 
 ---
@@ -145,100 +203,20 @@ Every other `@xmachines/*` package exports its own error subclasses from its `./
 | ---------------------------- | ----------------------------------- |
 | `@xmachines/play`            | `@xmachines/play/errors`            |
 | `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
+| `@xmachines/play-url`        | `@xmachines/play-url/errors`        |
+| `@xmachines/play-view`       | `@xmachines/play-view/errors`       |
 | `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
 | `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
 
 ---
 
-## Testing
-
-Run tests for this package in isolation:
-
-```bash
-pnpm --filter @xmachines/play test
-```
-
-Or from the package directory:
-
-```bash
-pnpm test
-```
-
-Tests use **Vitest** and cover the `PlayError` class construction, inheritance, `cause` support, and subclassing patterns.
-
----
-
 ## License
 
 MIT © [Mikael Karon](mailto:mikael@karon.se)
 
 See [LICENSE](./LICENSE) for details.
 
-@xmachines/play - the core protocol layer
-
-This package defines the architectural contracts that carry the communication
-between the Actor and the infrastructure, with no direct dependency between them.
-RFC section 5.2 gives these protocols. They are the base of the loose coupling
-between the business logic and the runtime adapters.
-
-## The exports
-
-**PlayEvent<TPayload>** - the generic event type of the Actor communication
-
-- It is every object with a `type: string` property
-- The generic `TPayload` parameter gives a type-safe event shape, and it is optional
-- The default is `Record<string, unknown>`, which accepts each shape
-- It is framework-agnostic, and it is not bound to XState or to another library
-
-**Use:**
-
-```typescript
-// Flexible, the default:
-const event: PlayEvent = { type: "auth.login", userId: "123" };
-
-// Type-safe, with the generic parameter:
-type LoginEvent = PlayEvent<{ userId: string }>;
-const event: LoginEvent = { type: "auth.login", userId: "123" };
-```
-
-**The common event patterns:**
-
-- A domain event: `{ type: 'auth.login', userId: '123' }`
-- Your own event: `{ type: 'form.submit', data: {...} }`
-
-**The routing events** come from @xmachines/play-router:
-
-- PlayRouteEvent: the routing event with the parameters and the target state ID
-- RouterBridge: the protocol that connects a router adapter to an actor
-
-**The browser navigation:** a router adapter handles the browser BACK and FORWARD
-buttons, through the `popstate` event. The user presses BACK or FORWARD, the
-router detects the new URL, and it sends a PlayRouteEvent to the actor. The actor
-then checks the event.
-
-```typescript
-import type { PlayRouteEvent, RouterBridge } from "@xmachines/play-router";
-```
-
-## The architectural invariants
-
-These protocols enforce the invariants below:
-
-1. **Actor Authority**: the infrastructure makes a request, and the Actor decides the validity
-2. **Strict Separation**: no layer depends on another layer directly
-3. **Passive Infrastructure**: the infrastructure observes the Actor signals. It never controls them
-4. **Signal-Only Reactivity**: every state change goes through a TC39 Signal
-5. **State-Driven Reset**: each navigation follows the transition rules of the state machine
-
-## Classes
-
-- [NonNullableError](classes/NonNullableError.md)
-- [PlayError](classes/PlayError.md)
-
-## Type Aliases
-
-- [PlayEvent](type-aliases/PlayEvent.md)
-
-## Functions
+## Modules
 
-- [assertNonNullable](functions/assertNonNullable.md)
+- [errors](errors/README.md)
+- [index](index/README.md)

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

@@ -0,0 +1,8 @@
+[API](../../../README.md) / [@xmachines/play](../README.md) / errors
+
+# errors
+
+## Classes
+
+- [NonNullableError](classes/NonNullableError.md)
+- [PlayError](classes/PlayError.md)

package/api/@xmachines/play/{classes → errors/classes}/NonNullableError.md

@@ -1,10 +1,10 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / NonNullableError
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [errors](../README.md) / NonNullableError
 
 # 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:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L112)
 
-[assertNonNullable](../functions/assertNonNullable.md) throws this error when a value is `null` or `undefined`.
+[@xmachines/play!index.assertNonNullable](../../index/functions/assertNonNullable.md) throws this error when a value is `null` or `undefined`.
 
 Catch it to separate a failed assertion of a missing value from every other
 runtime error:
@@ -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:113](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L113)
 
 #### 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:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L76) |
 | <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:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L66) |
 | <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 → errors/classes}/PlayError.md

@@ -1,8 +1,8 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / PlayError
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [errors](../README.md) / PlayError
 
 # 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:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L64)
 
 The base class of every typed runtime error of an `@xmachines/*` package.
 
@@ -23,16 +23,18 @@ An `@xmachines/*` package that defines typed subclasses exports them from an
 | ---------------------------- | ----------------------------------- |
 | `@xmachines/play`            | `@xmachines/play/errors`            |
 | `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
+| `@xmachines/play-url`        | `@xmachines/play-url/errors`        |
+| `@xmachines/play-view`       | `@xmachines/play-view/errors`       |
 | `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
 | `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
 
-The root `@xmachines/play` exports `PlayError` itself, and it is the base of every
-subclass above.
+`PlayError` is the base of every subclass above, and it sits on the subpath with them.
+The root barrel of `@xmachines/play` exports it never: one name has one import.
 
 ## How to catch an error by its type
 
 ```typescript
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 import { RouterSyncError } from "@xmachines/play-router/errors";
 
 try {
@@ -55,7 +57,7 @@ try {
 ## How to extend PlayError
 
 ```typescript
-import { PlayError } from "@xmachines/play";
+import { PlayError } from "@xmachines/play/errors";
 
 export class MyPackageError extends PlayError {
 	constructor(message: string, options?: ErrorOptions) {
@@ -72,6 +74,28 @@ export class MyPackageError extends PlayError {
 ## Extended by
 
 - [`NonNullableError`](NonNullableError.md)
+- [`DuplicateBridgeError`](../../../play-router/errors/classes/DuplicateBridgeError.md)
+- [`DuplicateRoutePathError`](../../../play-router/errors/classes/DuplicateRoutePathError.md)
+- [`EmptyRoutePathError`](../../../play-router/errors/classes/EmptyRoutePathError.md)
+- [`InvalidBasePathError`](../../../play-router/errors/classes/InvalidBasePathError.md)
+- [`InvalidRoutePatternError`](../../../play-router/errors/classes/InvalidRoutePatternError.md)
+- [`InvalidStateIdError`](../../../play-router/errors/classes/InvalidStateIdError.md)
+- [`MissingBasePathParamError`](../../../play-router/errors/classes/MissingBasePathParamError.md)
+- [`RouterSyncError`](../../../play-router/errors/classes/RouterSyncError.md)
+- [`UnknownStateTypeError`](../../../play-router/errors/classes/UnknownStateTypeError.md)
+- [`InvalidBasePathError`](../../../play-url/errors/classes/InvalidBasePathError.md)
+- [`InvalidRoutePatternError`](../../../play-url/errors/classes/InvalidRoutePatternError.md)
+- [`MissingBasePathParamError`](../../../play-url/errors/classes/MissingBasePathParamError.md)
+- [`ReadOnlyContextError`](../../../play-view/errors/classes/ReadOnlyContextError.md)
+- [`VueRouterNavigationError`](../../../play-vue-router/errors/classes/VueRouterNavigationError.md)
+- [`VueRouterSendError`](../../../play-vue-router/errors/classes/VueRouterSendError.md)
+- [`ActorThrewNonErrorError`](../../../play-xstate/errors/classes/ActorThrewNonErrorError.md)
+- [`InvalidEventError`](../../../play-xstate/errors/classes/InvalidEventError.md)
+- [`InvalidMachineError`](../../../play-xstate/errors/classes/InvalidMachineError.md)
+- [`InvalidRouteHandlerError`](../../../play-xstate/errors/classes/InvalidRouteHandlerError.md)
+- [`InvalidRouteMetadataError`](../../../play-xstate/errors/classes/InvalidRouteMetadataError.md)
+- [`MissingRouteParamError`](../../../play-xstate/errors/classes/MissingRouteParamError.md)
+- [`MissingStateIdError`](../../../play-xstate/errors/classes/MissingStateIdError.md)
 
 ## Constructors
 
@@ -82,10 +106,11 @@ new PlayError(
    scope,
    code,
    message,
-   options?): 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:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L84)
 
 #### Parameters
 
@@ -111,10 +136,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:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L76) |
 | <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:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/errors.ts#L66) |
 | <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/index/README.md

@@ -0,0 +1,75 @@
+[API](../../../README.md) / [@xmachines/play](../README.md) / index
+
+# index
+
+@xmachines/play - the core protocol layer
+
+This package defines the architectural contracts that carry the communication
+between the Actor and the infrastructure, with no direct dependency between them.
+RFC section 5.2 gives these protocols. They are the base of the loose coupling
+between the business logic and the runtime adapters.
+
+## The exports
+
+**PlayEvent<TPayload>** - the generic event type of the Actor communication
+
+- It is every object with a `type: string` property
+- The generic `TPayload` parameter gives a type-safe event shape, and it is optional
+- The default is `Record<string, unknown>`, which accepts each shape
+- It is framework-agnostic, and it is not bound to XState or to another library
+
+**Use:**
+
+```typescript
+// Flexible, the default:
+const event: PlayEvent = { type: "auth.login", userId: "123" };
+
+// Type-safe, with the generic parameter:
+type LoginEvent = PlayEvent<{ userId: string }>;
+const event: LoginEvent = { type: "auth.login", userId: "123" };
+```
+
+**The common event patterns:**
+
+- A domain event: `{ type: 'auth.login', userId: '123' }`
+- Your own event: `{ type: 'form.submit', data: {...} }`
+
+**The routing events** come from @xmachines/play-router:
+
+- PlayRouteEvent: the routing event with the parameters and the target state ID
+- RouterBridge: the protocol that connects a router adapter to an actor
+
+**The browser navigation:** a router adapter handles the browser BACK and FORWARD
+buttons, through the `popstate` event. The user presses BACK or FORWARD, the
+router detects the new URL, and it sends a PlayRouteEvent to the actor. The actor
+then checks the event.
+
+```typescript
+import type { PlayRouteEvent, RouterBridge } from "@xmachines/play-router";
+```
+
+## The architectural invariants
+
+These protocols enforce the invariants below:
+
+1. **Actor Authority**: the infrastructure makes a request, and the Actor decides the validity
+2. **Strict Separation**: no layer depends on another layer directly
+3. **Passive Infrastructure**: the infrastructure observes the Actor signals. It never controls them
+4. **Signal-Only Reactivity**: every state change goes through a TC39 Signal
+5. **State-Driven Reset**: each navigation follows the transition rules of the state machine
+
+## 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)
+- [shallowEqualExcept](functions/shallowEqualExcept.md)

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

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

package/api/@xmachines/play/{functions → index/functions}/assertNonNullable.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / assertNonNullable
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / assertNonNullable
 
 # Function: assertNonNullable()
 
@@ -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/v4.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