@xmachines/docs 1.0.0-beta.26 → 1.0.0-beta.28

package/examples/traffic-light.md

@@ -1,99 +1,148 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # Traffic Light State Machine
 
-Multi-state machine with automatic transitions demonstrating cyclic state flows.
+Multi-state machine with `meta.route` on every state, demonstrating cyclic transitions and `formatPlayRouteTransitions`.
 
 ## Use Case
 
-This example models a traffic light with a red → green → yellow → red cycle. It demonstrates how to handle multiple states with cyclic transitions, making it useful for:
+This example models a traffic light with a red → green → yellow → red cycle. Because traffic lights map naturally to URLs (each light colour is a distinct page in a web app), it is a good vehicle for showing how `meta.route` and `formatPlayRouteTransitions` work together.
+
+Applicable patterns:
 
 - Traffic light controllers
 - Multi-step workflows with repeating cycles
-- Game state loops (menu → playing → game over → menu)
-- Carousel or slideshow controls
+- Tab or wizard navigation where each step has a URL
+- Game state loops with distinct URL states
 
 ## Complete Code
 
 ```typescript
-import { createMachine } from "xstate";
-
-// Define states
-type TrafficState = "red" | "yellow" | "green";
-
-// Define events
-type TrafficEvent = { type: "TIMER" };
-
-// Create machine
-const trafficMachine = createMachine<TrafficState, TrafficEvent>({
-	id: "traffic",
-	initial: "red",
-	states: {
-		red: {
-			on: {
-				TIMER: "green",
-			},
-		},
-		green: {
-			on: {
-				TIMER: "yellow",
-			},
-		},
-		yellow: {
-			on: {
-				TIMER: "red",
-			},
+import { setup } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+
+// 1. Typed setup
+const trafficSetup = setup({
+	types: {
+		context: {} as {
+			params: Record<string, string>;
+			query: Record<string, string>;
 		},
+		events: {} as
+			| { type: "timer" }
+			| {
+					type: "play.route";
+					to: string;
+					params?: Record<string, string>;
+					query?: Record<string, string>;
+			  },
+		input: {} as undefined,
 	},
 });
 
-// Usage with timer
-let state = trafficMachine.initialState;
-console.log(state); // 'red'
+// 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: {},
+		},
+		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" },
+			},
+		},
+	}),
+);
 
-// Simulate automatic transitions
-setInterval(() => {
-	state = trafficMachine.transition(state, { type: "TIMER" });
-	console.log(`Light changed to: ${state}`);
-}, 3000); // Change every 3 seconds
-```
+// 3. Player factory
+const createPlayer = definePlayer({ machine: trafficMachine });
 
-## Code Explanation
+// 4. Create and start actor
+const actor = createPlayer();
+actor.start();
 
-1. **Multiple states** - Defines three distinct states (`'red'`, `'yellow'`, `'green'`) instead of just two, showing how state machines scale beyond binary toggles.
+// 5. Read current route via signal
+console.log(actor.currentRoute.get()); // "/red"
 
-2. **Cyclic transitions** - Each state transitions to the next state in the cycle when receiving a `TIMER` event, creating a continuous loop.
+// 6. Advance with domain events
+actor.send({ type: "timer" });
+console.log(actor.currentRoute.get()); // "/green"
 
-3. **Timer integration** - Uses `setInterval` to automatically trigger state transitions, demonstrating how external timing mechanisms integrate with state machines.
+actor.send({ type: "timer" });
+console.log(actor.currentRoute.get()); // "/yellow"
 
-4. **Deterministic behavior** - No matter how many cycles complete, the state is always predictable based on the number of `TIMER` events received.
+actor.send({ type: "timer" });
+console.log(actor.currentRoute.get()); // "/red"
 
-## Key Concepts
+// 7. Or navigate directly via play.route events (generated by formatPlayRouteTransitions)
+actor.send({ type: "play.route", to: "#green" });
+console.log(actor.currentRoute.get()); // "/green"
 
