@xmachines/docs 2.0.0-alpha.1 → 2.1.0

package/examples/form-validation.md

@@ -1,29 +1,21 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Form Validation with Typed Context
 
-Managing login form state using `setup({ schemas })`, typed context patches, guard logic in transition functions, and `meta.view` with `$bindState`.
+Managing login form state using `setup({ types })`, typed `assign`, guards, and `meta.view` with `$bindState`.
 
 ## Use Case
 
 This example mirrors the `authMachine` login pattern: a form state with a local state store (`$bindState` two-way binding), a guard on the submit action, and a `meta.view` spec describing the component tree. It covers:
 
-- Typed context patches returned from transition functions
-- Guard logic as early returns inside transition functions
+- Typed context mutations with `setup.assign`
+- Guards as inline functions checking context
 - `meta.view` spec with `$bindState` for two-way form binding
 - Sending typed domain events from the view layer
 
 ## 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";
 
 // Context shape
 interface LoginContext {
@@ -34,136 +26,133 @@ interface LoginContext {
 	query: Record<string, string>;
 }
 
-// 1. Typed setup — always use setup() before createMachine().
-//    The events schema maps event type -> payload shape (payload excludes `type`);
-//    event names are lowercase dot-separated.
+// Event union — lowercase dot-separated names
+type LoginEvent =
+	| {
+			type: "play.route";
+			to: string;
+			params?: Record<string, string>;
+			query?: Record<string, string>;
+	  }
+	| { type: "auth.login"; username: string }
+	| { type: "auth.logout" };
+
+// 1. Typed setup — always use setup() before createMachine()
 const loginSetup = setup({
-	schemas: {
-		context: types<LoginContext>(),
-		input: types<Partial<LoginContext> | undefined>(),
-		events: {
-			"play.route": playRouteEventSchema,
-			"auth.login": types<{ username: string }>(),
-			"auth.logout": emptyEventSchema,
-		},
-		// State meta carries route templates (meta.route) and typed PlaySpec
-		// view specs (meta.view)
-		meta: playMetaSchema,
+	types: {
+		context: {} as LoginContext,
+		events: {} as LoginEvent,
+		input: {} as Partial<LoginContext> | undefined,
 	},
 });
 
-// 2. Machine — createRoutedMachine wires play.route support from id + meta.route
-//    pairs, with the same config typing as loginSetup.createMachine itself
-const loginMachine = createRoutedMachine(loginSetup)({
-	id: "login",
-	initial: "idle",
-	context: ({ input }) => ({
-		isAuthenticated: input?.isAuthenticated ?? false,
-		username: input?.username ?? null,
-		errorMessage: null,
-		params: input?.params ?? {},
-		query: input?.query ?? {},
-	}),
-
-	// Root-level event handlers — accessible from any state.
-	// Transitions are plain functions: guard with an early return,
-	// update context by returning a shallow patch.
-	on: {
-		"auth.login": ({ context, event }) => {
-			// Guard: allow login only when not already authenticated
-			if (context.isAuthenticated) return;
-			return {
+// 2. Machine — wraps config in formatPlayRouteTransitions for play.route support
+const loginMachine = loginSetup.createMachine(
+	formatPlayRouteTransitions({
+		id: "login",
+		initial: "idle",
+		context: ({ input }) => ({
+			isAuthenticated: input?.isAuthenticated ?? false,
+			username: input?.username ?? null,
+			errorMessage: null,
+			params: input?.params ?? {},
+			query: input?.query ?? {},
+		}),
+
+		// Root-level event handlers — accessible from any state
+		on: {
+			"auth.login": {
 				target: ".dashboard",
-				context: {
+				// Guard: allow login only when not already authenticated
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: loginSetup.assign({
 					isAuthenticated: true,
 					errorMessage: null,
-					// Typed by the event schema — event.username is already narrowed
-					username: event.username,
-				},
-			};
-		},
-		"auth.logout": ({ context }) => {
-			if (!context.isAuthenticated) return;
-			return {
+					// Typed by the event union — TypeScript narrows event.username safely
+					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
+				}),
+			},
+			"auth.logout": {
 				target: ".idle",
-				context: {
+				guard: ({ context }) => context.isAuthenticated,
+				actions: loginSetup.assign({
 					isAuthenticated: false,
 					username: null,
-				},
-			};
+				}),
+			},
 		},
-	},
 
-	states: {
-		idle: {
-			id: "idle",
-			meta: {
-				route: "/",
-				view: {
-					root: "root",
-					elements: {
-						root: { type: "Home", props: { title: "Welcome" }, children: [] },
+		states: {
+			idle: {
+				id: "idle",
+				meta: {
+					route: "/",
+					view: {
+						root: "root",
+						elements: {
+							root: { type: "Home", props: { title: "Welcome" }, children: [] },
+						},
 					},
 				},
 			},
-		},
 
-		login: {
-			id: "login",
-			meta: {
-				route: "/login",
-				view: {
-					root: "root",
-					// Local state store — initial value shown in the form field
-					state: { username: "" },
-					elements: {
-						root: {
-							type: "Login",
-							props: {
-								title: "Sign In",
-								// $bindState wires the prop to the local state store (two-way)
-								username: { $bindState: "/username" },
-							},
-							children: [],
-							on: {
-								// emit("submit") → resolves username from $state, calls login action
-								submit: {
-									action: "login",
-									params: { username: { $state: "/username" } },
+			login: {
+				id: "login",
+				meta: {
+					route: "/login",
+					view: {
+						root: "root",
+						// Local state store — initial value shown in the form field
+						state: { username: "" },
+						elements: {
+							root: {
+								type: "Login",
+								props: {
+									title: "Sign In",
+									// $bindState wires the prop to the local state store (two-way)
+									username: { $bindState: "/username" },
+								},
+								children: [],
+								on: {
+									// emit("submit") → resolves username from $state, calls login action
+									submit: {
+										action: "login",
+										params: { username: { $state: "/username" } },
+									},
 								},
 							},
 						},
 					},
 				},
 			},
-		},
 
-		dashboard: {
-			id: "dashboard",
-			meta: {
-				route: "/dashboard",
-				view: {
-					root: "root",
-					elements: {
-						root: {
-							type: "Dashboard",
-							props: { title: "Dashboard" },
-							children: [],
-							on: {
-								logout: { action: "logout" },
+			dashboard: {
+				id: "dashboard",
+				meta: {
+					route: "/dashboard",
+					view: {
+						root: "root",
+						elements: {
+							root: {
+								type: "Dashboard",
+								props: { title: "Dashboard" },
+								children: [],
+								on: {
+									logout: { action: "logout" },
+								},
 							},
 						},
 					},
 				},
-			},
-			// always-transition: redirect to login if not authenticated
-			always: ({ context }) => {
-				if (context.isAuthenticated) return;
-				return { target: "login" };
+				// always-guard: redirect to login if not authenticated
+				always: {
+					guard: ({ context }) => !context.isAuthenticated,
+					target: "login",
+				},
 			},
 		},
-	},
-});
+	}),
+);
 
 // 3. Factory and actor
 const createPlayer = definePlayer({ machine: loginMachine });
@@ -180,7 +169,7 @@ console.log(actor.getSnapshot().value); // "dashboard"
 console.log(actor.getSnapshot().context.username); // "alice"
 
 // 6. Guard prevents re-login while authenticated
-actor.send({ type: "auth.login", username: "bob" }); // early return — transition rejected
+actor.send({ type: "auth.login", username: "bob" }); // guard fires, transition rejected
 console.log(actor.getSnapshot().context.username); // still "alice"
 
 // 7. Logout
@@ -226,10 +215,10 @@ view: {
 
 ## Key Concepts
 
-- **`setup({ schemas })`**: Always declare context, events, input, and meta schemas before `createMachine` — via `types<T>()` for your own shapes, and the shared `playRouteEventSchema` / `playMetaSchema` / `emptyEventSchema` constants from `@xmachines/play-xstate` for the Play-standard ones. `playMetaSchema` types `meta.view` as a `PlaySpec`, so view specs are checked, not `unknown`.
-- **Context patches**: Update context by returning a shallow `context` patch from the transition function. This provides full type inference — no `assign` action.
-- **Guards as early returns**: `if (context.isAuthenticated) return;` — the transition function checks state invariants ("can I BE in this state?") and returns `undefined` to reject the transition.
-- **`always` transitions**: Functions evaluated on state entry. Used for protected routes — return `{ target }` to redirect before the state is fully entered, or `undefined` to stay.
+- **`setup({ types })`**: Always declare context, events, and input types before `createMachine`.
+- **`setup.assign(...)`**: Use the scoped `assign` from your `setup` instance, not the bare one from `xstate`. This provides full type inference.
+- **Guards as inline functions**: `({ context }) => !context.isAuthenticated` — guards check state invariants ("can I BE in this state?"), not event details.
+- **`always` transitions**: Entry guards on states. Used for protected routes — if the guard fires, the machine redirects before the state is fully entered.
 - **Lowercase dot-separated event types**: `"auth.login"`, `"auth.logout"`, `"play.route"` — not `SCREAMING_SNAKE_CASE`.
 
 ## Connecting the Renderer
@@ -314,6 +303,6 @@ window.addEventListener("beforeunload", () => {
 ## Next Steps
 
 - **[Basic State Machine](basic-state-machine.md)** — Foundational concepts without a view layer
-- **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth redirects
-- **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, `$state`, and `contextProps`
+- **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
+- **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
 - **[`@xmachines/play-router`](../api/@xmachines/play-router/README.md)** — Route extraction and tree building

package/examples/multi-router-integration.md

@@ -1,5 +1,3 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Multi-Router Integration
 
 How to integrate XMachines Play with the 8 router adapters shipped in this monorepo.

package/examples/routing-patterns.md

@@ -1,8 +1,6 @@
-<!-- generated-by: gsd-doc-writer -->
-
 # Routing Patterns
 
-How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTransitions`, and `always` transitions to implement actor-authoritative URL routing.
+How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTransitions`, and `always` guards to implement actor-authoritative URL routing.
 
 ## Overview
 
@@ -62,17 +60,12 @@ states: {
 
 ### `formatPlayRouteTransitions` — Auto-Generating Route Handlers
 
-Instead of hand-writing `play.route` event handlers for every routable state, create the machine through `createRoutedMachine` — it has the same signature as the setup's own `createMachine` (full config inference) and applies `formatPlayRouteTransitions` at runtime:
+Instead of hand-writing `play.route` event handlers for every routable state, wrap your machine config with `formatPlayRouteTransitions`:
 
 ```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";
 
 interface AuthContext {
 	isAuthenticated: boolean;
@@ -82,72 +75,47 @@ interface AuthContext {
 }
 
 const authSetup = setup({
-	schemas: {
-		context: types<AuthContext>(),
-		input: types<Partial<AuthContext> | undefined>(),
-		events: {
-			"play.route": playRouteEventSchema,
-			"auth.login": types<{ username: string }>(),
-			"auth.logout": emptyEventSchema,
-		},
-		meta: playMetaSchema,
+	types: {
+		context: {} as AuthContext,
+		events: {} as
+			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
+		input: {} as Partial<AuthContext> | undefined,
 	},
 });
 
-const authMachine = createRoutedMachine(authSetup)({
-	id: "auth",
-	initial: "home",
-	context: ({ input }) => ({
-		isAuthenticated: input?.isAuthenticated ?? false,
-		username: input?.username ?? null,
-		params: input?.params ?? {},
-		query: input?.query ?? {},
+const authMachine = authSetup.createMachine(
+	formatPlayRouteTransitions({
+		id: "auth",
+		initial: "home",
+		context: ({ input }) => ({
+			isAuthenticated: input?.isAuthenticated ?? false,
+			username: input?.username ?? null,
+			params: input?.params ?? {},
+			query: input?.query ?? {},
+		}),
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+			login: { id: "login", meta: { route: "/login" } },
+			profile: { id: "profile", meta: { route: "/profile/:username" } },
+		},
 	}),
-	states: {
-		home: { id: "home", meta: { route: "/" } },
-		about: { id: "about", meta: { route: "/about" } },
-		login: { id: "login", meta: { route: "/login" } },
-		profile: { id: "profile", meta: { route: "/profile/:username" } },
-	},
-});
+);
 ```
 
-Under the hood, `formatPlayRouteTransitions` wires the routed states to XState v6's **native routing**: each routed state receives a static `route: {}` config (making it targetable via the built-in `xstate.route` event and visible to graph tooling), and one root-level `play.route` forwarder handles the public API by navigating those targets **directly, in one atomic transition**:
+`formatPlayRouteTransitions` generates root-level handlers equivalent to:
 
 ```typescript
-// Equivalent of what formatPlayRouteTransitions produces:
-states: {
-  home:    { id: "home",    meta: { route: "/" },                  route: {} },
-  about:   { id: "about",   meta: { route: "/about" },             route: {} },
-  login:   { id: "login",   meta: { route: "/login" },             route: {} },
-  profile: { id: "profile", meta: { route: "/profile/:username" }, route: {} },
-},
 on: {
   "play.route": [
-    // routeTargets maps each routed #id to its state path, collected during
-    // the crawl (or to null when the state declares its OWN route config).
-    ({ event }, enq) => {
-      const target = routeTargets.get(event.to);
-      if (target === undefined) return undefined; // fall through to your fallbacks
-      if (target === null) {
-        // user-declared route config: its resolver decides (and owns any patch)
-        enq.raise({ ...event, type: "xstate.route" });
-        return {};
-      }
-      // one atomic transition: navigation + params/query patch together
-      return {
-        target,
-        reenter: true,
-        context: { params: event.params ?? {}, query: event.query ?? {} },
-      };
-    },
-    // ...your own play.route fallbacks (e.g. a 404 route) run for unknown targets
+    { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: true, actions: assign({ params, query }) },
+    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: true, actions: assign({ params, query }) },
+    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: true, actions: assign({ params, query }) },
+    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: true, actions: assign({ params, query }) },
   ],
 }
 ```
 
-For injected routes the forwarder navigates directly — navigation and the `params`/`query` patch are one atomic transition, so exit actions see the old params and no `always` transition can observe a half-navigated state. The injected `route: {}` configs keep statically-targeted `xstate.route` edges in the graph for tooling. States that declare their **own** `route` config are re-raised as `xstate.route` instead, so the user's resolver decides (including blocking — in which case context stays untouched). Unknown targets return `undefined`, falling through to any `play.route` fallbacks you define yourself.
-
 ### `play.route` Events — Navigation
 
 To navigate, send a `play.route` event with `to: "#stateId"`:
@@ -176,63 +144,61 @@ actor.send({
 
 **`to` always uses `"#stateId"` format** — the state's `id` field prefixed with `#`. Do not pass URL paths here.
 
-### `always` Transitions — Protected Routes
+### `always` Guards — Protected Routes
 
-Use XState `always` transitions to protect states. An `always` transition is a function evaluated on state entry: return `{ target }` to redirect _before_ the state is fully entered, or `undefined` to stay:
+Use XState `always` transitions to protect states. If the guard fires, the machine redirects _before_ the state is fully entered:
 
 ```typescript
 dashboard: {
   id: "dashboard",
   meta: { route: "/dashboard" },
-  always: ({ context }) => {
+  always: {
     // If not authenticated, redirect to login immediately
-    if (context.isAuthenticated) return;
-    return { target: "login" };
+    guard: ({ context }) => !context.isAuthenticated,
+    target: "login",
   },
 },
 profile: {
   id: "profile",
   meta: { route: "/profile/:username" },
-  always: ({ context }) => {
-    if (context.isAuthenticated) return;
-    return { target: "login" };
+  always: {
+    guard: ({ context }) => !context.isAuthenticated,
+    target: "login",
   },
 },
 ```
 
-**Why `always` and not guards on events?** Guard checks inside event transitions answer "can I TAKE this transition?". `always` transitions check "can I BE in this state?" — the correct invariant for authentication. The actor enforces the check even on direct URL access (browser back/forward or deep link), because the router sends a `play.route` event which triggers the `always` transition.
+**Why `always` and not event guards?** Guards on events check "can I TAKE this transition?". `always` guards check "can I BE in this state?" — the correct invariant for authentication. The actor enforces the guard even on direct URL access (browser back/forward or deep link), because the router sends a `play.route` event which triggers the `always` guard.
 
 ### Root-Level Event Handlers
 
 Domain events placed at the root `on:` level are handled from any state:
 
 ```typescript
-const authMachine = createRoutedMachine(authSetup)({
-	// ...
-	on: {
-		"auth.login": ({ context, event }) => {
-			if (context.isAuthenticated) return;
-			return {
+const authMachine = authSetup.createMachine(
+	formatPlayRouteTransitions({
+		// ...
+		on: {
+			"auth.login": {
 				target: ".dashboard",
-				context: {
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: authSetup.assign({
 					isAuthenticated: true,
-					username: event.username,
-				},
-			};
-		},
-		"auth.logout": ({ context }) => {
-			if (!context.isAuthenticated) return;
-			return {
+					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
+				}),
+			},
+			"auth.logout": {
 				target: ".home",
-				context: {
+				guard: ({ context }) => context.isAuthenticated,
+				actions: authSetup.assign({
 					isAuthenticated: false,
 					username: null,
-				},
-			};
+				}),
+			},
 		},
-	},
-	states: {/* ... */},
-});
+		states: {/* ... */},
+	}),
+);
 ```
 
 ## Complete Actor Usage
@@ -319,7 +285,7 @@ function App() {
 | **Actor Authority (INV-01)**        | Guards on the machine validate every navigation. The router cannot change state directly.      |
 | **Passive Infrastructure (INV-04)** | The router observes `actor.currentRoute` — it never decides where to go.                       |
 | **State-Driven Reset (INV-03)**     | Browser back/forward sends `play.route` events to the actor. History is driven by actor state. |
-| **Strict Separation (INV-02)**      | The machine has zero framework imports. Guards, transitions, and context are pure TypeScript.  |
+| **Strict Separation (INV-02)**      | The machine has zero framework imports. Guards, actions, and context are pure TypeScript.      |
 
 ## Next Steps