@xmachines/docs 1.0.0-beta.9 → 2.0.0-alpha.1

package/guides/getting-started.md

@@ -1,223 +1,716 @@
+<!-- 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.
 
-## What is XMachines?
+#### 3. Build all packages
 
-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.
+```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
+```
 
-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.
+All tests should pass on a freshly cloned and built repository. If they do, your environment is correctly configured.
 
-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.
+### Dev Container (Optional)
 
-## Why XMachines?
+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.
 
-**Type Safety with TypeScript**
+**VS Code:** Open the repository and choose **Reopen in Container** when prompted.
 
-- 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
+**CLI:**
 
-**Predictable State Management**
+```bash
+pnpm run devcontainer:up
+```
 
-- State machines make application behavior explicit and testable
-- Actor model ensures clear message passing patterns
-- Guard enforcement prevents invalid state transitions
+To customize the container, copy the sample env file:
 
-**Platform Flexibility**
+```bash
+cp .devcontainer/.env.sample .devcontainer/.env
+```
 
-- 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
+Available variables:
 
-**Modular Architecture**
+| 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 |
 
-- 8 focused packages that work together seamlessly
-- `@xmachines/play` foundation works with any infrastructure
-- Mix and match adapters based on your stack
+### 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
+
+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`.
+
+#### Lint errors about import extensions
+
+All TypeScript imports must end with `.js`, even for `.ts` source files:
+
+```typescript
+// ✅ Correct
+import { PlayError } from "./errors.js";
+
+// ❌ Wrong — will fail at runtime
+import { PlayError } from "./errors";
+```
 
-## Quick Start
+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.
+
+### Next Steps (Contributors)
+
+Once your setup is verified, continue with:
+
+- **[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)
+
+---
+
+## Application Developer Quickstart
+
+This section covers installing XMachines packages into your own application and wiring together a state machine, router adapter, and view renderer.
+
+### Prerequisites
+
+- **Node.js** `>= 22.0.0`
+- **pnpm** via corepack (`corepack enable`)
+- **TypeScript** `>= 5.7` (strict mode recommended)
+- **XState** `v6` (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 v6 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
-npm install @xmachines/play @xmachines/play-xstate
+# 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
 ```
 
-### Import and Create Your First Machine
+#### 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, types } from "xstate";
+import { definePlayer, emptyEventSchema } from "@xmachines/play-xstate";
+
+// 1. Declare schemas with setup() — the XState v6 typed entry point
+const appSetup = setup({
+	schemas: {
+		context: types<{ count: number }>(),
+		events: {
+			toggle: emptyEventSchema,
+		},
+	},
+});
 
-// 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: ({ context }) => ({
+					target: "on",
+					context: { count: context.count + 1 },
+				}),
+			},
 		},
