@xmachines/docs 1.0.0 → 2.0.0-alpha.1

package/examples/traffic-light.md

@@ -18,58 +18,58 @@ Applicable patterns:
 ## Complete Code
 
 ```typescript
-import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { setup, types } from "xstate";
+import {
+	createRoutedMachine,
+	definePlayer,
+	emptyEventSchema,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
 
 // 1. Typed setup
 const trafficSetup = setup({
-	types: {
-		context: {} as {
+	schemas: {
+		context: types<{
 			params: Record<string, string>;
 			query: Record<string, string>;
+		}>(),
+		events: {
+			timer: emptyEventSchema,
+			"play.route": playRouteEventSchema,
 		},
-		events: {} as
-			| { type: "timer" }
-			| {
-					type: "play.route";
-					to: string;
-					params?: Record<string, string>;
-					query?: Record<string, string>;
-			  },
-		input: {} as undefined,
+		meta: playMetaSchema,
 	},
 });
 
-// 2. Machine with meta.route on every state
-//    formatPlayRouteTransitions() reads each state's id + meta.route and
-//    auto-generates the root-level play.route event handlers.
-const trafficMachine = trafficSetup.createMachine(
-	formatPlayRouteTransitions({
-		id: "traffic",
-		initial: "red",
-		context: {
-			params: {},
-			query: {},
+// 2. Machine with meta.route on every state.
+//    createRoutedMachine wires routing up from each state's id + meta.route,
+//    with the same config typing as trafficSetup.createMachine itself.
+const trafficMachine = createRoutedMachine(trafficSetup)({
+	id: "traffic",
+	initial: "red",
+	context: {
+		params: {},
+		query: {},
+	},
+	states: {
+		red: {
+			id: "red",
+			meta: { route: "/red" },
+			on: { timer: { target: "green" } },
+		},
+		green: {
+			id: "green",
+			meta: { route: "/green" },
+			on: { timer: { target: "yellow" } },
 		},
-		states: {
-			red: {
-				id: "red",
-				meta: { route: "/red" },
-				on: { timer: "green" },
-			},
-			green: {
-				id: "green",
-				meta: { route: "/green" },
-				on: { timer: "yellow" },
-			},
-			yellow: {
-				id: "yellow",
-				meta: { route: "/yellow" },
-				on: { timer: "red" },
-			},
+		yellow: {
+			id: "yellow",
+			meta: { route: "/yellow" },
+			on: { timer: { target: "red" } },
 		},
-	}),
-);
+	},
+});
 
 // 3. Player factory
 const createPlayer = definePlayer({ machine: trafficMachine });
@@ -101,23 +101,12 @@ actor.stop();
 
 ## How `formatPlayRouteTransitions` Works
 
-`formatPlayRouteTransitions` crawls every state that has **both** an `id` and a `meta.route`, then generates root-level `play.route` event handlers of the form:
-
-```typescript
-// Auto-generated by formatPlayRouteTransitions — you don't write this manually:
-on: {
-  "play.route": [
-    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: true, actions: assign({ params, query }) },
-    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: true, actions: assign({ params, query }) },
-    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: true, actions: assign({ params, query }) },
-  ],
-}
-```
+`formatPlayRouteTransitions` (applied by `createRoutedMachine`) crawls every state that has **both** an `id` and a `meta.route` and wires them to XState v6's native routing: each routed state gets a static `route: {}` config, and one root `play.route` forwarder navigates those targets in a single atomic transition while patching `params`/`query` into context. See the [routing patterns example](./routing-patterns.md) for the full mechanism, including user-declared route configs and fallback handling for unknown targets.
 
 **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` patches them into context on every `play.route` transition.
 
 ## `actor.currentRoute` Signal
 
@@ -137,12 +126,12 @@ unwatch();
 ## Key Concepts
 
 - **`meta.route`**: Marks a state as routable. The value is a URL template (e.g. `"/profile/:username"`).
-- **`formatPlayRouteTransitions`**: Utility that auto-generates `play.route` handlers from `id` + `meta.route` pairs. Wrap your machine config before passing to `createMachine`.
+- **`createRoutedMachine`**: Setup-typed entry point that applies `formatPlayRouteTransitions` — wiring `id` + `meta.route` pairs to XState v6's native routing (`route` configs + an `xstate.route` forwarder).
 - **`actor.currentRoute`**: TC39 `Signal.Computed` containing the resolved URL for the active state.
 - **`play.route` events**: Navigation events with a `to: "#stateId"` target. Use `to: "#red"` (state ID), not `to: "/red"` (URL path).
 
 ## Next Steps
 
