@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/guides/getting-started.md

@@ -1,223 +1,713 @@
 # 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:
 
-## What is XMachines?
+1. **Contributors** setting up the XMachines JS monorepo for development.
+2. **Application developers** installing XMachines packages into their own project.
 
-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.
+Jump to the section that applies to you:
 
-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.
+- [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
 
-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.
+---
+
+## 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 |
+
+### Common Setup Issues (Monorepo)
+
+#### Tests fail with `Cannot find module` errors
+
+The test suite relies on TypeScript path aliases that resolve to source files. If aliases are not resolving:
+
+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.
+
+#### TypeScript errors about missing types after adding a dependency
 
-## Why XMachines?
+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`.
 
-**Type Safety with TypeScript**
+#### Lint errors about import extensions
 
-- 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
+All TypeScript imports must end with `.js`, even for `.ts` source files:
 
-**Predictable State Management**
+```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.
 
-- State machines make application behavior explicit and testable
-- Actor model ensures clear message passing patterns
-- Guard enforcement prevents invalid state transitions
+### Next Steps (Contributors)
 
-**Platform Flexibility**
+Once your setup is verified, continue with:
 
-- 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
+- **[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)
 
-**Modular Architecture**
+---
+
+## Application Developer Quickstart
+
+This section covers installing XMachines packages into your own application and wiring together a state machine, router adapter, and view renderer.
 
-- 8 focused packages that work together seamlessly
-- `@xmachines/play` foundation works with any infrastructure
-- Mix and match adapters based on your stack
+### Prerequisites
 
-## Quick Start
+- **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
+pnpm add xstate @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals
+```
+
+| 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
-npm install @xmachines/play @xmachines/play-xstate
+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
 ```
 
-### Import and Create Your First Machine
+---
+
+### 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"
+
+// Attempt a protected route — always guard redirects to login
+actor.send({ type: "play.route", to: "#dashboard" });
+console.log(actor.getSnapshot().value); // "login" (guard fired)
 
-// Send events to transition states
-actor.send({ type: "TIMER" });
-console.log(actor.getSnapshot().value); // "green"
+// 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.send({ type: "TIMER" });
-console.log(actor.getSnapshot().value); // "yellow"
+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);
+---
 
-// Subscribe to actor changes
-actor.subscribe((snapshot) => {
-	currentState.value = snapshot.value;
-});
+### Connecting a Router Adapter
 
-// Create computed values
-const canProceed = computed(() => currentState.value === "green");
+Router adapters synchronize `actor.currentRoute` with the browser URL bidirectionally. There are two integration patterns:
 
-console.log(canProceed.value); // true when light is green
+#### 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() });
+
+// Actor also created outside the component (or memoized inside)
+const actor = createPlayer();
+actor.start();
+
+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" }),
+	},
+});
+
+function App() {
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
+}
+```
 
-// Bind to a signal for reactive updates
-const state = signal(toggleActor.getSnapshot());
+#### 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: {},
+	},
 });
 
-// Use the machine
-toggleActor.send({ type: "TOGGLE" });
-console.log(state.value.value); // "active"
-console.log(state.value.context.count); // 1
+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" }),
+	},
+});
+
+const mount = createPlayUI(registryResult);
+const disconnect = mount(actor, document.getElementById("app")!);
+
+window.addEventListener("beforeunload", () => disconnect());
+```
+
+---
+
+### Common Setup Issues (Application Developers)
+
+#### Query parameters missing from derived URLs
+
+**Symptom:** `currentRoute` renders the path but the `?query=...` string from a
+`play.route` event never appears. No error is raised — a context without a
+`query` field builds a query-less URL, exactly like `query: {}`.
 
-toggleActor.send({ type: "TOGGLE" });
-console.log(state.value.value); // "inactive"
-console.log(state.value.context.count); // 2
+**Fix:** With [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)
+nothing is needed — the generated transitions assign `event.query` to context
+on every navigation. A machine that handles `play.route` by hand must do that
+assignment itself:
+
+```typescript
+on: {
+  "play.route": {
+    actions: assign({
+      params: ({ event }) => event.params ?? {},
+      query: ({ event }) => event.query ?? {},
+    }),
+  },
+}
 ```
 
-### Understanding the Parts
+(Older releases threw `MissingQueryContextError` at construction for a
+routing-aware context without a `query` field; the error class remains
+exported for `instanceof` compatibility but is never thrown.)
 
-**States**: Discrete modes your application can be in (`inactive`, `active`)
+#### Missing `id` on routable states
 
-**Events**: Messages that trigger transitions (`TOGGLE`)
+**Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
 
-**Transitions**: Rules that define which events move between which states (`on: { TOGGLE: 'active' }`)
+**Fix:** Every state with `meta.route` must declare an explicit `id`:
 
-**Context**: Extended state data that persists across transitions (`count: 0`)
+```typescript
+// ❌ Missing id
+home: { meta: { route: "/" } }
 
-**Actions**: Side effects or context updates executed during transitions (`incrementCount`)
+// ✅ Correct
+home: { id: "home", meta: { route: "/" } }
+```
 
-**Actor**: Runtime instance of a machine that processes events and emits state changes
+#### Actor sends events before `start()`
 
-**Signals**: Reactive primitives (TC39 Signals) that enable infrastructure to observe state changes without coupling
+**Symptom:** Events are silently dropped; state never changes.
 
-## Next Steps
+**Fix:** Always call `actor.start()` before `actor.send()`:
 
-Now that you understand the basics, explore these resources:
+```typescript
+const actor = createPlayer();
+actor.start(); // required before any send()
+actor.send({ type: "toggle" });
+```
+
+#### `routeMap` or `actor` recreated on every render (React/SolidJS)
 
-**Core Documentation**
+**Symptom:** The router bridge disconnects and reconnects on every render.
 
-- [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:** Construct stable references outside JSX or memoize them:
 
-**Platform Guides**
+```typescript
+// ✅ Built outside the component
+const routeTree = extractMachineRoutes(appMachine);
+const routeMap = createRouteMapFromTree(routeTree);
 
-- [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
+// ✅ Or memoized inside the component (React)
+const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);
+```
 
-**Examples**
+#### Wrong Node.js version
 
-- [Examples Directory](/examples) - More code examples and usage patterns
-- Working dashboard demo (coming soon)
+**Error:** `SyntaxError: Cannot use import statement in a module` or TC39 Signals not available.
 
-**Architecture**
+**Fix:** Use Node.js `>= 22.0.0`. Check with:
 
-- [RFC Specification](/rfc) - Complete architectural specification
-- [Architecture Docs](/architecture) - System design and technical decisions
+```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)