@xmachines/docs 4.0.0 → 5.0.1

package/contributing/testing.md

@@ -6,11 +6,11 @@ This document describes the test framework, conventions, and CI integration for
 
 The monorepo uses **[Vitest](https://vitest.dev/) `^5.0.1`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
 
-All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from `@xmachines/shared/vitest`) which automatically applies:
+All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from [`@xmachines/shared/vitest`](../api/@xmachines/shared/README.md)) which automatically applies:
 
 - `@xmachines/*` source aliases so imports resolve to source during test runs
-- `@xmachines/shared/vitest-setup` — extends Vitest matchers with `@testing-library/jest-dom`
-- `@xmachines/shared/vitest-node-setup` — enforces Node.js ≥ 24 on non-browser projects
+- [`@xmachines/shared/vitest-setup`](../api/@xmachines/shared/README.md) — extends Vitest matchers with `@testing-library/jest-dom`
+- [`@xmachines/shared/vitest-node-setup`](../api/@xmachines/shared/README.md) — enforces Node.js ≥ 24 on non-browser projects
 
 **Auto-injected setup files:**
 
@@ -19,7 +19,7 @@ All packages extend the shared Vitest configuration helper `defineXmVitestConfig
 | `packages/shared/config/vitest.node.setup.ts` | All non-browser projects | Validates Node.js ≥ 24 runtime; throws if wrong runtime |
 | `packages/shared/config/vitest.setup.ts`      | All projects             | Imports `@testing-library/jest-dom/vitest` matchers     |
 
-`vitest.setup.ts` is also the one file that `@xmachines/shared/tsconfig-test` names in `files`, so its import puts the matcher TYPES in every test program. Each package overrides `include`, and `files` survives that.
+`vitest.setup.ts` is also the one file that [`@xmachines/shared/tsconfig-test`](../api/@xmachines/shared/README.md) names in `files`, so its import puts the matcher TYPES in every test program. Each package overrides `include`, and `files` survives that.
 
 ### The jest-dom patch
 
@@ -141,21 +141,21 @@ packages/<name>/
 
 ### File naming conventions
 
-| Extension                                | Purpose                                                                                                                                 |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `.spec.ts`                               | Protocol enforcement tests; compile-time type safety tests; used in core packages (`play`, `play-actor`, `play-signals`, `play-xstate`) |
-| `.test.ts`                               | Unit, integration, and behavioral tests; used across all packages                                                                       |
-| `.browser.test.ts` / `.browser.test.tsx` | Playwright browser environment tests; excluded from standard `vitest.config.ts`, only run via `vitest.browser.config.ts`                |
-| `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `pnpm run test:build`                                       |
-| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                     |
+| Extension                                | Purpose                                                                                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `.spec.ts`                               | Protocol enforcement tests; compile-time type safety tests; used in core packages (`play`, `play-actor`, `play-atom`, `play-xstate`) |
+| `.test.ts`                               | Unit, integration, and behavioral tests; used across all packages                                                                    |
+| `.browser.test.ts` / `.browser.test.tsx` | Playwright browser environment tests; excluded from standard `vitest.config.ts`, only run via `vitest.browser.config.ts`             |
+| `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `pnpm run test:build`                                    |
+| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                  |
 
 ### Test environments
 
-| Environment                   | Packages                                                                                                   |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `node`                        | Core logic: `@xmachines/play`, `play-actor`, `play-signals`, `play-xstate`, `play-router`, router adapters |
-| `jsdom`                       | UI renderers: `@xmachines/play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`                 |
-| Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                        |
+| Environment                   | Packages                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node`                        | Core logic: [`@xmachines/play`](../api/@xmachines/play/README.md), `play-actor`, `play-atom`, `play-xstate`, `play-router`, router adapters |
+| `jsdom`                       | UI renderers: [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), `play-vue`, `play-solid`, `play-svelte`, `play-dom`        |
+| Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                                                         |
 
 `defineXmVitestConfig` gives a jsdom project the `vmThreads` pool. The `forks` pool builds one jsdom for each test file, and a jsdom costs about 0.4 s. The `vmThreads` pool gives each file its own VM context in a worker that keeps the environment, so a worker builds one jsdom for all the files that it runs. Each file still gets a fresh module registry and fresh globals. The full `pnpm test` run takes 94 s with `vmThreads` and 160 s with `forks`, and the environment share of the tracked time drops from 42% to 14%.
 
