@xmachines/docs 2.0.0-alpha.1 → 2.0.0

package/examples/traffic-light.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Traffic Light State Machine
 
 Multi-state machine with `meta.route` on every state, demonstrating cyclic transitions and `formatPlayRouteTransitions`.
@@ -18,58 +16,58 @@ Applicable patterns:
 ## Complete Code
 
 ```typescript
-import { setup, types } from "xstate";
-import {
-	createRoutedMachine,
-	definePlayer,
-	emptyEventSchema,
-	playMetaSchema,
-	playRouteEventSchema,
-} from "@xmachines/play-xstate";
+import { setup } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
 
 // 1. Typed setup
 const trafficSetup = setup({
-	schemas: {
-		context: types<{
+	types: {
+		context: {} as {
 			params: Record<string, string>;
 			query: Record<string, string>;
-		}>(),
-		events: {
-			timer: emptyEventSchema,
-			"play.route": playRouteEventSchema,
 		},
-		meta: playMetaSchema,
+		events: {} as
+			| { type: "timer" }
+			| {
+					type: "play.route";
+					to: string;
+					params?: Record<string, string>;
+					query?: Record<string, string>;
+			  },
+		input: {} as undefined,
 	},
 });
 
-// 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" } },
+// 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: {},
 		},
-		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,12 +99,23 @@ actor.stop();
 
 ## How `formatPlayRouteTransitions` Works
 
-`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.
+`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 }) },
+  ],
+}
+```
 
 **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` patches them into context on every `play.route` transition.
+- The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` assigns them on every `play.route` transition.
 
 ## `actor.currentRoute` Signal
 
@@ -126,12 +135,12 @@ unwatch();
 ## Key Concepts
 
 - **`meta.route`**: Marks a state as routable. The value is a URL template (e.g. `"/profile/:username"`).
-- **`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).
+- **`formatPlayRouteTransitions`**: Utility that auto-generates `play.route` handlers from `id` + `meta.route` pairs. Wrap your machine config before passing to `createMachine`.
 - **`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 patches and guard logic in transition functions
