@xmachines/docs 7.0.0 → 8.0.0-next.1

package/examples/traffic-light.md

@@ -16,27 +16,24 @@ Applicable patterns:
 ## Complete Code
 
 ```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";
 
-// 1. Typed setup
+// 1. Typed setup. The events are a map from the type of each event to its payload.
 const trafficSetup = setup({
-	types: {
-		context: {} as {
+	schemas: {
+		context: types<{
 			params: Record<string, string>;
 			query: Record<string, string>;
+		}>(),
+		events: {
+			timer: types<void>(),
+			"play.route": types<Omit<PlayRouteEvent, "type">>(),
 		},
-		events: {} as
-			| { type: "timer" }
-			| {
-					type: "play.route";
-					to: string;
-					params?: Record<string, string>;
-					query?: Record<string, string>;
-			  },
-		input: undefined,
+		meta: types<{ route?: string }>(),
 	},
 });
 
@@ -55,17 +52,17 @@ const trafficMachine = trafficSetup.createMachine(
 			red: {
 				id: "red",
 				meta: { route: "/red" },
-				on: { timer: "green" },
+				on: { timer: { target: "green" } },
 			},
 			green: {
 				id: "green",
 				meta: { route: "/green" },
-				on: { timer: "yellow" },
+				on: { timer: { target: "yellow" } },
 			},
 			yellow: {
 				id: "yellow",
 				meta: { route: "/yellow" },
-				on: { timer: "red" },
+				on: { timer: { target: "red" } },
 			},
 		},
 	}),
@@ -110,9 +107,9 @@ actor.stop();
 // Auto-generated by formatPlayRouteTransitions — you don't write this manually:
 on: {
   "play.route": [
-    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: false, actions: assign({ params, query }) },
-    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: false, actions: assign({ params, query }) },
-    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: false, actions: assign({ params, query }) },
+    { target: ".red",    matches: { to: "#red" },    reenter: false, context: ({ context, event }) => ({ params, query }) },
+    { target: ".green",  matches: { to: "#green" },  reenter: false, context: ({ context, event }) => ({ params, query }) },
+    { target: ".yellow", matches: { to: "#yellow" }, reenter: false, context: ({ context, event }) => ({ params, query }) },
   ],
 }
 ```
@@ -120,7 +117,8 @@ on: {
 **Requirements:**
 
 - Every routable state must have both `id` (the `#id` navigation target) and `meta.route` (the URL template).
-- The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` assigns them on every `play.route` transition.
+- The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` writes them on every `play.route` transition.
+- Each generated transition is a config object: `matches` selects the event by its `to` field, and `context` returns the patch that XState merges into the context. The list holds the generated transitions first, and a `play.route` transition of your own last, as the fallback. The config types of XState 6 declare one transition for each event, and its runtime reads a list in its order.
 - `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state whose route must also re-enter the domain of the transition. See [Re-entry on a navigation](../guides/routing.md#re-entry-on-a-navigation).
 
 ## The `actor.currentRoute` atom
@@ -151,6 +149,6 @@ unwatch();
 
 ## Next Steps
 
-- **[Form Validation Example](form-validation.md)** — Context mutations with `setup.assign` and guards
+- **[Form Validation Example](form-validation.md)** — Context patches and guards in transition functions
 - **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification

package/guides/actor-model.md

@@ -102,8 +102,7 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 An adapter extends the actor class of its own engine. [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) extends `Actor` of XState, which means:
 
-- XState's inspection API works ([`@statelyai/inspect`](https://stately.ai/docs/inspector) — see [Inspecting a Running Actor](inspector.md))
-- XState DevTools attach to actors normally
+- The inspection API of XState works: the `inspect` option receives the `@xstate.actor` and `@xstate.transition` events of the actor — see [Inspecting a Running Actor](inspector.md)
 - The full XState ecosystem (testing utilities, visualization) is compatible
 
 [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) asks for two members: a reactive `state` property of type `Atom<TSnapshot>`, and a typed `send`. `state` is the single point where the pull-based snapshot API of an engine is bridged to the push-based atom system.
@@ -166,12 +165,12 @@ The factory accepts an optional `input` (initial context overrides) and an optio
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 
 const machine = setup({
-	types: {
-		input: {} as { userId: string } | undefined,
-		context: {} as { userId: string | null },
+	schemas: {
+		input: types<{ userId: string } | undefined>(),
+		context: types<{ userId: string | null }>(),
 	},
 }).createMachine({ context: ({ input }) => ({ userId: input?.userId ?? null }) });
 

package/guides/getting-started.md

@@ -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,14 +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@0.21.0-xm.6
+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.6`.
+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))                                                                                                                                                                      |
@@ -202,14 +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" },
+	schemas: {
+		context: types<{ count: number }>(),
+		events: { toggle: types<void>() },
 	},
 });
 
@@ -221,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 } }),
 			},
 		},
 	},
@@ -259,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.
 
@@ -314,22 +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" },
+		// The `meta` of each state: XState 6 types it from this schema
+		meta: types<{ route?: RouteMetadata }>(),
 	},
 });
 
@@ -347,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,
 		},
 	}),
 );
