@xmachines/docs 1.0.0-beta.50 → 1.0.0-beta.52

package/guides/getting-started.md

@@ -1,25 +1,164 @@
 <!-- generated-by: gsd-doc-writer -->
 
-# Getting Started with XMachines Play
+# Getting Started
 
-This guide walks you through installing XMachines packages, wiring a state machine with [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), connecting a view renderer, and plugging in a router adapter — from zero to a running actor-driven application.
+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
 
 ---
 
-## Prerequisites
+## 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             |
+| npm         | bundled with Node 22 | The project uses npm workspaces — no separate install needed |
+| 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 `npm ci`.
+
+> **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 `npm ci` (not `npm install`) to respect the lockfile exactly:
+
+```bash
+npm ci
+```
+
+This installs all workspace dependencies and automatically runs `patch-package` via the `postinstall` hook to apply the patches in `patches/`. The patch output is expected and required — do not skip it.
+
+#### 3. Build all packages
+
+```bash
+npm 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
+npm 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
+npm 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 `npm 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 `npm ci` 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`.
+
+#### `patch-package` errors during install
+
+The patches in `patches/` are version-specific. If you updated a `@json-render` package, regenerate the patch:
+
+```bash
+npx patch-package <package-name>
+```
+
+#### 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";
+```
+
+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:
+
+- **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** — System design, layers, invariants, and data flow
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** — Coding standards, branch conventions, and PR process
+- **[packages/docs/contributing/development.md](../packages/docs/contributing/development.md)** — Full development lifecycle: build commands, adding packages, commit conventions
+- **[packages/docs/contributing/testing.md](../packages/docs/contributing/testing.md)** — Vitest setup, test conventions, coverage thresholds, browser tests
+- **[packages/docs/rfc/](../packages/docs/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`
 - **npm** `>= 10.0.0`
 - **TypeScript** `>= 5.7` (strict mode recommended)
-- **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md))
+- **XState** `v5` (required peer dependency for [`@xmachines/play-xstate`](../packages/docs/api/@xmachines/play-xstate/README.md))
 
 All packages are ES modules (`"type": "module"`). Use `.js` extensions in all TypeScript imports.
 
----
-
-## Installation
+### Installation
 
-### Step 1: Install the core packages
+#### Step 1: Install the core packages
 
 Every XMachines application needs these three packages plus XState:
 
@@ -27,17 +166,17 @@ Every XMachines application needs these three packages plus XState:
 npm install 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))                                 |
+| Package                                                                             | Role                                                                                                                                                                                            |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `xstate`                                                                            | XState v5 state machine engine (peer dependency)                                                                                                                                                |
+| [`@xmachines/play-xstate`](../packages/docs/api/@xmachines/play-xstate/README.md)   | [`definePlayer()`](../packages/docs/api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../packages/docs/api/@xmachines/play-xstate/classes/PlayerActor.md), routing helpers |
+| [`@xmachines/play-actor`](../packages/docs/api/@xmachines/play-actor/README.md)     | Abstract actor base class and interface types                                                                                                                                                   |
+| [`@xmachines/play-signals`](../packages/docs/api/@xmachines/play-signals/README.md) | TC39 Signals polyfill (`Signal.State`, `Signal.Computed`, [`watchSignal`](../packages/docs/api/@xmachines/play-signals/functions/watchSignal.md))                                               |
 
-### Step 2: Install a router adapter (pick one)
+#### Step 2: Install a router adapter (pick one)
 
 ```bash
-# Framework-integrated routers (provider pattern)
+# Provider pattern (framework-integrated routers)
 npm install @xmachines/play-tanstack-react-router   # TanStack Router (React)
 npm install @xmachines/play-tanstack-solid-router   # TanStack Router (SolidJS)
 npm install @xmachines/play-react-router            # React Router v7
@@ -50,7 +189,7 @@ npm install @xmachines/play-sveltekit-router        # SvelteKit
 npm install @xmachines/play-svelte-spa-router       # Svelte SPA Router
 ```
 
-### Step 3: Install a view renderer (pick one)
+#### Step 3: Install a view renderer (pick one)
 
 ```bash
 npm install @xmachines/play-react    # React 18/19
@@ -62,7 +201,7 @@ npm install @xmachines/play-dom      # Vanilla DOM
 
 ---
 
-## First Run: Core Actor (No Router, No Renderer)
+### Core Actor (No Router, No Renderer)
 
 The minimum viable XMachines actor — no framework dependencies:
 
@@ -132,11 +271,13 @@ actor.stop();
 
 ---
 
-## Adding Routing
+### 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
+#### Define a routable machine with `formatPlayRouteTransitions`
+
+[`formatPlayRouteTransitions`](../packages/docs/api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) auto-generates `play.route` handlers from `id` + `meta.route` state pairs:
 
 ```typescript
 import { setup } from "xstate";
@@ -186,7 +327,6 @@ const appMachine = appSetup.createMachine(
 				guard: ({ context }) => !context.isAuthenticated,
 				actions: appSetup.assign({
 					isAuthenticated: true,
-					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
 				}),
 			},
 			"auth.logout": {
@@ -223,93 +363,95 @@ actor.stop();
 
 **Routing rules:**
 
-- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) throws `MissingStateIdError` if absent.
+- Every routable state **must** have an `id` — [`formatPlayRouteTransitions`](../packages/docs/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's context must include `params: Record<string, string>` and `query: Record<string, string>` for [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) to work.
+- 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.
 
 ---
 
-## Connecting a Router Adapter
+### 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)
+#### Pattern 1: Provider pattern (React, Vue, SolidJS)
 
-```typescript
+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,
-  createRouteMapFromTree,
+	PlayRouterProvider,
+	extractMachineRoutes,
+	createRouteMapFromTree,
 } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes } from "@xmachines/play-router";
 