-- **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth redirects
+- **[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
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification

package/guides/README.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # XMachines Guides
 
 User-facing guides for the XMachines Play architecture.
@@ -15,3 +13,9 @@ Background reading that explains the _why_ behind XMachines design decisions.
 - **[Understanding State Machines](state-machines.md)** — What finite state machines are, how `meta.route` and `meta.view` extend them, and why they replace boolean flags and component-level routing logic
 - **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
 - **[Understanding TC39 Signals](signals.md)** — The three signal primitives (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`), why XMachines uses them instead of observables, and the architectural invariants they enforce
+
+## Tooling
+
+Working with a running actor.
+
+- **[Inspecting a Running Actor](inspector.md)** — Attaching the Stately inspector via `PlayerOptions.inspect`, reading inspection events, enabling an inspector after startup, and inspecting without a browser

package/guides/actor-model.md

@@ -91,7 +91,7 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) (from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
 
-- XState's inspection API works (`@xstate/inspect`)
+- 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 full XState ecosystem (testing utilities, visualization) is compatible
 

package/guides/getting-started.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Getting Started
 
 This guide serves two audiences:
@@ -145,7 +143,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** `v6` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
+- **XState** `v5` (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.
 
@@ -153,18 +151,19 @@ All packages are ES modules (`"type": "module"`). Use `.js` extensions in all Ty
 
 #### Step 1: Install the core packages
 
-Every XMachines application needs these three packages plus XState:
+Every XMachines application needs these four packages plus XState:
 
 ```bash
-pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals @xmachines/json-render-core
 ```
 
 | Package                                                               | Role                                                                                                                                                                |
 | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `xstate`                                                              | XState v6 state machine engine (peer dependency)                                                                                                                    |
+| `xstate`                                                              | XState v5 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))                                 |
+| `@xmachines/json-render-core`                                         | Spec and store types the actor layer builds on — a peer of `@xmachines/play-actor`, and of every renderer package                                                   |
 
 #### Step 2: Install a router adapter (pick one)
 
@@ -199,16 +198,15 @@ pnpm add @xmachines/play-dom      # Vanilla DOM
 The minimum viable XMachines actor — no framework dependencies:
 
 ```typescript
-import { setup, types } from "xstate";
-import { definePlayer, emptyEventSchema } from "@xmachines/play-xstate";
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
 
-// 1. Declare schemas with setup() — the XState v6 typed entry point
+// 1. Declare types with setup() — the XState v5 typed entry point
 const appSetup = setup({
-	schemas: {
-		context: types<{ count: number }>(),
-		events: {
-			toggle: emptyEventSchema,
-		},
+	types: {
+		context: {} as { count: number },
+		events: {} as { type: "toggle" },
+		input: {} as undefined,
 	},
 });
 
@@ -220,18 +218,18 @@ const machine = appSetup.createMachine({
 	states: {
 		off: {
 			on: {
-				toggle: ({ context }) => ({
+				toggle: {
 					target: "on",
-					context: { count: context.count + 1 },
-				}),
+					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
 			},
 		},
 		on: {
 			on: {
-				toggle: ({ context }) => ({
+				toggle: {
 					target: "off",
-					context: { count: context.count + 1 },
-				}),
+					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
 			},
 		},
 	},
@@ -258,8 +256,8 @@ actor.stop();
 
 **Key rules:**
 
-- 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.
+- Always use `setup({ types })` before `createMachine` — never bare `createMachine` from xstate.
+- Use `setup.assign(...)` for context mutations — not the bare `assign` from xstate.
 - Call `actor.start()` before sending events.
 - Call `actor.stop()` when done to clean up signal subscriptions.
 
@@ -271,73 +269,64 @@ State machines control navigation through `meta.route` on states and `play.route
 
 #### Define a routable machine with `formatPlayRouteTransitions`
 
-`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:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
 
 ```typescript
-import { setup, types } from "xstate";
-import {
-	createRoutedMachine,
-	definePlayer,
-	emptyEventSchema,
-	playMetaSchema,
-	playRouteEventSchema,
-} from "@xmachines/play-xstate";
+import { setup } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import type { PlayRouteEvent } from "@xmachines/play-router";
 
 const appSetup = setup({
-	schemas: {
-		// params and query are REQUIRED for routed machines
-		context: types<{
+	types: {
+		// params and query are REQUIRED for formatPlayRouteTransitions
+		context: {} as {
 			isAuthenticated: boolean;
 			params: Record<string, string>;
 			query: Record<string, string>;
-		}>(),
-		events: {
-			"play.route": playRouteEventSchema,
-			"auth.login": types<{ username: string }>(),
-			"auth.logout": emptyEventSchema,
 		},
-		// meta.route on state nodes needs a declared meta schema
-		meta: playMetaSchema,
+		events: {} as
+			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
+		input: {} as undefined,
 	},
 });
 
-// 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" };
+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",
+				},
 			},
+			profile: { id: "profile", meta: { route: "/profile/:username" } },
 		},
-		profile: { id: "profile", meta: { route: "/profile/:username" } },
-	},
-	on: {
-		"auth.login": ({ context }) => {
-			if (context.isAuthenticated) return;
-			return {
+		on: {
+			"auth.login": {
 				target: ".dashboard",
-				context: { isAuthenticated: true },
-			};
-		},
-		"auth.logout": ({ context }) => {
-			if (!context.isAuthenticated) return;
-			return {
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: appSetup.assign({
+					isAuthenticated: true,
+				}),
+			},
+			"auth.logout": {
 				target: ".home",
-				context: { isAuthenticated: false },
-			};
+				guard: ({ context }) => context.isAuthenticated,
+				actions: appSetup.assign({ isAuthenticated: false }),
+			},
 		},
-	},
-});
+	}),
+);
 
 const createPlayer = definePlayer({ machine: appMachine });
 const actor = createPlayer();
@@ -350,9 +339,9 @@ console.log(actor.currentRoute.get()); // "/"
 actor.send({ type: "play.route", to: "#about" });
 console.log(actor.currentRoute.get()); // "/about"
 
-// Attempt a protected route — always transition redirects to login
+// Attempt a protected route — always guard redirects to login
 actor.send({ type: "play.route", to: "#dashboard" });
-console.log(actor.getSnapshot().value); // "login" (redirect fired)
+console.log(actor.getSnapshot().value); // "login" (guard fired)
 
 // Navigate with params
 actor.send({ type: "auth.login", username: "alice" });
@@ -367,7 +356,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` transitions (function form, with an early-return guard) to protect states from direct URL access — these fire even on browser back/forward.
+- Use `always` guards to protect states from direct URL access — these fire even on browser back/forward.
 
 ---
 
@@ -615,22 +604,32 @@ window.addEventListener("beforeunload", () => disconnect());
 
 ### Common Setup Issues (Application Developers)
 
-#### Missing `params` / `query` in context
+#### Query parameters missing from derived URLs
 
-**Error:** `MissingQueryContextError` at runtime when using [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md).
+**Symptom:** `currentRoute` renders the path but the `?query=...` string from a
+`play.route` event never appears. No error is raised — a context without a
+`query` field builds a query-less URL, exactly like `query: {}`.
 
-**Fix:** Add `params` and `query` fields to your machine context schema and initial value:
+**Fix:** With [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/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:
 
 ```typescript
-context: types<{
-  params: Record<string, string>;
-  query: Record<string, string>;
-  // ...other fields
-}>()
-// and initialize them:
-context: { params: {}, query: {}, /* ...other fields */ }
+on: {
+  "play.route": {
+    actions: assign({
+      params: ({ event }) => event.params ?? {},
+      query: ({ event }) => event.query ?? {},
+    }),
+  },
+}
 ```
 
+(Older releases threw `MissingQueryContextError` at construction for a
+routing-aware context without a `query` field; the error class remains
+exported for `instanceof` compatibility but is never thrown.)
+
 #### Missing `id` on routable states
 
 **Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
@@ -688,7 +687,7 @@ node --version
 
 | Term                                                                                                  | Description                                                                                                     |
 | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `setup({ schemas })`                                                                                  | XState v6 entry point — declares schemas (via `types<T>()`) for context, events, input, and state meta          |
+| `setup({ types })`                                                                                    | XState v5 entry point — declares TypeScript types for context, events, and input                                |
 | [`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                                               |
@@ -696,10 +695,9 @@ 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`                                    |
-| `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                          |
+| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) | Generates `play.route` handlers from `id` + `meta.route` state pairs                                            |
 | `play.route` event                                                                                    | Navigation event — `to: "#stateId"`, optional `params`, `query`                                                 |
-| `always` transition                                                                                   | Protects states — fires on entry before any event, even on direct URL access                                    |
+| `always` guard                                                                                        | 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                               |
@@ -709,6 +707,7 @@ node --version
 
 ## Next Steps
 
+- **[Inspecting a Running Actor](inspector.md)** — Attaching the Stately inspector to see the machine, its transitions, and its context live
 - **[Architecture](../contributing/architecture.md)** — System design, layers, invariants, and data flow
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification
 - **[API Reference](../api/README.md)** — Auto-generated API docs for all packages