-		yellow: {
-			on: { TIMER: "red" },
+		on: {
+			on: {
+				toggle: ({ context }) => ({
+					target: "off",
+					context: { count: 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({ schemas })` before `createMachine` — never bare `createMachine` from xstate.
+- Update context by returning a shallow `context` patch from the transition function — there is no `assign` action.
+- 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`
+
+`createRoutedMachine` wires routing up from `id` + `meta.route` state pairs (via [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md)): each routed state gets a native XState v6 `route: {}` config, and one root `play.route` forwarder navigates those targets in a single atomic transition, patching `params`/`query` into context:
 
 ```typescript
-import { createActor } from "@xmachines/play-actor";
+import { setup, types } from "xstate";
+import {
+	createRoutedMachine,
+	definePlayer,
+	emptyEventSchema,
+	playMetaSchema,
+	playRouteEventSchema,
+} from "@xmachines/play-xstate";
+
+const appSetup = setup({
+	schemas: {
+		// params and query are REQUIRED for routed machines
+		context: types<{
+			isAuthenticated: boolean;
+			params: Record<string, string>;
+			query: Record<string, string>;
+		}>(),
+		events: {
+			"play.route": playRouteEventSchema,
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": emptyEventSchema,
+		},
+		// meta.route on state nodes needs a declared meta schema
+		meta: playMetaSchema,
+	},
+});
 
-// Instantiate the machine as an actor
-const actor = createActor(trafficLightMachine);
+// createRoutedMachine(appSetup) has the same signature as appSetup.createMachine
+const appMachine = createRoutedMachine(appSetup)({
+	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 transition: redirect to /login if not authenticated
+			always: ({ context }) => {
+				if (context.isAuthenticated) return;
+				return { target: "login" };
+			},
+		},
+		profile: { id: "profile", meta: { route: "/profile/:username" } },
+	},
+	on: {
+		"auth.login": ({ context }) => {
+			if (context.isAuthenticated) return;
+			return {
+				target: ".dashboard",
+				context: { isAuthenticated: true },
+			};
+		},
+		"auth.logout": ({ context }) => {
+			if (!context.isAuthenticated) return;
+			return {
+				target: ".home",
+				context: { 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 transition redirects to login
+actor.send({ type: "play.route", to: "#dashboard" });
+console.log(actor.getSnapshot().value); // "login" (redirect 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` transitions (function form, with an early-return guard) 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
+
+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.
 
-// Create computed values
-const canProceed = computed(() => currentState.value === "green");
+```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";
 
-console.log(canProceed.value); // true when light is green
+// 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" }),
+	},
+});
 
-toggleActor.send({ type: "TOGGLE" });
-console.log(state.value.value); // "inactive"
-console.log(state.value.context.count); // 2
+const mount = createPlayUI(registryResult);
+const disconnect = mount(actor, document.getElementById("app")!);
+
+window.addEventListener("beforeunload", () => disconnect());
 ```
 
-### Understanding the Parts
+---
 
-**States**: Discrete modes your application can be in (`inactive`, `active`)
+### Common Setup Issues (Application Developers)
 
-**Events**: Messages that trigger transitions (`TOGGLE`)
+#### Missing `params` / `query` in context
 
-**Transitions**: Rules that define which events move between which states (`on: { TOGGLE: 'active' }`)
+**Error:** `MissingQueryContextError` at runtime when using [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md).
 
-**Context**: Extended state data that persists across transitions (`count: 0`)
+**Fix:** Add `params` and `query` fields to your machine context schema and initial value:
 
-**Actions**: Side effects or context updates executed during transitions (`incrementCount`)
+```typescript
+context: types<{
+  params: Record<string, string>;
+  query: Record<string, string>;
+  // ...other fields
+}>()
+// and initialize them:
+context: { params: {}, query: {}, /* ...other fields */ }
+```
 
-**Actor**: Runtime instance of a machine that processes events and emits state changes
+#### Missing `id` on routable states
 
-**Signals**: Reactive primitives (TC39 Signals) that enable infrastructure to observe state changes without coupling
+**Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
 
-## Next Steps
+**Fix:** Every state with `meta.route` must declare an explicit `id`:
+
+```typescript
+// ❌ Missing id
+home: { meta: { route: "/" } }
+
+// ✅ Correct
+home: { id: "home", meta: { route: "/" } }
+```
+
+#### Actor sends events before `start()`
+
+**Symptom:** Events are silently dropped; state never changes.
+
+**Fix:** Always call `actor.start()` before `actor.send()`:
+
+```typescript
+const actor = createPlayer();
+actor.start(); // required before any send()
+actor.send({ type: "toggle" });
+```
 
-Now that you understand the basics, explore these resources:
+#### `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({ schemas })`                                                                                  | XState v6 entry point — declares schemas (via `types<T>()`) for context, events, input, and state meta          |
+| [`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`                                    |
+| `createRoutedMachine(setup)`                                                                          | Setup-typed `createMachine` that wires `id` + `meta.route` state pairs to native routing                        |
+| [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) | Underlying transform — native `route: {}` configs plus one root `play.route` forwarder                          |
+| `play.route` event                                                                                    | Navigation event — `to: "#stateId"`, optional `params`, `query`                                                 |
+| `always` transition                                                                                   | 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)