-// Build these OUTSIDE of JSX — must be stable references
+// 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() {
-  const actor = useMemo(() => {
-    const a = createPlayer();
-    a.start();
-    return a;
-  }, []);
-
-  useEffect(() => () => { actor.stop(); }, [actor]);
-
-  return (
-    <PlayRouterProvider
-      actor={actor}
-      router={router}
-      routeMap={routeMap}
-      renderer={(currentActor) => (
-        // Your shell/layout component here
-        <Shell actor={currentActor} />
-      )}
-    />
-  );
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor, currentRouter) => (
+				// Your shell/layout component here
+				<Shell actor={currentActor} />
+			)}
+		/>
+	);
 }
 ```
 
-### Pattern 2: `connectRouter` pattern (Vanilla DOM, SvelteKit, Svelte)
+#### Pattern 2: `connectRouter` pattern (Vanilla DOM, SvelteKit, Svelte)
+
+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 { connectRouter, createRouteMap } from "@xmachines/play-dom-router";
+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 routeMap = createRouteMap(appMachine);
 const actor = createPlayer();
 actor.start();
 
-// connectRouter handles bidirectional sync:
-// - actor.currentRoute signal → browser URL
-// - browser URL changes → play.route event sent to actor
-const disconnectRouter = connectRouter({ actor, routeMap });
+const disconnectRouter = connectRouter({ actor, router, routeMap });
 
 // Cleanup on unload
 window.addEventListener("beforeunload", () => {
 	disconnectRouter();
+	router.destroy();
 	actor.stop();
 });
 ```
 
 ---
 
-## Connecting a View Renderer
+### Connecting a View Renderer
 
-View renderers map `meta.view` specs from your machine states to real UI components. Each framework has a [`defineRegistry`](../api/@xmachines/play-dom/functions/defineRegistry.md) function that binds components and actions to a catalog.
+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.
 
-### Vanilla DOM
+#### React
 
-```typescript
-import { createPlayUI, defineRegistry, schema } from "@xmachines/play-dom";
+```tsx
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { defineCatalog } from "@json-render/core";
+import { schema } from "@xmachines/play-react";
 import { z } from "zod";
-import type { ComponentFn } from "@xmachines/play-dom";
 
