@xmachines/play-xstate 2.0.0 → 2.1.0

package/README.md

@@ -1,10 +1,8 @@
 # @xmachines/play-xstate
 
-> XState v5 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and router integration.
+> 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.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
-
-Part of the [XMachines Play](../../README.md) monorepo.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-2.1.0-blue)](https://www.npmjs.com/package/@xmachines/play-xstate)
 
 ---
 
@@ -14,7 +12,7 @@ Part of the [XMachines Play](../../README.md) monorepo.
 pnpm add @xmachines/play-xstate xstate
 ```
 
-`xstate ^5.31.0` is a peer dependency and must be installed alongside this package.
+`xstate ^5.31.0` is a peer dependency. Install it with this package.
 
 ---
 
@@ -28,7 +26,7 @@ import { definePlayer } from "@xmachines/play-xstate";
 const machine = setup({}).createMachine({
 	initial: "idle",
 	states: {
-		idle: { meta: { route: "/" } },
+		idle: { meta: { route: "/" }, on: { activate: "active" } },
 		active: { meta: { route: "/active" } },
 	},
 });
@@ -56,7 +54,7 @@ actor.stop();
 
 ### `definePlayer(config)`
 
-Creates a `PlayerFactory` from an XState v5 machine. The factory pattern enables multiple independent actor instances from a single configuration — useful for multi-user scenarios, SSR, or testing.
+This function creates a `PlayerFactory` from an XState v5 machine. One configuration can therefore make more than one independent actor instance. This helps with a multi-user application, with SSR, and with a test.
 
 ```typescript
 import { setup } from "xstate";
@@ -92,9 +90,9 @@ const bob = createPlayer({ userId: "bob" });
 
 #### `PlayerFactory` signature
 
-`input` requiredness mirrors XState's `createActor`: a machine whose input type
-cannot be `undefined` makes the factory's first argument required, so forgetting
-it is a compile error instead of an actor stuck in an error status.
+The `input` argument follows the rule of `createActor` in XState. If the input type of a
+machine cannot be `undefined`, the first argument of the factory is necessary. An absent
+input is then a compile error, not an actor that stops in an error status.
 
 ```typescript
 type PlayerFactory<TMachine> =
@@ -121,35 +119,35 @@ restored.start();
 console.log(restored.currentRoute.get()); // same route as when saved
 ```
 
-> **Note:** Persist with `getPersistedSnapshot()`, not `getSnapshot()` — it is
-> the form `createActor` accepts, and the only one that round-trips machines
-> with invoked or spawned children.
+> **Note:** persist the state with `getPersistedSnapshot()`, not with
+> `getSnapshot()`. `createActor` accepts that form only, and it is the only form
+> that restores a machine with an invoked child or a spawned child.
 
 ---
 
 ### `PlayerActor<TMachine>`
 
-Concrete actor class: an XState v5 actor that also exposes TC39 Signal-based reactive signals. Implements both `Routable` and `Viewable` interfaces from `@xmachines/play-actor`.
+This concrete actor class is an XState v5 actor that also exposes reactive TC39 Signals. It implements both the `Routable` interface and the `Viewable` interface from `@xmachines/play-actor`.
 
 #### Signals
 
-| Signal         | Type                                   | Description                                                                                                      |
-| -------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `state`        | `Signal.State<SnapshotFrom<TMachine>>` | Current XState snapshot; updated on every active transition                                                      |
-| `currentRoute` | `Signal.Computed<string \| null>`      | Derived URL from active state's `meta.route` template and context                                                |
-| `currentView`  | `Signal.State<PlaySpec \| null>`       | View spec from active state's `meta.view` metadata; enriched with context params                                 |
-| `initialRoute` | `readonly string \| null`              | Machine's initial-state route (fixed at construction; used by router bridges for deep-link vs restore detection) |
+| Signal         | Type                                   | Description                                                                                                                             |
+| -------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `state`        | `Signal.State<SnapshotFrom<TMachine>>` | The current XState snapshot. The actor updates it on every active transition                                                            |
+| `currentRoute` | `Signal.Computed<string \| null>`      | The URL that comes from the `meta.route` template of the active state and from the context                                              |
+| `currentView`  | `Signal.State<PlaySpec \| null>`       | The view spec from the `meta.view` metadata of the active state, with the context params added                                          |
+| `initialRoute` | `readonly string \| null`              | The route of the initial state of the machine. The constructor fixes it, and a router bridge uses it to detect a deep link or a restore |
 
 #### Methods
 
-| Method          | Description                                                    |
-| --------------- | -------------------------------------------------------------- |
-| `start()`       | Start the actor and fire `onStart` hook                        |
-| `stop()`        | Stop the actor, clean up subscriptions, fire `onStop` hook     |
-| `send(event)`   | Send a typed event to the machine; fires `onTransition` hook   |
-| `can(event)`    | Returns `true` if the current state can accept the given event |
-| `getSnapshot()` | Returns the current XState snapshot                            |
-| `dispose()`     | Alias for `stop()`                                             |
+| Method          | Description                                                               |
+| --------------- | ------------------------------------------------------------------------- |
+| `start()`       | Starts the actor and calls the `onStart` hook                             |
+| `stop()`        | Stops the actor, cleans up the subscriptions, and calls the `onStop` hook |
+| `send(event)`   | Sends a typed event to the machine and calls the `onTransition` hook      |
+| `can(event)`    | Returns `true` when the current state accepts the given event             |
+| `getSnapshot()` | Returns the current XState snapshot                                       |
+| `dispose()`     | The alias of `stop()`                                                     |
 
 #### Signal usage example
 
@@ -170,11 +168,12 @@ actor.start();
 
 ### Guard utilities
 
-> **Deprecated:** the guard helpers wrap XState's own `and()` / `or()` / `not()`
-> combinators without composing with `setup()`-typed guard slots. Use XState's
-> combinators directly; this module will be removed in the next major.
+> **Deprecated:** these guard helpers wrap the `and()`, `or()`, and `not()`
+> combinators of XState, but they do not compose with a guard slot that
+> `setup()` types. Use the combinators of XState directly. The next major
+> version removes this module.
 
-Composable guard helpers that wrap XState's built-in `and()`, `or()`, and `not()` for use in machine `setup({ guards })` definitions.
+These composable guard helpers wrap the `and()`, `or()`, and `not()` functions of XState. Use them in a machine `setup({ guards })` definition.
 
 ```typescript
 import { setup } from "xstate";
@@ -198,9 +197,9 @@ const machine = setup({
 			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
 			target: "adminPanel",
 		},
-		accessDashboard: {
-			guard: negateGuard("isGuest"),
-			target: "dashboard",
+		accessLogin: {
+			guard: negateGuard("isLoggedIn"),
+			target: "login",
 		},
 	},
 	// ...
@@ -211,11 +210,11 @@ const machine = setup({
 
 ### Routing utilities
 
-Helper functions for declarative route configuration in XState machines.
+These helper functions configure the routes of an XState machine declaratively.
 
 #### `formatPlayRouteTransitions(machineConfig)`
 
-Crawls machine states with `meta.route` and auto-generates `play.route` event handlers at the root level — eliminating boilerplate routing transitions.
+This function reads each machine state that has a `meta.route` field. It then generates the `play.route` event handlers at the root level. You therefore write no repetitive routing transition.
 
 ```typescript
 import { setup } from "xstate";
@@ -240,23 +239,23 @@ const config = formatPlayRouteTransitions({
 const machine = setup({}).createMachine(config);
 ```
 
-> **Note:** Every state with `meta.route` must also have an explicit `id` field; omitting it throws `MissingStateIdError` at machine-definition time.
+> **Note:** every state with a `meta.route` field must also have an explicit `id` field. A state without an `id` field throws `MissingStateIdError` when you define the machine.
 
 #### Other routing exports
 
-| Export                             | Description                                                               |
-| ---------------------------------- | ------------------------------------------------------------------------- |
-| `deriveRoute(meta)`                | Extract the route template string from a state's metadata object          |
-| `isAbsoluteRoute(route)`           | Returns `true` if the route string is an absolute URL path                |
-| `buildRouteUrl(template, context)` | Substitute `:param` placeholders in a route template using context values |
+| Export                             | Description                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------- |
+| `deriveRoute(meta)`                | Reads the route template string from the metadata object of a state         |
+| `isAbsoluteRoute(route)`           | Returns `true` when the route string is an absolute URL path                |
+| `buildRouteUrl(template, context)` | Replaces each `:param` placeholder of a route template with a context value |
 
 ---
 
 ## Inspection
 
-`options.inspect` is forwarded verbatim to XState's `createActor`, so every XState
-inspection tool — [`@statelyai/inspect`](https://stately.ai/docs/inspector)
-included — works against a `PlayerActor` unchanged:
+The factory gives `options.inspect` to `createActor` of XState without a change.
+Therefore every XState inspection tool works with a `PlayerActor`, and this
+includes [`@statelyai/inspect`](https://stately.ai/docs/inspector):
 
 ```typescript
 import { createBrowserInspector } from "@statelyai/inspect";
@@ -265,25 +264,27 @@ const { inspect } = createBrowserInspector();
 const createPlayer = definePlayer({ machine, options: { inspect } });
 ```
 
-Three things are worth knowing:
+Three points are important:
 
-- **It is a factory option, not a per-instance one.** Every actor a factory creates
-  reports to the same observer. Demultiplex by root: `event.rootId === actor.sessionId`
-  covers an actor's whole tree, children included.
-- **It is the only route that sees construction.** `actor.system.inspect(fn)` attaches
-  later and only sees events from that point on — including missing the `@xstate.actor`
-  registration an inspector needs in order to draw the machine at all.
-- **A `PlayerActor` is the actor.** Its own events carry `actorRef === playerActor`, so a
-  player can be recognised by identity. The one caveat: `@xstate.actor` fires from inside
-  the constructor, where `state`, `currentRoute`, `currentView` and `initialRoute` do not
-  exist yet — reading them there throws.
+- **`inspect` is an option of the factory, not of one instance.** Every actor of a
+  factory reports to the same observer. Separate the actors by root:
+  `event.rootId === actor.sessionId` covers the complete tree of an actor, with its
+  children.
+- **`inspect` is the only path that sees the construction.** `actor.system.inspect(fn)`
+  attaches later, and it sees only the events after that moment. It therefore misses the
+  `@xstate.actor` registration, and an inspector needs that registration to draw the
+  machine.
+- **A `PlayerActor` is the actor.** Its own events carry `actorRef === playerActor`, so
+  you can recognize a player by its identity. Note one point: `@xstate.actor` fires from
+  inside the constructor, and `state`, `currentRoute`, `currentView`, and `initialRoute`
+  do not exist yet. A read of one of them there throws.
 
-For an inspector created after the factory (a dev-tools toggle, say), pass a forwarding
-function: `inspect: (event) => currentInspector?.(event)`.
+For an inspector that you create after the factory, such as a dev-tools switch, give the
+factory a function that forwards each event: `inspect: (event) => currentInspector?.(event)`.
 
-See the [inspector guide](../docs/guides/inspector.md) for the full walkthrough —
-late attachment with replay, browser-free WebSocket inspection, and production
-considerations.
+The [inspector guide](../docs/guides/inspector.md) gives the complete procedure: a late
+attachment with a replay, a WebSocket inspection without a browser, and the points to
+consider in production.
 
 ---
 
@@ -310,7 +311,7 @@ import type {
 
 ## Error Classes
 
-Error classes are exported from the `@xmachines/play-xstate/errors` sub-path to keep the main bundle lean.
+The `@xmachines/play-xstate/errors` subpath exports the error classes. The main bundle therefore stays small.
 
 ```typescript
 import {
@@ -325,7 +326,7 @@ import {
 } from "@xmachines/play-xstate/errors";
 ```
 
-All error classes extend `PlayError` from `@xmachines/play` and carry typed detail fields (`param`, `template`, `combinator`, etc.) for programmatic inspection without message parsing.
+Every error class extends `PlayError` from `@xmachines/play`. Each class also carries typed detail fields, such as `param`, `template`, and `combinator`. Your code therefore reads the details of an error, and it does not parse the message.
 
 ---
 
@@ -339,7 +340,7 @@ pnpm --filter @xmachines/play-xstate test
 pnpm --filter @xmachines/play-xstate run test:watch
 ```
 
-Tests use [Vitest](https://vitest.dev/) and live in `packages/play-xstate/test/`.
+The tests use [Vitest](https://vitest.dev/). They are in `packages/play-xstate/test/`.
 
 ---
 

package/dist/define-player.d.ts

@@ -1,23 +1,23 @@
 import type { AnyStateMachine } from "xstate";
 import type { PlayerConfig, PlayerFactory } from "./types.js";
 /**
- * Create a player factory from an XState machine
+ * Creates a player factory from an XState machine
  *
- * Factory pattern that accepts an XState v5 machine,
- * returning a function that creates {@link PlayerActor} instances. This enables
- * creating multiple actor instances from a single configuration, useful for
- * testing, multi-instance scenarios, or server-side rendering.
+ * This factory function accepts an XState v5 machine. It returns a function that
+ * makes {@link PlayerActor} instances. One configuration can therefore make more
+ * than one actor instance, and this helps with a test, with an application of
+ * several instances, and with a render on the server.
  *
- * @typeParam TMachine - XState v5 state machine type
+ * @typeParam TMachine - The type of the XState v5 state machine
  *
- * @param config - Player configuration object
- * @param config.machine - XState v5 state machine
- * @param config.options - Optional lifecycle hooks (onStart, onTransition, etc.)
+ * @param config - The configuration object of the player
+ * @param config.machine - The XState v5 state machine
+ * @param config.options - The optional lifecycle hooks: onStart, onTransition, and the others
  *
- * @returns Factory function that creates actor instances with optional input context
+ * @returns The factory function. It makes an actor instance, with an optional input context
  *
  * @example
- * Basic player factory
+ * A basic player factory
  * ```typescript
  * import { setup } from "xstate";
  * import { definePlayer } from "@xmachines/play-xstate";
@@ -36,25 +36,25 @@ import type { PlayerConfig, PlayerFactory } from "./types.js";
  * ```
  *
  * @example
- * Multiple actor instances from single factory
+ * More than one actor instance from one factory
  * ```typescript
  * const createPlayer = definePlayer({ machine });
  *
- * // Create actors for different users
+ * // Create an actor for each user
  * const alice = createPlayer({ userId: 'alice' });
  * const bob = createPlayer({ userId: 'bob' });
  *
  * alice.start();
  * bob.start();
  *
- * // Independent state machines
+ * // The two state machines are independent
  * console.log(alice.state.get() !== bob.state.get());
  * ```
  *
  * @see [Play RFC](../../docs/rfc/play.md)
  * @see {@link PlayerActor} for the concrete actor implementation
- * @see {@link PlayerConfig} for configuration options
- * @see {@link PlayerFactory} for factory function signature
+ * @see {@link PlayerConfig} for the configuration options
+ * @see {@link PlayerFactory} for the signature of the factory function
  */
 export declare const definePlayer: <TMachine extends AnyStateMachine>(config: PlayerConfig<TMachine>) => PlayerFactory<TMachine>;
 //# sourceMappingURL=define-player.d.ts.map

package/dist/define-player.js

@@ -1,22 +1,22 @@
 import { PlayerActor } from "./player-actor.js";
 /**
- * Create a player factory from an XState machine
+ * Creates a player factory from an XState machine
  *
- * Factory pattern that accepts an XState v5 machine,
- * returning a function that creates {@link PlayerActor} instances. This enables
- * creating multiple actor instances from a single configuration, useful for
- * testing, multi-instance scenarios, or server-side rendering.
+ * This factory function accepts an XState v5 machine. It returns a function that
+ * makes {@link PlayerActor} instances. One configuration can therefore make more
+ * than one actor instance, and this helps with a test, with an application of
+ * several instances, and with a render on the server.
  *
- * @typeParam TMachine - XState v5 state machine type
+ * @typeParam TMachine - The type of the XState v5 state machine
  *
- * @param config - Player configuration object
- * @param config.machine - XState v5 state machine
- * @param config.options - Optional lifecycle hooks (onStart, onTransition, etc.)
+ * @param config - The configuration object of the player
+ * @param config.machine - The XState v5 state machine
+ * @param config.options - The optional lifecycle hooks: onStart, onTransition, and the others
  *
- * @returns Factory function that creates actor instances with optional input context
+ * @returns The factory function. It makes an actor instance, with an optional input context
  *
  * @example
- * Basic player factory
+ * A basic player factory
  * ```typescript
  * import { setup } from "xstate";
  * import { definePlayer } from "@xmachines/play-xstate";
@@ -35,25 +35,25 @@ import { PlayerActor } from "./player-actor.js";
  * ```
  *
  * @example
- * Multiple actor instances from single factory
+ * More than one actor instance from one factory
  * ```typescript
  * const createPlayer = definePlayer({ machine });
  *
- * // Create actors for different users
+ * // Create an actor for each user
  * const alice = createPlayer({ userId: 'alice' });
  * const bob = createPlayer({ userId: 'bob' });
  *
  * alice.start();
  * bob.start();
  *
- * // Independent state machines
+ * // The two state machines are independent
  * console.log(alice.state.get() !== bob.state.get());
  * ```
  *
  * @see [Play RFC](../../docs/rfc/play.md)
  * @see {@link PlayerActor} for the concrete actor implementation
- * @see {@link PlayerConfig} for configuration options
- * @see {@link PlayerFactory} for factory function signature
+ * @see {@link PlayerConfig} for the configuration options
+ * @see {@link PlayerFactory} for the signature of the factory function
  */
 export const definePlayer = (config) => {
     const { machine, options } = config;

package/dist/errors.d.ts

@@ -1,16 +1,16 @@
 import { PlayError } from "@xmachines/play";
 /**
- * Thrown by `buildRouteUrl()` when a required route parameter is absent from the
- * actor's context.
+ * `buildRouteUrl()` throws this error when the context of the actor does not hold a
+ * necessary route parameter.
  *
- * Use the `param` and `template` fields to identify the missing parameter without
- * parsing the `.message` string.
+ * Read the `param` field and the `template` field to identify the parameter that is
+ * absent. Your code therefore parses no `.message` string.
  *
  * **Error code:** `PLAY_XSTATE_ROUTE_PARAM_MISSING`
  *
- * Note: `actor.currentRoute.get()` never surfaces this error — route
- * derivation catches it and returns `null` for the transient mid-transition
- * case. It only escapes direct `buildRouteUrl()` calls.
+ * Note: `actor.currentRoute.get()` shows this error never. The route derivation
+ * catches it, and it returns `null` for the temporary case during a transition. The
+ * error leaves a direct `buildRouteUrl()` call only.
  *
  * @example
  * ```typescript
@@ -29,23 +29,23 @@ import { PlayError } from "@xmachines/play";
  * ```
  */
 export declare class MissingRouteParamError extends PlayError {
-    /** The name of the route parameter that was missing (e.g. `"userId"`). */
+    /** The name of the route parameter that was absent, for example `"userId"`. */
     readonly param: string;
-    /** The route template that required the missing parameter (e.g. `"/profile/:userId"`). */
+    /** The route template that needs the absent parameter, for example `"/profile/:userId"`. */
     readonly template: string;
     constructor(param: string, template: string);
 }
 /**
- * @deprecated Never thrown any more. `buildRouteUrl` treats a missing `query`
- * field as `query: {}` — the generated `play.route` transitions assign
- * `query` on every navigation, so the loss this error guarded against cannot
- * occur through route derivation. Machines that handle `play.route` by hand
- * and want query forwarding must assign `event.query` to context themselves.
- * Kept exported so existing `instanceof` handlers keep compiling; remove them
- * at leisure.
+ * @deprecated Nothing throws this error now. `buildRouteUrl` reads an absent `query`
+ * field as `query: {}`. The generated `play.route` transitions assign `query` on
+ * every navigation, and the loss that this error guarded against therefore cannot
+ * happen through the route derivation. A machine that handles `play.route` itself
+ * and wants the query must assign `event.query` to its context itself. This class
+ * stays in the exports, so that an `instanceof` handler that exists now still
+ * compiles. Remove such a handler when you have the time.
  *
- * Formerly thrown by `buildRouteUrl()` when the context had a `params` field
- * (a routing-aware machine context) but no `query` field.
+ * `buildRouteUrl()` threw this error before, when the context had a `params` field,
+ * which means a context that knows the routing, but no `query` field.
  *
  * **Error code:** `PLAY_XSTATE_MISSING_QUERY_CONTEXT`
  */
@@ -53,23 +53,24 @@ export declare class MissingQueryContextError extends PlayError {
     constructor();
 }
 /**
- * Thrown by `formatPlayRouteTransitions()` when a state node declares `meta.route`
- * but omits an explicit `id`.
+ * `formatPlayRouteTransitions()` throws this error when a state node declares a
+ * `meta.route` field but no explicit `id` field.
  *
- * Without `id`, the function cannot generate a `play.route` guard that targets the
- * state — the guard compares `event.to` against `#<id>`, so a missing `id` means
- * the state is silently unreachable via routing. This error surfaces the
- * misconfiguration at machine-definition time rather than silently skipping the state.
+ * Without an `id`, the function can generate no `play.route` guard that targets the
+ * state: the guard compares `event.to` with `#<id>`. An absent `id` therefore makes
+ * the state unreachable through the routing, and nothing says so. This error shows
+ * the fault of the configuration at the moment of the machine definition, and the
+ * function skips no state in silence.
  *
  * **Error code:** `PLAY_XSTATE_MISSING_STATE_ID`
  *
  * @example
  * ```typescript
- * // Bad — meta.route without id:
+ * // Bad — a meta.route field without an id field:
  * states: {
  *   profile: {
  *     meta: { route: "/profile/:username" },
- *     // ← missing id: "profile"
+ *     // ← the id: "profile" field is absent
  *   }
  * }
  *
@@ -83,15 +84,16 @@ export declare class MissingQueryContextError extends PlayError {
  * ```
  */
 export declare class MissingStateIdError extends PlayError {
-    /** The state key (position in the states tree) that is missing an explicit `id`. */
+    /** The state key, which is the position in the tree of the states, without an explicit `id` field. */
     readonly stateKey: string;
-    /** The route template declared on the state (e.g. `"/profile/:username"`). */
+    /** The route template of the state, for example `"/profile/:username"`. */
     readonly route: string;
     constructor(stateKey: string, route: string);
 }
 /**
- * Thrown by the `PlayerActor` constructor when the `machine` argument is not a
- * valid XState machine object (null, undefined, or a non-object).
+ * 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
+ * object.
  *
  * **Error code:** `PLAY_XSTATE_INVALID_MACHINE`
  */
@@ -99,35 +101,38 @@ export declare class InvalidMachineError extends PlayError {
     constructor();
 }
 /**
- * Thrown by `normalizeRoute()` when a state's `meta.route` value is neither a
- * string nor an object with a `path` property.
+ * `normalizeRoute()` throws this error when the `meta.route` value of a state is not
+ * a string and not an object with a `path` property.
  *
  * **Error code:** `PLAY_XSTATE_INVALID_ROUTE_METADATA`
  */
 export declare class InvalidRouteMetadataError extends PlayError {
-    /** The serialised form of the invalid route value for debugging. */
+    /** The invalid route value, as a string, for the debug work. */
     readonly detail: string;
     constructor(route: unknown, source?: string);
 }
 /**
- * Thrown by `composeGuards()` or `composeGuardsOr()` when called with an empty
- * guards array. A composition of zero guards has no meaningful semantics.
+ * `composeGuards()` and `composeGuardsOr()` throw this error for an empty array of
+ * guards. A composition of zero guards has no meaning.
  *
  * **Error code:** `PLAY_XSTATE_EMPTY_GUARD_ARRAY`
  */
 export declare class EmptyGuardArrayError extends PlayError {
-    /** The combinator that was called with an empty array (`"and"` or `"or"`). */
+    /** The combinator of the call with the empty array: `"and"` or `"or"`. */
     readonly combinator: "and" | "or";
     constructor(combinator: "and" | "or");
 }
 /**
- * Thrown by `PlayerActor.send()` when the event argument is not a plain object.
+ * `PlayerActor.send()` throws this error when the event argument is not a plain
+ * object.
  *
- * `PlayEvent` requires `{ type: string, ...fields }`. Passing `null`, `undefined`,
- * a string, or any other non-object value is a programmer error.
+ * A `PlayEvent` needs the shape `{ type: string, ...fields }`. A `null` value, an
+ * `undefined` value, a string, and every other value that is not an object are an
+ * error of the programmer.
  *
- * The offending value is attached as the `detail` readonly class field for debugging.
- * TypeScript consumers can access `err.detail` directly without any unsafe cast.
+ * The error holds the value in question in its readonly class field `detail`, for
+ * the debug work. A TypeScript consumer reads `err.detail` directly, with no unsafe
+ * cast.
  *
  * **Error code:** `PLAY_XSTATE_INVALID_EVENT`
  *
@@ -139,25 +144,27 @@ export declare class EmptyGuardArrayError extends PlayError {
  *   actor.send(null as any);
  * } catch (err) {
  *   if (err instanceof InvalidEventError) {
- *     // err.detail is typed as `unknown` — no cast needed
+ *     // err.detail has the type `unknown`, and it needs no cast
  *     console.error("Invalid event passed to actor.send():", err.detail);
  *   }
  * }
  * ```
  */
 export declare class InvalidEventError extends PlayError {
-    /** The offending value passed to `send()`. */
+    /** The value in question, from the `send()` call. */
     readonly detail: unknown;
     constructor(detail: unknown);
 }
 /**
- * Passed to `PlayerOptions.onError` when the actor failed with a value that is
- * not an `Error` — e.g. a machine action ran `throw { code: 42 }`.
+ * 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
+ * `throw { code: 42 }`.
  *
- * An actor error that *is* an `Error` reaches `onError` untouched, keeping the
- * identity the machine gave it. Only this case constructs a new error, so it
- * carries a matchable code instead of a `String(value)` message such as
- * `"[object Object]"`. The thrown value is preserved on `cause`.
+ * An actor error that *is* an `Error` reaches `onError` without a change, and it
+ * keeps the identity of the machine. This case alone builds a new error. The new
+ * error therefore carries a code that your code can match, and not a
+ * `String(value)` message such as `"[object Object]"`. The `cause` field holds the
+ * value from the throw.
  *
  * **Error code:** `PLAY_XSTATE_NON_ERROR_THROWN`
  *
@@ -170,7 +177,7 @@ export declare class InvalidEventError extends PlayError {
  *   options: {
  *     onError: (actor, err) => {
  *       if (err instanceof ActorThrewNonErrorError) {
- *         // err.cause is the value the machine actually threw
+ *         // err.cause is the value that the machine threw
  *         console.error("Machine threw a non-Error:", err.cause);
  *       }
  *     },

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAqB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAsB5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,SAAS;;CAWtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAW3C;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CASjD;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,OAAO,EAAE,MAAM,SAAgB;CAUlD;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC;gBAEtB,UAAU,EAAE,KAAK,GAAG,IAAI;CASpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,MAAM,EAAE,OAAO;CAS3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACzC,KAAK,EAAE,OAAO;CAS1B"}