@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

package/examples/routing-patterns.md

@@ -1,260 +1,333 @@
-# Routing Patterns - Play Architecture
+<!-- generated-by: gsd-doc-writer -->
 
-Learn how to implement parameter-aware navigation using routing patterns with `meta.route` URL patterns and `play.route` events.
+# Routing Patterns
+
+How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTransitions`, and `always` transitions to implement actor-authoritative URL routing.
 
 ## Overview
 
-introduces enhanced routing capabilities that allow state machines to handle dynamic routes with parameters while maintaining Actor Authority (INV-01). The router observes actor state changes and syncs the browser URL, but the actor decides which routes are valid through guards.
+XMachines inverts the usual routing model. The **actor** owns navigation — its guards decide which states are valid. The **router** is passive infrastructure that observes `actor.currentRoute` and keeps the browser URL in sync. This is **Actor Authority (INV-01)**.
+
+Every routing interaction starts with a `play.route` event sent to the actor. If the machine's guards allow the transition, the state changes and `actor.currentRoute` updates. The router bridge sees the new signal value and pushes a history entry. The URL never changes unless the actor approves.
 
 ## Key Concepts
 
-### Route Marker
+### `meta.route` — Marking States as Routable
 
-States with `meta.route` property are routable - they can receive `play.route` events and be navigated to by URL. States without `meta.route` are internal machine states that don't correspond to URLs.
+Add a `meta.route` URL template to any state to make it routable:
 
 ```typescript
 states: {
+  home: {
+    id: "home",            // required: used as the play.route target ("#home")
+    meta: {
+      route: "/",          // absolute URL path
+    },
+  },
   dashboard: {
+    id: "dashboard",
+    meta: {
+      route: "/dashboard", // absolute URL path
+    },
+    states: {
+      overview: {
+        id: "dashboard-overview",
+        meta: {
+          route: "overview", // RELATIVE — resolves to /dashboard/overview
+        },
+      },
+    },
+  },
+  profile: {
+    id: "profile",
+    meta: {
+      route: "/profile/:username", // required parameter
+    },
+  },
+  settings: {
+    id: "settings",
     meta: {
-      route: '/dashboard',  // Marks state as routable
-      view: { component: 'Dashboard' }
-    }
-  }
+      route: "/settings/:section?", // optional parameter
+    },
+  },
 }
 ```
 
-### Play.route Events with Parameters
+**Rules:**
 
-Use `play.route` events to navigate with parameters. Unlike `xstate.route` (which doesn't support parameters), `play.route` allows passing data alongside navigation:
-
-```typescript
-// Navigate to profile with userId parameter
-actor.send({
-	type: "play.route",
-	to: "/profile/user123",
-	params: { userId: "user123" },
-});
-```
+- Absolute paths start with `/`.
+- Relative paths (no leading `/`) are resolved against the parent state's route.
+- Parameter segments use `:param` (required) and `:param?` (optional).
+- Every routable state **must** have an `id` — `formatPlayRouteTransitions` throws `MissingStateIdError` otherwise.
 
-### Parameter Patterns in meta.route
+### `formatPlayRouteTransitions` — Auto-Generating Route Handlers
 
-Define URL patterns with `:param` syntax for required parameters and `:param?` for optional ones:
+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:
 
 ```typescript
