@xmachines/docs 6.1.0 → 8.0.0-next.1

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";
 
@@ -143,7 +143,7 @@ This section covers installing XMachines packages into your own application and
 - **Node.js** `>= 24.0.0`
 - **pnpm** via corepack (`corepack enable`)
 - **TypeScript** `>= 5.7` (strict mode recommended)
-- **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
+- **XState** `6.0.0-alpha.71` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
 
 All packages are ES modules (`"type": "module"`). Use `.js` extensions in all TypeScript imports.
 
@@ -154,12 +154,14 @@ 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@6.0.0-alpha.71 @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom @xmachines/play @xmachines/core @xmachines/json-render-core@0.21.0-xm.7
 ```
 
+The json-render packages are exact peers: install the version that this release names, `0.21.0-xm.7`.
+
 | Package                                                             | Role                                                                                                                                                                                                                                                                       |
 | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `xstate`                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                                                                                                           |
+| `xstate`                                                            | XState v6 state machine engine (peer dependency)                                                                                                                                                                                                                           |
 | [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) | [`definePlayer()`](../api/@xmachines/play-xstate/index/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md), routing helpers                                                                                            |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)   | The actor contract: `PlayActor`, which names no state machine library                                                                                                                                                                                                      |
 | [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)     | The atom primitives (`createAtom`, [`watchAtom`](../api/@xmachines/play-atom/functions/watchAtom.md))                                                                                                                                                                      |
@@ -200,15 +202,14 @@ pnpm add @xmachines/play-dom      # Vanilla DOM
 The minimum viable XMachines actor — no framework dependencies:
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 import { definePlayer } from "@xmachines/play-xstate";
 
-// 1. Declare types with setup() — the XState v5 typed entry point
+// 1. Declare the schemas with setup() — the XState v6 typed entry point
 const appSetup = setup({
-	types: {
-		context: {} as { count: number },
-		events: {} as { type: "toggle" },
-		input: {} as undefined,
+	schemas: {
+		context: types<{ count: number }>(),
+		events: { toggle: types<void>() },
 	},
 });
 
@@ -220,18 +221,12 @@ const machine = appSetup.createMachine({
 	states: {
 		off: {
 			on: {
-				toggle: {
-					target: "on",
-					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
-				},
+				toggle: ({ context }) => ({ target: "on", context: { count: context.count + 1 } }),
 			},
 		},
 		on: {
 			on: {
-				toggle: {
-					target: "off",
-					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
-				},
+				toggle: ({ context }) => ({ target: "off", context: { count: context.count + 1 } }),
 			},
 		},
 	},
@@ -258,8 +253,8 @@ actor.stop();
 
 **Key rules:**
 
-- Always use `setup({ types })` before `createMachine` — never bare `createMachine` from xstate.
-- Use `setup.assign(...)` for context mutations — not the bare `assign` from xstate.
+- Always use `setup({ schemas })` before `createMachine` — never bare `createMachine` from xstate.
+- Return a context patch from a transition function — `{ context: { count: 1 } }`. XState 6 has no `assign` action.
 - Call `actor.start()` before sending events.
 - Call `actor.stop()` when done to clean up atom subscriptions.
 
@@ -272,6 +267,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);
@@ -309,23 +308,27 @@ State machines control navigation through `meta.route` on states and `play.route
 [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 import { withRouting } from "@xmachines/play-xstate/routing";
-import type { PlayRouteEvent } from "@xmachines/play-router";
+import type { PlayRouteEvent, RouteMetadata } from "@xmachines/play-router";
 
 const appSetup = setup({
-	types: {
+	schemas: {
 		// params and query are REQUIRED for formatPlayRouteTransitions
-		context: {} as {
+		context: types<{
 			isAuthenticated: boolean;
 			params: Record<string, string>;
 			query: Record<string, string>;
+		}>(),
+		events: {
+			"play.route": types<Omit<PlayRouteEvent, "type">>(),
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": types<void>(),
 		},
-		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
+		// The `meta` of each state: XState 6 types it from this schema
+		meta: types<{ route?: RouteMetadata }>(),
 	},
 });
 
@@ -343,26 +346,21 @@ const appMachine = appSetup.createMachine(
 				id: "dashboard",
 				meta: { route: "/dashboard" },
 				// always guard: redirect to /login if not authenticated
-				always: {
-					guard: ({ context }) => !context.isAuthenticated,
-					target: "login",
-				},
+				always: ({ context }) =>
+					context.isAuthenticated ? undefined : { target: "login" },
 			},
 			profile: { id: "profile", meta: { route: "/profile/:username" } },
 		},
 		on: {
-			"auth.login": {
-				target: ".dashboard",
-				guard: ({ context }) => !context.isAuthenticated,
-				actions: appSetup.assign({
-					isAuthenticated: true,
-				}),
-			},
-			"auth.logout": {
-				target: ".home",
-				guard: ({ context }) => context.isAuthenticated,
-				actions: appSetup.assign({ isAuthenticated: false }),
-			},
+			// A transition function is the guard: it returns nothing to refuse the event
+			"auth.login": ({ context }) =>
+				context.isAuthenticated
+					? undefined
+					: { target: ".dashboard", context: { isAuthenticated: true } },
+			"auth.logout": ({ context }) =>
+				context.isAuthenticated
+					? { target: ".home", context: { isAuthenticated: false } }
+					: undefined,
 		},
 	}),
 );
