@xmachines/docs 2.0.0 → 2.1.0

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

@@ -2,11 +2,9 @@
 
 # @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)
 
 ---
 
@@ -16,7 +14,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.
 
 ---
 
@@ -30,7 +28,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" } },
 	},
 });
@@ -58,7 +56,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";
@@ -94,9 +92,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> =
@@ -123,35 +121,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
 
@@ -172,11 +170,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";
@@ -200,9 +199,9 @@ const machine = setup({
 			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
 			target: "adminPanel",
 		},
-		accessDashboard: {
-			guard: negateGuard("isGuest"),
-			target: "dashboard",
+		accessLogin: {
+			guard: negateGuard("isLoggedIn"),
+			target: "login",
 		},
 	},
 	// ...
@@ -213,11 +212,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";
@@ -242,23 +241,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";
@@ -267,25 +266,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](../../../guides/inspector.md) for the full walkthrough —
-late attachment with replay, browser-free WebSocket inspection, and production
-considerations.
+The [inspector guide](../../../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.
 
 ---
 
@@ -312,7 +313,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 {
@@ -327,7 +328,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.
 
 ---
 
@@ -341,7 +342,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/`.
 
 ---
 
@@ -349,13 +350,14 @@ Tests use [Vitest](https://vitest.dev/) and live in `packages/play-xstate/test/`
 
 MIT — see [LICENSE](LICENSE) for details.
 
-@xmachines/play-xstate - XState v5 adapter for Play Architecture
+@xmachines/play-xstate - the XState v5 adapter of the Play Architecture
 
-Provides definePlayer() API for binding XState state machines to the
-actor base with signal lifecycle and DevTools integration.
+This package gives you the definePlayer() API. That function binds an XState state
+machine to the actor base, with the signal lifecycle and the DevTools
+integration.
 
-Per the Play RFC, this package implements the Logic Layer adapter that
-transforms declarative machine definitions into live actors with signal-driven
+The Play RFC gives this package as the adapter of the logic layer. It converts a
+declarative machine definition into a live actor with a signal-driven
 reactivity.
 
 ## Classes