@@ -167,15 +167,15 @@ A project that declares its own `pool` keeps it.
 
 Isolation gives each test FILE its own worker: Vitest spawns a process, builds the environment, and evaluates the module graph one more time. That costs about 110 ms for each file, and the full `pnpm test` run takes 90 s with isolation on every project and 62 s with this rule.
 
-A jsdom project keeps isolation and loses no time by it, because `vmThreads` above already gives one worker to many files. It also needs isolation: `isolate: false` shares the globals between the files of one worker, and three `@xmachines/play-react` tests fail under it.
+A jsdom project keeps isolation and loses no time by it, because `vmThreads` above already gives one worker to many files. It also needs isolation: `isolate: false` shares the globals between the files of one worker, and three [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) tests fail under it.
 
-A worker that runs without isolation keeps ONE module registry for all the files that it runs, so `vi.mock` applies only while the worker has not yet loaded the real module. The order that the pool picks decides the winner, and the suite then fails on some runs and passes on others. `@xmachines/play-router` showed it: one file mocked `machine-to-graph.js` while twenty-five sibling files called the real module, and the package failed three tests on one run of the whole suite and twenty-five on the next. The file now builds a real machine, the package needs no isolation, and it runs in 1.0 s rather than 5.4 s.
+A worker that runs without isolation keeps ONE module registry for all the files that it runs, so `vi.mock` applies only while the worker has not yet loaded the real module. The order that the pool picks decides the winner, and the suite then fails on some runs and passes on others. [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) showed it: one file mocked `machine-to-graph.js` while twenty-five sibling files called the real module, and the package failed three tests on one run of the whole suite and twenty-five on the next. The file now builds a real machine, the package needs no isolation, and it runs in 1.0 s rather than 5.4 s.
 
 **A project whose test files call `vi.mock`, `vi.doMock`, `vi.stubGlobal`, or `vi.stubEnv` declares `isolate: true` in its own `vitest.config.ts`, with the reason.** `tests/isolate-policy.test.ts` holds this rule true: it asks `vitest list` which project collects which file, reads `isolate` from the config module, and names the file and the config when the two disagree. The scan follows the relative imports of each test file and reads the setup files of the project, so a fixture that mocks a module cannot hide, and it reads each `@vitest-environment` docblock, which reaches no config. Two projects declare it today: the `play-sveltekit-router` demo, which mocks `$app/navigation`, and the `play-actor` shared example, which stubs `window`.
 
 Prefer the other answer where you can reach it. A test that builds the real collaborator needs no isolation, and it costs the whole project nothing.
 
-A project that gives SOME of its files another environment isolates for the same reason. Vitest builds and tears down that environment inside a worker that keeps its module registry, so a module evaluated against the jsdom of one file stays cached for the next one and holds a `window` that no longer exists. `@xmachines/play-react-router` runs three React files that way.
+A project that gives SOME of its files another environment isolates for the same reason. Vitest builds and tears down that environment inside a worker that keeps its module registry, so a module evaluated against the jsdom of one file stays cached for the next one and holds a `window` that no longer exists. [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md) runs three React files that way.
 
 A spy needs no isolation, and neither do fake timers. Each patches something that the test itself owns and restores, and neither depends on a fresh module registry.
 
@@ -187,8 +187,8 @@ pnpm exec vitest run --sequence.shuffle.files
 
 ### Test helpers and shared setup
 
-- **`@xmachines/shared/vitest-setup`** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
-- **`@xmachines/shared/vitest-node-setup`** — Enforces Node ≥ 24 at runtime. Auto-injected for non-browser configs.
+- **[`@xmachines/shared/vitest-setup`](../api/@xmachines/shared/README.md)** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
+- **[`@xmachines/shared/vitest-node-setup`](../api/@xmachines/shared/README.md)** — Enforces Node ≥ 24 at runtime. Auto-injected for non-browser configs.
 - **`packages/play-react/test/test-utils.ts`** — React-specific test utilities for the `play-react` package.
 - **`packages/play-router/examples/shared/`** and **`packages/play-actor/examples/shared/`** — Shared test fixtures for router and actor integration tests.
 
