@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/examples/routing-patterns.md

@@ -1,260 +1,299 @@
-# Routing Patterns - Play Architecture
+# Routing Patterns
 
-Learn how to implement parameter-aware navigation using routing patterns with `meta.route` URL patterns and `play.route` events.
+How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTransitions`, and `always` guards 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: '/dashboard',  // Marks state as routable
-      view: { component: 'Dashboard' }
-    }
-  }
+      route: "/profile/:username", // required parameter
+    },
+  },
+  settings: {
+    id: "settings",
+    meta: {
+      route: "/settings/:section?", // optional parameter
+    },
+  },
 }
 ```
 
-### Play.route Events with Parameters
-
-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" },
-});
-```
-
-### Parameter Patterns in meta.route
+**Rules:**
 
-Define URL patterns with `:param` syntax for required parameters and `:param?` for optional ones:
+- 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.
 
-```typescript
-meta: {
-  route: '/profile/:userId',        // Required parameter
-  route: '/settings/:section?',     // Optional parameter
-}
-```
-
-## Complete Example
+### `formatPlayRouteTransitions` — Auto-Generating Route Handlers
 
-See [routing-example.ts](./src/routing-example.ts) for a complete runnable example demonstrating all patterns.
-
-### Machine Configuration
+Instead of hand-writing `play.route` event handlers for every routable state, wrap your machine config with `formatPlayRouteTransitions`:
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+interface AuthContext {
+	isAuthenticated: boolean;
+	username: string | null;
+	params: Record<string, string>; // required for formatPlayRouteTransitions
+	query: Record<string, string>; // required for formatPlayRouteTransitions
+}
 
-const authMachine = setup({
+const authSetup = setup({
 	types: {
-		context: {} as {
-			isAuthenticated: boolean;
-			userId: string;
-			routeParams: Record<string, string>;
-		},
+		context: {} as AuthContext,
 		events: {} as
-			| { type: "play.route"; to: string; params?: Record<string, string> }
-			| { type: "auth.login"; userId: string },
-	},
-}).createMachine({
-	initial: "login",
-	context: {
-		isAuthenticated: false,
-		userId: "",
-		routeParams: {},
-	},
-	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 };
-						}
-					},
-				},
-			},
-		},
+			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
+		input: {} as Partial<AuthContext> | undefined,
 	},
 });
 
-const createPlayer = definePlayer({ machine: authMachine });
+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" } },
+		},
+	}),
+);
 ```
 
-### Using the Actor
+`formatPlayRouteTransitions` generates root-level handlers equivalent to:
 
 ```typescript
-// Create and start actor
-const actor = createPlayer();
-actor.start();
+on: {
+  "play.route": [
+    { 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 }) },
+  ],
+}
+```
 
-// 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` Guards — 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. If the guard fires, the machine redirects _before_ the state is fully entered:
 
-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: {
+    // If not authenticated, redirect to login immediately
+    guard: ({ context }) => !context.isAuthenticated,
+    target: "login",
+  },
+},
+profile: {
+  id: "profile",
+  meta: { route: "/profile/:username" },
+  always: {
+    guard: ({ context }) => !context.isAuthenticated,
+    target: "login",
+  },
+},
+```
 
-## Guard Placement Architecture
+**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.
 
-**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 = authSetup.createMachine(
+	formatPlayRouteTransitions({
+		// ...
+		on: {
+			"auth.login": {
+				target: ".dashboard",
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: authSetup.assign({
+					isAuthenticated: true,
+					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
+				}),
+			},
+			"auth.logout": {
+				target: ".home",
+				guard: ({ context }) => context.isAuthenticated,
+				actions: authSetup.assign({
+					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, actions, 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