@xmachines/docs 2.0.0-alpha.1 → 2.1.0

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

@@ -1,15 +1,10 @@
 [API](../../README.md) / @xmachines/play-xstate
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-xstate
 
-> XState v6 adapter for the XMachines Play Architecture — bind state machines to the actor base with signal-driven reactivity and 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-1.0.0--beta.51-blue)](https://www.npmjs.com/package/@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.
 
-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)
 
 ---
 
@@ -19,7 +14,7 @@ Part of the [XMachines Play](../../README.md) monorepo.
 pnpm add @xmachines/play-xstate xstate
 ```
 
-`xstate ^6.0.0-alpha.19` is a peer dependency and must be installed alongside this package.
+`xstate ^5.31.0` is a peer dependency. Install it with this package.
 
 ---
 
@@ -27,18 +22,13 @@ pnpm add @xmachines/play-xstate xstate
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, emptyEventSchema, playMetaSchema } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-// 1. Define your XState v6 machine
-const machine = setup({
-	schemas: {
-		events: { activate: emptyEventSchema },
-		meta: playMetaSchema, // types meta.route / meta.view on state nodes
-	},
-}).createMachine({
+// 1. Define your XState v5 machine
+const machine = setup({}).createMachine({
 	initial: "idle",
 	states: {
-		idle: { meta: { route: "/" }, on: { activate: { target: "active" } } },
+		idle: { meta: { route: "/" }, on: { activate: "active" } },
 		active: { meta: { route: "/active" } },
 	},
 });
@@ -66,16 +56,16 @@ actor.stop();
 
 ### `definePlayer(config)`
 
-Creates a `PlayerFactory` from an XState v6 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, types } from "xstate";
+import { setup } from "xstate";
 import { definePlayer } from "@xmachines/play-xstate";
 
 const machine = setup({
-	schemas: {
-		context: types<{ userId: string }>(),
-		input: types<{ userId: string }>(),
+	types: {
+		context: {} as { userId: string },
+		input: {} as { userId: string },
 	},
 }).createMachine({
 	context: ({ input }) => ({ userId: input.userId }),
@@ -91,6 +81,7 @@ const createPlayer = definePlayer({
 		onTransition: (actor, prev, next) => console.log("transitioned"),
 		onStateChange: (actor, state) => console.log("state changed"),
 		onError: (actor, err) => console.error(err),
+		inspect: (event) => console.log(event.type), // handed to XState's actor constructor — enables @statelyai/inspect
 	},
 });
 
@@ -101,17 +92,27 @@ const bob = createPlayer({ userId: "bob" });
 
 #### `PlayerFactory` signature
 
+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> = (
-	input?: InputFrom<TMachine>,
-	options?: PlayerFactoryResumeOptions<TMachine>,
-) => PlayerActor<TMachine>;
+type PlayerFactory<TMachine> =
+	undefined extends InputFrom<TMachine>
+		? (
+				input?: InputFrom<TMachine>,
+				options?: PlayerFactoryResumeOptions<TMachine>,
+			) => PlayerActor<TMachine>
+		: (
+				input: InputFrom<TMachine>,
+				options?: PlayerFactoryResumeOptions<TMachine>,
+			) => PlayerActor<TMachine>;
 ```
 
 #### Restoring from a snapshot
 
 ```typescript
-const snapshot = actor.getSnapshot();
+const snapshot = actor.getPersistedSnapshot();
 actor.stop();
 
 // Restore to the exact saved state
@@ -120,31 +121,35 @@ restored.start();
 console.log(restored.currentRoute.get()); // same route as when saved
 ```
 
+> **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 that wraps an XState v6 actor and 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
 
@@ -165,7 +170,12 @@ actor.start();
 
 ### Guard utilities
 
-Composable guard helpers that combine predicates with AND, OR, and NOT logic. Each helper returns a plain predicate — call it inside a transition function with the transition arguments and return early to block the transition. String guard names are resolved against the named guards declared in `setup({ guards })`.
+> **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.
+
+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";
@@ -178,24 +188,20 @@ import {
 	contextFieldMatches, // guard: context field equals a value
 } from "@xmachines/play-xstate";
 
