@xmachines/docs 4.0.0 → 5.0.0

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

@@ -2,9 +2,9 @@
 
 # @xmachines/play-xstate
 
-> XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with signal-driven reactivity and a router integration.
+> XState v5 adapter for the XMachines Play Architecture. It binds a state machine to the actor base, with atom-driven reactivity and a router integration.
 
-[![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-xstate)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-5.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 ---
 
@@ -15,10 +15,24 @@
 ## Installation
 
 ```bash
-pnpm add @xmachines/play-xstate xstate
+pnpm add @xmachines/play-xstate @xmachines/play @xmachines/play-atom xstate
 ```
 
-`xstate ^5.33.0` is a peer dependency. Install it with this package.
+**Peer dependencies.** Install them with the package:
+
+- [`@xmachines/play`](../play/README.md) — the core protocol. This package reads `shallowEqualExcept` and `DISPOSE` from it.
+- [`@xmachines/play-atom`](../play-atom/README.md) — the atom primitives. `PlayerActor` holds `currentView` and `currentRoute` as atoms.
+- `xstate` ^5.33.0 — the XState v5 runtime.
+
+**Optional peers.** Each capability subpath carries one. Install it when you read that subpath, and not before:
+
+```bash
+pnpm add @xmachines/play-router   # @xmachines/play-xstate/routing
+pnpm add @xmachines/play-view     # @xmachines/play-xstate/view
+```
+
+- [`@xmachines/play-router`](../play-router/README.md) — the routing capability reads `Routable`, `PlayRouteEvent` and `RouteData` from it.
+- [`@xmachines/play-view`](../play-view/README.md) — the view capability reads `composePlayState`, `PlaySpec` and `Viewable` from it.
 
 ---
 
@@ -45,7 +59,7 @@ const createPlayer = definePlayer({ machine, actor: compose(PlayerActor, withRou
 const actor = createPlayer();
 actor.start();
 
-// 4. Observe TC39 Signal-based reactive state
+// 4. Observe atom-based reactive state
 console.log(actor.currentRoute.get()); // "/"
 console.log(actor.state.get().value); // "idle"
 
@@ -134,13 +148,13 @@ console.log(restored.currentRoute.get()); // same route as when saved
 
 ### `PlayerActor<TMachine>`
 
-This concrete actor class is an XState v5 actor that exposes reactive TC39 Signals. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
+This concrete actor class is an XState v5 actor that exposes reactive atoms. It holds the protocol of `PlayActor` and nothing else: `state` and `send`.
 
-#### Signals
+#### Atoms
 
-| Signal  | Type                                   | Description                                                                  |
-| ------- | -------------------------------------- | ---------------------------------------------------------------------------- |
-| `state` | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
+| Atom    | Type                           | Description                                                                  |
+| ------- | ------------------------------ | ---------------------------------------------------------------------------- |
+| `state` | `Atom<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition |
 
 ### The capabilities
 
@@ -156,12 +170,12 @@ pnpm add @xmachines/play-view     # for @xmachines/play-xstate/view
 The main entry point of this package names neither. `@xmachines/play-xstate/routing` also
 carries the route utilities — `deriveRoute`, `isAbsoluteRoute`, `buildRouteUrl`,
 `formatPlayRouteTransitions` and the route types — because each one names
-`@xmachines/play-router` in its own types.
+[`@xmachines/play-router`](../play-router/README.md) in its own types.
 
-| Capability | Entry point                      | Adds                           | Interface                              |
-| ---------- | -------------------------------- | ------------------------------ | -------------------------------------- |
-| Routing    | `@xmachines/play-xstate/routing` | `currentRoute`, `initialRoute` | `Routable` of `@xmachines/play-router` |
-| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of `@xmachines/play-view`   |
+| Capability | Entry point                      | Adds                           | Interface                                                          |
+| ---------- | -------------------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| Routing    | `@xmachines/play-xstate/routing` | `currentRoute`, `initialRoute` | `Routable` of [`@xmachines/play-router`](../play-router/README.md) |
+| View       | `@xmachines/play-xstate/view`    | `currentView`                  | `Viewable` of [`@xmachines/play-view`](../play-view/README.md)     |
 
 `compose` applies each capability from left to right:
 
@@ -183,7 +197,7 @@ const createRouted = definePlayer({ machine, actor: compose(PlayerActor, withRou
 const createBare = definePlayer({ machine });
 ```
 
-**Compose `withView` after `withRouting`.** An override calls `super.onSnapshot()` first, so the composition order decides the derivation order: the route holds its new value before the view derives from the same transition. A router bridge therefore sees a guard redirect before a renderer sees the view of the state that the guard refused.
+**The composition ORDER decides nothing.** `currentRoute` and `currentView` are computed atoms over `state`, and neither reads the other, so one write for each transition reaches both and the engine evaluates them in topological order. A router bridge therefore sees a guard redirect and a renderer sees the view of the same snapshot, whatever order `compose` applied. A release before this one wrote `currentView` from an `onSnapshot` override, and the order was load-bearing there.
 
 **A lifecycle hook receives the bare actor.** `PlayerOptions` is typed before the class is composed, so it cannot name the capabilities, and a narrower hook parameter is refused under `strictFunctionTypes`. A hook that reads `currentRoute` or `currentView` reads them through a binding of the composed type:
 
@@ -198,11 +212,27 @@ const actor = definePlayer({
 composed = actor;
 ```
 
-| Signal         | Type                              | Capability | Description                                                                                                                              |
-| -------------- | --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `currentRoute` | `Signal.Computed<string \| null>` | routing    | The URL that comes from the `meta.route` template of the active state and from the context                                               |
-| `initialRoute` | `readonly string \| null`         | routing    | The route of the initial state of the machine. The construction fixes it, and a router bridge uses it to detect a deep link or a restore |
-| `currentView`  | `Signal.State<PlaySpec \| null>`  | view       | The view spec from the `meta.view` metadata of the active state, with the context params added                                           |
+| Atom           | Type                             | Capability | Description                                                                                                                              |
+| -------------- | -------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentRoute` | `ReadonlyAtom<string \| null>`   | routing    | The URL that comes from the `meta.route` template of the active state and from the context                                               |
+| `initialRoute` | `readonly string \| null`        | routing    | The route of the initial state of the machine. The construction fixes it, and a router bridge uses it to detect a deep link or a restore |
+| `currentView`  | `ReadonlyAtom<PlaySpec \| null>` | view       | The view spec from the `meta.view` metadata of the active state, with the context params added                                           |
+
+`state` is the ONE atom that the actor writes. `currentRoute` and `currentView` are
+COMPUTED over it, so one write for each transition reaches both in one propagation and no
+observer reads the new state beside an old derivation. Each derivation reports a failure
+through the `onError` option and keeps its last good value; it throws never, because it
+runs inside the write.
+
+**`currentRoute` notifies on every transition, and `currentView` notifies on a change of
+the view alone.** The two atoms answer two different questions. A router bridge needs the
+answer of the actor to each event that it proposed, and a guard that refuses an inbound
+location and holds the machine where it was derives the SAME path — so `currentRoute`
+compares "different" always, and the bridge learns that the address bar must go back.
+`currentView` gates its emission on the value, and a snapshot that changes no view on the
+screen keeps the previous reference, so a provider below it mounts the UI again not on
+every event. Debounce your own `watchAtom(actor.currentRoute, ...)` callback, or compare
+the path yourself, when you run work that belongs to a change of the route alone.
 
 #### Methods
 
@@ -215,19 +245,19 @@ composed = actor;
 | `getSnapshot()` | Returns the current XState snapshot                                       |
 | `[DISPOSE]()`   | Stops the actor at the end of a `using` scope. The release is `stop()`    |
 
-#### Signal usage example
+#### Atom usage example
 
 ```typescript
-import { Signal } from "@xmachines/play-signals";
+import { watchAtom } from "@xmachines/play-atom";
 
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		console.log("Route changed:", actor.currentRoute.get());
-	});
+const stop = watchAtom(actor.currentRoute, (route) => {
+	console.log("Route changed:", route);
 });
 
-watcher.watch(actor.currentRoute);
 actor.start();
+
+// Later, on teardown
+stop();
 ```
 
 ---
@@ -373,7 +403,7 @@ import type {
 ```
 
 `RouteObject`, `RouteMetadata`, `RouteData`, and `RouteDataResolver` have one
-definition, and it lives in `@xmachines/play-router`. `@xmachines/play-xstate/routing`
+definition, and it lives in [`@xmachines/play-router`](../play-router/README.md). `@xmachines/play-xstate/routing`
 re-exports them, so either import path gives you the same type. The MAIN entry point of
 this package re-exports them no longer: it would name an optional peer in the types of
 every consumer, including one that composes no routing.
@@ -437,6 +467,7 @@ The `@xmachines/play-xstate/errors` subpath exports the error classes. The main
 ```typescript
 import {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
+	InvalidRouteParamError, // A :param carries a dot segment, which a URL resolves away
 	MissingStateIdError, // meta.route declared without a state id field
 	InvalidMachineError, // PlayerActor constructed with a non-object machine
 	InvalidEventError, // actor.send() called with null/undefined/non-object
@@ -446,7 +477,7 @@ import {
 } from "@xmachines/play-xstate/errors";
 ```
 
-Every error class extends `PlayError` from `@xmachines/play/errors`. Each class also carries typed detail fields, such as `param`, `template`, and `handler`. Your code therefore reads the details of an error, and it does not parse the message.
+Every error class extends `PlayError` from [`@xmachines/play/errors`](../play/README.md). Each class also carries typed detail fields, such as `param`, `template`, and `handler`. Your code therefore reads the details of an error, and it does not parse the message.
 
 ---
 

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

@@ -9,5 +9,6 @@
 - [InvalidMachineError](classes/InvalidMachineError.md)
 - [InvalidRouteHandlerError](classes/InvalidRouteHandlerError.md)
 - [InvalidRouteMetadataError](classes/InvalidRouteMetadataError.md)
+- [InvalidRouteParamError](classes/InvalidRouteParamError.md)
 - [MissingRouteParamError](classes/MissingRouteParamError.md)
 - [MissingStateIdError](classes/MissingStateIdError.md)

package/api/@xmachines/play-xstate/errors/classes/ActorThrewNonErrorError.md

@@ -2,7 +2,7 @@
 
 # Class: ActorThrewNonErrorError
 
-Defined in: [packages/play-xstate/src/errors.ts:295](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L295)
+Defined in: [packages/play-xstate/src/errors.ts:347](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L347)
 
 The actor gives this error to `PlayerOptions.onError` when it failed with a value
 that is not an `Error`, for example after a machine action ran
@@ -46,7 +46,7 @@ definePlayer({
 new ActorThrewNonErrorError(value): ActorThrewNonErrorError;
 ```
 
-Defined in: [packages/play-xstate/src/errors.ts:296](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L296)
+Defined in: [packages/play-xstate/src/errors.ts:348](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L348)
 
 #### Parameters
 
@@ -67,10 +67,10 @@ Defined in: [packages/play-xstate/src/errors.ts:296](https://gitlab.com/xmachin-
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/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-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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L76) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/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-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L66) |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                          |
 

package/api/@xmachines/play-xstate/errors/classes/InvalidEventError.md

@@ -2,7 +2,7 @@
 
 # Class: InvalidEventError
 
-Defined in: [packages/play-xstate/src/errors.ts:250](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L250)
+Defined in: [packages/play-xstate/src/errors.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L302)
 
 `PlayerActor.send()` throws this error when the event argument is not a plain
 object.
@@ -44,7 +44,7 @@ try {
 new InvalidEventError(detail): InvalidEventError;
 ```
 
-Defined in: [packages/play-xstate/src/errors.ts:254](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L254)
+Defined in: [packages/play-xstate/src/errors.ts:306](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L306)
 
 #### Parameters
 
@@ -65,11 +65,11 @@ Defined in: [packages/play-xstate/src/errors.ts:254](https://gitlab.com/xmachin-
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/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-detail"></a> `detail`                   | `readonly` | `unknown` | The value in question, from the `send()` call.                                                                                                                                                                                                                                                                                                                                                                                                    | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:252](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L252) |
+| <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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L76)                 |
+| <a id="property-detail"></a> `detail`                   | `readonly` | `unknown` | The value in question, from the `send()` call.                                                                                                                                                                                                                                                                                                                                                                                                    | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:304](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L304) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/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-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L66)                 |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                                          |
 

package/api/@xmachines/play-xstate/errors/classes/InvalidMachineError.md

@@ -2,7 +2,7 @@
 
 # Class: InvalidMachineError
 
-Defined in: [packages/play-xstate/src/errors.ts:128](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L128)
+Defined in: [packages/play-xstate/src/errors.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L180)
 
 The `PlayerActor` constructor throws this error when the `machine` argument is not
 a valid XState machine object, which means that it is null, undefined, or not an
@@ -22,7 +22,7 @@ object.
 new InvalidMachineError(): InvalidMachineError;
 ```
 
-Defined in: [packages/play-xstate/src/errors.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L129)
+Defined in: [packages/play-xstate/src/errors.ts:181](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L181)
 
 #### Returns
 
@@ -37,10 +37,10 @@ Defined in: [packages/play-xstate/src/errors.ts:129](https://gitlab.com/xmachin-
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/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-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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L76) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/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-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L66) |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                          |
 

package/api/@xmachines/play-xstate/errors/classes/InvalidRouteHandlerError.md

@@ -2,7 +2,7 @@
 
 # Class: InvalidRouteHandlerError
 
-Defined in: [packages/play-xstate/src/errors.ts:206](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L206)
+Defined in: [packages/play-xstate/src/errors.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L258)
 
 `formatPlayRouteTransitions()` throws this error for a `meta.route` object whose
 `handler` field holds a value that the routing layer does not know.
@@ -42,7 +42,7 @@ try {
 new InvalidRouteHandlerError(handler, source?): InvalidRouteHandlerError;
 ```
 
-Defined in: [packages/play-xstate/src/errors.ts:210](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L210)
+Defined in: [packages/play-xstate/src/errors.ts:262](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L262)
 
 #### Parameters
 
@@ -64,11 +64,11 @@ Defined in: [packages/play-xstate/src/errors.ts:210](https://gitlab.com/xmachin-
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/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-handler"></a> `handler`                 | `readonly` | `string`  | The value that the config declared, as a string, for the debug work.                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:208](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L208) |
+| <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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L76)                 |
+| <a id="property-handler"></a> `handler`                 | `readonly` | `string`  | The value that the config declared, as a string, for the debug work.                                                                                                                                                                                                                                                                                                                                                                              | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L260) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/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-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L66)                 |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                                          |
 

package/api/@xmachines/play-xstate/errors/classes/InvalidRouteMetadataError.md

@@ -2,7 +2,7 @@
 
 # Class: InvalidRouteMetadataError
 
-Defined in: [packages/play-xstate/src/errors.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L164)
+Defined in: [packages/play-xstate/src/errors.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L216)
 
 `normalizeRoute()` throws this error when the `meta.route` value of a state is not
 a string and not an object with a `path` property.
@@ -21,7 +21,7 @@ a string and not an object with a `path` property.
 new InvalidRouteMetadataError(route, source?): InvalidRouteMetadataError;
 ```
 
-Defined in: [packages/play-xstate/src/errors.ts:168](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L168)
+Defined in: [packages/play-xstate/src/errors.ts:220](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L220)
 
 #### Parameters
 
@@ -43,11 +43,11 @@ Defined in: [packages/play-xstate/src/errors.ts:168](https://gitlab.com/xmachin-
 | Property                                                | Modifier   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       | Inherited from                                                                                                                                   | Defined in                                                                                                                                 |
 | ------------------------------------------------------- | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | <a id="property-cause"></a> `cause?`                    | `public`   | `unknown` | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`cause`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/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-detail"></a> `detail`                   | `readonly` | `string`  | The invalid route value, as a string, for the debug work.                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:166](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-xstate/src/errors.ts#L166) |
+| <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`](../../../play/errors/classes/PlayError.md).[`code`](../../../play/errors/classes/PlayError.md#property-code)                       | [packages/play/src/errors.ts:76](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L76)                 |
+| <a id="property-detail"></a> `detail`                   | `readonly` | `string`  | The invalid route value, as a string, for the debug work.                                                                                                                                                                                                                                                                                                                                                                                         | -                                                                                                                                                | [packages/play-xstate/src/errors.ts:218](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play-xstate/src/errors.ts#L218) |
 | <a id="property-message"></a> `message`                 | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`message`](../../../play/errors/classes/PlayError.md#property-message)                 | -                                                                                                                                          |
 | <a id="property-name"></a> `name`                       | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`name`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/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-scope"></a> `scope`                     | `readonly` | `string`  | The class or the module that threw this error, for example `"RouterBridgeBase"`.                                                                                                                                                                                                                                                                                                                                                                  | [`PlayError`](../../../play/errors/classes/PlayError.md).[`scope`](../../../play/errors/classes/PlayError.md#property-scope)                     | [packages/play/src/errors.ts:66](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.0/packages/play/src/errors.ts#L66)                 |
 | <a id="property-stack"></a> `stack?`                    | `public`   | `string`  | -                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [`PlayError`](../../../play/errors/classes/PlayError.md).[`stack`](../../../play/errors/classes/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`](../../../play/errors/classes/PlayError.md).[`stackTraceLimit`](../../../play/errors/classes/PlayError.md#property-stacktracelimit) | -                                                                                                                                          |