-// 1. Define a catalog (schema of components and actions)
 const catalog = defineCatalog(schema, {
 	components: {
 		Home: { props: z.object({ title: z.string() }) },
@@ -321,44 +463,11 @@ const catalog = defineCatalog(schema, {
 	},
 });
 
-// 2. Implement components
-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;
-};
-
-// 3. Build registry and mount
 const registryResult = defineRegistry(catalog, {
-	components: { Home, Login },
-	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
-		logout: async () => actor.send({ type: "auth.logout" }),
+	components: {
+		Home: ({ props }) => <section>{props.title}</section>,
+		Login: ({ on }) => <button onClick={() => on("submit").emit()}>Log in</button>,
 	},
-});
-
-const mount = createPlayUI(registryResult);
-const disconnect = mount(actor, document.getElementById("app")!);
-
-// Cleanup
-window.addEventListener("beforeunload", () => disconnect());
-```
-
-### React
-
-```tsx
-import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
-
-const registryResult = defineRegistry(catalog, {
-	components: { Home, Login },
 	actions: {
 		login: async ({ username }) => actor.send({ type: "auth.login", username }),
 		logout: async () => actor.send({ type: "auth.logout" }),
@@ -374,7 +483,7 @@ function App() {
 }
 ```
 
-### Vue 3
+#### Vue 3
 
 ```html
 <!-- App.vue -->
@@ -386,9 +495,26 @@ function App() {
 
 <script setup lang="ts">
 	import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-vue";
+	import { defineCatalog } from "@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({}) },
+		},
+		actions: {
+			login: { params: z.object({ username: z.string() }) },
+			logout: {},
+		},
+	});
 
 	const registryResult = defineRegistry(catalog, {
-		components: { Home, Login },
+		components: {
+			Home: { template: `<section>{{ props.title }}</section>` },
+			Login: { template: `<button @click="on('submit').emit()">Log in</button>` },
+		},
 		actions: {
 			login: async ({ username }) => actor.send({ type: "auth.login", username }),
 			logout: async () => actor.send({ type: "auth.logout" }),
@@ -397,13 +523,30 @@ function App() {
 </script>
 ```
 
-### SolidJS
+#### SolidJS
 
 ```tsx
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-solid";
+import { defineCatalog } from "@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: {},
+	},
+});
 
 const registryResult = defineRegistry(catalog, {
-	components: { Home, Login },
+	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" }),
@@ -419,15 +562,63 @@ function App() {
 }
 ```
 
+#### Vanilla DOM
+
+```typescript
+import { createPlayUI, defineRegistry, schema } from "@xmachines/play-dom";
+import { defineCatalog } from "@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" }),
+	},
+});
+
+const mount = createPlayUI(registryResult);
+const disconnect = mount(actor, document.getElementById("app")!);
+
+window.addEventListener("beforeunload", () => disconnect());
+```
+
 ---
 
-## Common Setup Issues
+### Common Setup Issues (Application Developers)
 
-### Missing `params` / `query` in context
+#### Missing `params` / `query` in context
 
-**Error:** `MissingQueryContextError` at runtime when using [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md).
+**Error:** `MissingQueryContextError` at runtime when using [`formatPlayRouteTransitions`](../packages/docs/api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md).
 
-**Fix:** Add `params` and `query` fields to your machine context:
+**Fix:** Add `params` and `query` fields to your machine context type and initial value:
 
 ```typescript
 context: {} as {
@@ -439,7 +630,7 @@ context: {} as {
 context: { params: {}, query: {}, /* ...other fields */ }
 ```
 
-### Missing `id` on routable states
+#### Missing `id` on routable states
 
 **Error:** `MissingStateIdError: State "home" has meta.route "/" but no id`.
 
@@ -453,7 +644,7 @@ home: { meta: { route: "/" } }
 home: { id: "home", meta: { route: "/" } }
 ```
 
-### Actor sends events before `start()`
+#### Actor sends events before `start()`
 
 **Symptom:** Events are silently dropped; state never changes.
 
@@ -465,7 +656,7 @@ actor.start(); // required before any send()
 actor.send({ type: "toggle" });
 ```
 
-### `routeMap` or `actor` recreated on every render (React/Solid)
+#### `routeMap` or `actor` recreated on every render (React/SolidJS)
 
 **Symptom:** The router bridge disconnects and reconnects on every render.
 
@@ -476,11 +667,11 @@ actor.send({ type: "toggle" });
 const routeTree = extractMachineRoutes(appMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 
-// ✅ Or memoized inside the component
+// ✅ Or memoized inside the component (React)
 const routeMap = useMemo(() => createRouteMapFromTree(routeTree), [routeTree]);
 ```
 
-### Wrong Node.js version
+#### Wrong Node.js version
 
 **Error:** `SyntaxError: Cannot use import statement in a module` or TC39 Signals not available.
 
@@ -494,28 +685,30 @@ node --version
 
 ## 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"`, `params`, `query`                                                          |
-| `always` guard                                                                                        | Protects states — fires on entry before any event, even on direct URL access                                    |
+| Term                                                                                                                | Description                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `setup({ types })`                                                                                                  | XState v5 entry point — declares TypeScript types for context, events, and input                                              |
+| [`definePlayer({ machine })`](../packages/docs/api/@xmachines/play-xstate/functions/definePlayer.md)                | Creates a factory that produces [`PlayerActor`](../packages/docs/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`](../packages/docs/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`](../packages/docs/api/@xmachines/play-router/functions/extractMachineRoutes.md)             | Extracts a `RouteTree` from a state machine — used by framework-integrated router adapters                                    |
+| [`createRouteMapFromTree`](../packages/docs/api/@xmachines/play-router/functions/createRouteMapFromTree.md)         | Builds a `RouteMap` from a `RouteTree` for bidirectional state ID ↔ URL lookups                                               |
+| [`connectRouter`](../packages/docs/api/@xmachines/play-dom-router/functions/connectRouter.md)                       | Connects a vanilla DOM router to an actor — returns a disconnect cleanup function                                             |
+| [`PlayRouterProvider`](../packages/docs/api/@xmachines/play-tanstack-react-router/functions/PlayRouterProvider.md)  | React component that connects a `PlayerActor` to TanStack React Router                                                        |
 
 ---
 
 ## Next Steps
 
-- **[ARCHITECTURE.md](ARCHITECTURE.md)** — System design, component diagram, data flow, and architectural invariants
-- **[CONFIGURATION.md](CONFIGURATION.md)** — Environment variables and configuration options
-- **[Routing Patterns](../packages/docs/examples/routing-patterns.md)** — `meta.route`, `play.route`, `always` guards, and parameter routes
-- **[Multi-Router Integration](../packages/docs/examples/multi-router-integration.md)** — All 8 router adapters with full code examples
-- **[Examples Index](../packages/docs/examples/README.md)** — Basic state machine, form validation, and traffic light demos
-- **[API Reference](../packages/docs/api/README.md)** — Auto-generated API docs for all packages
-- **[Play RFC](../rfc/play.md)** — Complete architectural specification
+- **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** — System design, layers, invariants, and data flow
+- **[packages/docs/rfc/play.md](../packages/docs/rfc/play.md)** — Complete architectural specification
+- **[packages/docs/api/README.md](../packages/docs/api/README.md)** — Auto-generated API docs for all packages
+- **[packages/docs/examples/](../packages/docs/examples/)** — Basic state machine, form validation, routing pattern demos
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** — Coding standards, branch conventions, and PR process (contributors)

package/guides/signals.md

@@ -161,6 +161,6 @@ Failing to clean up watchers causes memory leaks and stale callbacks firing afte
 - [Understanding the Actor Model](concepts-actor-model.md) — why the actor owns all signal writes
 - [Understanding State Machines](concepts-state-machines.md) — how state nodes produce the metadata that signals derive
 - [Getting Started](getting-started.md) — hands-on walkthrough using signals to observe an actor
-- [@xmachines/play-signals README](../api/@xmachines/play-signals/README.md) — API reference
+- [@xmachines/play-signals](../api/@xmachines/play-signals/README.md) — API reference
 - [Play RFC](../rfc/play.md) — architectural specification
 - [TC39 Signals proposal](https://github.com/tc39/proposal-signals) — upstream proposal