-const canAccessAdmin = composeGuards(["isLoggedIn", "hasAdminRole"]);
-const isAuthenticated = negateGuard("isGuest");
-
 const machine = setup({
 	guards: {
 		isLoggedIn: ({ context }) => !!context.userId,
 		hasAdminRole: ({ context }) => context.role === "admin",
-		isGuest: ({ context }) => !context.userId,
 	},
 }).createMachine({
 	on: {
-		accessAdmin: (args) => {
-			if (!canAccessAdmin(args)) return;
-			return { target: "adminPanel" };
+		accessAdmin: {
+			guard: composeGuards(["isLoggedIn", "hasAdminRole"]),
+			target: "adminPanel",
 		},
-		accessDashboard: (args) => {
-			if (!isAuthenticated(args)) return;
-			return { target: "dashboard" };
+		accessLogin: {
+			guard: negateGuard("isLoggedIn"),
+			target: "login",
 		},
 	},
 	// ...
@@ -206,19 +212,17 @@ 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.
 
-#### `createRoutedMachine(setup)`
+#### `formatPlayRouteTransitions(machineConfig)`
 
-The recommended entry point: returns a `createMachine` with the same signature as the setup's own — full contextual typing for the config — that wires routing up at runtime.
+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";
-import { createRoutedMachine } from "@xmachines/play-xstate";
-
-const appSetup = setup({/* schemas, guards, ... */});
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
 
-const machine = createRoutedMachine(appSetup)({
+const config = formatPlayRouteTransitions({
 	id: "app",
 	states: {
 		home: {
@@ -231,61 +235,58 @@ const machine = createRoutedMachine(appSetup)({
 		},
 	},
 });
+
+// config now includes auto-generated play.route handlers:
+// on: { "play.route": [ { target: ".home", guard: e => e.to === "#home" }, ... ] }
+const machine = setup({}).createMachine(config);
 ```
 
-#### `formatPlayRouteTransitions(machineConfig)`
+> **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.
 
-The underlying transform. Crawls machine states with `meta.route` and wires them to XState v6's native routing: each routed state gets a native `route: {}` config (targetable via the built-in `xstate.route` event and visible to graph tooling), and one root `play.route` forwarder navigates those targets in a single atomic transition — patching `params`/`query` into context — while re-raising `xstate.route` only for states that declare their own `route` config. Unknown targets fall through to user-defined `play.route` fallbacks (e.g. a 404 route); one `play.route` send is one atomic transition, so exit actions see the old `params` and entry actions the new ones.
+#### Other routing exports
 
-```typescript
-import { setup } from "xstate";
-import {
-	formatPlayRouteTransitions,
-	playMetaSchema,
-	playRouteEventSchema,
-} from "@xmachines/play-xstate";
+| 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 |
 
-const config = formatPlayRouteTransitions({
-	id: "app",
-	states: {
-		home: {
-			id: "home",
-			meta: { route: "/home" },
-		},
-		profile: {
-			id: "profile",
-			meta: { route: "/users/:userId" },
-		},
-	},
-});
+---
 
-// config now carries native route configs plus the play.route forwarder:
-// states: { home: { ..., route: {} }, profile: { ..., route: {} } }
-// on: { "play.route": [forwarder, ...userFallbacks] }
-// The forwarder navigates injected-route targets directly (atomically);
-// xstate.route is raised only for states declaring their own route config.
-const machine = setup({
-	schemas: {
-		events: { "play.route": playRouteEventSchema },
-		meta: playMetaSchema,
-	},
-}).createMachine(config);
+## Inspection
+
+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";
+
+const { inspect } = createBrowserInspector();
+const createPlayer = definePlayer({ machine, options: { inspect } });
 ```
 
-Because the injected `route` configs are static, route transitions keep statically-known targets — `machineToGraph()` sees real edges to every routed state, so reachability queries work.
+Three points are important:
 
-> **Note:** Every state with `meta.route` must also have an explicit `id` field; omitting it throws `MissingStateIdError` at machine-definition time.
+- **`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.
 
-#### Other routing exports
+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)`.
 
-| Export                             | Description                                                               |
-| ---------------------------------- | ------------------------------------------------------------------------- |
-| `playMetaSchema`                   | Shared `schemas.meta` declaration for `meta.route` / `meta.view` metadata |
-| `playRouteEventSchema`             | Shared `schemas.events` entry for the `play.route` event payload          |
-| `emptyEventSchema`                 | Shared `schemas.events` entry for events that carry no payload            |
-| `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 |
+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.
 
 ---
 
@@ -294,12 +295,12 @@ Because the injected `route` configs are static, route transitions keep statical
 ```typescript
 import type {
 	PlayerConfig, // definePlayer() config argument shape
-	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError)
+	PlayerOptions, // Lifecycle hooks (onStart, onStop, onTransition, onStateChange, onError) + inspect
 	PlayerFactory, // Factory function returned by definePlayer()
 	PlayerFactoryResumeOptions, // { snapshot? } for restoring actor state
-	Guard, // Single XState guard predicate
-	GuardArray, // Array of guards for compose helpers
-	ComposedGuard, // Return type of composeGuards / composeGuardsOr / negateGuard
+	Guard, // deprecated with the guard utilities — removed in the next major
+	GuardArray, // deprecated with the guard utilities — removed in the next major
+	ComposedGuard, // deprecated with the guard utilities — removed in the next major
 	RouteMachineConfig, // Minimal machine config accepted by formatPlayRouteTransitions
 	RouteStateNode, // Single state node shape used during route crawling
 	RouteContext, // Context shape expected by buildRouteUrl ({ params?, query?, basePath?, hash? })
@@ -312,23 +313,22 @@ 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 {
 	MissingRouteParamError, // Required :param absent from context when resolving currentRoute
-	MissingQueryContextError, // context.params present but context.query missing
+	MissingQueryContextError, // deprecated: no longer thrown
 	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
+	ActorThrewNonErrorError, // actor failed with a thrown value that is not an Error
 	InvalidRouteMetadataError, // meta.route is neither a string nor { path: string }
 	EmptyGuardArrayError, // composeGuards/composeGuardsOr called with empty array
-	UnresolvableGuardNameError, // string guard name could not be resolved at call time
-	InvalidGuardEntryError, // guard entry was neither a predicate nor a name (e.g. undefined)
 } 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.
 
 ---
 
@@ -342,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/`.
 
 ---
 
@@ -350,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 v6 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
@@ -373,34 +374,24 @@ reactivity.
 
 ## Type Aliases
 
-- [ComposedGuard](type-aliases/ComposedGuard.md)
-- [Guard](type-aliases/Guard.md)
-- [GuardArray](type-aliases/GuardArray.md)
+- [~~ComposedGuard~~](type-aliases/ComposedGuard.md)
+- [~~Guard~~](type-aliases/Guard.md)
+- [~~GuardArray~~](type-aliases/GuardArray.md)
 - [PlayerFactory](type-aliases/PlayerFactory.md)
-- [PlayRoutePayload](type-aliases/PlayRoutePayload.md)
 - [RouteMachineConfig](type-aliases/RouteMachineConfig.md)
 - [RouteMetadata](type-aliases/RouteMetadata.md)
 - [RouteStateNode](type-aliases/RouteStateNode.md)
-- [SetupLike](type-aliases/SetupLike.md)
-- [WithOptional](type-aliases/WithOptional.md)
-
-## Variables
-
-- [emptyEventSchema](variables/emptyEventSchema.md)
-- [playMetaSchema](variables/playMetaSchema.md)
-- [playRouteEventSchema](variables/playRouteEventSchema.md)
 
 ## Functions
 
 - [buildRouteUrl](functions/buildRouteUrl.md)
-- [composeGuards](functions/composeGuards.md)
-- [composeGuardsOr](functions/composeGuardsOr.md)
-- [contextFieldMatches](functions/contextFieldMatches.md)
-- [createRoutedMachine](functions/createRoutedMachine.md)
+- [~~composeGuards~~](functions/composeGuards.md)
+- [~~composeGuardsOr~~](functions/composeGuardsOr.md)
+- [~~contextFieldMatches~~](functions/contextFieldMatches.md)
 - [definePlayer](functions/definePlayer.md)
 - [deriveRoute](functions/deriveRoute.md)
-- [eventMatches](functions/eventMatches.md)
+- [~~eventMatches~~](functions/eventMatches.md)
 - [formatPlayRouteTransitions](functions/formatPlayRouteTransitions.md)
-- [hasContext](functions/hasContext.md)
+- [~~hasContext~~](functions/hasContext.md)
 - [isAbsoluteRoute](functions/isAbsoluteRoute.md)
-- [negateGuard](functions/negateGuard.md)
+- [~~negateGuard~~](functions/negateGuard.md)