@xmachines/docs 6.1.0 → 7.1.0

package/guides/getting-started.md

@@ -102,13 +102,13 @@ The test suite relies on TypeScript path aliases that resolve to source files. I
 
 #### TypeScript errors about missing types after adding a dependency
 
-Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, also add the correct `references` entry in the package's `tsconfig.base.json`.
+Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, declare it in the `package.json` of the package with a `workspace:*` range. The root `tsconfig.json` holds the build order, and `tests/tsconfig-reference-graph.test.ts` fails when that order misses the new edge.
 
 #### Lint errors about import extensions
 
 All TypeScript imports must end with `.js`, even for `.ts` source files:
 
-```typescript
+```typescript fragment
 // ✅ Correct
 import { PlayError } from "./errors.js";
 
@@ -154,9 +154,11 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 Every XMachines application needs these six packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core@0.21.0-xm.6
 ```
 
+The json-render packages are exact peers: install the version that this release names, `0.21.0-xm.6`.
+
 | Package                                                             | Role                                                                                                                                                                                                                                                                       |
 | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                                                                                                           |
@@ -208,7 +210,6 @@ const appSetup = setup({
 	types: {
 		context: {} as { count: number },
 		events: {} as { type: "toggle" },
-		input: {} as undefined,
 	},
 });
 
@@ -272,6 +273,10 @@ release:
 
 ```typescript
 import { watchAtom } from "@xmachines/play-atom";
+import type { PlayerActor } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const actor: PlayerActor<AnyStateMachine>; // the actor of the example above
 
 const stop = watchAtom(actor.state, (snapshot) => {
 	console.log("the machine is now:", snapshot.value);
@@ -324,8 +329,9 @@ const appSetup = setup({
 			query: Record<string, string>;
 		},
 		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
+			| PlayRouteEvent
+			| { type: "auth.login"; username: string }
+			| { type: "auth.logout" },
 	},
 });
 
@@ -412,16 +418,27 @@ Used with framework-integrated routers like TanStack Router. All three props (`a
 
 ```tsx
 // React + TanStack Router example
-import { useMemo, useEffect } from "react";
+import { useMemo, useEffect, type ReactNode } from "react";
 import { createRouter, createRootRoute } from "@tanstack/react-router";
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // the machine of "Adding Routing"
+declare function Shell(props: { actor: typeof actor }): ReactNode; // your layout
+
 // Build OUTSIDE of JSX — must be stable references
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 const router = createRouter({ routeTree: createRootRoute() });
 
 // Actor also created outside the component (or memoized inside)
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -448,12 +465,21 @@ Used with framework-agnostic or server-rendered routers. `connectRouter` handles
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
 import { createRouteMapFromTree } from "@xmachines/play-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // the machine of "Adding Routing"
 
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree, history });
 
+const createPlayer = definePlayer({
+	machine: appMachine,
+	actor: compose(PlayerActor, withRouting),
+});
 const actor = createPlayer();
 actor.start();
 
@@ -483,6 +509,10 @@ import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-re
 import { defineCatalog } from "@xmachines/json-render-core";
 import { schema } from "@xmachines/play-react";
 import { z } from "zod";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -501,7 +531,9 @@ const registryResult = defineRegistry(catalog, {
 		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
 	},
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -548,7 +580,9 @@ function App() {
 			Login: { template: `<button @click="on('submit').emit()">Log in</button>` },
 		},
 		actions: {
-			login: async ({ username }) => actor.send({ type: "auth.login", username }),
+			login: async (params) => {
+				if (params) actor.send({ type: "auth.login", username: params.username });
+			},
 			logout: async () => actor.send({ type: "auth.logout" }),
 		},
 	});