@@ -698,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 fragment
 on: {
-  "play.route": {
-    actions: assign({
-      params: ({ event }) => event.params ?? {},
-      query: ({ event }) => event.query ?? {},
-    }),
-  },
+  "play.route": ({ event }) => ({
+    context: {
+      params: event.params ?? {},
+      query: event.query ?? {},
+    },
+  }),
 }
 ```
 
@@ -776,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,37 +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 type { AnyStateMachine } from "xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
 
 declare const appMachine: AnyStateMachine; // your machine
 
-const { inspect } = createBrowserInspector();
+const inspect = (event: InspectionEvent): void => {
+	if (event.type === "@xstate.transition") {
+		console.log(event.event.type, "→", event.snapshot.status);
+	}
+};
 
 const createPlayer = definePlayer({
 	machine: appMachine,
@@ -42,7 +41,7 @@ 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:
 
@@ -96,7 +95,12 @@ 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
 
@@ -108,14 +112,14 @@ const inspect = (event: InspectionEvent) => {
 		// ❌ 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()`.
 
 ---
 
@@ -124,23 +128,22 @@ 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 { createBrowserInspector } from "@statelyai/inspect";
 import { definePlayer } from "@xmachines/play-xstate";
-import type { AnyStateMachine, InspectionEvent, Observer } from "xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
 
 declare const appMachine: AnyStateMachine; // your machine
+declare function openInspector(): (event: InspectionEvent) => void; // your transport
 
-let current: Observer<InspectionEvent> | undefined;
+let current: ((event: InspectionEvent) => void) | undefined;
 
 const createPlayer = definePlayer({
 	machine: appMachine,
-	options: { inspect: (event) => current?.next?.(event) },
+	options: { inspect: (event) => current?.(event) },
 });
 
 // Later, from a click handler
 export function enableInspector() {
-	const { inspect } = createBrowserInspector();
-	current = inspect;
+	current = openInspector();
 }
 ```
 
@@ -152,21 +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 } from "xstate";
+import type { AnyStateMachine, InspectionEvent } from "xstate";
 
 declare const appMachine: AnyStateMachine; // your machine
+declare const socket: { send(data: string): void }; // your transport
 
-const { inspect } = createWebSocketInspector({ url: "ws://localhost:8080" });
+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.
 
 ---
 
@@ -180,24 +187,26 @@ 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()`, 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:
+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
-import { createBrowserInspector } from "@statelyai/inspect";
 import { definePlayer } from "@xmachines/play-xstate";
-import type { AnyStateMachine, InspectionEvent, Observer } from "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: Observer<InspectionEvent> | undefined;
+let current: ((event: InspectionEvent) => void) | undefined;
 
 const actor = definePlayer({
 	machine: appMachine,
 	options: {
 		inspect: (event) => {
 			if (current) {
-				current.next?.(event);
+				current(event);
 				return;
 			}
 			// Keep the last 500 events while nobody opens the inspector. A long session drops
@@ -214,11 +223,8 @@ actor.start();
 // 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);
+	current = openInspector();
+	for (const event of buffer.splice(0)) current(event);
 }
 ```
 
@@ -228,23 +234,23 @@ The demo controller answers the late-opening problem from the previous section:
 
 ## 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
 /// <reference types="vite/client" />
-import { createBrowserInspector } from "@statelyai/inspect";
 import { definePlayer } from "@xmachines/play-xstate";
-import type { AnyStateMachine } from "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: createBrowserInspector().inspect } : {};
+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.
 
 ---
 
@@ -254,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

package/guides/routing.md

@@ -55,10 +55,12 @@ A **modifier** follows a param, a wildcard or a group:
 | `*`      | zero or more | matches                  |
 
 ```ts
-import { createMachine } from "xstate";
+import { createMachine, types } from "xstate";
 
 const machine = createMachine({
 	id: "app",
+	// XState 6 types the `meta` of each state from this schema
+	schemas: { meta: types<{ route?: string }>() },
 	initial: "home",
 	states: {
 		home: { meta: { route: "/" } },
@@ -145,7 +147,7 @@ This rule is about the PATTERN that a state declares. A param VALUE needs no esc
 
 `encodeURIComponent` leaves `*` as it stands, and that is the one exception. A bridge refuses a path that still holds a `:` or a `*`, because such a character marks a param that nothing substituted. A value of `a*b` therefore stops the push, and the URL stays where it is.
 
-A route that carries a QUERY STRING is the same case as a raw `?`, and it is the form a machine writes most often. The grammar reads the `?` of `meta: { route: "/dates?trip=one-way" }` as a modifier that follows no part, so `RouteMap` throws `InvalidRoutePatternError` in its constructor and the application starts never. A route declares a PATHNAME: put the default in `context.query`, which the generated `play.route` transition assigns and `buildRouteUrl` writes to the URL.
+A route that carries a QUERY STRING is the same case as a raw `?`, and it is the form a machine writes most often. The grammar reads the `?` of `meta: { route: "/dates?trip=one-way" }` as a modifier that follows no part, so `RouteMap` throws `InvalidRoutePatternError` in its constructor and the application starts never. A route declares a PATHNAME: put the default in `context.query`, which the generated `play.route` transition writes and `buildRouteUrl` writes to the URL.
 
 ### The prefix rule