-- **Multi-state machines**: Not limited to two states - model complex workflows with many states
-- **Cyclic transitions**: States can form loops, returning to previous states in a predictable pattern
-- **External triggers**: State machines react to external events like timers, user actions, or network responses
-- **Deterministic**: Same sequence of events always produces the same sequence of states
+// 8. Cleanup
+actor.stop();
+```
 
-## Variations
+## How `formatPlayRouteTransitions` Works
 
-**Different timing per state:**
+`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
-const timings = { red: 5000, green: 4000, yellow: 2000 };
-let state = trafficMachine.initialState;
-
-function scheduleNext() {
-	setTimeout(() => {
-		state = trafficMachine.transition(state, { type: "TIMER" });
-		console.log(`Light: ${state}`);
-		scheduleNext();
-	}, timings[state]);
+// 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` assigns them on every `play.route` transition.
 
-scheduleNext();
+## `actor.currentRoute` Signal
+
+`actor.currentRoute` is a `Signal.Computed<string | null>` derived from the active state's `meta.route` template and `context.params`. Route signals let router bridges observe URL changes reactively without polling.
+
+```typescript
+import { watchSignal } from "@xmachines/play-signals";
+
+const unwatch = watchSignal(actor.currentRoute, () => {
+	console.log("URL changed to:", actor.currentRoute.get());
+});
+
+// later...
+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`.
+- **`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)** - Learn about guards and conditional transitions
-- **[Basic State Machine](basic-state-machine.md)** - Return to foundational concepts
-- **[API Documentation](../api/@xmachines/play/README.md)** - Explore advanced features like actions and context
+- **[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,29 +1,43 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # XMachines Guides
 
-Entry points for current XMachines Play architecture and package documentation.
+Entry points for the current XMachines Play architecture.
 
 ## Start Here
 
-- [Examples Index](../examples/README.md) - Runnable and conceptual usage patterns
+- **[Installation](installation.md)** — Core packages, framework-specific additions, TypeScript config, ESM setup
+- **[Getting Started](getting-started.md)** — `setup().createMachine()` → `definePlayer()` → `actor.start()` → TC39 Signals
+
+## Examples
+
+- **[Examples Index](../examples/README.md)** — Conceptual patterns and complete runnable demo applications
 
 ## Router Adapter Guides
 
-Use these READMEs for the current RouterBridge-first integrations:
+Framework-specific adapter documentation:
+
+- **[@xmachines/play-router](../api/@xmachines/play-router/README.md)** — Route extraction, route maps, and `RouterBridgeBase`
+- **[@xmachines/play-tanstack-react-router](../api/@xmachines/play-tanstack-react-router/README.md)** — TanStack React adapter (`PlayRouterProvider`, `createRouteMapFromTree`)
+- **[@xmachines/play-react-router](../api/@xmachines/play-react-router/README.md)** — React Router v7 data-router adapter
+- **[@xmachines/play-tanstack-solid-router](../api/@xmachines/play-tanstack-solid-router/README.md)** — TanStack Solid adapter
+- **[@xmachines/play-solid-router](../api/@xmachines/play-solid-router/README.md)** — SolidJS Router adapter
+- **[@xmachines/play-vue-router](../api/@xmachines/play-vue-router/README.md)** — Vue Router adapter
+- **[@xmachines/play-dom-router](../api/@xmachines/play-dom-router/README.md)** — Vanilla DOM: `connectRouter`, `createBrowserHistory`, `createRouter`
+- **[@xmachines/play-sveltekit-router](../api/@xmachines/play-sveltekit-router/README.md)** — SvelteKit adapter
+- **[@xmachines/play-svelte-spa-router](../api/@xmachines/play-svelte-spa-router/README.md)** — Svelte SPA Router (hash-based) adapter
 
-- [@xmachines/play-router](../api/@xmachines/play-router/README.md) - Route extraction, route maps, and `RouterBridgeBase`
-- [@xmachines/play-tanstack-react-router](../api/@xmachines/play-tanstack-react-router/README.md) - TanStack React adapter
-- [@xmachines/play-react-router](../api/@xmachines/play-react-router/README.md) - `react-router` v7 data-router adapter
-- [@xmachines/play-tanstack-solid-router](../api/@xmachines/play-tanstack-solid-router/README.md) - TanStack Solid adapter
-- [@xmachines/play-solid-router](../api/@xmachines/play-solid-router/README.md) - SolidJS Router adapter
-- [@xmachines/play-vue-router](../api/@xmachines/play-vue-router/README.md) - Vue Router adapter
+## Renderer Guides
 
-## Core Runtime Guides
+View layer documentation by framework:
 
-- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) - `definePlayer`, routing transitions, and actor lifecycle
-- [@xmachines/play-react](../api/@xmachines/play-react/README.md) - React rendering from actor-driven view state
-- [@xmachines/play-vue](../api/@xmachines/play-vue/README.md) - Vue rendering from actor-driven view state
-- [@xmachines/play-solid](../api/@xmachines/play-solid/README.md) - SolidJS rendering from actor-driven view state
+- **[@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md)** — `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor`
+- **[@xmachines/play-react](../api/@xmachines/play-react/README.md)** — React rendering from actor-driven view state (`PlayRenderer`, `defineRegistry`)
+- **[@xmachines/play-vue](../api/@xmachines/play-vue/README.md)** — Vue rendering from actor-driven view state
+- **[@xmachines/play-solid](../api/@xmachines/play-solid/README.md)** — SolidJS rendering from actor-driven view state
+- **[@xmachines/play-svelte](../api/@xmachines/play-svelte/README.md)** — Svelte 5 rendering from actor-driven view state
+- **[@xmachines/play-dom](../api/@xmachines/play-dom/README.md)** — Vanilla DOM rendering (`connectRenderer`, `defineRegistry`)
 
 ## API Reference
 
-- [API Reference](../api/README.md) - Generated API docs for all public packages
+- **[API Reference](../api/README.md)** — Generated TypeDoc API docs for all public packages