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

package/guides/getting-started.md

@@ -1,215 +1,295 @@
+<!-- generated-by: gsd-doc-writer -->
+
 # Getting Started
 
-Welcome to XMachines! This guide will help you understand what XMachines is and get you up and running with your first state machine.
+Welcome to XMachines! This guide gets you from zero to a running actor using the current XState v5 + XMachines API.
 
 ## What is XMachines?
 
-XMachines is a TypeScript implementation of the Universal Player Architecture—a state machine library that strictly separates business logic from infrastructure. It enables logic-driven applications where state machines control routing, views, and navigation through standardized TC39 Signals.
-
-At its core, XMachines is built on the actor model, following the principle that **business logic must be the single source of truth** for navigation, state, and UI structure. Infrastructure reflects actor state—it never decides.
-
-Unlike traditional frameworks where your logic adapts to the framework, XMachines inverts this relationship. Your state machines own the application behavior, and the infrastructure (routers, view renderers, React components) passively observes and reflects the current state through signals. This results in complete runtime agnosticism—your logic has zero framework dependencies.
-
-## Why XMachines?
-
-**Type Safety with TypeScript**
-
-- Full type inference from state machine catalog through to components
-- Catch navigation errors and state bugs at compile time
-- Zod validation for UI schemas and state structures
-
-**Predictable State Management**
-
-- State machines make application behavior explicit and testable
-- Actor model ensures clear message passing patterns
-- Guard enforcement prevents invalid state transitions
-
-**Platform Flexibility**
+XMachines is a TypeScript implementation of the Universal Player Architecture — a state machine system that strictly separates business logic from infrastructure. State machines (actors) control routing, views, and navigation through TC39 Signals. Infrastructure (routers, renderers, React components) passively observes and reflects actor state.
 
-- Runtime-agnostic core packages work in browser, Node, or Deno
-- Choose only the packages you need for your platform
-- Framework integrations (React, TanStack Router) are optional adapters
+Your state machines have **zero framework dependencies**. Routers and renderers are optional adapters.
 
-**Modular Architecture**
+## Installation
 
-- 8 focused packages that work together seamlessly
-- `@xmachines/play` foundation works with any infrastructure
-- Mix and match adapters based on your stack
-
-## Quick Start
-
-### Installation
-
-First, install XMachines packages. See the complete [Installation →](installation.md) guide for all package managers and environments.
+Install the core packages (see [Installation →](installation.md) for the full package guide):
 
 ```bash
-npm install @xmachines/play @xmachines/play-xstate
+npm install @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
 ```
 
-### Import and Create Your First Machine
+## Step 1: Define a Machine
+
+Use `setup({ types })` from XState v5 to declare types, then call `setup.createMachine()`:
 
 ```typescript
-import { createMachine } from "@xmachines/play-xstate";
+import { setup } from "xstate";
 
-// Define a simple traffic light machine
-const trafficLightMachine = createMachine({
-	id: "trafficLight",
-	initial: "red",
+const toggleSetup = setup({
+	types: {
+		context: {} as { count: number },
+		events: {} as { type: "toggle" },
+		input: {} as { count?: number } | undefined,
+	},
+});
+
+const toggleMachine = toggleSetup.createMachine({
+	id: "toggle",
+	initial: "off",
+	context: ({ input }) => ({
+		count: input?.count ?? 0,
+	}),
 	states: {
-		red: {
-			on: { TIMER: "green" },
-		},
-		green: {
-			on: { TIMER: "yellow" },
+		off: {
+			on: {
+				toggle: {
+					target: "on",
+					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
+			},
 		},
-		yellow: {
-			on: { TIMER: "red" },
+		on: {
+			on: {
+				toggle: {
+					target: "off",
+					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
+			},
 		},
 	},
 });
 ```
 
-### Create an Actor and Transition States
+**Key rules:**
+
+- Always use `setup({ types })` before `createMachine` — not the bare `createMachine` from xstate.
+- Use `setup.assign(...)` (not the bare `assign` from xstate) for context mutations.
+- Event types use lowercase dot-separated names: `"toggle"`, `"auth.login"`, `"play.route"`.
+
+## Step 2: Define a Player
+
+`definePlayer` wraps the machine in a factory. Each call to the factory creates an independent `PlayerActor` instance:
 
 ```typescript
-import { createActor } from "@xmachines/play-actor";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const createPlayer = definePlayer({ machine: toggleMachine });
+```
 
-// Instantiate the machine as an actor
-const actor = createActor(trafficLightMachine);
+## Step 3: Create and Start an Actor
 
