@xmachines/docs 2.0.0 → 2.1.0

package/README.md

@@ -2,13 +2,11 @@
 
 > Documentation, guides, RFCs, and generated API reference for XMachines.
 
-Part of the `XMachines Play monorepo`.
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.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-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/docs)
 
 ## Overview
 
-`@xmachines/docs` is the documentation package for the XMachines Play monorepo. It ships five categories of content:
+`@xmachines/docs` is the documentation package of the XMachines Play monorepo. It ships five categories of content:
 
 | Location        | Contents                                                         |
 | --------------- | ---------------------------------------------------------------- |
@@ -16,7 +14,7 @@ Part of the `XMachines Play monorepo`.
 | `guides/`       | Concept guides, tutorials, and getting-started docs              |
 | `contributing/` | Operational docs for contributors and maintainers                |
 | `examples/`     | Runnable code examples and demo application references           |
-| `api/`          | TypeDoc-generated API reference for all public packages          |
+| `api/`          | The API reference for every public package, generated by TypeDoc |
 
 ## Installation
 
@@ -28,7 +26,7 @@ pnpm add @xmachines/docs
 
 ### Import the package URL
 
-The package default export is its own module URL — useful for resolving doc assets at runtime:
+The default export of the package is its own module URL. Use it to resolve documentation assets at run time:
 
 ```typescript
 import docsUrl from "@xmachines/docs";
@@ -37,7 +35,7 @@ import docsUrl from "@xmachines/docs";
 
 ### Access documentation files directly
 
-All documentation directories are exposed as package exports:
+The package exports every documentation directory:
 
 ```typescript
 // Access RFC files
@@ -62,7 +60,7 @@ Architectural specifications that define the XMachines system:
 | File                               | Title   | Description                                                          |
 | ---------------------------------- | ------- | -------------------------------------------------------------------- |
 | [`rfc/play.md`](rfc/play.md)       | Play    | Universal Player Architecture — core protocol, roles, and invariants |
-| [`rfc/streams.md`](rfc/streams.md) | Streams | WHATWG Streams as integration boundary                               |
+| [`rfc/streams.md`](rfc/streams.md) | Streams | WHATWG Streams as the integration boundary                           |
 | [`rfc/broker.md`](rfc/broker.md)   | Broker  | Event broker specification                                           |
 | [`rfc/git.md`](rfc/git.md)         | Git     | Git-compatible ID and history model                                  |
 | [`rfc/run.md`](rfc/run.md)         | Run     | Runtime execution model                                              |
@@ -74,7 +72,7 @@ Architectural specifications that define the XMachines system:
 
 ### Guides
 
-Concept guides and tutorials for working with XMachines:
+Concept guides and tutorials that show how to use XMachines:
 
 **Learning:**
 
@@ -99,7 +97,7 @@ Reference documentation for contributors and maintainers:
 
 ### Examples
 
