@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/examples/traffic-light.md

@@ -1,99 +1,146 @@
 # 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](/docs/api/xmachines/play/readme)** - 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,15 @@
 # XMachines Guides
 
-Entry points for current XMachines Play architecture and package documentation.
+User-facing guides for the XMachines Play architecture.
 
 ## Start Here
 
-- [Root README](../../README.md) - Monorepo overview and architecture invariants
-- [Examples Index](../examples/README.md) - Runnable and conceptual usage patterns
+- **[Getting Started](getting-started.md)** — Installation, first actor, routing, router adapters, and view renderers
 
-## Router Adapter Guides
+## Concepts
 
-Use these READMEs for the current RouterBridge-first integrations:
+Background reading that explains the _why_ behind XMachines design decisions.
 
-- [@xmachines/play-router](../../packages/play-router/README.md) - Route extraction, route maps, and `RouterBridgeBase`
-- [@xmachines/play-tanstack-react-router](../../packages/play-tanstack-react-router/README.md) - TanStack React adapter
-- [@xmachines/play-react-router](../../packages/play-react-router/README.md) - `react-router` v7 data-router adapter
-- [@xmachines/play-tanstack-solid-router](../../packages/play-tanstack-solid-router/README.md) - TanStack Solid adapter
-- [@xmachines/play-solid-router](../../packages/play-solid-router/README.md) - SolidJS Router adapter
-- [@xmachines/play-vue-router](../../packages/play-vue-router/README.md) - Vue Router adapter
-
-## Core Runtime Guides
-
-- [@xmachines/play-xstate](../../packages/play-xstate/README.md) - `definePlayer`, routing transitions, and actor lifecycle
-- [@xmachines/play-react](../../packages/play-react/README.md) - React rendering from actor-driven view state
-- [@xmachines/play-catalog](../../packages/play-catalog/README.md) - Catalog and schema contracts
-
-## API Reference
-
-- [/docs/api](/docs/api) - Generated API docs for all public packages
+- **[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

package/guides/actor-model.md

@@ -0,0 +1,180 @@
+# Understanding the Actor Model and the Actor/Infrastructure Split
+
+XMachines is built around one central design principle: **business logic must never depend on infrastructure**. This page explains what that means, why the split is enforced the way it is, and what concrete responsibilities belong to each side of the boundary.
+
+After reading this, you will understand why a state machine in XMachines has no import from React, Vue, or any router — and why that constraint is a feature, not a limitation.
+
+---
+
+## Two roles, one boundary
+
+Every XMachines application has exactly two roles:
+
+**The Actor** — owns state, guards, routing intent, and view structure. It has zero knowledge of browsers, routing libraries, or UI frameworks.
+
+**Infrastructure** — the runtime environment. It reflects actor state into the world and forwards world events to the actor. It has no opinion on whether a transition is valid.
+
+The boundary between them is enforced by the signal protocol: the actor exposes `Signal.State` and `Signal.Computed` properties; infrastructure observes them. The actor never calls into infrastructure; infrastructure never mutates actor state directly.
+
+```
+Actor (business logic)
+  │
+  │  emits signals: state, currentRoute, currentView
+  ▼
+Infrastructure (runtime adapters)
+  ├── Router Bridge — reflects currentRoute into the URL bar
+  ├── Renderer — renders currentView into framework components
+  └── ... (any other observer)
+
+Infrastructure → actor: only via actor.send({ type: "..." })
+```
+
+---
+
+## What the actor owns
+
+An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md). It implements three reactive properties:
+
+| Property             | Type                              | What it is                                                                                                                     |
+| -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `actor.state`        | `Signal.State<Snapshot>`          | Updated on every XState transition. The full machine snapshot.                                                                 |
+| `actor.currentRoute` | `Signal.Computed<string \| null>` | Derived from the active state node's `meta.route`.                                                                             |
+| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) that drives renderers. |
+
+All three are set by the actor, never by infrastructure. Infrastructure reads them via signals.
+
+The actor also owns:
+
+- **Guards** — it decides whether a transition is valid. If a router sends a `play.route` event for a path the actor's guards reject, the actor does not transition. It then emits its current valid route back through `currentRoute`, and the router bridge overwrites the URL to match.
+- **Error states** — structured errors ([`PlayError`](../api/@xmachines/play/classes/PlayError.md)) are part of the actor's state graph, not thrown into the environment.
+- **Initial route** — `actor.initialRoute` is the route the actor starts in. Router adapters use this for initial navigation, not the browser's current URL.
+
+---
+
+## What infrastructure owns
+
+Infrastructure owns everything that touches the environment:
+
+- **Pushing URLs**: reading `actor.currentRoute` and calling `history.pushState()` or a router's navigation API.
+- **Forwarding navigation events**: listening to `popstate`, `routeChange`, or equivalent, then calling `actor.send({ type: "play.route", to: path })`.
+- **Rendering**: reading `actor.currentView` and projecting the spec through framework components.
+- **Lifecycle**: connecting on mount, disconnecting on unmount, explicitly cleaning up signal subscriptions.
+
+Infrastructure does **not**:
+
+- Decide whether a `play.route` event is valid (that is the actor's job via guards).
+- Override the URL to something the actor did not emit.
+- Read `actor.getSnapshot()` to make routing decisions (use `actor.currentRoute` instead).
+
+---
+
+## The reset invariant
+
+One of the most important behaviors in XMachines falls out directly from this split.
+
+If a user navigates directly to `/admin` in the browser but the actor's guards reject that route (because the user is not authenticated), the actor:
+
+1. Receives `{ type: "play.route", to: "/admin" }` from the router bridge.
+2. Evaluates its guards. The guard fails.
+3. Does not transition. It remains in its current state (e.g., `/login`).
+4. `actor.currentRoute` still signals `"/login"`.
+5. The router bridge, watching `currentRoute`, calls its `navigateRouter("/login")` method.
+6. The URL bar resets to `/login`.
+
+The environment is always made to match actor reality. The router bridge does not need any special "auth guard" logic — the state machine already has it.
+
+This is why the invariant is called **State-Driven Reset** in the Play RFC.
+
+---
+
+## [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) — the enforced contract
+
+[`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 DevTools attach to actors normally
+- The full XState ecosystem (testing utilities, visualization) is compatible
+
+[`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) adds one abstract requirement: a reactive `state` property of type `Signal.State<unknown>`. This is the single point where XState's pull-based snapshot API is bridged to TC39's push-based signal system.
+
+The two optional capability interfaces — [`Routable`](../api/@xmachines/play-actor/interfaces/Routable.md) and [`Viewable`](../api/@xmachines/play-actor/interfaces/Viewable.md) — are deliberately separate:
+
+- Not every actor needs routing (e.g., a background data-sync actor).
+- Not every actor drives a view (e.g., a sub-actor composed inside a parent).
+
+An actor implements only the capabilities it actually uses:
+
+```typescript
+// Minimal actor: just reactive state
+class MinimalActor extends AbstractActor<SomeLogic> {
+	state = new Signal.State(this.getSnapshot());
+}
+
+// Full actor: state + routing + view
+class PlayerActor extends AbstractActor<SomeMachine> implements Routable, Viewable {
+	state = new Signal.State(this.getSnapshot());
+	currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+	currentView = new Signal.State<PlaySpec | null>(null);
+}
+```
+
+In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
+
+---
+
+## [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) — the factory builder
+
+[`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md) is the primary entry point for creating actors:
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import { myMachine } from "./machine.js";
+
+const createPlayer = definePlayer({ machine: myMachine });
+
+// Each call creates an independent actor instance
+const actor = createPlayer();
+actor.start();
+```
+
+[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
+
+The factory accepts optional `input` (initial context overrides) and a `restore` snapshot (for resumable sessions):
+
+```typescript
+const actor = createPlayer({ userId: "abc" }); // with input
+const actor = createPlayer(undefined, { snapshot }); // restored from snapshot
+```
+
+---
+
+## Why the actor has no framework imports
+
+The machine definition — the `setup().createMachine(...)` call — is pure TypeScript with zero runtime dependencies on browsers, routers, or UI frameworks. This is not a convention; it is enforced by the dependency graph.
+
+[`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) depends on `xstate` and [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md). It does not depend on React, Vue, any router library, or any browser API. Your machine file inherits those same boundaries.
+
+This has concrete practical benefits:
+
+- **Portable**: the same machine runs in a browser, a Node.js server, a web worker, and a Vitest test suite — with zero modification.
+- **Testable in isolation**: you test the machine with `actor.send()` and `actor.state.get()`. No DOM, no router, no React to mock.
+- **Replaceable infrastructure**: swap the React renderer for a Vue renderer, or swap TanStack Router for React Router, without touching the machine file.
+
+---
+
+## The lock statement
+
+The Play RFC captures the actor/infrastructure split in a single statement:
+
+> _Logic is sovereign. Infrastructure reflects, never decides. Capabilities compose, never prescribe. Logic owns structure and flow. Adapters project, never decide. This is Universal Player._
+
+---
+
+## See also
+
+- [Understanding TC39 Signals](signals.md) — how the actor communicates with infrastructure
+- [Understanding State Machines](state-machines.md) — how the machine definition drives actor behavior
+- [Getting Started](getting-started.md) — hands-on walkthrough creating and starting an actor
+- [@xmachines/play-actor](../api/@xmachines/play-actor/README.md) — API reference for [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md)
+- [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md)
+- [Play RFC](../rfc/play.md) — complete architectural specification