-meta: {
-  route: '/profile/:userId',        // Required parameter
-  route: '/settings/:section?',     // Optional parameter
+import { setup, types } from "xstate";
+import {
+	createRoutedMachine,
+	definePlayer,
+	emptyEventSchema,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
+
+interface AuthContext {
+	isAuthenticated: boolean;
+	username: string | null;
+	params: Record<string, string>; // required for formatPlayRouteTransitions
+	query: Record<string, string>; // required for formatPlayRouteTransitions
 }
-```
-
-## Complete Example
-
-See [routing-example.ts](./src/routing-example.ts) for a complete runnable example demonstrating all patterns.
-
-### Machine Configuration
 
-```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-
-const authMachine = setup({
-	types: {
-		context: {} as {
-			isAuthenticated: boolean;
-			userId: string;
-			routeParams: Record<string, string>;
+const authSetup = setup({
+	schemas: {
+		context: types<AuthContext>(),
+		input: types<Partial<AuthContext> | undefined>(),
+		events: {
+			"play.route": playRouteEventSchema,
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": emptyEventSchema,
 		},
-		events: {} as
-			| { type: "play.route"; to: string; params?: Record<string, string> }
-			| { type: "auth.login"; userId: string },
-	},
-}).createMachine({
-	initial: "login",
-	context: {
-		isAuthenticated: false,
-		userId: "",
-		routeParams: {},
+		meta: playMetaSchema,
 	},
-	states: {
-		login: {
-			id: "login",
-			meta: {
-				route: "/login",
-				view: { component: "LoginView" },
-			},
-			on: {
-				"auth.login": {
-					target: "profile",
-					actions: ({ context, event }) => {
-						context.isAuthenticated = true;
-						context.userId = event.userId;
-					},
-				},
-			},
-		},
+});
 
-		profile: {
-			id: "profile",
-			meta: {
-				route: "/profile/:userId",
-				view: {
-					component: "ProfileView",
-					userId: (ctx) => ctx.routeParams.userId || ctx.userId,
-				},
-			},
-			always: [
-				{
-					target: "login",
-					guard: ({ context }) => !context.isAuthenticated,
-					// Redirect to login if not authenticated
-				},
-			],
-			on: {
-				"play.route": {
-					actions: ({ context, event }) => {
-						if (event.params?.userId) {
-							context.routeParams = { userId: event.params.userId };
-						}
-					},
-				},
-			},
-		},
+const authMachine = createRoutedMachine(authSetup)({
+	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" } },
 	},
 });
-
-const createPlayer = definePlayer({ machine: authMachine });
 ```
 
-### Using the Actor
+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**:
 
 ```typescript
-// Create and start actor
-const actor = createPlayer();
-actor.start();
+// 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
+  ],
+}
+```
+
+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.
 
-// Login (transitions to profile)
-actor.send({ type: "auth.login", userId: "user123" });
+### `play.route` Events — Navigation
 
-// Navigate to different profile with parameters
+To navigate, send a `play.route` event with `to: "#stateId"`:
+
+```typescript
+// Navigate to home
+actor.send({ type: "play.route", to: "#home" });
+
+// Navigate to profile — params are stored in context and used to resolve the URL
 actor.send({
 	type: "play.route",
-	to: "/profile/user456",
-	params: { userId: "user456" },
+	to: "#profile",
+	params: { username: "alice" },
 });
 
-// Parameter extracted and available in view
-const view = actor.currentView.get();
-console.log(view.userId); // 'user456'
+// actor.currentRoute.get() → "/profile/alice"
+
+// Navigate with query string
+actor.send({
+	type: "play.route",
+	to: "#settings",
+	params: { section: "privacy" },
+	query: { tab: "advanced" },
+});
 ```
 
-## Pattern Matching for Dynamic Routes
+**`to` always uses `"#stateId"` format** — the state's `id` field prefixed with `#`. Do not pass URL paths here.
 
-Routes with parameters use pattern matching to resolve URL paths:
+### `always` Transitions — Protected Routes
 
-- `/profile/:userId` matches `/profile/user123`, `/profile/alice`, etc.
-- `/settings/:section?` matches `/settings` (no section) or `/settings/privacy`
+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:
 
-The router extracts parameters from the URL and passes them in `play.route` events, which the machine stores in context for view projection.
+```typescript
+dashboard: {
+  id: "dashboard",
+  meta: { route: "/dashboard" },
+  always: ({ context }) => {
+    // If not authenticated, redirect to login immediately
+    if (context.isAuthenticated) return;
+    return { target: "login" };
+  },
+},
+profile: {
+  id: "profile",
+  meta: { route: "/profile/:username" },
+  always: ({ context }) => {
+    if (context.isAuthenticated) return;
+    return { target: "login" };
+  },
+},
+```
 
-## Guard Placement Architecture
+**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.
 
-**Core Principle:** Guards check if you can BE in a state (state entry), not if you can TAKE an event (event handlers).
+### Root-Level Event Handlers
 
-### Pattern 1: Using formatPlayRouteTransitions (RECOMMENDED)
+Domain events placed at the root `on:` level are handled from any state:
 
 ```typescript
-import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
-
-const machineConfig = {
-	initial: "home",
-	context: { isAuthenticated: false },
-	states: {
-		home: { id: "home", meta: { route: "/" } },
-		profile: {
-			id: "profile",
-			meta: { route: "/profile/:userId" },
-			// Always-guard validates state entry
-			always: [
-				{
-					target: "login",
-					guard: ({ context }) => !context.isAuthenticated,
+const authMachine = createRoutedMachine(authSetup)({
+	// ...
+	on: {
+		"auth.login": ({ context, event }) => {
+			if (context.isAuthenticated) return;
+			return {
+				target: ".dashboard",
+				context: {
+					isAuthenticated: true,
+					username: event.username,
 				},
-			],
+			};
+		},
+		"auth.logout": ({ context }) => {
+			if (!context.isAuthenticated) return;
+			return {
+				target: ".home",
+				context: {
+					isAuthenticated: false,
+					username: null,
+				},
+			};
 		},
 	},
-};
-
-// Utility handles routing infrastructure
-const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+	states: {/* ... */},
+});
 ```
 
-**Why this works:**
+## Complete Actor Usage
+
+```typescript
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+// Initial state
+console.log(actor.currentRoute.get()); // "/"
 
-- `formatPlayRouteTransitions` adds routing infrastructure (event.to matching)
-- Always-guards handle business logic (authentication, authorization)
-- Clear separation: routing layer (infrastructure) vs validation layer (business logic)
+// Navigate to about
+actor.send({ type: "play.route", to: "#about" });
+console.log(actor.currentRoute.get()); // "/about"
 
-### Pattern 2: Manual Always-Guards (Advanced)
+// Attempt protected route (redirect fires because isAuthenticated=false)
+actor.send({ type: "play.route", to: "#dashboard" });
+console.log(actor.getSnapshot().value); // "login" — guard redirected
 
-For advanced users who need full control:
+// Login first
+actor.send({ type: "auth.login", username: "alice" });
+// auth.login root handler transitions to dashboard
+console.log(actor.getSnapshot().value); // "dashboard"
+console.log(actor.getSnapshot().context.username); // "alice"
 
-```typescript
-const machine = createMachine({
-	context: { intendedRoute: null, isAuthenticated: false },
-	on: {
-		"play.route": {
-			actions: assign({
-				intendedRoute: ({ event }) => event.to,
-			}),
-		},
-	},
-	always: [
-		{
-			target: "profile",
-			guard: ({ context }) => context.intendedRoute === "#profile" && context.isAuthenticated,
-			reenter: true,
-		},
-		{
-			target: "login",
-			guard: ({ context }) =>
-				context.intendedRoute === "#profile" && !context.isAuthenticated,
-		},
-	],
-});
+// Navigate to profile with params
+actor.send({ type: "play.route", to: "#profile", params: { username: "alice" } });
+console.log(actor.currentRoute.get()); // "/profile/alice"
+
+actor.stop();
 ```
 
-### Anti-Pattern: Guards on Events
+## Vanilla Router Setup
 
-**NEVER do this:**
+To sync the browser URL with `actor.currentRoute`, use `@xmachines/play-dom-router`:
 
 ```typescript
-// ❌ WRONG - Guard on event checking event property
-on: {
-  'play.route': [
-    {
-      guard: ({ event }) => event.to === "#dashboard",
-      target: "dashboard"
-    }
-  ]
-}
+import {
+	createBrowserHistory,
+	createRouter,
+	connectRouter,
+	createRouteMap,
+} from "@xmachines/play-dom-router";
+
+// createRouteMap extracts meta.route declarations from the machine
+const routeMap = createRouteMap(authMachine);
+
+const history = createBrowserHistory({ window });
+const router = createRouter({ routeTree: authMachine, history });
+
+// connectRouter handles all bidirectional sync:
+// - actor.currentRoute signal → browser URL (history.push)
+// - browser URL changes → play.route event sent to actor
+const disconnect = connectRouter({ actor, router, routeMap });
+
+// Cleanup on unload
+window.addEventListener("beforeunload", () => {
+	disconnect();
+	router.destroy();
+});
 ```
 
-**Why this is wrong:** The state doesn't care HOW it was entered (which event triggered it). Guards should validate state invariants: "Can I BE in this state given current context?" not "Can I TAKE this event?"
+## React Router Setup
+
+For React, use `@xmachines/play-react-router` or `@xmachines/play-tanstack-react-router`:
 
-**Correct approach:** Use `formatPlayRouteTransitions` for routing infrastructure, use always-guards for state validation.
+```tsx
+import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router";
+
+const routeTree = extractMachineRoutes(authMachine);
+const routeMap = createRouteMapFromTree(routeTree);
+
+function App() {
+	return <PlayRouterProvider actor={actor} router={router} routeMap={routeMap} />;
+}
+```
 
-### Actor Authority in Action
+## Architectural Invariants
 
-This demonstrates **Actor Authority (INV-01)** — the state machine controls navigation through guards, not the router. If a guard returns `false`, the transition is rejected and the URL doesn't change.
+| Invariant                           | Description                                                                                    |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| **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.  |
 
 ## Next Steps
 
-- **[Multi-Router Integration](./multi-router-integration.md)** - Learn about renderer prop pattern
-- **[Integration Example](./src/integration-example.ts)** - See complete authentication flow with all patterns
-- **[React + TanStack Router Demo](../../packages/play-tanstack-react-router/examples/demo-app/)** - Production example with all 5 architectural invariants
+- **[Multi-Router Integration](./multi-router-integration.md)** — All 8 router adapters and the two integration patterns
+- **[Examples Index](./README.md)** — Complete catalog of runnable demos
 
 ## Learn More
 
-- [XState Routes Documentation](https://stately.ai/docs/routes) - Official Stately routing patterns
-- [RFC Play v1](https://gitlab.com/xmachin-es/rfc/-/blob/main/src/play-v1.md) - Complete architectural specification
-- [play-router README](../../packages/play-router/README.md) - Route extraction and tree building
+- [Play RFC](../rfc/play.md) — Complete architectural specification
+- [play-router](../api/@xmachines/play-router/README.md) — Route extraction and tree building
+- [play-dom-router](../api/@xmachines/play-dom-router/README.md) — Vanilla DOM bindings