@@ -562,6 +596,10 @@ import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-so
 import { defineCatalog } from "@xmachines/json-render-core";
 import { schema } from "@xmachines/play-solid";
 import { z } from "zod";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -580,7 +618,9 @@ const registryResult = defineRegistry(catalog, {
 		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
 	},
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -601,6 +641,10 @@ import { createPlayUI, defineRegistry, schema } from "@xmachines/play-dom";
 import { defineCatalog } from "@xmachines/json-render-core";
 import { z } from "zod";
 import type { ComponentFn } from "@xmachines/play-dom";
+import type { ViewActor } from "@xmachines/play-view";
+
+type AuthEvent = { type: "auth.login"; username: string } | { type: "auth.logout" };
+declare const actor: ViewActor<unknown, AuthEvent>; // your actor, composed with `withView`
 
 const catalog = defineCatalog(schema, {
 	components: {
@@ -631,7 +675,9 @@ const Login: ComponentFn<typeof catalog, "Login"> = ({ on }) => {
 const registryResult = defineRegistry(catalog, {
 	components: { Home, Login },
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 		logout: async () => actor.send({ type: "auth.logout" }),
 	},
 });
@@ -658,7 +704,7 @@ nothing is needed — the generated transitions assign `event.query` to context
 on every navigation. A machine that handles `play.route` by hand must do that
 assignment itself:
 
-```typescript
+```typescript fragment
 on: {
   "play.route": {
     actions: assign({
@@ -675,7 +721,7 @@ on: {
 
 **Fix:** Every state with `meta.route` must declare an explicit `id`:
 
-```typescript
+```typescript fragment
 // ❌ Missing id
 home: { meta: { route: "/" } }
 
@@ -690,6 +736,12 @@ home: { id: "home", meta: { route: "/" } }
 **Fix:** Always call `actor.start()` before `actor.send()`:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
+const createPlayer = definePlayer({ machine });
 const actor = createPlayer();
 actor.start(); // required before any send()
 actor.send({ type: "toggle" });
@@ -701,7 +753,7 @@ actor.send({ type: "toggle" });
 
 **Fix:** Construct stable references outside JSX or memoize them:
 
-```typescript
+```typescript fragment
 // ✅ Built outside the component
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);

package/guides/inspector.md

@@ -27,7 +27,9 @@ Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@
 ```typescript
 import { createBrowserInspector } from "@statelyai/inspect";
 import { definePlayer } from "@xmachines/play-xstate";
-import { appMachine } from "./machine.js";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
 
 const { inspect } = createBrowserInspector();
 
@@ -45,6 +47,12 @@ actor.start();
 That is the whole integration. [`PlayerOptions.inspect`](../api/@xmachines/play-xstate/index/interfaces/PlayerOptions.md) is forwarded verbatim to XState's `createActor`, so anything XState accepts there is accepted here — a function, or an observer object with a `next` method:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+declare const sink: { write(event: InspectionEvent): void }; // your log
+
 // Function form — the common case
 definePlayer({ machine, options: { inspect: (event) => console.log(event.type) } });
 
@@ -61,6 +69,13 @@ Two properties of the attachment point matter in practice.
 **It is configured on the factory, not on the instance.** `definePlayer({ machine, options })` returns a factory; `options.inspect` belongs to that configuration, and every actor the factory creates reports to the same observer. The factory's per-call options bag carries `snapshot` for restoring persisted state and nothing else — there is no per-instance `inspect` override. When one factory produces several live actors (multi-user scenarios, SSR, tests), demultiplex the stream by root instead:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
+const inspect = (event: InspectionEvent) => console.log(event.type);
+
 const createPlayer = definePlayer({ machine, options: { inspect } });
 
 const alice = createPlayer({ userId: "alice" });
@@ -87,7 +102,7 @@ The event types are XState's: `@xstate.actor` when an actor registers, `@xstate.
 
 `@xstate.actor` fires from _inside_ the actor's constructor. The `actorRef` it carries is a real `PlayerActor`, but a mid-construction one: `state`, `currentRoute`, `currentView` and `initialRoute` do not exist yet, and reading them there throws — XState itself refuses to read a snapshot in that window.
 
-```typescript
+```typescript fragment
 const inspect = (event: InspectionEvent) => {
 	if (event.type === "@xstate.actor") {
 		// ❌ throws — the atoms are not assigned yet
@@ -109,11 +124,17 @@ Capture the reference during construction if you need it, and read the atoms fro
 An inspector that is only created when the user asks for it — a dev-tools toggle, a keyboard shortcut, a debug panel button — cannot be passed to `definePlayer`, which ran at module scope long before the click. Pass a forwarding function instead, so the attachment point is fixed at factory time while the destination stays swappable:
 
 ```typescript
-let current: ((event: InspectionEvent) => void) | undefined;
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent, Observer } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+
+let current: Observer<InspectionEvent> | undefined;
 
 const createPlayer = definePlayer({
 	machine: appMachine,
-	options: { inspect: (event) => current?.(event) },
+	options: { inspect: (event) => current?.next?.(event) },
 });
 
 // Later, from a click handler
@@ -135,6 +156,10 @@ There is a catch worth knowing before you ship it: events that arrive while `cur
 
 ```typescript
 import { createWebSocketInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
 
 const { inspect } = createWebSocketInspector({ url: "ws://localhost:8080" });
 
@@ -147,30 +172,57 @@ Both transports consume the identical `options.inspect` observer, so switching b
 
 ## Trying it in the demos
 
-Every demo in this repository — all five renderer demos and all eight router demos — wires the inspector the same way, so any of them can be used to see the flow end to end:
+Every demo in this repository — the five renderer galleries and every router demo — wires the inspector the same way, so any of them can be used to see the flow end to end:
 
 ```bash
-pnpm --filter @xmachines/play-react-demo run dev
+pnpm --filter @xmachines/play-react-gallery-demo run dev
 ```
 
-Click **Show Inspector** in the debug panel at the bottom of the page. The inspector opens in its own window with the machine already drawn and the session's history replayed, and it keeps updating as you log in, navigate, and log out.
+Click **Show Inspector** in the debug panel at the bottom of the page. The inspector opens in its own window with the machine already drawn and the session's history replayed, and it keeps updating as you use the machine that you opened in the gallery.
 
-The demos share one controller, `createDemoInspector()` from `@xmachines/play-actor-shared`, which each demo passes straight through to `definePlayer`:
+The demos share one controller, `createDemoInspector()`, which each demo passes straight through to `definePlayer`. The controller lives in a private package of this repository, so you cannot install it. The block below shows the same wiring with the public API. It keeps each event from the creation of the actor, and it replays the events when the user opens the inspector:
 
 ```typescript
-const inspector = createDemoInspector();
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent, Observer } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+
+const buffer: InspectionEvent[] = [];
+let current: Observer<InspectionEvent> | undefined;
 
 const actor = definePlayer({
-	machine: authMachine,
-	options: { inspect: inspector.inspect },
+	machine: appMachine,
+	options: {
+		inspect: (event) => {
+			if (current) {
+				current.next?.(event);
+				return;
+			}
+			// Keep the last 500 events while nobody opens the inspector. A long session drops
+			// its oldest events, also the registration of the root actor, and the inspector
+			// then has no machine to draw. The demo controller pins each registration for
+			// that reason, and it costs more code.
+			buffer.push(event);
+			if (buffer.length > 500) buffer.shift();
+		},
+	},
 })();
 actor.start();
 
-// The debug panel's button
-<button onClick={() => inspector.show()}>Show Inspector</button>;
+// The click handler of the "Show Inspector" button of the debug panel
+export function showInspector() {
+	if (current) return;
+	// The inspector holds these events until its window connects, and it drops the oldest
+	// past `maxDeferredEvents`. The limit leaves room for the events of the handshake, so
+	// the inspector keeps every event of the replay.
+	current = createBrowserInspector({ maxDeferredEvents: 1000 }).inspect;
+	for (const event of buffer.splice(0)) current.next?.(event);
+}
 ```
 
-The controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the registration of every live root so it can never roll out of the bounded buffer, and flushes those buffers when the inspector window completes its handshake. Several machines can be alive together — one for each document a host has open — and the handshake replays each of them. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. The shared package's own README, at `packages/play-actor/examples/shared/README.md` in this repository, documents the design in full.
+The demo controller answers the late-opening problem from the previous section: it buffers serialized events from actor creation, pins the registration of every live root so it can never roll out of the bounded buffer, and flushes those buffers when the inspector window completes its handshake. Several machines can be alive together — one for each document a host has open — and the handshake replays each of them. That is a demo trade-off rather than a general recommendation — every transition pays serialization whether or not anyone ever opens the inspector — but it is what makes the button work at any point in a session. The shared package's own README, at `packages/play-actor/examples/shared/README.md` in this repository, documents the design in full.
 
 ---
 
@@ -179,6 +231,14 @@ The controller answers the late-opening problem from the previous section: it bu
 **Cost.** Inspection serializes events. A `console.log` observer is cheap; a browser inspector posting every transition, and any buffering scheme layered on top, is not. Gate the inspector behind a development-only branch, and prefer letting the bundler drop it entirely:
 
 ```typescript
+/// <reference types="vite/client" />
+import { createBrowserInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+
+// `import.meta.env.DEV` is the development flag of Vite
 const options = import.meta.env.DEV ? { inspect: createBrowserInspector().inspect } : {};
 
 const createPlayer = definePlayer({ machine: appMachine, options });

package/guides/routing.md

@@ -55,8 +55,11 @@ A **modifier** follows a param, a wildcard or a group:
 | `*`      | zero or more | matches                  |
 
 ```ts
+import { createMachine } from "xstate";
+
 const machine = createMachine({
 	id: "app",
+	initial: "home",
 	states: {
 		home: { meta: { route: "/" } },
 		profile: { meta: { route: "/profile/:userId" } },
@@ -184,7 +187,7 @@ CAUTION: a parallel state loses the position of its other regions when it is the
 
 A state whose navigation must re-enter the domain too declares the flag for itself. Here the root runs its `exit` and `entry` actions on each navigation to `dashboard`:
 
-```ts
+```ts fragment
 states: {
 	dashboard: { meta: { route: { path: "/dashboard", reenter: true } } },
 },

package/guides/state-machines.md

@@ -33,7 +33,6 @@ const authSetup = setup({
 	types: {
 		context: {} as { username: string | null },
 		events: {} as { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
 	},
 });
 
@@ -47,7 +46,8 @@ const authMachine = authSetup.createMachine({
 				"auth.login": {
 					target: "authenticated",
 					actions: authSetup.assign({
-						username: ({ event }) => event.username,
+						username: ({ event }) =>
+							event.type === "auth.login" ? event.username : null,
 					}),
 				},
 			},
@@ -78,6 +78,7 @@ XMachines extends XState's `meta` field on each state node. This is where routin
 
 ```typescript
 import { typedSpec } from "@xmachines/play-view";
+import { setup } from "xstate";
 
 const appMachine = setup({/* ... */}).createMachine({
 	id: "app",
@@ -126,6 +127,8 @@ const appMachine = setup({/* ... */}).createMachine({
 
 The machine's whole context is available to every view through the **`/context` projection**: the derived spec's `state` carries `context: <machine context>`. Specs read it with ordinary state expressions — `{ $state: "/context/username" }` in props, `visible` conditions, or `repeat.statePath`. The subtree is **read-only**: context changes only through machine events, and a `$bindState`/`setState` write under `/context` throws. URL data lives at its own paths (`/context/params/…`, `/context/query/…`, written into context by `formatPlayRouteTransitions`), so a URL param can never shadow a machine-owned field. When validating specs with tools like `validateSpec`, validate the **derived** view (`actor.currentView.get()`) — its `state` honestly describes the store contents — not the raw `meta.view`. A context change re-emits the view with the same `viewKey`; providers respond by refreshing `/context` in the live store, not by remounting the UI.
 
+**Give each state its own id, and do not use an array index as an id.** XState does not check that the ids of the states are unique, and a repeated id makes a `#id` target name two states. XMachines keys the route, the view and its store on the id of a state, so two states that share an id share one route entry, one store, and one key. An array index is a whole number from 0 to 2³² − 2 with no leading zero, such as `"42"`. JavaScript lists such a key first in every object that is keyed on ids, so the route of its state loses its place in the branch. [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) writes one warning for each machine that breaks these rules.
+
 **The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
 
 ### A layout and its pages: `outlets`
@@ -133,6 +136,11 @@ The machine's whole context is available to every view through the **`/context`
 Without outlets, the deepest active state that declares a view wins, and a view on a parent state stays off the screen. Declare `outlets` in the view of the parent to show the parent view AND the view of its active child. Each outlet names an element of the parent view, and the view of the child goes into that element:
 
 ```typescript
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
+import { setup } from "xstate";
+
+declare const menuView: ViewMeta, homeView: ViewMeta, searchView: ViewMeta; // your views
+
 const shell = typedSpec({
 	root: "shell",
 	state: { collapsed: false },
@@ -166,11 +174,11 @@ const appMachine = setup({/* ... */}).createMachine({
 - **The key of an outlet** is the key of a child state in `states`, or `"*"` for each active child that has no outlet of its own. A child with neither stays off the screen.
 - **A compound state** fills one outlet with its active child. **A parallel state** fills one outlet for each region, in the order of `states`.
 - **`slot`** names a named slot of the element. Omit it to append the child view to the `children` of the element. The component of the element renders the slot, as the renderer of your framework describes.
-- **The view of a child** is the deepest view in its active subtree, and a child view can declare `outlets` of its own for a nested layout. A parallel state without outlets shows the region of the URL when that region has a view, and its first region that has a view otherwise.
+- **The view of a child** is the deepest view in its active subtree, and a child view can declare `outlets` of its own for a nested layout. A parallel state without outlets shows the region of the routes when that region has a view, and its first region that has a view otherwise. The region of the routes keeps the screen while it sits in a state without a route of its own.
 
 The derived spec holds the elements of every composed view. The keys of the outer view stay as you wrote them, and each key of a child view gets the id of its state as a prefix, for example `app.page.search/root`, so two views never collide.
 
-The `viewKey` of a composed view is the id of the outermost state that declares `outlets`. A change of the page therefore keeps the store of the layout: the `collapsed` value in the example above does not change. The first time that a page shows, the provider writes the keys of its authored `state` that the store does not hold. A page that comes back finds the values that it left. All the pages of one layout share one store, so two pages that declare the same key share one value: give each page its own keys. When two composed views declare the same state key, the outer view wins, and the library writes a warning.
+The `viewKey` of a composed view is the id of the outermost state that declares `outlets`. A change of the page therefore keeps the store of the layout: the `collapsed` value in the example above does not change. The first time that a page shows, the provider writes the keys of its authored `state` that the store does not hold. A page that comes back finds the values that it left. All the pages of one layout share one store, so two pages that declare the same key share one value: give each page its own keys. When two composed views declare the same state key, the outer view wins. The library writes one warning for each layout that names every key that two of its views declare, also for two pages that are never on the screen together.
 
 An outlet that names an element that its view does not hold throws `InvalidViewOutletError`. The actor reports it through its `onError` option, and it keeps the last good view.
 
@@ -198,7 +206,7 @@ A URL path has one hierarchy, and it cannot hold the branches of two regions. Ke
 
 For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
 
-```typescript
+```typescript fragment
 // Without formatPlayRouteTransitions — verbose and repetitive
 states: {
   home: {
@@ -218,6 +226,7 @@ states: {
 
 ```typescript
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
+import { setup } from "xstate";
 
 const appMachine = setup({/* ... */}).createMachine(
 	formatPlayRouteTransitions({
@@ -234,7 +243,7 @@ const appMachine = setup({/* ... */}).createMachine(
 
 [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
 
-```typescript
+```typescript fragment
 types: {
   context: {} as {
     params: Record<string, string>;
@@ -252,7 +261,12 @@ types: {
 Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of `{ context, event }` that return a boolean.
 
 ```typescript
+import { setup } from "xstate";
+
 const authSetup = setup({
+	types: {
+		context: {} as { isAuthenticated: boolean; role: "user" | "admin" },
+	},
 	guards: {
 		isAuthenticated: ({ context }) => context.isAuthenticated,
 		isAdmin: ({ context }) => context.role === "admin",
@@ -280,7 +294,7 @@ Each combinator resolves a guard NAME against the `guards` of `setup()`, so a na
 
 Context is the machine's persistent data store. It survives transitions and can be read and updated by actions:
 
-```typescript
+```typescript fragment
 // Context is defined in setup({ types })
 types: {
   context: {} as {
@@ -307,22 +321,30 @@ Context is accessed in guards, actions, and when computing routes or views. It i
 A snapshot is a point-in-time serialisation of the machine's current state and context. XState produces snapshots in a JSON-compatible format:
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
+
+const createPlayer = definePlayer({ machine });
+const actor = createPlayer();
+actor.start();
+
 const snapshot = actor.getSnapshot();
 // snapshot.value → current state node name, e.g. "dashboard"
 // snapshot.context → current context object
 
-// Stop and serialize
+// Serialize and stop
+const saved = JSON.stringify(actor.getPersistedSnapshot());
 actor.stop();
-const saved = JSON.stringify(snapshot);
 
 // Restore
-const restored = JSON.parse(saved);
-const actor = createPlayer(undefined, { snapshot: restored });
-actor.start();
+const restored = createPlayer(undefined, { snapshot: JSON.parse(saved) });
+restored.start();
 // Actor resumes from where it left off
 ```
 
-[`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+The factory that [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) returns accepts an optional second argument, `{ snapshot }`, for this purpose. Serialize the result of `getPersistedSnapshot()`, and not of `getSnapshot()`: XState restores from the persisted form. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
 
 ---