-- **[Form Validation Example](form-validation.md)** — Context mutations with `setup.assign` and guards
-- **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
+- **[Form Validation Example](form-validation.md)** — Context patches and guard logic in transition functions
+- **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth redirects
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification

package/guides/getting-started.md

@@ -145,7 +145,7 @@ This section covers installing XMachines packages into your own application and
 - **Node.js** `>= 22.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** `v6` (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.
 
@@ -161,7 +161,7 @@ pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-sig
 
 | 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/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), routing helpers |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | Abstract actor base class and interface types                                                                                                                       |
 | [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md))                                 |
@@ -199,15 +199,16 @@ pnpm add @xmachines/play-dom      # Vanilla DOM
 The minimum viable XMachines actor — no framework dependencies:
 
 ```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { setup, types } from "xstate";
+import { definePlayer, emptyEventSchema } from "@xmachines/play-xstate";
 
-// 1. Declare types with setup() — the XState v5 typed entry point
+// 1. Declare 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: emptyEventSchema,
+		},
 	},
 });
 
@@ -219,18 +220,18 @@ const machine = appSetup.createMachine({
 	states: {
 		off: {
 			on: {
-				toggle: {
+				toggle: ({ context }) => ({
 					target: "on",
-					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
-				},
+					context: { count: context.count + 1 },
+				}),
 			},
 		},
 		on: {
 			on: {
-				toggle: {
+				toggle: ({ context }) => ({
 					target: "off",
-					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
-				},
+					context: { count: context.count + 1 },
+				}),
 			},
 		},
 	},
@@ -257,8 +258,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.
+- Update context by returning a shallow `context` patch from the transition function — there is no `assign` action.
 - Call `actor.start()` before sending events.
 - Call `actor.stop()` when done to clean up signal subscriptions.
 
@@ -270,64 +271,73 @@ State machines control navigation through `meta.route` on states and `play.route
 
 #### Define a routable machine with `formatPlayRouteTransitions`
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
+`createRoutedMachine` wires routing up from `id` + `meta.route` state pairs (via [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)): each routed state gets a native XState v6 `route: {}` config, and one root `play.route` forwarder navigates those targets in a single atomic transition, patching `params`/`query` into context:
 
 ```typescript
-import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
-import type { PlayRouteEvent } from "@xmachines/play-router";
+import { setup, types } from "xstate";
+import {
+	createRoutedMachine,
+	definePlayer,
+	emptyEventSchema,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
 
 const appSetup = setup({
-	types: {
-		// params and query are REQUIRED for formatPlayRouteTransitions
-		context: {} as {
+	schemas: {
+		// params and query are REQUIRED for routed machines
+		context: types<{
 			isAuthenticated: boolean;
 			params: Record<string, string>;
 			query: Record<string, string>;
+		}>(),
+		events: {
+			"play.route": playRouteEventSchema,
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": emptyEventSchema,
 		},
-		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
+		// meta.route on state nodes needs a declared meta schema
+		meta: playMetaSchema,
 	},
 });
 
-const appMachine = appSetup.createMachine(
-	// formatPlayRouteTransitions auto-generates play.route handlers from id + meta.route pairs
-	formatPlayRouteTransitions({
-		id: "app",
-		initial: "home",
-		context: { isAuthenticated: false, params: {}, query: {} },
-		states: {
-			home: { id: "home", meta: { route: "/" } },
-			about: { id: "about", meta: { route: "/about" } },
-			login: { id: "login", meta: { route: "/login" } },
-			dashboard: {
-				id: "dashboard",
-				meta: { route: "/dashboard" },
-				// always guard: redirect to /login if not authenticated
-				always: {
-					guard: ({ context }) => !context.isAuthenticated,
-					target: "login",
-				},
+// createRoutedMachine(appSetup) has the same signature as appSetup.createMachine
+const appMachine = createRoutedMachine(appSetup)({
+	id: "app",
+	initial: "home",
+	context: { isAuthenticated: false, params: {}, query: {} },
+	states: {
+		home: { id: "home", meta: { route: "/" } },
+		about: { id: "about", meta: { route: "/about" } },
+		login: { id: "login", meta: { route: "/login" } },
+		dashboard: {
+			id: "dashboard",
+			meta: { route: "/dashboard" },
+			// always transition: redirect to /login if not authenticated
+			always: ({ context }) => {
+				if (context.isAuthenticated) return;
+				return { target: "login" };
 			},
-			profile: { id: "profile", meta: { route: "/profile/:username" } },
 		},
-		on: {
-			"auth.login": {
+		profile: { id: "profile", meta: { route: "/profile/:username" } },
+	},
+	on: {
+		"auth.login": ({ context }) => {
+			if (context.isAuthenticated) return;
+			return {
 				target: ".dashboard",
-				guard: ({ context }) => !context.isAuthenticated,
-				actions: appSetup.assign({
-					isAuthenticated: true,
-				}),
-			},
-			"auth.logout": {
+				context: { isAuthenticated: true },
+			};
+		},
+		"auth.logout": ({ context }) => {
+			if (!context.isAuthenticated) return;
+			return {
 				target: ".home",
-				guard: ({ context }) => context.isAuthenticated,
-				actions: appSetup.assign({ isAuthenticated: false }),
-			},
+				context: { isAuthenticated: false },
+			};
 		},
-	}),
-);
+	},
+});
 
 const createPlayer = definePlayer({ machine: appMachine });
 const actor = createPlayer();
@@ -340,9 +350,9 @@ console.log(actor.currentRoute.get()); // "/"
 actor.send({ type: "play.route", to: "#about" });
 console.log(actor.currentRoute.get()); // "/about"
 
-// Attempt a protected route — always guard redirects to login
+// Attempt a protected route — always transition redirects to login
 actor.send({ type: "play.route", to: "#dashboard" });
-console.log(actor.getSnapshot().value); // "login" (guard fired)
+console.log(actor.getSnapshot().value); // "login" (redirect fired)
 
 // Navigate with params
 actor.send({ type: "auth.login", username: "alice" });
@@ -357,7 +367,7 @@ actor.stop();
 - Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
 - Send `play.route` events with `to: "#stateId"` — always use the `id` field prefixed with `#`, never raw URL paths.
 - The machine context **must** include `params: Record<string, string>` and `query: Record<string, string>`.
-- Use `always` guards to protect states from direct URL access — these fire even on browser back/forward.
+- Use `always` transitions (function form, with an early-return guard) to protect states from direct URL access — these fire even on browser back/forward.
 
 ---
 
@@ -609,14 +619,14 @@ window.addEventListener("beforeunload", () => disconnect());
 
 **Error:** `MissingQueryContextError` at runtime when using [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md).
 
-**Fix:** Add `params` and `query` fields to your machine context type and initial value:
+**Fix:** Add `params` and `query` fields to your machine context schema and initial value:
 
 ```typescript
-context: {} as {
+context: types<{
   params: Record<string, string>;
   query: Record<string, string>;
   // ...other fields
-}
+}>()
 // and initialize them:
 context: { params: {}, query: {}, /* ...other fields */ }
 ```
@@ -678,7 +688,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 schemas (via `types<T>()`) for context, events, input, and state meta          |
 | [`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md)                | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/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                                               |
@@ -686,9 +696,10 @@ node --version
 | `actor.state`                                                                                         | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                           |
 | `actor.currentRoute`                                                                                  | `Signal.Computed<string \| null>` — resolved URL from active state's `meta.route`                               |
 | `actor.currentView`                                                                                   | `Signal.State<PlaySpec \| null>` — view spec from active state's `meta.view`                                    |
-| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) | Generates `play.route` handlers from `id` + `meta.route` state pairs                                            |
+| `createRoutedMachine(setup)`                                                                          | Setup-typed `createMachine` that wires `id` + `meta.route` state pairs to native routing                        |
+| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) | Underlying transform — native `route: {}` configs plus one root `play.route` forwarder                          |
 | `play.route` event                                                                                    | Navigation event — `to: "#stateId"`, optional `params`, `query`                                                 |
-| `always` guard                                                                                        | Protects states — fires on entry before any event, even on direct URL access                                    |
+| `always` transition                                                                                   | Protects states — fires on entry before any event, even on direct URL access                                    |
 | [`extractMachineRoutes`](../api/@xmachines/play-router/functions/extractMachineRoutes.md)             | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                      |
 | [`createRouteMapFromTree`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md)         | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                 |
 | [`connectRouter`](../api/@xmachines/play-dom-router/functions/connectRouter.md)                       | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                               |

package/guides/state-machines.md

@@ -1,6 +1,6 @@
 # Understanding State Machines in XMachines
 
-XMachines uses XState v5 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
+XMachines uses XState v6 as its state machine engine. This page explains what finite state machines are, how XMachines extends them with routing and view metadata, and why this design eliminates an entire category of bugs common in traditional frontend architecture.
 
 After reading this, you will understand what a machine definition actually encodes — and why state machines are a better unit of business logic than component-level state or ad-hoc if/else trees.
 
@@ -22,18 +22,21 @@ In traditional component-level state (e.g., boolean flags, `useState` combinatio
 
 ---
 
-## How XMachines uses XState v5
+## How XMachines uses XState v6
 
-XMachines wraps XState v5 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
+XMachines wraps XState v6 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
+import { emptyEventSchema } from "@xmachines/play-xstate";
 
 const authSetup = setup({
-	types: {
-		context: {} as { username: string | null },
-		events: {} as { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as undefined,
+	schemas: {
+		context: types<{ username: string | null }>(),
+		events: {
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": emptyEventSchema,
+		},
 	},
 });
 
@@ -44,20 +47,18 @@ const authMachine = authSetup.createMachine({
 	states: {
 		unauthenticated: {
 			on: {
-				"auth.login": {
+				"auth.login": ({ event }) => ({
 					target: "authenticated",
-					actions: authSetup.assign({
-						username: ({ event }) => event.username,
-					}),
-				},
+					context: { username: event.username },
+				}),
 			},
 		},
 		authenticated: {
 			on: {
-				"auth.logout": {
+				"auth.logout": () => ({
 					target: "unauthenticated",
-					actions: authSetup.assign({ username: null }),
-				},
+					context: { username: null },
+				}),
 			},
 		},
 	},
@@ -66,8 +67,8 @@ const authMachine = authSetup.createMachine({
 
 Key patterns:
 
-- **Always use `setup({ types })`** before `createMachine`. The type declarations let TypeScript check that your events, context fields, and actions are consistent throughout the machine.
-- **Use `setup.assign()`**, not the bare `assign` from xstate. This keeps the type checker aware of which context fields the action touches.
+- **Always use `setup({ schemas })`** before `createMachine`. The `types<T>()` helper declares type-only schemas so TypeScript can check that your events, context fields, and transitions are consistent throughout the machine. The `events` schema is a map from event type to payload shape — the payload excludes the `type` field itself.
+- **Transitions are plain functions** that return `{ target, context }`. Context updates are shallow patches returned from the transition function — there is no separate `assign` action.
 - **Event names use lowercase dot-separated namespaces**: `"auth.login"`, `"play.route"`, `"form.submit"`. This convention makes the event log readable and avoids collisions.
 
 ---
@@ -138,8 +139,8 @@ states: {
   home: {
     on: {
       "play.route": [
-        { guard: ({ event }) => event.to === "#login", target: "login" },
-        { guard: ({ event }) => event.to === "#dashboard", target: "dashboard" },
+        ({ event }) => (event.to === "#login" ? { target: "login" } : undefined),
+        ({ event }) => (event.to === "#dashboard" ? { target: "dashboard" } : undefined),
       ],
     },
     meta: { route: "/" },
@@ -148,34 +149,38 @@ states: {
 }
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) wires this up automatically from the `id` and `meta.route` fields you already have — each routed state gets a native XState v6 `route: {}` config (for `xstate.route` interop and graph tooling), and one root `play.route` forwarder navigates those targets in a single atomic transition, patching `params`/`query` into context:
 
 ```typescript
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-
-const appMachine = setup({/* ... */}).createMachine(
-	formatPlayRouteTransitions({
-		id: "app",
-		initial: "home",
-		states: {
-			home: { id: "home", meta: { route: "/" } },
-			login: { id: "login", meta: { route: "/login" } },
-			dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
-		},
-	}),
-);
+import { createRoutedMachine, emptyEventSchema } from "@xmachines/play-xstate";
+
+const appSetup = setup({/* ... */});
+
+const appMachine = createRoutedMachine(appSetup)({
+	id: "app",
+	initial: "home",
+	states: {
+		home: { id: "home", meta: { route: "/" } },
+		login: { id: "login", meta: { route: "/login" } },
+		dashboard: { id: "dashboard", meta: { route: "/dashboard" } },
+	},
+});
 ```
 
-[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/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):
+`createRoutedMachine` has the same signature as the setup's own `createMachine`, so the config keeps full contextual typing. (The underlying transform, [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md), can also be called directly on a config before `createMachine`.) The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
 
 ```typescript
-types: {
-  context: {} as {
+schemas: {
+  context: types<{
     params: Record<string, string>;
     query:  Record<string, string>;
     // ... other context fields
+  }>(),
+  events: {
+    "play.route": playRouteEventSchema, // exported by @xmachines/play-xstate
+    // ... other event schemas
   },
-  events: {} as PlayRouteEvent | OtherEvents,
+  meta: playMetaSchema, // exported by @xmachines/play-xstate — types meta.route / meta.view
 }
 ```
 
@@ -183,7 +188,7 @@ types: {
 
 ## Guards — the actor's authority
 
-Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of `{ context, event }` that return a boolean.
+Guards are the mechanism by which the actor controls whether a transition occurs. They are pure functions of transition arguments (`{ context, event, ... }`) that return a boolean. Named guards declared in `setup({ guards })` are passed to every transition function via `args.guards`:
 
 ```typescript
 const authSetup = setup({
@@ -194,11 +199,22 @@ const authSetup = setup({
 });
 ```
 
-Guards are evaluated by XState before a transition fires. If the guard returns `false`, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
+A transition function evaluates its guard condition and returns early to reject the transition:
+
+```typescript
+on: {
+	"admin.open": (args) => {
+		if (!args.guards.isAdmin(args)) return;
+		return { target: "adminPanel" };
+	},
+},
+```
+
+When the guard fails, the transition function returns `undefined`, the transition does not occur — the machine stays in its current state and the `play.route` event is discarded. The router bridge then sees that `actor.currentRoute` has not changed and corrects the URL back to the current valid route.
 
 This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
 
-XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions:
+XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions. Each combinator returns a plain predicate — call it inside a transition function with the transition arguments:
 
 | Function                                                                                            | What it does                            |
 | --------------------------------------------------------------------------------------------------- | --------------------------------------- |
@@ -213,27 +229,27 @@ XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmach
 
 ## Context — persistent state across transitions
 
-Context is the machine's persistent data store. It survives transitions and can be read and updated by actions:
+Context is the machine's persistent data store. It survives transitions and is updated by the shallow patches transition functions return:
 
 ```typescript
-// Context is defined in setup({ types })
-types: {
-  context: {} as {
+// Context is defined in setup({ schemas })
+schemas: {
+  context: types<{
     isAuthenticated: boolean;
     username: string | null;
     loginAttempts: number;
-  },
+  }>(),
 },
 
-// Actions mutate context via assign
-actions: {
-  recordLoginFailure: assign({
-    loginAttempts: ({ context }) => context.loginAttempts + 1,
+// Transitions update context by returning a patch
+on: {
+  "login.failure": ({ context }) => ({
+    context: { loginAttempts: context.loginAttempts + 1 },
   }),
 },
 ```
 
-Context is accessed in guards, actions, and when computing routes or views. It is not directly observable from outside the actor via signals — only the derived signals (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a `Signal.Computed` to the actor that derives from `actor.state`.
+Context is accessed in guards, transition functions, and when computing routes or views. It is not directly observable from outside the actor via signals — only the derived signals (`state`, `currentRoute`, `currentView`) are public. If you need to expose a context field reactively, add a `Signal.Computed` to the actor that derives from `actor.state`.
 
 ---
 
@@ -280,5 +296,5 @@ actor.start();
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
 - [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), guard combinators
-- [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
+- [XState documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0",
+  "version": "2.0.0-alpha.1",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -54,7 +54,7 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^26.1.1",
-    "@xmachines/shared": "1.0.0",
+    "@xmachines/shared": "2.0.0-alpha.1",
     "oxfmt": "^0.58.0",
     "oxlint": "^1.73.0",
     "typedoc": "^0.28.19",