@xmachines/docs 1.0.0-beta.9 → 1.0.0

package/guides/getting-started.md

@@ -1,223 +1,705 @@
+<!-- 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.
+This guide serves two audiences:
+
+1. **Contributors** setting up the XMachines JS monorepo for development.
+2. **Application developers** installing XMachines packages into their own project.
+
+Jump to the section that applies to you:
+
+- [Contributor Setup](#contributor-setup) — Clone, install, build, and test the monorepo
+- [Application Developer Quickstart](#application-developer-quickstart) — Install packages, define a machine, connect router and renderer
+
+---
+
+## Contributor Setup
+
+### Prerequisites
+
+You need the following installed before cloning the repository:
+
+| Requirement | Version            | Notes                                                                                                                 |
+| ----------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Node.js     | `>= 22.0.0`        | Specified in all `package.json` `engines` fields                                                                      |
+| pnpm        | via corepack       | Enable with `corepack enable`; the version is pinned by the `packageManager` field. The project uses pnpm workspaces. |
+| Git         | any recent version | Conventional commit format is enforced by CI                                                                          |
+
+No global TypeScript install is needed — it is installed as a dev dependency via `pnpm install --frozen-lockfile`.
+
+> **Node.js version manager tip:** If you manage multiple Node versions with `nvm` or `fnm`, install and activate Node 22 before proceeding.
+
+### Installation Steps
+
+#### 1. Clone the repository
+
+```bash
+git clone git@gitlab.com:xmachin-es/xmachines-js.git
+cd xmachines-js
+```
+
+#### 2. Install dependencies
+
+Always use `pnpm install --frozen-lockfile` (not `pnpm install`) to respect the lockfile exactly:
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+```
+
+This installs the exact versions recorded in the lockfile for all workspace packages.
+
+#### 3. Build all packages
+
+```bash
+pnpm run build
+```
+
+The root `tsc --build` command uses TypeScript project references to compile all packages in correct dependency order. Build outputs go to each package's `dist/` directory (gitignored).
+
+### First Run
+
+Verify your setup is working end-to-end:
+
+```bash
+pnpm test
+```
+
+All tests should pass on a freshly cloned and built repository. If they do, your environment is correctly configured.
+
+### Dev Container (Optional)
+
+A fully configured dev container is provided at `.devcontainer/`. It uses Docker Compose with a Node 22 Bookworm base image and includes Docker-outside-of-Docker, Claude Code, and OpenCode pre-installed.
+
+**VS Code:** Open the repository and choose **Reopen in Container** when prompted.
+
+**CLI:**
+
+```bash
+pnpm run devcontainer:up
+```
+
+To customize the container, copy the sample env file:
+
+```bash
+cp .devcontainer/.env.sample .devcontainer/.env
+```
+
+Available variables:
+
+| Variable                      | Default | Description                                        |
+| ----------------------------- | ------- | -------------------------------------------------- |
+| `OPENCODE_EXPERIMENTAL_OXFMT` | `false` | Enables experimental oxfmt inside the opencode UI  |
+| `OPENCODE_PORT_MAPPING`       | `4096`  | Docker port mapping for the opencode web interface |
 
-## What is XMachines?
+### Common Setup Issues (Monorepo)
 
-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.
+#### Tests fail with `Cannot find module` errors
 
-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.
+The test suite relies on TypeScript path aliases that resolve to source files. If aliases are not resolving:
 
-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.
+1. Run `pnpm run build` first — some packages need their `dist/` present even in development.
+2. Confirm your package's `vitest.config.ts` uses `defineXmVitestConfig` from `@xmachines/shared/vitest`, which automatically configures the `@xmachines/*` path aliases.
 
-## Why XMachines?
+#### TypeScript errors about missing types after adding a dependency
 
-**Type Safety with TypeScript**
+Run `pnpm install --frozen-lockfile` again to ensure all types are installed. If you added a workspace-local dependency, also add the correct `references` entry in the package's `tsconfig.base.json`.
 
-- 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
+#### Lint errors about import extensions
 
-**Predictable State Management**
+All TypeScript imports must end with `.js`, even for `.ts` source files:
 
-- State machines make application behavior explicit and testable
-- Actor model ensures clear message passing patterns
-- Guard enforcement prevents invalid state transitions
+```typescript
+// ✅ Correct
+import { PlayError } from "./errors.js";
+
+// ❌ Wrong — will fail at runtime
+import { PlayError } from "./errors";
+```
+
+Your editor's auto-import may omit the extension — fix it manually or configure the editor to add `.js` automatically.
+
+#### Build is slow after `git clean`
+
+TypeScript incremental builds depend on `.tsbuildinfo` files. After a full clean, these are gone and the initial build will be slower. This is expected.
 
-**Platform Flexibility**
+### Next Steps (Contributors)
 
-- 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
+Once your setup is verified, continue with:
 
-**Modular Architecture**
+- **[Architecture](../contributing/architecture.md)** — System design, layers, invariants, and data flow
+- **[Contributing](../../../CONTRIBUTING.md)** — Coding standards, branch conventions, and PR process
+- **[Development](../contributing/development.md)** — Full development lifecycle: build commands, adding packages, commit conventions
+- **[Testing](../contributing/testing.md)** — Vitest setup, test conventions, coverage thresholds, browser tests
+- **[packages/docs/rfc/](../rfc/)** — RFC specifications (read the relevant RFC before implementing any feature)
 
-- 8 focused packages that work together seamlessly
-- `@xmachines/play` foundation works with any infrastructure
-- Mix and match adapters based on your stack
+---
+
+## Application Developer Quickstart
+
+This section covers installing XMachines packages into your own application and wiring together a state machine, router adapter, and view renderer.
 
-## Quick Start
+### Prerequisites
+
+- **Node.js** `>= 22.0.0`
+- **pnpm** via corepack (`corepack enable`)
+- **TypeScript** `>= 5.7` (strict mode recommended)
+- **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
+
+All packages are ES modules (`"type": "module"`). Use `.js` extensions in all TypeScript imports.
 
 ### Installation
 
-First, install XMachines packages. See the complete [Installation →](installation.md) guide for all package managers and environments.
+#### Step 1: Install the core packages
+
+Every XMachines application needs these three packages plus XState:
 
 ```bash
-npm install @xmachines/play @xmachines/play-xstate
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
 ```
 
-### Import and Create Your First Machine
+| Package                                                               | Role                                                                                                                                                                |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xstate`                                                              | XState v5 state machine engine (peer dependency)                                                                                                                    |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | [`definePlayer()`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), routing helpers |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | Abstract actor base class and interface types                                                                                                                       |
+| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md))                                 |
+
+#### Step 2: Install a router adapter (pick one)
+
+```bash
+# Provider pattern (framework-integrated routers)
+pnpm add @xmachines/play-tanstack-react-router   # TanStack Router (React)
+pnpm add @xmachines/play-tanstack-solid-router   # TanStack Router (SolidJS)
+pnpm add @xmachines/play-react-router            # React Router v7
+pnpm add @xmachines/play-vue-router              # Vue Router 4.x/5.x
+pnpm add @xmachines/play-solid-router            # SolidJS Router
+
+# connectRouter pattern (framework-agnostic)
+pnpm add @xmachines/play-dom-router              # Vanilla DOM (Browser History API)
+pnpm add @xmachines/play-sveltekit-router        # SvelteKit
+pnpm add @xmachines/play-svelte-spa-router       # Svelte SPA Router
+```
+
+#### Step 3: Install a view renderer (pick one)
+
+```bash
+pnpm add @xmachines/play-react    # React 18/19
+pnpm add @xmachines/play-vue      # Vue 3
+pnpm add @xmachines/play-solid    # SolidJS
+pnpm add @xmachines/play-svelte   # Svelte 5
+pnpm add @xmachines/play-dom      # Vanilla DOM
+```
+
+---
+
+### Core Actor (No Router, No Renderer)
+
+The minimum viable XMachines actor — no framework dependencies:
 
 ```typescript
-import { createMachine } from "@xmachines/play-xstate";
+import { setup } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+// 1. Declare types with setup() — the XState v5 typed entry point
+const appSetup = setup({
+	types: {
+		context: {} as { count: number },
+		events: {} as { type: "toggle" },
+		input: {} as undefined,
+	},
+});
 
-// Define a simple traffic light machine
-const trafficLightMachine = createMachine({
-	id: "trafficLight",
-	initial: "red",
+// 2. Create the machine using setup().createMachine()
+const machine = appSetup.createMachine({
+	id: "app",
+	initial: "off",
+	context: { count: 0 },
 	states: {
-		red: {
-			on: { TIMER: "green" },
-		},
-		green: {
-			on: { TIMER: "yellow" },
+		off: {
+			on: {
+				toggle: {
+					target: "on",
+					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
+			},
 		},
-		yellow: {
-			on: { TIMER: "red" },
+		on: {
+			on: {
+				toggle: {
+					target: "off",
+					actions: appSetup.assign({ count: ({ context }) => context.count + 1 }),
+				},
+			},
 		},
 	},
 });
+
+// 3. Create a player factory
+const createPlayer = definePlayer({ machine });
+
+// 4. Create and start an actor
+const actor = createPlayer();
+actor.start();
+
+// 5. Read state
+console.log(actor.getSnapshot().value); // "off"
+console.log(actor.state.get().value); // "off" (TC39 Signal)
+
+// 6. Send events — the machine's guards decide all transitions
+actor.send({ type: "toggle" });
+console.log(actor.getSnapshot().value); // "on"
+
+// 7. Cleanup
+actor.stop();
 ```
 
-### Create an Actor and Transition States
+**Key rules:**
+
+- Always use `setup({ types })` before `createMachine` — never bare `createMachine` from xstate.
+- Use `setup.assign(...)` for context mutations — not the bare `assign` from xstate.
+- Call `actor.start()` before sending events.
+- Call `actor.stop()` when done to clean up signal subscriptions.
+
+---
+
+### Adding Routing
+
+State machines control navigation through `meta.route` on states and `play.route` events. The router is passive infrastructure that observes `actor.currentRoute`.
+
+#### Define a routable machine with `formatPlayRouteTransitions`
+
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
 
 ```typescript
-import { createActor } from "@xmachines/play-actor";
+import { setup } from "xstate";
+import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import type { PlayRouteEvent } from "@xmachines/play-router";
+
+const appSetup = setup({
+	types: {
+		// params and query are REQUIRED for formatPlayRouteTransitions
+		context: {} as {
+			isAuthenticated: boolean;
+			params: Record<string, string>;
+			query: Record<string, string>;
+		},
+		events: {} as
+			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
+		input: {} as undefined,
+	},
+});
 
-// Instantiate the machine as an actor
-const actor = createActor(trafficLightMachine);
+const appMachine = appSetup.createMachine(
+	// formatPlayRouteTransitions auto-generates play.route handlers from id + meta.route pairs
+	formatPlayRouteTransitions({
+		id: "app",
+		initial: "home",
+		context: { isAuthenticated: false, params: {}, query: {} },
+		states: {
+			home: { id: "home", meta: { route: "/" } },
+			about: { id: "about", meta: { route: "/about" } },
+			login: { id: "login", meta: { route: "/login" } },
+			dashboard: {
+				id: "dashboard",
+				meta: { route: "/dashboard" },
+				// always guard: redirect to /login if not authenticated
+				always: {
+					guard: ({ context }) => !context.isAuthenticated,
+					target: "login",
+				},
+			},
+			profile: { id: "profile", meta: { route: "/profile/:username" } },
+		},
+		on: {
+			"auth.login": {
+				target: ".dashboard",
+				guard: ({ context }) => !context.isAuthenticated,
+				actions: appSetup.assign({
+					isAuthenticated: true,
+				}),
+			},
+			"auth.logout": {
+				target: ".home",
+				guard: ({ context }) => context.isAuthenticated,
+				actions: appSetup.assign({ isAuthenticated: false }),
+			},
+		},
+	}),
+);
 
-// Start the actor
+const createPlayer = definePlayer({ machine: appMachine });
+const actor = createPlayer();
 actor.start();
 
-// Check initial state
-console.log(actor.getSnapshot().value); // "red"
+// Read the current route via TC39 Signal
+console.log(actor.currentRoute.get()); // "/"
+
+// Navigate — actor guards validate the transition
+actor.send({ type: "play.route", to: "#about" });
+console.log(actor.currentRoute.get()); // "/about"
 
-// Send events to transition states
-actor.send({ type: "TIMER" });
-console.log(actor.getSnapshot().value); // "green"
+// Attempt a protected route — always guard redirects to login
+actor.send({ type: "play.route", to: "#dashboard" });
+console.log(actor.getSnapshot().value); // "login" (guard fired)
 
-actor.send({ type: "TIMER" });
-console.log(actor.getSnapshot().value); // "yellow"
+// Navigate with params
+actor.send({ type: "auth.login", username: "alice" });
+actor.send({ type: "play.route", to: "#profile", params: { username: "alice" } });
+console.log(actor.currentRoute.get()); // "/profile/alice"
+
+actor.stop();
 ```
 
-### Observe State Changes with Signals
+**Routing rules:**
 
-```typescript
-import { signal, computed } from "@xmachines/play-signals";
+- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
+- Send `play.route` events with `to: "#stateId"` — always use the `id` field prefixed with `#`, never raw URL paths.
+- The machine context **must** include `params: Record<string, string>` and `query: Record<string, string>`.
+- Use `always` guards to protect states from direct URL access — these fire even on browser back/forward.
+
+---
 
-// Create a signal to track actor state
-const currentState = signal(actor.getSnapshot().value);
+### Connecting a Router Adapter
 
-// Subscribe to actor changes
-actor.subscribe((snapshot) => {
-	currentState.value = snapshot.value;
-});
+Router adapters synchronize `actor.currentRoute` with the browser URL bidirectionally. There are two integration patterns:
+
+#### Pattern 1: Provider pattern (React, Vue, SolidJS)
+
+Used with framework-integrated routers like TanStack Router. All three props (`actor`, `router`, `routeMap`) **must be stable references** — construct them outside JSX or memoize them.
+
+```tsx
+// React + TanStack Router example
+import { useMemo, useEffect } from "react";
+import { createRouter, createRootRoute } from "@tanstack/react-router";
+import {
+	PlayRouterProvider,
+	extractMachineRoutes,
+	createRouteMapFromTree,
+} from "@xmachines/play-tanstack-react-router";
+
+// Build OUTSIDE of JSX — must be stable references
+const routeTree = extractMachineRoutes(appMachine);
+const routeMap = createRouteMapFromTree(routeTree);
+const router = createRouter({ routeTree: createRootRoute() });
 
-// Create computed values
-const canProceed = computed(() => currentState.value === "green");
+// Actor also created outside the component (or memoized inside)
+const actor = createPlayer();
+actor.start();
 
-console.log(canProceed.value); // true when light is green
+export function App() {
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor, currentRouter) => (
+				// Your shell/layout component here
+				<Shell actor={currentActor} />
+			)}
+		/>
+	);
+}
 ```
 
-## Your First Machine: Toggle Example
+#### Pattern 2: `connectRouter` pattern (Vanilla DOM, SvelteKit, Svelte)
 
-Here's a complete working example that demonstrates the core concepts:
+Used with framework-agnostic or server-rendered routers. `connectRouter` handles bidirectional sync: `actor.currentRoute` signal → browser URL, and browser URL changes → `play.route` events sent to the actor.
 
 ```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,
+import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
+import { extractMachineRoutes, createRouteMapFromTree } from "@xmachines/play-router";
+
+const routeTree = extractMachineRoutes(appMachine);
+const routeMap = createRouteMapFromTree(routeTree);
+const history = createBrowserHistory({ window });
+const router = createRouter({ routeTree, history });
+
+const actor = createPlayer();
+actor.start();
+
+const disconnectRouter = connectRouter({ actor, router, routeMap });
+
+// Cleanup on unload
+window.addEventListener("beforeunload", () => {
+	disconnectRouter();
+	router.destroy();
+	actor.stop();
+});
+```
+
+---
+
+### Connecting a View Renderer
+
+View renderers map `meta.view` specs from your machine states to real UI components. Each framework package exports a `defineRegistry` function that binds components and actions to a catalog.
+
+#### React
+
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { schema } from "@xmachines/play-react";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({}) },
+	},
+	actions: {
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
+
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Home: ({ props }) => <section>{props.title}</section>,
+		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
+	},
+	actions: {
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
+
+function App() {
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
+}
+```
+
+#### Vue 3
+
+```html
+<!-- App.vue -->
+<template>
+	<PlayUIProvider :actor="actor" :registry-result="registryResult">
+		<PlayRenderer />
+	</PlayUIProvider>
+</template>
+
+<script setup lang="ts">
+	import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-vue";
+	import { defineCatalog } from "@xmachines/json-render-core";
+	import { schema } from "@xmachines/play-vue";
+	import { z } from "zod";
+
+	const catalog = defineCatalog(schema, {
+		components: {
+			Home: { props: z.object({ title: z.string() }) },
+			Login: { props: z.object({}) },
 		},
-		states: {
-			inactive: {
-				on: {
-					TOGGLE: {
-						target: "active",
-						actions: "incrementCount",
-					},
-				},
-			},
-			active: {
-				on: {
-					TOGGLE: {
-						target: "inactive",
-						actions: "incrementCount",
-					},
-				},
-			},
+		actions: {
+			login: { params: z.object({ username: z.string() }) },
+			logout: {},
+		},
+	});
+
+	const registryResult = defineRegistry(catalog, {
+		components: {
+			Home: { template: `<section>{{ props.title }}</section>` },
+			Login: { template: `<button @click="on('submit').emit()">Log in</button>` },
 		},
-	},
-	{
 		actions: {
-			incrementCount: ({ context }) => ({
-				count: context.count + 1,
-			}),
+			login: async ({ username }) => actor.send({ type: "auth.login", username }),
+			logout: async () => actor.send({ type: "auth.logout" }),
 		},
+	});
+</script>
+```
+
+#### SolidJS
+
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { schema } from "@xmachines/play-solid";
+import { z } from "zod";
+
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({}) },
 	},
-);
+	actions: {
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
 
-// Create and start the actor
-const toggleActor = createActor(toggleMachine);
-toggleActor.start();
+const registryResult = defineRegistry(catalog, {
+	components: {
+		Home: ({ props }) => <section>{props.title}</section>,
+		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
+	},
+	actions: {
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
+});
 
-// Bind to a signal for reactive updates
-const state = signal(toggleActor.getSnapshot());
+function App() {
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
+}
+```
+
+#### Vanilla DOM
 
-toggleActor.subscribe((snapshot) => {
-	state.value = snapshot;
+```typescript
+import { createPlayUI, defineRegistry, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { z } from "zod";
+import type { ComponentFn } from "@xmachines/play-dom";
+
+const catalog = defineCatalog(schema, {
+	components: {
+		Home: { props: z.object({ title: z.string() }) },
+		Login: { props: z.object({}) },
+	},
+	actions: {
+		login: { params: z.object({ username: z.string() }) },
+		logout: {},
+	},
+});
+
+const Home: ComponentFn<typeof catalog, "Home"> = ({ props }) => {
+	const el = document.createElement("section");
+	el.textContent = props.title;
+	return el;
+};
+
+const Login: ComponentFn<typeof catalog, "Login"> = ({ on }) => {
+	const el = document.createElement("div");
+	const btn = document.createElement("button");
+	btn.textContent = "Log in";
+	btn.addEventListener("click", () => on("submit").emit());
+	el.append(btn);
+	return el;
+};
+
+const registryResult = defineRegistry(catalog, {
+	components: { Home, Login },
+	actions: {
+		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		logout: async () => actor.send({ type: "auth.logout" }),
+	},
 });
 
-// Use the machine
-toggleActor.send({ type: "TOGGLE" });
-console.log(state.value.value); // "active"
-console.log(state.value.context.count); // 1
+const mount = createPlayUI(registryResult);
+const disconnect = mount(actor, document.getElementById("app")!);
 
-toggleActor.send({ type: "TOGGLE" });
-console.log(state.value.value); // "inactive"
-console.log(state.value.context.count); // 2
+window.addEventListener("beforeunload", () => disconnect());
 ```
 
-### Understanding the Parts
+---
+
+### Common Setup Issues (Application Developers)
 
-**States**: Discrete modes your application can be in (`inactive`, `active`)
+#### Missing `params` / `query` in context
 
-**Events**: Messages that trigger transitions (`TOGGLE`)
+**Error:** `MissingQueryContextError` at runtime when using [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md).
 
-**Transitions**: Rules that define which events move between which states (`on: { TOGGLE: 'active' }`)
+**Fix:** Add `params` and `query` fields to your machine context type and initial value:
 
-**Context**: Extended state data that persists across transitions (`count: 0`)
+```typescript
+context: {} as {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  // ...other fields
+}
+// and initialize them:
+context: { params: {}, query: {}, /* ...other fields */ }
+```
 
-**Actions**: Side effects or context updates executed during transitions (`incrementCount`)
+#### Missing `id` on routable states
 
-**Actor**: Runtime instance of a machine that processes events and emits state changes
+**Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
 
-**Signals**: Reactive primitives (TC39 Signals) that enable infrastructure to observe state changes without coupling
+**Fix:** Every state with `meta.route` must declare an explicit `id`:
 
-## Next Steps
+```typescript
+// ❌ Missing id
+home: { meta: { route: "/" } }
 
-Now that you understand the basics, explore these resources:
+// ✅ Correct
+home: { id: "home", meta: { route: "/" } }
+```
+
+#### Actor sends events before `start()`
 
-**Core Documentation**
+**Symptom:** Events are silently dropped; state never changes.
 
-- [Core Concepts](/docs/api/guides/core-concepts) - Deep dive into architecture and patterns
-- [Package Overview](/docs/api/guides/package-overview) - Choose the right packages for your needs
-- [API Reference](/docs/api/xmachines/play/readme) - Detailed API documentation
+**Fix:** Always call `actor.start()` before `actor.send()`:
 
-**Platform Guides**
+```typescript
+const actor = createPlayer();
+actor.start(); // required before any send()
+actor.send({ type: "toggle" });
+```
 
-- [React Integration](/docs/api/xmachines/play-react/readme) - Use XMachines with React
-- [Router Integration](/docs/api/xmachines/play-tanstack-react-router/readme) - Logic-driven routing with TanStack Router
-- [UI Schemas](/docs/api/xmachines/play-ui/readme) - Define UI structure from state
+#### `routeMap` or `actor` recreated on every render (React/SolidJS)
 
-**Examples**
+**Symptom:** The router bridge disconnects and reconnects on every render.
 
-- [Examples Directory](/examples) - More code examples and usage patterns
-- Working dashboard demo (coming soon)
+**Fix:** Construct stable references outside JSX or memoize them:
 
-**Architecture**
+```typescript
+// ✅ Built outside the component
+const routeTree = extractMachineRoutes(appMachine);
+const routeMap = createRouteMapFromTree(routeTree);
 
-- [RFC Specification](/rfc) - Complete architectural specification
-- [Architecture Docs](/architecture) - System design and technical decisions
+// ✅ Or memoized inside the component (React)
+const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);
+```
+
+#### Wrong Node.js version
+
+**Error:** `SyntaxError: Cannot use import statement in a module` or TC39 Signals not available.
+
+**Fix:** Use Node.js `>= 22.0.0`. Check with:
+
+```bash
+node --version
+```
 
 ---
 
-**Ready to install?** → [Installation Guide](installation.md)
+## Key Concepts Reference
+
+| Term                                                                                                  | Description                                                                                                     |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `setup({ types })`                                                                                    | XState v5 entry point — declares TypeScript types for context, events, and input                                |
+| [`definePlayer({ machine })`](../api/@xmachines/play-xstate/functions/definePlayer.md)                | Creates a factory that produces [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md) instances |
+| `actor.start()`                                                                                       | Activates the machine — always call before sending events                                                       |
+| `actor.send({ type })`                                                                                | Sends an event; machine guards decide whether a transition occurs                                               |
+| `actor.getSnapshot()`                                                                                 | Synchronous read of current state and context                                                                   |
+| `actor.state`                                                                                         | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                           |
+| `actor.currentRoute`                                                                                  | `Signal.Computed<string \| null>` — resolved URL from active state's `meta.route`                               |
+| `actor.currentView`                                                                                   | `Signal.State<PlaySpec \| null>` — view spec from active state's `meta.view`                                    |
+| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) | Generates `play.route` handlers from `id` + `meta.route` state pairs                                            |
+| `play.route` event                                                                                    | Navigation event — `to: "#stateId"`, optional `params`, `query`                                                 |
+| `always` guard                                                                                        | Protects states — fires on entry before any event, even on direct URL access                                    |
+| [`extractMachineRoutes`](../api/@xmachines/play-router/functions/extractMachineRoutes.md)             | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                      |
+| [`createRouteMapFromTree`](../api/@xmachines/play-router/functions/createRouteMapFromTree.md)         | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                 |
+| [`connectRouter`](../api/@xmachines/play-dom-router/functions/connectRouter.md)                       | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                               |
+| [`PlayRouterProvider`](../api/@xmachines/play-tanstack-react-router/variables/PlayRouterProvider.md)  | React component that connects a `PlayerActor` to TanStack React Router                                          |
+
+---
+
+## Next Steps
+
+- **[Architecture](../contributing/architecture.md)** — System design, layers, invariants, and data flow
+- **[Play RFC](../rfc/play.md)** — Complete architectural specification
+- **[API Reference](../api/README.md)** — Auto-generated API docs for all packages
+- **[Examples](../examples/)** — Basic state machine, form validation, routing pattern demos
+- **[Contributing](../../../CONTRIBUTING.md)** — Coding standards, branch conventions, and PR process (contributors)