-Practical code examples demonstrating XMachines patterns:
+Practical code examples that show the XMachines patterns:
 
 - **[Basic State Machine](examples/basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + TC39 Signals
 - **[Traffic Light](examples/traffic-light.md)** — Multi-state machine with `meta.route` and `formatPlayRouteTransitions`
@@ -109,9 +107,9 @@ Practical code examples demonstrating XMachines patterns:
 
 ### API Reference
 
-TypeDoc-generated API reference for all public packages — see [`api/README.md`](api/README.md).
+TypeDoc generates the API reference for every public package. See [`api/README.md`](api/README.md).
 
-Packages documented:
+The documented packages:
 
 - [`@xmachines/play`](../play/README.md) — Core protocols (`PlayEvent`, `PlayError`)
 - [`@xmachines/play-actor`](../play-actor/README.md) — `AbstractActor`, `Routable`, `Viewable`
@@ -135,7 +133,7 @@ pnpm test
 
 ## Regenerating API Docs
 
-The `api/` directory is auto-generated by TypeDoc and must not be edited directly. Regenerate it from the monorepo root:
+TypeDoc generates the `api/` directory. Never edit it by hand. Generate it again from the monorepo root:
 
 ```bash
 pnpm run docs

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

@@ -2,11 +2,9 @@
 
 # `@xmachines/play`
 
-> Core protocol layer for the Universal Player Architecture — defines `PlayEvent`, `PlayError`, and architectural contracts enabling loose coupling between business logic and runtime adapters.
+> 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.0.0-blue)](https://www.npmjs.com/package/@xmachines/play)
-
-Part of the [XMachines JS monorepo](../../README.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play)
 
 ---
 
@@ -16,27 +14,27 @@ Part of the [XMachines JS monorepo](../../README.md).
 pnpm add @xmachines/play
 ```
 
-> **Node.js `>= 22.0.0` required.** All packages are ES modules (`"type": "module"`).
+> **This package requires Node.js `>= 22.0.0`.** Every package is an ES module (`"type": "module"`).
 
 ---
 
 ## Overview
 
-`@xmachines/play` is the foundational package in the XMachines ecosystem. It defines the minimal set of types and utilities that all other `@xmachines/*` packages build upon:
+`@xmachines/play` is the base package of the XMachines ecosystem. It defines the smallest set of types and utilities that every other `@xmachines/*` package builds on:
 
 - **`PlayEvent<TPayload>`** — the universal event contract for Actor ↔ Infrastructure communication
 - **`PlayError`** — the typed base class for all `@xmachines/*` runtime errors
-- **`NonNullableError`** — thrown when a required value is `null` or `undefined`
-- **`assertNonNullable()`** — assertion utility that narrows `T | null | undefined` to `T`
+- **`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`
 
-These protocols implement the architectural invariants defined in the Play RFC:
+These protocols implement the architectural invariants that the Play RFC defines:
 
-| #      | Invariant                  | Description                                                        |
-| ------ | -------------------------- | ------------------------------------------------------------------ |
-| INV-01 | **Actor Authority**        | The Actor is the final authority; guards decide all transitions    |
-| INV-02 | **Strict Separation**      | Business logic never imports UI frameworks or routing libraries    |
-| INV-04 | **Passive Infrastructure** | Infrastructure observes Actor signals; it never enforces guards    |
-| INV-05 | **Signal-Only Reactivity** | TC39 Signals are the exclusive cross-boundary communication medium |
+| #      | Invariant                  | Description                                                              |
+| ------ | -------------------------- | ------------------------------------------------------------------------ |
+| INV-01 | **Actor Authority**        | The Actor is the final authority. Guards decide all transitions          |
+| INV-02 | **Strict Separation**      | The business logic never imports a UI framework or a routing library     |
+| INV-04 | **Passive Infrastructure** | The infrastructure observes the Actor signals. It never enforces a guard |
+| INV-05 | **Signal-Only Reactivity** | TC39 Signals are the only medium that crosses a boundary                 |
 
 ---
 
@@ -44,7 +42,7 @@ These protocols implement the architectural invariants defined in the Play RFC:
 
 ### `PlayEvent<TPayload>`
 
-The minimal event contract: any object with a `type: string` property. Framework-agnostic — works with XState, Robot, and any other state machine library.
+The minimal event contract is any object with a `type: string` property. The contract is framework-agnostic. It works with XState, with Robot, and with every other state machine library.
 
 ```typescript
 import type { PlayEvent } from "@xmachines/play";
@@ -67,14 +65,14 @@ const invalid: LoginEvent = { type: "auth.login" }; // Error!
 
 ### `PlayError`
 
-Base class for all `@xmachines/*` runtime errors. Every error has a stable `scope` (throwing class/module) and `code` (machine-readable identifier). Always branch on `.code` or subclass — never on `.message`.
+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 } from "@xmachines/play";
+import { PlayError, assertNonNullable } from "@xmachines/play";
 import { NonNullableError } from "@xmachines/play/errors";
 
 try {
-	bridge.connect();
+	assertNonNullable(document.getElementById("app"), "#app");
 } catch (err) {
 	if (err instanceof NonNullableError) {
 		// err.scope === "assertNonNullable"
@@ -104,15 +102,12 @@ export class MyPackageError extends PlayError {
 
 ### `assertNonNullable(value, name?)`
 
-Assertion utility that returns `value` typed as `NonNullable<V>` or throws `NonNullableError`. Eliminates unsafe `!` non-null assertions.
+The assertion utility returns `value` with the type `NonNullable<V>`, or it throws `NonNullableError`. It removes the unsafe `!` non-null assertion.
 
 ```typescript
 import { assertNonNullable } from "@xmachines/play";
 
-// Inject + assert in one line — no intermediate variable or `!` needed:
-const actor = assertNonNullable(inject<AuthActor>("actor"), "actor");
-
-// DOM element lookup:
+// DOM element lookup — no intermediate variable or `!` needed:
 const el = assertNonNullable(document.getElementById("app"), "#app");
 ```
 
@@ -122,18 +117,18 @@ const el = assertNonNullable(document.getElementById("app"), "#app");
 
 ### 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`    | Thrown by `assertNonNullable` when a value is `null`/`undefined` |
-| `assertNonNullable`   | `function` | Asserts non-null, returns 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   |
 
 ### Exported from `@xmachines/play/errors`
 
 | Export             | Kind    | Description                                               |
 | ------------------ | ------- | --------------------------------------------------------- |
-| `PlayError`        | `class` | Re-exported base error class                              |
+| `PlayError`        | `class` | The base error class, re-exported                         |
 | `NonNullableError` | `class` | `scope: "assertNonNullable"`, `code: "PLAY_NON_NULLABLE"` |
 
 ---
@@ -144,15 +139,13 @@ const el = assertNonNullable(document.getElementById("app"), "#app");
 | ------------------- | ------------------ | ---------------------------------------------------- |
 | `PLAY_NON_NULLABLE` | `NonNullableError` | `assertNonNullable()` receives `null` or `undefined` |
 
-Other `@xmachines/*` packages export their own error subclasses from their respective `./errors` subpath:
+Every other `@xmachines/*` package exports its own error subclasses from its `./errors` subpath:
 
 | Package                      | Import path                         |
 | ---------------------------- | ----------------------------------- |
 | `@xmachines/play`            | `@xmachines/play/errors`            |
 | `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
 | `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
-| `@xmachines/play-react`      | `@xmachines/play-react/errors`      |
-| `@xmachines/play-solid`      | `@xmachines/play-solid/errors`      |
 | `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
 
 ---
@@ -181,59 +174,61 @@ MIT © [Mikael Karon](mailto:mikael@karon.se)
 
 See [LICENSE](./LICENSE) for details.
 
-@xmachines/play - Core Protocol Layer
+@xmachines/play - the core protocol layer
 
-Defines architectural contracts enabling Actor ↔ Infrastructure communication
-without direct dependencies. Per RFC section 5.2, these protocols establish
-the foundation for loose coupling between business logic and runtime adapters.
+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.
 
-## Exports
+## The exports
 
-**PlayEvent<TPayload>** - Generic event type for Actor communication
+**PlayEvent<TPayload>** - the generic event type of the Actor communication
 
-- Any object with a `type: string` property
-- Generic `TPayload` parameter for type-safe event shapes (optional)
-- Defaults to `Record<string, unknown>` for maximum flexibility
-- Framework-agnostic (not tied to XState or any specific library)
+- 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
 
-**Usage:**
+**Use:**
 
 ```typescript
-// Flexible (default):
+// Flexible, the default:
 const event: PlayEvent = { type: "auth.login", userId: "123" };
 
-// Type-safe (with generic):
+// Type-safe, with the generic parameter:
 type LoginEvent = PlayEvent<{ userId: string }>;
 const event: LoginEvent = { type: "auth.login", userId: "123" };
 ```
 
-**Common Event Patterns:**
+**The common event patterns:**
 
-- Domain events: `{ type: 'auth.login', userId: '123' }`
-- Custom events: `{ type: 'form.submit', data: {...} }`
+- A domain event: `{ type: 'auth.login', userId: '123' }`
+- Your own event: `{ type: 'form.submit', data: {...} }`
 
-**Routing Events** are provided by @xmachines/play-router:
+**The routing events** come from @xmachines/play-router:
 
-- PlayRouteEvent: Enhanced routing with parameters and state ID targeting
-- RouterBridge: Protocol for router adapters to connect with actors
+- PlayRouteEvent: the routing event with the parameters and the target state ID
+- RouterBridge: the protocol that connects a router adapter to an actor
 
-**Browser Navigation:** Browser back/forward buttons are handled by router adapters
-via the `popstate` event. When users press back/forward, the router detects the URL
-change and sends a PlayRouteEvent to the actor for validation.
+**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";
 ```
 
-## Architectural Invariants
+## The architectural invariants
 
-These protocols enforce the following invariants:
+These protocols enforce the invariants below:
 
-1. **Actor Authority**: Infrastructure proposes intents, Actor decides validity
-2. **Strict Separation**: No direct dependencies between layers
-3. **Passive Infrastructure**: Infrastructure observes Actor signals, never controls
-4. **Signal-Only Reactivity**: All state changes flow through TC39 Signals
-5. **State-Driven Reset**: Navigation follows state machine transition rules
+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
 

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

@@ -2,12 +2,12 @@
 
 # Class: NonNullableError
 
-Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L111)
+Defined in: [packages/play/src/errors.ts:110](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/errors.ts#L110)
 
-Thrown by [assertNonNullable](../functions/assertNonNullable.md) when a value is `null` or `undefined`.
+[assertNonNullable](../functions/assertNonNullable.md) throws this error when a value is `null` or `undefined`.
 
-Catch this specifically to distinguish a missing-value assertion failure from
-other runtime errors:
+Catch it to separate a failed assertion of a missing value from every other
+runtime error:
 
 ```ts
 import { NonNullableError } from "@xmachines/play/errors";
@@ -35,7 +35,7 @@ try {
 new NonNullableError(message, options?): NonNullableError;
 ```
 
-Defined in: [packages/play/src/errors.ts:112](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L112)
+Defined in: [packages/play/src/errors.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/errors.ts#L111)
 
 #### Parameters
 
@@ -57,10 +57,10 @@ Defined in: [packages/play/src/errors.ts:112](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 error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | [`PlayError`](PlayError.md).[`code`](PlayError.md#property-code)                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L75) |
+| <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.1.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 module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | [`PlayError`](PlayError.md).[`scope`](PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L66) |
+| <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.1.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,21 +2,21 @@
 
 # Class: PlayError
 
-Defined in: [packages/play/src/errors.ts:64](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L64)
+Defined in: [packages/play/src/errors.ts:62](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/errors.ts#L62)
 
-Base class for all typed runtime errors thrown by `@xmachines/*` packages.
+The base class of every typed runtime error of an `@xmachines/*` package.
 
-`PlayError` gives every error two structured fields:
+`PlayError` gives each error two structured fields:
 
-- `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
-- `code` — a stable, machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
+- `scope` — the class or the module that threw the error, for example `"RouterBridgeBase"`
+- `code` — a stable, machine-readable identifier, for example `"PLAY_ROUTER_SYNC_FAILED"`
 
-These fields let application code branch on error type without parsing `.message`
-strings, which change across releases.
+Your application code therefore branches on the type of an error, and it does not
+parse the `.message` string. A message changes between releases.
 
-## Error codes
+## The error codes
 
-Each `@xmachines/*` package exports its own typed subclasses from an
+An `@xmachines/*` package that defines typed subclasses exports them from an
 `"./errors"` subpath:
 
 | Package                      | Import                              |
@@ -25,13 +25,11 @@ Each `@xmachines/*` package exports its own typed subclasses from an
 | `@xmachines/play-router`     | `@xmachines/play-router/errors`     |
 | `@xmachines/play-vue-router` | `@xmachines/play-vue-router/errors` |
 | `@xmachines/play-xstate`     | `@xmachines/play-xstate/errors`     |
-| `@xmachines/play-react`      | `@xmachines/play-react/errors`      |
-| `@xmachines/play-solid`      | `@xmachines/play-solid/errors`      |
 
-`PlayError` itself is exported from the root `@xmachines/play` and is the base
-for all of those subclasses.
+The root `@xmachines/play` exports `PlayError` itself, and it is the base of every
+subclass above.
 
-## Catching errors by type
+## How to catch an error by its type
 
 ```typescript
 import { PlayError } from "@xmachines/play";
@@ -43,18 +41,18 @@ try {
 	if (err instanceof RouterSyncError) {
 		// err.scope === "RouterBridgeBase"
 		// err.code  === "PLAY_ROUTER_SYNC_FAILED"
-		// err.cause  — the original error that triggered the sync failure
+		// err.cause  — the original error of the failed synchronization
 		reportToMonitoring(err);
 	} else if (err instanceof PlayError) {
-		// Any other @xmachines/* error
+		// Every other @xmachines/* error
 		console.error(`[${err.scope}:${err.code}] ${err.message}`);
 	} else {
-		throw err; // Re-throw unknown errors
+		throw err; // Throw an unknown error again
 	}
 }
 ```
 
-## Extending PlayError
+## How to extend PlayError
 
 ```typescript
 import { PlayError } from "@xmachines/play";
@@ -87,16 +85,16 @@ new PlayError(
    options?): PlayError;
 ```
 
-Defined in: [packages/play/src/errors.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L83)
+Defined in: [packages/play/src/errors.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/errors.ts#L82)
 
 #### Parameters
 
-| Parameter  | Type           | Description                                                               |
-| ---------- | -------------- | ------------------------------------------------------------------------- |
-| `scope`    | `string`       | The class or module throwing this error.                                  |
-| `code`     | `string`       | Machine-readable error identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`).     |
-| `message`  | `string`       | Human-readable description. Do not match on this in code.                 |
-| `options?` | `ErrorOptions` | Standard `ErrorOptions`; pass `{ cause: originalError }` to chain errors. |
+| Parameter  | Type           | Description                                                                             |
+| ---------- | -------------- | --------------------------------------------------------------------------------------- |
+| `scope`    | `string`       | The class or the module that throws this error.                                         |
+| `code`     | `string`       | The machine-readable identifier of the error, for example `"PLAY_ROUTER_SYNC_FAILED"`.  |
+| `message`  | `string`       | The description for a person. Never match on it in your code.                           |
+| `options?` | `ErrorOptions` | The standard `ErrorOptions`. Give `{ cause: originalError }` to make a chain of errors. |
 
 #### Returns
 
@@ -113,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 error identifier. Error codes follow the `PLAY_<PACKAGE>_<DESCRIPTION>` naming convention and are guaranteed stable across patch and minor releases within a major version. Never match on `.message` — always match on `.code` or the subclass.                                                                                                                                                                       | -                       | [packages/play/src/errors.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L75) |
+| <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.1.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 module that threw this error (e.g. `"RouterBridgeBase"`).                                                                                                                                                                                                                                                                                                                                                                            | -                       | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/errors.ts#L66) |
+| <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.1.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/assertNonNullable.md

@@ -6,19 +6,19 @@
 function assertNonNullable<V>(value, name?): NonNullable<V>;
 ```
 
-Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0/packages/play/src/utils.ts#L39)
+Defined in: [packages/play/src/utils.ts:39](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play/src/utils.ts#L39)
 
-Assert that `value` is neither `null` nor `undefined`, and return it typed
-as `NonNullable<V>` — combining the guard and the narrowed value in a single
-expression.
+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
+value.
 
-Unlike a non-null assertion (`value!`), this throws a descriptive error at
-the point of failure rather than producing `undefined`-is-not-an-object`
-crashes somewhere downstream.
+A non-null assertion (`value!`) is different: it produces `undefined`, and your
+code then fails later with a message such as "undefined is not an object". This
+function throws a clear error at the point of the failure.
 
-Unlike an `asserts value is T` assertion function, this returns the narrowed
-value directly, so no separate variable or `as` cast is required at the call
-site.
+An assertion function of the form `asserts value is T` is also different: this
+function returns the narrowed value directly. Therefore the call site needs no
+second variable and no `as` cast.
 
 ## Type Parameters
 
@@ -28,16 +28,16 @@ site.
 
 ## Parameters
 
-| Parameter | Type     | Description                                                                                                          |
-| --------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
-| `value`   | `V`      | The value to check.                                                                                                  |
-| `name?`   | `string` | Optional name included in the error message to identify the missing value (e.g. the variable or injection key name). |
+| Parameter | Type     | Description                                                                                                                            |
+| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`   | `V`      | The value to check.                                                                                                                    |
+| `name?`   | `string` | The optional name in the error message. It identifies the missing value, for example the name of the variable or of the injection key. |
 
 ## Returns
 
 `NonNullable`\<`V`\>
 
-`value` typed as `NonNullable<V>` — `null` and `undefined` removed.
+`value` with the type `NonNullable<V>`, without `null` and without `undefined`.
 
 ## Throws
 
@@ -48,9 +48,9 @@ When `value` is `null` or `undefined`.
 ```ts
 import { assertNonNullable } from "@xmachines/play";
 
-// inject() + assertNonNullable in one line — no `!` or intermediate variable:
+// inject() and assertNonNullable in one line, with no `!` and no second variable:
 const actor = assertNonNullable(inject<AuthActor>("actor"), "actor");
 
-// Element lookup:
+// A lookup of an element:
 const el = assertNonNullable(document.getElementById("app"), "#app");
 ```