-// Start the actor
+```typescript
+const actor = createPlayer();
 actor.start();
 
-// Check initial state
-console.log(actor.getSnapshot().value); // "red"
+// Read initial state
+console.log(actor.getSnapshot().value); // "off"
+console.log(actor.getSnapshot().context); // { count: 0 }
 
-// Send events to transition states
-actor.send({ type: "TIMER" });
-console.log(actor.getSnapshot().value); // "green"
+// Send events
+actor.send({ type: "toggle" });
+console.log(actor.getSnapshot().value); // "on"
+console.log(actor.getSnapshot().context.count); // 1
 
-actor.send({ type: "TIMER" });
-console.log(actor.getSnapshot().value); // "yellow"
+// Cleanup
+actor.stop();
 ```
 
-### Observe State Changes with Signals
+## Step 4: Read State via TC39 Signals
 
-```typescript
-import { signal, computed } from "@xmachines/play-signals";
+`actor.state` is a `Signal.State<Snapshot>`. Use it when wiring infrastructure that needs to react to state changes:
 
-// Create a signal to track actor state
-const currentState = signal(actor.getSnapshot().value);
+```typescript
+import { watchSignal } from "@xmachines/play-signals";
 
-// Subscribe to actor changes
-actor.subscribe((snapshot) => {
-	currentState.value = snapshot.value;
+// Watch the state signal — callback fires on every transition
+const unwatch = watchSignal(actor.state, () => {
+	console.log("State changed to:", actor.state.get().value);
 });
 
-// Create computed values
-const canProceed = computed(() => currentState.value === "green");
+actor.send({ type: "toggle" }); // logs "State changed to: on"
 
-console.log(canProceed.value); // true when light is green
+// Stop watching
+unwatch();
 ```
 
-## Your First Machine: Toggle Example
+## Step 5: Add Routing (Optional)
 
-Here's a complete working example that demonstrates the core concepts:
+Add `meta.route` to states and wrap the config with `formatPlayRouteTransitions`. The machine's context must include `params` and `query` fields:
 
 ```typescript
-import { createMachine } from "@xmachines/play-xstate";
-import { createActor } from "@xmachines/play-actor";
-import { signal } from "@xmachines/play-signals";
-
-// Define the machine configuration
-const toggleMachine = createMachine(
-	{
-		id: "toggle",
-		initial: "inactive",
-		context: {
-			count: 0,
-		},
-		states: {
-			inactive: {
-				on: {
-					TOGGLE: {
-						target: "active",
-						actions: "incrementCount",
-					},
-				},
-			},
-			active: {
-				on: {
-					TOGGLE: {
-						target: "inactive",
-						actions: "incrementCount",
-					},
-				},
-			},
+import { setup } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const appSetup = setup({
+	types: {
+		context: {} as {
+			isAuthenticated: boolean;
+			params: Record<string, string>;
+			query: Record<string, string>;
 		},
+		events: {} as PlayRouteEvent | { type: "auth.login"; username: string },
+		input: {} as undefined,
 	},
-	{
-		actions: {
-			incrementCount: ({ context }) => ({
-				count: context.count + 1,
-			}),
+});
+
+const appMachine = appSetup.createMachine(
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		context: { isAuthenticated: false, params: {}, query: {} },
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			login: { id: "login", meta: { route: "/login" } },
 		},
-	},
+	}),
 );
 
-// Create and start the actor
-const toggleActor = createActor(toggleMachine);
-toggleActor.start();
+const createPlayer = definePlayer({ machine: appMachine });
+const actor = createPlayer();
+actor.start();
+
+console.log(actor.currentRoute.get()); // "/"
+
+actor.send({ type: "play.route", to: "#login" });
+console.log(actor.currentRoute.get()); // "/login"
+
+actor.stop();
+```
+
+## Step 6: Add a View Registry (Optional)
+
+Connect a renderer to map `meta.view` specs to real components. The vanilla DOM renderer uses `connectRenderer` + `defineRegistry`:
 
-// Bind to a signal for reactive updates
-const state = signal(toggleActor.getSnapshot());
+```typescript
+import { connectRenderer, defineRegistry } from "@xmachines/play-dom";
+import { authCatalog } from "@xmachines/play-actor-shared";
+import { Home, Login } from "./components/index.js";
 
-toggleActor.subscribe((snapshot) => {
-	state.value = snapshot;
+const { registry } = defineRegistry(authCatalog, {
+	components: { Home, Login },
 });
 
-// Use the machine
-toggleActor.send({ type: "TOGGLE" });
-console.log(state.value.value); // "active"
-console.log(state.value.context.count); // 1
+const disconnectRenderer = connectRenderer({
+	actor,
+	registry,
+	container: document.getElementById("app")!,
+});
 
-toggleActor.send({ type: "TOGGLE" });
-console.log(state.value.value); // "inactive"
-console.log(state.value.context.count); // 2
+// cleanup
+window.addEventListener("beforeunload", () => {
+	disconnectRenderer();
+	actor.stop();
+});
 ```
 
-### Understanding the Parts
+For React, use `PlayRenderer` from `@xmachines/play-react`:
 
-**States**: Discrete modes your application can be in (`inactive`, `active`)
+```tsx
+import { PlayRenderer, defineRegistry } from "@xmachines/play-react";
+import { authCatalog } from "@xmachines/play-actor-shared";
+import { Home, Login } from "./components/index.js";
 
-**Events**: Messages that trigger transitions (`TOGGLE`)
-
-**Transitions**: Rules that define which events move between which states (`on: { TOGGLE: 'active' }`)
+const { registry } = defineRegistry(authCatalog, {
+	components: { Home, Login },
+	actions: {
+		login: async () => {},
+		logout: async () => {},
+	},
+});
 
-**Context**: Extended state data that persists across transitions (`count: 0`)
+function App() {
+	return (
+		<PlayRenderer
+			actor={actor}
+			registry={registry}
+			actions={{
+				login: "auth.login",
+				logout: "auth.logout",
+			}}
+		/>
+	);
+}
+```
 
-**Actions**: Side effects or context updates executed during transitions (`incrementCount`)
+## Complete Toggle Example
 
-**Actor**: Runtime instance of a machine that processes events and emits state changes
+```typescript
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+import { watchSignal } from "@xmachines/play-signals";
+
+const toggleSetup = setup({
+	types: {
+		context: {} as { count: number },
+		events: {} as { type: "toggle" },
+		input: {} as undefined,
+	},
+});
 
-**Signals**: Reactive primitives (TC39 Signals) that enable infrastructure to observe state changes without coupling
+const toggleMachine = toggleSetup.createMachine({
+	id: "toggle",
+	initial: "off",
+	context: { count: 0 },
+	states: {
+		off: {
+			on: {
+				toggle: {
+					target: "on",
+					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
+			},
+		},
+		on: {
+			on: {
+				toggle: {
+					target: "off",
+					actions: toggleSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
+			},
+		},
+	},
+});
 
-## Next Steps
+const createPlayer = definePlayer({ machine: toggleMachine });
+const actor = createPlayer();
 
-Now that you understand the basics, explore these resources:
+const unwatch = watchSignal(actor.state, () => {
+	const snap = actor.state.get();
+	console.log(`State: ${String(snap.value)}, Count: ${snap.context.count}`);
+});
 
-**Core Documentation**
+actor.start();
+// logs: State: off, Count: 0
 
-- [API Reference](../api/README.md) - Detailed API documentation
+actor.send({ type: "toggle" });
+// logs: State: on, Count: 1
 
-**Platform Guides**
+actor.send({ type: "toggle" });
+// logs: State: off, Count: 2
 
-- [React Integration](../api/@xmachines/play-react/README.md) - Use XMachines with React
-- [Router Integration](../api/@xmachines/play-tanstack-react-router/README.md) - Logic-driven routing with TanStack Router
+unwatch();
+actor.stop();
+```
 
-**Examples**
+## Glossary
 
-- [Examples Directory](../examples/README.md) - More code examples and usage patterns
-- Working dashboard demo (coming soon)
+| Term                         | Description                                                                                  |
+| ---------------------------- | -------------------------------------------------------------------------------------------- |
+| `setup({ types })`           | XState v5 entry point — declares TypeScript types for context, events, and input             |
+| `definePlayer({ machine })`  | Creates a factory that produces `PlayerActor` instances from the machine                     |
+| `actor.start()`              | Activates the machine — always call before sending events                                    |
+| `actor.send({ type })`       | Sends an event to the machine                                                                |
+| `actor.getSnapshot()`        | Synchronous snapshot of the current state and context                                        |
+| `actor.state`                | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                        |
+| `actor.currentRoute`         | `Signal.Computed<string \| null>` — resolved URL from the active state's `meta.route`        |
+| `actor.currentView`          | `Signal.State<ViewMetadata \| null>` — current view spec from the active state's `meta.view` |
+| `formatPlayRouteTransitions` | Utility that generates `play.route` handlers from `id` + `meta.route` state pairs            |
 
----
+## Next Steps
 
-**Ready to install?** → [Installation Guide](installation.md)
+- **[Installation Guide](installation.md)** — Framework-specific packages, TypeScript config
+- **[Examples](../examples/README.md)** — Routing patterns, form validation, multi-router demos
+- **[API Reference](../api/README.md)** — Generated API docs for all packages
+- **[Play RFC](../rfc/play.md)** — Complete architectural specification