@@ -412,16 +410,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 +457,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 +501,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 +523,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 +572,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 +588,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 +610,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 +633,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 +667,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" }),
 	},
 });
@@ -654,18 +692,18 @@ const disconnect = mount(actor, document.getElementById("app")!);
 `query` field builds a query-less URL, exactly like `query: {}`.
 
 **Fix:** With [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
-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:
+nothing is needed — the generated transitions write `event.query` to context
+on every navigation. A machine that handles `play.route` by hand must return that
+context patch itself:
 
-```typescript
+```typescript fragment
 on: {
-  "play.route": {
-    actions: assign({
-      params: ({ event }) => event.params ?? {},
-      query: ({ event }) => event.query ?? {},
-    }),
-  },
+  "play.route": ({ event }) => ({
+    context: {
+      params: event.params ?? {},
+      query: event.query ?? {},
+    },
+  }),
 }
 ```
 
@@ -675,7 +713,7 @@ on: {
 
 **Fix:** Every state with `meta.route` must declare an explicit `id`:
 
-```typescript
+```typescript fragment
 // ❌ Missing id
 home: { meta: { route: "/" } }
 
@@ -690,6 +728,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 +745,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);
@@ -726,7 +770,7 @@ node --version
 
 | Term                                                                                                               | Description                                                                                                           |
 | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| `setup({ types })`                                                                                                 | XState v5 entry point — declares TypeScript types for context, events, and input                                      |
+| `setup({ schemas })`                                                                                               | XState v6 entry point — declares the schemas of the context, the events, the input, and the `meta` of the states      |
 | [`definePlayer({ machine })`](../api/@xmachines/play-xstate/index/functions/definePlayer.md)                       | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) instances |
 | `actor.start()`                                                                                                    | Activates the machine — always call before sending events                                                             |
 | `actor.send({ type })`                                                                                             | Sends an event; machine guards decide whether a transition occurs                                                     |

package/guides/inspector.md

@@ -1,35 +1,36 @@
 # Inspecting a Running Actor
 
-A `PlayerActor` is an XState actor, so every XState inspection tool works on it unchanged. This guide covers how to attach an inspector, what the events look like once they arrive, and the two things that are specific to XMachines: the actor _is_ the actor an inspector sees, and the observer is configured on the factory rather than on each instance.
+A `PlayerActor` is an XState actor, so every observer of the inspection events of XState 6 works on it unchanged. This guide covers how to attach an inspector, what the events look like once they arrive, and the two things that are specific to XMachines: the actor _is_ the actor an inspector sees, and the observer is configured on the factory rather than on each instance.
 
-After reading this you will be able to open the [Stately inspector](https://stately.ai/docs/inspector) against a running demo or your own app, inspect an actor that has no browser around it, and wire an inspector that can be turned on after the actor has already started.
+After reading this you will be able to observe a running demo or your own app, inspect an actor that has no browser around it, and wire an inspector that can be turned on after the actor has already started.
 
-- [Quick start](#quick-start) — three lines to a live inspector
+- [Quick start](#quick-start) — one observer on the factory
 - [Where the observer attaches](#where-the-observer-attaches) — factory-level, creation-time
 - [Reading the events](#reading-the-events) — identity, `rootId`, the construction caveat
 - [Turning the inspector on later](#turning-the-inspector-on-later) — dev-tools toggles and replay
-- [Inspecting without a browser](#inspecting-without-a-browser) — WebSocket transport, Node and SSR
-- [Trying it in the demos](#trying-it-in-the-demos) — the shared demo controller
+- [Inspecting without a browser](#inspecting-without-a-browser) — Node and SSR
+- [Trying it in the demos](#trying-it-in-the-demos) — the shared demo controller and the Stately inspector
 - [Production considerations](#production-considerations) — cost and data exposure
 
+> **`@statelyai/inspect` and XState 6.** Release 0.7 of `@statelyai/inspect` imports `toObserver` from `xstate`, which XState 6 no longer exports, so its module does not load beside XState 6. It also reads the inspection events of XState 5. The [demos](#trying-it-in-the-demos) of this repository therefore convert the events of XState 6 to the protocol of the [Stately inspector](https://stately.ai/docs/inspector) app themselves.
+
 ---
 
 ## Quick start
 
-Install the inspect client alongside your existing XState dependency:
-
-```bash
-pnpm add -D @statelyai/inspect
-```
-
-Create an inspector and hand its `inspect` observer to [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md):
+Hand an observer of the inspection events to [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md):
 
 ```typescript
-import { createBrowserInspector } from "@statelyai/inspect";
 import { definePlayer } from "@xmachines/play-xstate";
-import { appMachine } from "./machine.js";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
 
-const { inspect } = createBrowserInspector();
+declare const appMachine: AnyStateMachine; // your machine
+
+const inspect = (event: InspectionEvent): void => {
+	if (event.type === "@xstate.transition") {
+		console.log(event.event.type, "→", event.snapshot.status);
+	}
+};
 
 const createPlayer = definePlayer({
 	machine: appMachine,
@@ -40,11 +41,17 @@ const actor = createPlayer();
 actor.start();
 ```
 
-`createBrowserInspector()` opens Stately's hosted inspector in a new tab and streams the actor's events to it. From there the machine draws itself, every transition animates, and the context is readable at each step.
+The observer receives one `@xstate.actor` event for each actor that the system creates, and one `@xstate.transition` event for each transition, with its event and its snapshot.
 
 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 +68,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" });
@@ -81,26 +95,31 @@ Because a `PlayerActor` _is_ the XState actor rather than a wrapper around a hid
 - `event.actorRef === actor` for the player's own events — recognise a player by identity, no bookkeeping required.
 - `event.rootId === actor.sessionId` for the whole tree, including invoked and spawned children, whose `actorRef` is the child rather than the player.
 
-The event types are XState's: `@xstate.actor` when an actor registers, `@xstate.event` when an event is sent, `@xstate.snapshot` after a transition, `@xstate.action` for executed actions, and `@xstate.microstep` for intermediate steps.
+XState 6 emits two event types:
+
+- `@xstate.actor` when an actor registers: `actorRef`, `parentRef`, `id`, `src`, and its initial `snapshot`.
+- `@xstate.transition` for each transition: the `event`, the resulting `snapshot`, `sourceRef`, `targetRef`, the `microsteps`, the executed `actions`, and the events that the transition `sent`. The stop of an actor is its last `@xstate.transition`, whose `snapshot.status` is `"stopped"`.
+
+The `@xstate.event`, `@xstate.snapshot`, `@xstate.action` and `@xstate.microstep` events of XState 5 are facets of `@xstate.transition` now.
 
 ### The construction caveat
 
 `@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
 		console.log(event.actorRef.currentRoute.get());
 	}
-	if (event.type === "@xstate.snapshot") {
+	if (event.type === "@xstate.transition") {
 		// ✅ construction has returned; atoms are live
 		console.log(event.actorRef.getSnapshot().value);
 	}
 };
 ```
 
-Capture the reference during construction if you need it, and read the atoms from a later event or from outside the observer entirely.
+Capture the reference during construction if you need it, and read the atoms from a later event or from outside the observer entirely. The `@xstate.actor` event carries the initial `snapshot` itself, so an observer reads that field and not `getSnapshot()`.
 
 ---
 
@@ -109,6 +128,12 @@ 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
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+declare function openInspector(): (event: InspectionEvent) => void; // your transport
+
 let current: ((event: InspectionEvent) => void) | undefined;
 
 const createPlayer = definePlayer({
@@ -118,8 +143,7 @@ const createPlayer = definePlayer({
 
 // Later, from a click handler
 export function enableInspector() {
-	const { inspect } = createBrowserInspector();
-	current = inspect;
+	current = openInspector();
 }
 ```
 
@@ -131,17 +155,25 @@ There is a catch worth knowing before you ship it: events that arrive while `cur
 
 ## Inspecting without a browser
 
-`createBrowserInspector` is one transport, not the only one. `@statelyai/inspect` also exports `createWebSocketInspector`, which pairs with `createInspectorServer` from `@statelyai/inspect/server` to stream the same events over a socket — the route to an actor with no browser around it at all, such as one running in a Node process or on the server half of an SSR render:
+An observer needs no browser. A `console.log`, a test spy that asserts a transition sequence, and a writer that appends each event to a log or sends it over a socket are all valid `inspect` values — the route to an actor with no browser around it at all, such as one running in a Node process or on the server half of an SSR render:
 
 ```typescript
-import { createWebSocketInspector } from "@statelyai/inspect";
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
 
-const { inspect } = createWebSocketInspector({ url: "ws://localhost:8080" });
+declare const appMachine: AnyStateMachine; // your machine
+declare const socket: { send(data: string): void }; // your transport
+
+const inspect = (event: InspectionEvent): void => {
+	if (event.type !== "@xstate.transition") return;
+	// The snapshot holds live references, so send the fields that you need
+	socket.send(JSON.stringify({ event: event.event, status: event.snapshot.status }));
+};
 
 const createPlayer = definePlayer({ machine: appMachine, options: { inspect } });
 ```
 
-Both transports consume the identical `options.inspect` observer, so switching between them touches only the line that creates the inspector. The same is true of an observer you write yourself: a `console.log`, a test spy asserting a transition sequence, or a writer that appends events to a log are all valid `inspect` values, and none of them require the inspect client at all.
+Every transport consumes the identical `options.inspect` observer, so switching between them touches only the line that creates the observer.
 
 ---
 
@@ -155,36 +187,70 @@ pnpm --filter @xmachines/play-react-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.
 
-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 converts each event of XState 6 to the protocol of the Stately inspector app: `@xstate.actor` becomes the registration of the actor, and each `@xstate.transition` becomes the `@xstate.event` and the `@xstate.snapshot` that the app draws one transition from. It posts the converted events to the window of the inspector app.
+
+The controller lives in a private package of this repository, so you cannot install it. The block below shows the buffer and the replay 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 { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+declare function openInspector(): (event: InspectionEvent) => void; // your transport
+
+const buffer: InspectionEvent[] = [];
+let current: ((event: InspectionEvent) => void) | undefined;
 
 const actor = definePlayer({
-	machine: authMachine,
-	options: { inspect: inspector.inspect },
+	machine: appMachine,
+	options: {
+		inspect: (event) => {
+			if (current) {
+				current(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;
+	current = openInspector();
+	for (const event of buffer.splice(0)) current(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.
 
 ---
 
 ## Production considerations
 
-**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:
+**Cost.** Inspection serializes events. A `console.log` observer is cheap; a transport 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
-const options = import.meta.env.DEV ? { inspect: createBrowserInspector().inspect } : {};
+/// <reference types="vite/client" />
+import { definePlayer } from "@xmachines/play-xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
+
+declare const appMachine: AnyStateMachine; // your machine
+declare function openInspector(): (event: InspectionEvent) => void; // your transport
+
+// `import.meta.env.DEV` is the development flag of Vite
+const options = import.meta.env.DEV ? { inspect: openInspector() } : {};
 
 const createPlayer = definePlayer({ machine: appMachine, options });
 ```
 
-**Data exposure.** Inspection events carry the machine's definition and its context — which in a real application may include user identifiers, tokens, or form input. The browser transport posts that data to the inspector's origin over `postMessage`, and the WebSocket transport sends it to whatever server is listening. Treat an inspector connection as a data egress path: keep it out of production builds, and when inspecting a shared environment, know where the events are going.
+**Data exposure.** Inspection events carry the machine's definition and its context — which in a real application may include user identifiers, tokens, or form input. A browser transport posts that data to the inspector's origin over `postMessage`, and a socket transport sends it to whatever server is listening. Treat an inspector connection as a data egress path: keep it out of production builds, and when inspecting a shared environment, know where the events are going.
 
 ---
 
@@ -194,4 +260,4 @@ const createPlayer = definePlayer({ machine: appMachine, options });
 - **[`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)** — the actor an inspector observes
 - **[The Actor Model](actor-model.md)** — why the actor is the actor, and what that buys
 - **[Getting Started](getting-started.md)** — installing packages and creating your first actor
-- **[Stately inspect docs](https://stately.ai/docs/inspector)** — the inspector itself, its transports and options
+- **[Stately inspect docs](https://stately.ai/docs/inspector)** — the inspector app itself