@xmachines/docs 3.0.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-3.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-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-3.0.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"`).
 
 ---
 
@@ -69,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");
@@ -91,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) {
@@ -176,8 +176,6 @@ pair.
 | 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 |
@@ -188,7 +186,7 @@ pair.
 
 | 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"` |
 
 ---
@@ -205,107 +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
-
-- [Cleanup](type-aliases/Cleanup.md)
-- [DisposeKey](type-aliases/DisposeKey.md)
-- [PlayEvent](type-aliases/PlayEvent.md)
-
-## Variables
-
-- [DISPOSE](variables/DISPOSE.md)
-
-## Functions
+## Modules
 
-- [asCleanup](functions/asCleanup.md)
-- [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/v3.0.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/v3.0.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/v3.0.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/v3.0.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/v3.0.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/v3.0.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/v3.0.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/v3.0.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/{functions → index/functions}/asCleanup.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / asCleanup
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / asCleanup
 
 # Function: asCleanup()
 
@@ -6,7 +6,7 @@
 function asCleanup<R>(release): Cleanup;
 ```
 
-Defined in: [packages/play/src/disposable.ts:150](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play/src/disposable.ts#L150)
+Defined in: [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).
 

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/v3.0.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

package/api/@xmachines/{play-actor → play/index}/functions/shallowEqualExcept.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-actor](../README.md) / shallowEqualExcept
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / shallowEqualExcept
 
 # Function: shallowEqualExcept()
 
@@ -6,7 +6,7 @@
 function shallowEqualExcept(a, b, except?): boolean;
 ```
 
-Defined in: [packages/play-actor/src/context-projection.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-actor/src/context-projection.ts#L58)
+Defined in: [packages/play/src/utils.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/utils.ts#L59)
 
 The shallow equality of the own keys, with `Object.is`. It can ignore one key on
 both sides.
@@ -14,7 +14,7 @@ both sides.
 This is the one comparison rule behind every decision of the emission dedup: the
 equality of a slice, and also the emit gate of the player, which compares the
 spec fields in `viewSpecsEquivalent` and reuses the composed state in
-[reuseComposedState](reuseComposedState.md).
+`reuseComposedState` of `@xmachines/play-view`.
 
 ## Parameters
 

package/api/@xmachines/play/{type-aliases → index/type-aliases}/Cleanup.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / Cleanup
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / Cleanup
 
 # Type Alias: Cleanup
 
@@ -6,7 +6,7 @@
 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)
+Defined in: [packages/play/src/disposable.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L66)
 
 The release of a subscription. A caller runs it, or a scope releases it.
 
@@ -35,4 +35,4 @@ the type. See [DisposeKey](DisposeKey.md) for the second half of that.
 
 ## See
 
-[Play RFC](../../../../rfc/play.md)
+[Play RFC](../../../../../rfc/play.md)

package/api/@xmachines/play/{type-aliases → index/type-aliases}/DisposeKey.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / DisposeKey
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / DisposeKey
 
 # Type Alias: DisposeKey
 
@@ -6,7 +6,7 @@
 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)
+Defined in: [packages/play/src/disposable.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L34)
 
 The dispose key of the ambient library, and `never` where the consumer omits it.
 

package/api/@xmachines/play/{type-aliases → index/type-aliases}/PlayEvent.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / PlayEvent
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / PlayEvent
 
 # Type Alias: PlayEvent\<TPayload\>
 
@@ -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/v3.0.0/packages/play/src/types.ts#L71)
+Defined in: [packages/play/src/types.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.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/v3.0.0/packages/play/src/types.ts#L72) |
+| `type` | `string` | [packages/play/src/types.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/types.ts#L72) |
 
 ## Type Parameters
 
@@ -79,4 +79,4 @@ const invalid: LoginEvent = { type: "auth.login" }; // Error!
 
 ## See
 
-[Play RFC](../../../../rfc/play.md)
+[Play RFC](../../../../../rfc/play.md)

package/api/@xmachines/play/{variables → index/variables}/DISPOSE.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play](../README.md) / DISPOSE
+[API](../../../../README.md) / [@xmachines/play](../../README.md) / [index](../README.md) / DISPOSE
 
 # Variable: DISPOSE
 
@@ -6,7 +6,7 @@
 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)
+Defined in: [packages/play/src/disposable.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play/src/disposable.ts#L94)
 
 The key that a release is stored under.