@@ -263,7 +263,6 @@ describe("ClassName or functionName()", () => {
 
 ```typescript
 import { PlayActor } from "../src/abstract-actor.js";
-import { Signal } from "@xmachines/play-signals";
 ```
 
 ### Lifecycle hooks
@@ -306,7 +305,7 @@ afterEach(() => {
 
 **Never mock these:**
 
-- **TC39 Signals** (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`) — always use real implementations from `@xmachines/play-signals`. Signals have precise reactive semantics (synchronous propagation, lazy computation) that mocks cannot replicate accurately.
+- **Atoms** (`createAtom`, `watchAtom`) — always use real implementations from [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md). Atoms have precise reactive semantics (synchronous propagation, memoized derivation) that mocks cannot replicate accurately.
 - **Internal `@xmachines/*` packages** — these are resolved directly to source via the `xmAliases` Vite plugin in the Vitest config. Mocking them would hide integration bugs and defeat the purpose of cross-package testing.
 - **XState** — always use real `setup()` / `createMachine()` / `createActor()`. XState's actor lifecycle (start, stop, snapshot, subscription) is a behavioral contract that mocks cannot reliably emulate.
 
@@ -317,17 +316,16 @@ afterEach(() => {
 ```typescript
 import { PlayActor } from "@xmachines/play-actor";
 import type { Routable } from "@xmachines/play-router";
-import { Signal } from "@xmachines/play-signals";
 
 class MockActor implements PlayActor, Routable {
-	readonly state = new Signal.State({} as unknown);
-	private _routeState: Signal.State<string | null>;
-	readonly currentRoute: Signal.Computed<string | null>;
+	readonly state = createAtom({} as unknown);
+	private _routeState: Atom<string | null>;
+	readonly currentRoute: ReadonlyAtom<string | null>;
 	readonly initialRoute: string | null;
 
 	constructor(startRoute: string | null = "/") {
-		this._routeState = new Signal.State<string | null>(startRoute);
-		this.currentRoute = new Signal.Computed(() => this._routeState.get());
+		this._routeState = createAtom<string | null>(startRoute);
+		this.currentRoute = createAtom(() => this._routeState.get());
 		this.initialRoute = startRoute;
 	}
 
@@ -344,14 +342,14 @@ import { stubOf } from "@xmachines/shared/test-support";
 
 function createMockActor(initialView: PlaySpec | null = null) {
 	return stubOf<ViewActor>({
-		currentView: new Signal.State<PlaySpec | null>(initialView),
+		currentView: createAtom<PlaySpec | null>(initialView),
 		send: vi.fn(),
 		start: vi.fn(),
 		stop: vi.fn(),
 		getSnapshot: vi.fn(),
 		subscribe: vi.fn(),
-		state: new Signal.State<unknown>({}),
-		currentRoute: new Signal.Computed(() => null),
+		state: createAtom<unknown>({}),
+		currentRoute: createAtom(() => null),
 	});
 }
 ```
@@ -363,9 +361,9 @@ sites. `X as unknown as T` is banned in this repo; if `stubOf` cannot express
 the case, `unsafeCast<T>(value)` from the same module is the deliberate,
 greppable escape hatch.
 
-### Async and signal patterns
+### Async and atom patterns
 
-**Flushing the microtask queue (required for Signal propagation):**
+**Flushing the microtask queue (required for `watchAtom` delivery):**
 
 ```typescript
 function waitForMicrotask(): Promise<void> {
@@ -377,23 +375,26 @@ await waitForMicrotask();
 await vi.waitFor(() => expect(result).toBe(expected), { timeout: 100 });
 ```
 
-**Signal watcher pattern:**
+**Atom watch pattern:**
 
 ```typescript
-let notified = false;
-const watcher = new Signal.subtle.Watcher(() => {
-	notified = true;
+import { createAtom, watchAtom } from "@xmachines/play-atom";
+
+let notified: string | null = null;
+const stop = watchAtom(actor.currentRoute, (route) => {
+	notified = route;
 });
-watcher.watch(actor.currentRoute);
-actor.currentRoute.get(); // Initial read required to prime computed signals
 
 actor.state.set({ path: "/dashboard" });
-watcher.getPending(); // Process notifications synchronously
+// `watchAtom` coalesces into a microtask, so flush before the assertion.
+await new Promise((resolve) => setTimeout(resolve, 0));
 
-expect(notified).toBe(true);
-watcher.unwatch(actor.currentRoute); // Always clean up
+expect(notified).toBe("/dashboard");
+stop(); // Always clean up
 ```
 
+`atom.subscribe` delivers SYNCHRONOUSLY, inside the `set`, and it needs no flush. Use it when a test must observe the notification at the moment of the write. Use `watchAtom` everywhere else, because it is what the renderers and the bridges use.
+
 ### Compile-time type tests
 
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
@@ -448,18 +449,18 @@ try {
 
 ### An expected report in the log
 
-A test that makes a component fail gets a report of the framework for free. React writes the error and a component stack to `console.error` when the root declares no `onCaughtError`, and `@xmachines/play-solid` writes a line of its own when the caller gives no `onError`. Both reports are correct, and both reach the log of the pipeline, where 29 of them once filled more than half of the `test` job.
+A test that makes a component fail gets a report of the framework for free. React writes the error and a component stack to `console.error` when the root declares no `onCaughtError`, and [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md) writes a line of its own when the caller gives no `onError`. Both reports are correct, and both reach the log of the pipeline, where 29 of them once filled more than half of the `test` job.
 
 Claim the report in the test that expects it, and assert it:
 
-- **React.** Take `render` from `test/test-utils.js` of `@xmachines/play-react`, and not from `@testing-library/react`. It gives an `onCaughtError` to the root, which stops the print, and the result carries `caughtErrors` for an assertion. Keep the `render` of the library for a test that holds the DEFAULT report: the print of React IS the report of play-react for a caller that gives no `onError`.
+- **React.** Take `render` from `test/test-utils.js` of [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), and not from `@testing-library/react`. It gives an `onCaughtError` to the root, which stops the print, and the result carries `caughtErrors` for an assertion. Keep the `render` of the library for a test that holds the DEFAULT report: the print of React IS the report of play-react for a caller that gives no `onError`.
 - **Any framework.** Call `vi.spyOn(console, "error").mockImplementation(() => {})` before the render, and `expect(spy).toHaveBeenCalled()` after it. An `afterEach` with `vi.restoreAllMocks()` returns the console to the next test.
 
 A report that a spy swallows and no assertion reads is worse than the noise, because it hides the day that the renderer stops to report.
 
 ## Contract Tests
 
-The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in `@xmachines/play-router`) because the suite drives a real actor via `@xmachines/play-xstate` and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps `@xmachines/play-router` free of any dependency on the actor runtime:
+The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)) because the suite drives a real actor via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) free of any dependency on the actor runtime:
 
 ```typescript
 // packages/play-router/examples/shared/test/router-bridge-contract.ts
@@ -481,7 +482,7 @@ runBridgeContractTests({
 
 The contract covers: deep-link sync on connect, router→actor navigation sync, actor→router sync, guard redirect flows, duplicate event deduplication, and restore-from-snapshot behavior.
 
-**Used by:** `@xmachines/play-router`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-react-router`, and other adapter packages.
+**Used by:** [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-react-router`, and other adapter packages.
 
 **Compile-time bridge contract verification:**
 
@@ -505,13 +506,13 @@ Coverage is collected using the **v8** provider. The root `vitest.config.ts` def
 
 Individual packages enforce their own (typically stricter) thresholds inside their `vitest.config.ts`:
 
-| Package tier                                                                       | Lines | Functions | Branches | Statements |
-| ---------------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
-| Core packages (`@xmachines/play`, `@xmachines/play-actor`, `@xmachines/play-view`) | 90%   | 90%       | 85%      | 90%        |
-| Complex logic (`@xmachines/play-xstate`, `@xmachines/play-router`)                 | 85%   | 85%       | 80%      | 85%        |
-| Integration packages (e.g. `@xmachines/play-react`, `@xmachines/play-dom`)         | 80%   | 80%       | 80%      | 80%        |
+| Package tier                                                                                                                                                                                              | Lines | Functions | Branches | Statements |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
+| Core packages ([`@xmachines/play`](../api/@xmachines/play/README.md), [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md), [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)) | 90%   | 90%       | 85%      | 90%        |
+| Complex logic ([`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md), [`@xmachines/play-router`](../api/@xmachines/play-router/README.md))                                                  | 85%   | 85%       | 80%      | 85%        |
+| Integration packages (e.g. [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md))                                              | 80%   | 80%       | 80%      | 80%        |
 
-`@xmachines/play-router` carries the lower numbers for a reason that its `vitest.config.ts` states: the bridge and the provider lifecycle are the mass of that package, and neither is measured by its own project. `@xmachines/play-router-shared` drives them through 3032 lines of contract suite, and each of the nine router adapters drives them again from its own project. The root `pnpm run test:coverage` is what measures the package whole.
+[`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries the lower numbers for a reason that its `vitest.config.ts` states: the bridge and the provider lifecycle are the mass of that package, and neither is measured by its own project. `@xmachines/play-router-shared` drives them through 3032 lines of contract suite, and each of the nine router adapters drives them again from its own project. The root `pnpm run test:coverage` is what measures the package whole.
 
 Coverage includes: `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
 
@@ -530,23 +531,19 @@ Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (ver
 **CI test command** (from `.gitlab-ci.yml`):
 
 ```bash
-pnpm run test:coverage -- \
-  --coverage.reporter=text \
-  --coverage.reporter=cobertura \
-  --coverage.reportsDirectory=reports/coverage \
-  --reporter=default \
-  --reporter=junit \
-  --outputFile.junit=reports/junit.xml
+pnpm run test:coverage
 ```
 
-**Artifacts:** The CI job (`node-build`) publishes:
+The job passes no reporter flag. `vitest.config.ts` owns the reporters, the JUnit file and the coverage directory, and it reads `COVERAGE_REPORTS_DIR` — which the `test` job sets to `reports/`. A new package therefore needs no CI change.
+
+**Artifacts:** The `test` job publishes:
 
-- JUnit XML report at `reports/junit.xml` (surfaced in GitLab's test results panel)
-- Cobertura coverage XML at `reports/coverage/cobertura-coverage.xml` (used for GitLab's coverage percentage badge — extracted from the `All files` line)
+- JUnit XML report at `reports/test-results.xml` (surfaced in GitLab's test results panel)
+- Cobertura coverage XML at `reports/cobertura-coverage.xml` (used for GitLab's coverage percentage badge — extracted from the `All files` line)
 
 Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.
 
-The `pnpm run format:check` and `pnpm run lint` commands enforce code style and are run separately from tests (via the `lint-enabled: true` input to the pipeline component).
+The `pnpm run format:check` and `pnpm run lint` commands enforce code style. They run as the separate `format` and `lint` jobs: the component's own lint job is turned off with `lint-enabled: "false"`, because it runs ESLint.
 
 ## Test Types Reference
 

package/examples/@xmachines/play-dom-demo/README.md

@@ -1,18 +1,24 @@
 [Examples](../../README.md) / @xmachines/play-dom-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-dom-demo
 
 Vanilla DOM renderer demo for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — actor + `createPlayUI` without a router.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
 - `createPlayUI` wiring `PlayRenderer`-equivalent DOM rendering without a framework
-- Auth machine states (home → login → dashboard) drive DOM updates via TC39 Signal watchers
-- `watchSignal` for reactive nav visibility and debug panel updates
+- Auth machine states (home → login → dashboard) drive DOM updates via atom watchers
+- `watchAtom` for reactive nav visibility and debug panel updates
 - Non-browser invariant tests plus browser renderer coverage
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+- json-render 0.20 showcase pages driven purely by spec:
+    - **Overview** — two data planes side by side: `/context/tasks` (machine context via the read-only `/context` projection; `repeat` + `key`, `$item`-filtered lists, per-row actions sending inspectable machine events) next to ephemeral store state (`pushState`/`removeState`/`setState` built-ins driving filter chips and toggles that survive context updates)
+    - **Stats** — nested repeats (`repeat.statePath: { $item: "members" }`) over `/context/teams`
+    - **Settings** — declarative field validation, the `validateForm` built-in, a confirm-gated `resetForm` host action, and `onSuccess`/`onError` chains
+    - **Contact** — a chained named action: submit validates, then routes home on success or writes `"$error.message"` to state on failure
 
 ## Running the Demo
 
@@ -29,64 +35,41 @@ Then open `http://localhost:3000`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` calls `definePlayer({ machine: authMachine })` and starts the actor.
-2. `initShell(actor, app)` from `src/components/Shell.ts` builds the HTML scaffold, mounts a reactive `NavBar`, wires the debug panel, and returns a disconnect function.
+1. `src/main.ts` creates the page's inspector with `createDemoInspector()`, calls `definePlayer({ machine: authMachine, options: { inspect: inspector.inspect } })`, and starts the actor.
+2. `initShell(actor, app, inspector)` from `src/components/Shell.ts` builds the HTML scaffold, mounts a reactive `NavBar`, wires the debug panel, and returns a disconnect function.
 3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
 4. `createPlayUI(registryResult)` produces a `mount` function; `mount(actor, container)` wires the registry to the actor — view switches happen automatically when `actor.currentView` changes.
-5. `createNavBar(actor, headerEl)` in `src/components/NavBar.ts` uses `watchSignal(actor.state, ...)` to update nav button visibility based on auth state.
-6. `createDebugPanel(actor, shell)` in `src/components/DebugPanel.ts` uses `watchSignal(actor.state, ...)` and `watchSignal(actor.currentRoute, ...)` to drive live debug panel updates.
+5. `createNavBar(actor, headerEl)` in `src/components/NavBar.ts` uses `watchAtom(actor.state, ...)` to update nav button visibility based on auth state.
+6. `createDebugPanel(actor, shell, inspector)` in `src/components/DebugPanel.ts` uses `watchAtom(actor.state, ...)` and `watchAtom(actor.currentRoute, ...)` to drive live debug panel updates, and renders the **Show Inspector** button that calls `inspector.show()`.
 7. Browser tests in `test/browser/` validate startup rendering and auth interactions.
 
 ```ts
 // src/main.ts (shape)
-const createPlayer = definePlayer({ machine: authMachine });
+const inspector = createDemoInspector();
+const createPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+});
 const actor = createPlayer();
 actor.start();
 
 const app = document.getElementById("app");
 if (!app) throw new Error("Root element not found");
 
-initShell(actor, app);
+initShell(actor, app, inspector);
 ```
 
 ```ts
 // src/components/Shell.ts (shape)
 const registryResult = defineRegistry(authCatalog, {
-	components: {
-		Home,
-		About,
-		Contact,
-		Login,
-		Dashboard,
-		Overview,
-		Stats,
-		Profile,
-		Settings,
-		Navigation,
-		NavBar: NavBarView,
-	},
-	actions: {
-		login: async (args) =>
-			actor.send({
-				type: "auth.login",
-				username: assertNonNullable(args, "args").username,
-			}),
-		logout: async () => actor.send({ type: "auth.logout" }),
-		route: async (args) => {
-			const { to, params } = assertNonNullable(args, "args");
-			actor.send({
-				type: "play.route",
-				to,
-				...(params != null && { params }),
-			});
-		},
-	},
+	components: demoComponents, // one shared map — Home…NavBar plus the 0.20 Panel/Field/Button leaves
+	actions: createAuthActionHandlers(actor), // login/logout/route + task events + form actions
 });
 
 const disconnectNavBar = createNavBar(actor, headerEl);
-const mount = createPlayUI(registryResult);
+const mount = createPlayUI(registryResult, { onConfirm: createConfirmDialog });
 const disconnectRenderer = mount(actor, viewContent);
-const disconnectDebugPanel = createDebugPanel(actor, shell);
+const disconnectDebugPanel = createDebugPanel(actor, shell, inspector);
 
 return () => {
 	disconnectNavBar();
@@ -99,8 +82,8 @@ return () => {
 
 - `src/main.ts` - actor creation and shell bootstrap
 - `src/components/Shell.ts` - DOM scaffold, `DomRegistry` construction, `createPlayUI` wiring, `createNavBar`, and `createDebugPanel`
-- `src/components/NavBar.ts` - reactive nav bar using `watchSignal(actor.state, ...)` for auth-driven button visibility
-- `src/components/DebugPanel.ts` - live debug footer using `watchSignal` on both `actor.state` and `actor.currentRoute`
+- `src/components/NavBar.ts` - reactive nav bar using `watchAtom(actor.state, ...)` for auth-driven button visibility
+- `src/components/DebugPanel.ts` - live debug footer using `watchAtom` on both `actor.state` and `actor.currentRoute`, plus the **Show Inspector** button
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
 
@@ -109,24 +92,22 @@ return () => {
 The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** Navigation buttons dispatch `play.route` events to the actor. The actor evaluates guards and transitions to the correct state — the DOM never decides which view to show.
-2. **Passive Infrastructure:** `createPlayUI` and `watchSignal` only react to actor signals. They do not hold business state or make routing decisions.
-3. **Signal-Only Reactivity:** `watchSignal` (from [`@xmachines/play-signals`](../../../api/@xmachines/play-signals/README.md)) wraps the canonical TC39 Signals watcher lifecycle, keeping all reactivity in the actor signal layer rather than in ad-hoc DOM event listeners.
+2. **Passive Infrastructure:** `createPlayUI` and `watchAtom` only react to actor atoms. They do not hold business state or make routing decisions.
+3. **Atom-Only Reactivity:** `watchAtom` (from [`@xmachines/play-atom`](../../../api/@xmachines/play-atom/README.md)) wraps the canonical atoms watcher lifecycle, keeping all reactivity in the actor atom layer rather than in ad-hoc DOM event listeners.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher lifecycle:
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and project DOM state
-5. Re-arm with `watch()`/`watch(...signals)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and projects DOM state
 
-Watcher notifications are one-shot. Cleanup is explicit: `disconnectNavBar()`, `disconnectRenderer()`, and `disconnectDebugPanel()` are all called from the disconnect function returned by `initShell`. In this demo, cleanup is called on `beforeunload` via `actor.stop()`.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `disconnectNavBar()`, `disconnectRenderer()`, and `disconnectDebugPanel()` are all called from the disconnect function returned by `initShell`. In this demo, cleanup is called on `beforeunload` via `actor.stop()`.
 
 ## Adapter Boundaries
 
-`createPlayUI` (from [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md)) is passive infrastructure. It translates actor view signals into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
+`createPlayUI` (from [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md)) is passive infrastructure. It translates actor view atoms into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
 
 ## Available Scripts
 
@@ -140,21 +121,11 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-dom-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-dom-demo run test:browser` | Run browser-focused Vitest suite               |
 
-## Verification
-
-Use these checks to validate README claims against the current demo implementation:
-
-```bash
-pnpm --filter @xmachines/play-dom-demo run test
-pnpm --filter @xmachines/play-dom-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
-
 ## Learn More
 
 - [Play DOM](../../../api/@xmachines/play-dom/README.md)
 - [Play DOM Router](../play-dom-router-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
 
 ## Type Aliases
 
@@ -164,18 +135,24 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 - [About](variables/About.md)
 - [authCatalog](variables/authCatalog.md)
+- [Button](variables/Button.md)
 - [Contact](variables/Contact.md)
 - [Dashboard](variables/Dashboard.md)
+- [demoComponents](variables/demoComponents.md)
+- [Field](variables/Field.md)
 - [Home](variables/Home.md)
 - [Login](variables/Login.md)
 - [NavBarView](variables/NavBarView.md)
 - [Navigation](variables/Navigation.md)
 - [Overview](variables/Overview.md)
+- [Panel](variables/Panel.md)
 - [Profile](variables/Profile.md)
 - [Settings](variables/Settings.md)
 - [Stats](variables/Stats.md)
 
 ## Functions
 
+- [createAuthActionHandlers](functions/createAuthActionHandlers.md)
+- [createConfirmDialog](functions/createConfirmDialog.md)
 - [createNavBar](functions/createNavBar.md)
 - [initShell](functions/initShell.md)

package/examples/@xmachines/play-dom-demo/functions/createAuthActionHandlers.md

@@ -0,0 +1,35 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / createAuthActionHandlers
+
+# Function: createAuthActionHandlers()
+
+```ts
+function createAuthActionHandlers(actor): object;
+```
+
+Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L48)
+
+Build the demo action handler map for one actor.
+
+Returned functions use the `(params, setState) => Promise<void>` shape every
+framework's `defineRegistry` accepts; spread the result into its `actions`.
+
+## Parameters
+
+| Parameter | Type        |
+| --------- | ----------- |
+| `actor`   | `AuthActor` |
+
+## Returns
+
+`object`
+
+| Name             | Type                                                    | Defined in                                                                                                                                                               |
+| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L65) |
+| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L72) |
+| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L50) |
+| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L54) |
+| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L81) |
+| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L99) |
+| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L55) |
+| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L92) |

package/examples/@xmachines/play-dom-demo/functions/createConfirmDialog.md

@@ -0,0 +1,27 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / createConfirmDialog
+
+# Function: createConfirmDialog()
+
+```ts
+function createConfirmDialog(confirm): Promise<boolean>;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/ConfirmDialog.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/ConfirmDialog.ts#L12)
+
+ConfirmDialog — the DOM demo's onConfirm implementation.
+
+The DOM package ships no dialog of its own (it only exposes `ctx.onConfirm`),
+so the demo renders one. The buttons carry the spec's
+`confirmLabel`/`cancelLabel` verbatim — the same text the framework
+renderers' ConfirmDialogManager shows — so the shared browser suite drives
+every demo's dialog by label text.
+
+## Parameters
+
+| Parameter | Type            |
+| --------- | --------------- |
+| `confirm` | `ActionConfirm` |
+
+## Returns
+
+`Promise`\<`boolean`\>

package/examples/@xmachines/play-dom-demo/functions/createNavBar.md

@@ -6,10 +6,10 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
 
 NavBar — App-shell navigation factory. Mounts a reactive nav into
-`container`, observes actor.state via watchSignal, and updates button
+`container`, observes actor.state via watchAtom, and updates button
 visibility based on auth state. Returns a disconnect function.
 
 ## Parameters

package/examples/@xmachines/play-dom-demo/functions/initShell.md

@@ -3,10 +3,10 @@
 # Function: initShell()
 
 ```ts
-function initShell(actor, appElement): () => void;
+function initShell(actor, appElement, inspector): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
+Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
 
 Shell — DOM shell layout factory. Renders demo chrome (header + main +
 debug panel), mounts NavBar, connects DOM renderer, and wires DebugPanel.
@@ -14,10 +14,11 @@ Returns a disconnect function.
 
 ## Parameters
 
-| Parameter    | Type          |
-| ------------ | ------------- |
-| `actor`      | `AuthActor`   |
-| `appElement` | `HTMLElement` |
+| Parameter    | Type            |
+| ------------ | --------------- |
+| `actor`      | `AuthActor`     |
+| `appElement` | `HTMLElement`   |
+| `inspector`  | `DemoInspector` |
 
 ## Returns
 

package/examples/@xmachines/play-dom-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/catalog.ts#L6)

package/examples/@xmachines/play-dom-demo/variables/About.md

@@ -6,7 +6,7 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/About.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/About.ts#L8)
 
 About — Public information page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'About'>). Renders static content from props.

package/examples/@xmachines/play-dom-demo/variables/Button.md

@@ -0,0 +1,12 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Button
+
+# Variable: Button
+
+```ts
+const Button: ComponentFn<AuthCatalog, "Button">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Button.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/Button.ts#L8)
+
+Button — emits `press`; the spec's `on.press` binding decides what happens
+(a host action sending a machine event, or a built-in like setState).