@xmachines/docs 6.1.0 → 7.1.0

package/contributing/migrating-to-play-atom.md

@@ -95,8 +95,14 @@ If you call `subscribe` directly, wrap the body.
 **A DERIVATION must contain its own failures.** A subscriber makes a computed atom eager, so the derivation itself runs inside the `set`, before any observer. No subscriber can wrap that, so the rule belongs to the derivation: report through your error channel, and return the previous value. `currentRoute` and `currentView` of the actor both do this, and a release before this one let `currentRoute` throw — which was safe only while the TC39 watcher read it from a microtask.
 
 ```typescript
+import { createAtom, type ReadonlyAtom } from "@xmachines/play-atom";
+
+declare const source: ReadonlyAtom<string>;
+declare function expensiveDerivation(input: string): number;
+declare function report(error: unknown): void;
+
 // A derivation that a subscriber may watch.
-const derived = createAtom((previous) => {
+const derived = createAtom<number | null>((previous) => {
 	try {
 		return expensiveDerivation(source.get());
 	} catch (error) {
@@ -112,7 +118,7 @@ const derived = createAtom((previous) => {
 
 **Derive the value, and read `previous`.** Almost every `untrack` guarded the same shape: a gate that compares the new value with the last one it emitted. A computed atom is handed that last value, so the gate needs no read and therefore tracks nothing. `withView` of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) is the worked example:
 
-```typescript
+```typescript fragment
 // Before: a written atom, plus untrack to read what it held.
 this.currentView = new Signal.State<View | null>(null);
 const last = Signal.subtle.untrack(() => this.currentView.get());
@@ -136,7 +142,7 @@ A read that already stands outside every computed atom and every effect tracks n
 
 The codemod renames the call, and it cannot write the source list. Add that array yourself, and move the callback one place to the right:
 
-```tsx
+```tsx fragment
 // Before
 useSignalEffect(() => {
 	setView(actor.currentView.get());
@@ -195,7 +201,7 @@ Property 'set' is missing in type 'ReadonlyAtom<T>' but required in type 'Atom<T
 
 Use `createWritableAtom`, which states the one signature:
 
-```typescript
+```typescript fragment
 import { createWritableAtom } from "@xmachines/play-atom";
 
 this.state = createWritableAtom(this.getSnapshot());

package/contributing/testing.md

@@ -4,7 +4,7 @@ This document describes the test framework, conventions, and CI integration for
 
 ## Test Framework and Setup
 
-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.
+The monorepo uses **[Vitest](https://vitest.dev/) `^5.0.3`** 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`](../api/@xmachines/shared/README.md)) which automatically applies:
 
@@ -25,7 +25,7 @@ All packages extend the shared Vitest configuration helper `defineXmVitestConfig
 
 `patches/@testing-library__jest-dom@7.0.1.patch` moves the matcher declaration of the library from `Assertion` to `Matchers`. The library declares this:
 
-```ts
+```ts fragment
 declare module "vitest" {
 	interface Assertion<T = any> extends TestingLibraryMatchers<any, T> {}
 }
@@ -35,14 +35,6 @@ Vitest 5 declares `interface Assertion<R extends void | Promise<void> = void, T
 
 Delete the patch, its `patchedDependencies` entry in `pnpm-workspace.yaml`, and `tests/jest-dom-augmentation.test.ts` on the day the library ships a declaration that vitest 5 accepts. See [testing-library/jest-dom#738](https://github.com/testing-library/jest-dom/issues/738).
 
-### The vitest mocker patch
-
-`patches/@vitest__mocker@5.0.1.patch` takes the `configureServer` hook off `vitest:mocks:interceptor` when the caller passes `registerWebSocketEvents: false`, which is how `@vitest/browser` calls it.
-
-Vitest returns that plugin from the `applyToEnvironment` of another plugin, and Vite 8 ignores a `configureServer` that it finds there. Vite reports the fact one time for each environment, so a run of 29 projects wrote 29 lines, in the `test` job and in the `test:browser` job both. The hook returns at once for `registerWebSocketEvents: false`, so the omission changes no behaviour.
-
-Delete the patch and its `patchedDependencies` entry when vitest ships the fix. See [vitest-dev/vitest#11276](https://github.com/vitest-dev/vitest/issues/11276).
-
 Before running any tests, ensure all dependencies are installed:
 
 ```bash
@@ -85,24 +77,24 @@ pnpm run test:dist           # the node suites
 pnpm run test:browser:dist   # the browser suites
 ```
 
-`pnpm test` runs every suite on the SOURCE of each package. It needs no build, and it cannot see a defect of the build. `pnpm run test:dist` runs the same test files on the BUILD OUTPUT, as a consumer installs it. The 6.0.0 release shows why both runs are necessary. [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md) and [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) shipped compiled for server-side rendering, and neither rendered in a browser. Every source suite was green. The node dist run fails 14 test files on that output, and the browser dist run fails the Vue suites.
+`pnpm test` runs every suite on the SOURCE of each package. It needs no build, and it cannot see a defect of the build. `pnpm run test:dist` runs the same test files on the BUILD OUTPUT, as a consumer installs it. The 6.0.0 release shows why both runs are necessary. [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md) and [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) shipped compiled for server-side rendering, and neither rendered in a browser. Every source suite was green. The node dist run fails 14 test files on that output, and the browser dist run fails the Vue suites. Run the source suites while you work. CI runs the dist suites alone, so each test counts one time in the merge request.
 
 The two scripts set `XM_TEST_TARGET=dist`, and the config helpers of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md) read it. No package config holds a copy of the dist setup. The variable changes two things:
 
 - **A specifier.** The alias map drops each published package. [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) then resolves through the `exports` map of the package to `dist/with-routing.js`. The `source` condition is not set either, so the resolution is the one that a consumer gets.
 - **A path into `src/`.** A test imports the module under test by path, as `../src/define-player.js`, and that import reaches no exports map. The `xmBuildOutput` plugin moves it to `dist/define-player.js`, which is the file that the package entry imports. The test and the package then share ONE module, and a `vi.mock` of the `src/` path replaces the module of the build. The build keeps the module structure, so each source file has one counterpart.
 
-The private packages — the demos and the `examples/shared` fixtures — reach no consumer, and the build does not compile them for one. Both runs read their source, and that source imports the packages from `dist/`.
+The private packages — the demos and the `examples/shared` fixtures — are never published. Both runs read their source, and that source imports the packages from `dist/`. The release packs the demos as assets, with the shared package of the demos. The build therefore compiles each packed package whose exports map names `dist/`, from its `vite.lib.config.ts`: the shared package of the demos, and the DOM, React and Solid galleries, which the router demos import.
 
 The plugin fails an import when the build output holds no counterpart. The import then names both files. A fallback to the source would hide the defect that the dist run exists to find. The plugin also fails the run when anything loads a `src/` file of a published package by another route.
 
-**Keep one file set.** Both runs collect the same files. A test that cannot run on the build output imports an internal module that the package does not ship. Import that module through the public entry of the package. If that is not possible, exclude the test from the dist run in its project config, and write the reason beside the exclusion. No test is excluded today.
+**Keep one file set.** Both runs collect the same files, except the code examples of the documentation. The examples document the API, so the dist run leaves out the `doc-examples` project, and CI runs it in the `test:docs:examples` job. A test that cannot run on the build output imports an internal module that the package does not ship. Import that module through the public entry of the package. If that is not possible, exclude the test from the dist run in its project config, and write the reason beside the exclusion. No other test is excluded today.
 
 **The proof.** `packages/play-xstate/test/test-target.test.ts` (node) and `packages/play-dom/test/browser/test-target.browser.test.ts` (browser) run in both runs. Each reads the target with `inject("xmTestTarget")`, and it asserts which file each kind of import loads. `import.meta.resolve` cannot answer that question, because it asks the resolver of Node. A stack trace cannot answer it either, because Vite applies the source maps of `dist/` and names `src/` in both runs.
 
 Run `pnpm run build` first. The dist run reads whatever `dist/` holds, and it does not build. A change to `src/` reaches the dist run only through a new build.
 
-Coverage stays on the source run. The build output carries none of the lines that the gate measures.
+CI measures the coverage on the dist run. The source maps of `dist/` carry the source, so the report names the files of `src/`. v8 matches `coverage.include` against the file that ran, before it reads the source map. The root config therefore adds `packages/*/dist/**/*.js` to `include` in the dist run, and `excludeAfterRemap` applies the filter again to the files of `src/`. The browser config sets no `include`, so it needs neither setting. A file can show a few statements more or less than in a source run, because the build and the dev transform of Vite emit different code. `pnpm run test:coverage` measures the source, locally.
 
 ### With coverage
 
@@ -269,6 +261,10 @@ The root `vitest.config.ts` needs no edit: it collects `packages/*/vitest.config
 
 ```typescript
 import { describe, it, test, expect, vi, beforeEach, afterEach } from "vitest";
+import type { PlayActor } from "@xmachines/play-actor";
+import type { PlayRouteEvent, Routable } from "@xmachines/play-router";
+
+declare function createMockActor(startRoute: string): PlayActor<unknown, PlayRouteEvent> & Routable;
 
 describe("ClassName or functionName()", () => {
 	describe("feature group or scenario", () => {
@@ -288,13 +284,16 @@ describe("ClassName or functionName()", () => {
 
 **Import style:** Always use `.js` extensions in imports (ESM requirement):
 
-```typescript
-import { PlayActor } from "../src/abstract-actor.js";
+```typescript fragment
+import type { PlayActor } from "../src/play-actor.js";
 ```
 
 ### Lifecycle hooks
 
 ```typescript
+import { cleanup } from "@testing-library/react";
+import { afterEach, beforeEach, vi } from "vitest";
+
 beforeEach(() => {
 	vi.spyOn(console, "error").mockImplementation(() => {});
 });
@@ -312,6 +311,8 @@ afterEach(() => {
 - **Framework router objects** (TanStack Router, Vue Router, React Router, SolidJS Router) — mock with typed `vi.fn()` interfaces because they are external framework dependencies and carry significant setup complexity:
 
     ```typescript
+    import { vi } from "vitest";
+
     const mocks = vi.hoisted(() => ({ goto: vi.fn() }));
 
     vi.mock("$app/navigation", () => ({ goto: mocks.goto }));
@@ -321,7 +322,9 @@ afterEach(() => {
 
 - **`console.warn` / `console.error`** when testing code that legitimately emits warnings — mock to suppress noise and assert call counts:
 
-    ```typescript
+    ```typescript norun
+    import { expect, vi } from "vitest";
+
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     // ... test ...
     expect(warnSpy).toHaveBeenCalled();
@@ -338,10 +341,11 @@ afterEach(() => {
 
 ### Test actor patterns
 
-**Preferred: extend `PlayActor` for full type safety:**
+**Preferred: implement `PlayActor` for full type safety:**
 
 ```typescript
-import { PlayActor } from "@xmachines/play-actor";
+import { createAtom, type Atom, type ReadonlyAtom } from "@xmachines/play-atom";
+import type { PlayActor } from "@xmachines/play-actor";
 import type { Routable } from "@xmachines/play-router";
 
 class MockActor implements PlayActor, Routable {
@@ -356,7 +360,7 @@ class MockActor implements PlayActor, Routable {
 		this.initialRoute = startRoute;
 	}
 
-	override send(_event: { readonly type: string } & Record<string, unknown>): void {
+	send(_event: { readonly type: string } & Record<string, unknown>): void {
 		// no-op or capture events for assertion
 	}
 }
@@ -365,18 +369,16 @@ class MockActor implements PlayActor, Routable {
 **Factory functions for lightweight inline mocks — use `stubOf`, never a double-cast:**
 
 ```typescript
+import { vi } from "vitest";
+import { createAtom } from "@xmachines/play-atom";
+import type { PlaySpec, ViewActor } from "@xmachines/play-view";
 import { stubOf } from "@xmachines/shared/test-support";
 
 function createMockActor(initialView: PlaySpec | null = null) {
 	return stubOf<ViewActor>({
 		currentView: createAtom<PlaySpec | null>(initialView),
 		send: vi.fn(),
-		start: vi.fn(),
-		stop: vi.fn(),
-		getSnapshot: vi.fn(),
-		subscribe: vi.fn(),
 		state: createAtom<unknown>({}),
-		currentRoute: createAtom(() => null),
 	});
 }
 ```
@@ -393,6 +395,11 @@ greppable escape hatch.
 **Flushing the microtask queue (required for `watchAtom` delivery):**
 
 ```typescript
+import { expect, vi } from "vitest";
+
+declare const result: string;
+declare const expected: string;
+
 function waitForMicrotask(): Promise<void> {
 	return new Promise<void>((resolve) => queueMicrotask(resolve));
 }
@@ -405,8 +412,12 @@ await vi.waitFor(() => expect(result).toBe(expected), { timeout: 100 });
 **Atom watch pattern:**
 
 ```typescript
+import { expect } from "vitest";
 import { createAtom, watchAtom } from "@xmachines/play-atom";
 
+const state = createAtom({ path: "/" });
+const actor = { state, currentRoute: createAtom(() => state.get().path) };
+
 let notified: string | null = null;
 const stop = watchAtom(actor.currentRoute, (route) => {
 	notified = route;
@@ -427,6 +438,9 @@ stop(); // Always clean up
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
 
 ```typescript
+import { expect } from "vitest";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
+
 const bad: ViewMeta = typedSpec({
 	root: "root",
 	elements: {},
@@ -443,6 +457,11 @@ For purely structural type assertions with no runtime test needed, use `.typeche
 
 ```typescript
 // packages/play-xstate/test/define-player.typecheck.ts
+import { createMachine } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const actor = definePlayer({ machine: createMachine({}) })();
+
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type AssertFalse<T extends false> = T;
 
@@ -455,8 +474,17 @@ These files are validated by `pnpm run test:build` (`tsc --build tsconfig.test.j
 ### Error testing
 
 ```typescript
+import { expect } from "vitest";
+import type { AnyStateMachine } from "xstate";
+import type { PlayEvent } from "@xmachines/play";
+import type { PlayActor } from "@xmachines/play-actor";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { InvalidEventError } from "@xmachines/play-xstate/errors";
 import { unsafeCast } from "@xmachines/shared/test-support";
 
+declare const actor: PlayActor;
+declare const dupMachine: AnyStateMachine;
+
 // Synchronous throws — feed a runtime guard an invalid value through
 // unsafeCast, the named escape hatch (never `null as unknown as PlayEvent`).
 expect(() => actor.send(unsafeCast<PlayEvent>(null))).toThrow(InvalidEventError);
@@ -489,7 +517,7 @@ A report that a spy swallows and no assertion reads is worse than the noise, bec
 
 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
+```typescript fragment
 // packages/play-router/examples/shared/test/router-bridge-contract.ts
 export function runBridgeContractTests(opts: ContractSuiteOptions): void;
 
@@ -513,7 +541,7 @@ The contract covers: deep-link sync on connect, router→actor navigation sync,
 
 **Compile-time bridge contract verification:**
 
-```typescript
+```typescript fragment
 import { assertImplementsRouterBridge } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
 import { MyRouterBridge } from "../src/my-router-bridge.js";
 
@@ -555,20 +583,25 @@ Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (ver
 - Pushes to the default branch (`$CI_DEFAULT_BRANCH`)
 - Merge requests (`$CI_MERGE_REQUEST_IID`)
 
-**CI test command** (from `.gitlab-ci.yml`):
+**CI test jobs** (from `.gitlab-ci.yml`):
 
 ```bash
-pnpm run test:coverage
+pnpm run test:dist --coverage           # test:dist
+pnpm run test:browser:dist --coverage --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL   # test:browser:dist, on the Playwright image
+pnpm run test:docs:examples             # test:docs:examples
 ```
 
-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.
+CI runs the suites on the build output alone. `test:dist` and `test:browser:dist` take `dist/` from `node-build` through `needs:`, so they test the build that the pipeline produced. They block: a failure is a defect of the tarball that a consumer installs, and it holds the release, because `semantic-release` runs in a later stage. `test:docs:examples` reads the source, so it waits for no build.
+
+`test:browser:dist` runs in four shards of a parallel job. One process that runs every browser project holds a Vite server for each one, and the job ran out of memory. Each shard runs a quarter of the test files. To run one shard locally, give `--shard=1/4` to `pnpm run test:browser:dist`.
 
-**Tests on the build output:** `test:dist` runs `pnpm run test:dist`, and `test:browser:dist` runs `pnpm run test:browser:dist` on the Playwright image. Both take `dist/` from `node-build` through `needs:`, so they test the build that the pipeline produced. They follow the rules of `test`, and they block: a failure is a defect of the tarball that a consumer installs, and it holds the release, because `semantic-release` runs in a later stage. They write `reports/test-results-dist.xml` and `reports/browser-results-dist.xml`, and each test case carries a `dist:` class name, so the widget of the merge request keeps them apart from the source runs. Neither job collects coverage.
+The jobs pass no reporter flag. `vitest.config.ts` and `vitest.browser.config.ts` own the reporters, the JUnit file and the coverage directory, and they read `COVERAGE_REPORTS_DIR` — which the dist jobs set to `reports/`. A new package therefore needs no CI change. `test:docs:examples` shares the root config with `test:dist`, so it names its own JUnit file on the command line.
 
-**Artifacts:** The `test` job publishes:
+**Artifacts:**
 
-- 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)
+- `test:dist`: JUnit at `reports/test-results.xml`, and Cobertura at `reports/cobertura-coverage.xml`. GitLab reads the coverage percentage from the `All files` line.
+- `test:browser:dist`: in each shard, JUnit at `reports/browser-results.xml`, and its own Cobertura report. GitLab merges the Cobertura reports.
+- `test:docs:examples`: JUnit at `reports/docs-examples.xml`.
 
 Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.
 

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

@@ -0,0 +1,127 @@
+[Examples](../../README.md) / @xmachines/play-dom-gallery-demo
+
+# @xmachines/play-dom-gallery-demo
+
+Vanilla DOM renderer gallery for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — all nine shared machines behind one picker, actor + `createPlayUI` without a router.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- All nine shared machines (fetch, stopwatch, tic-tac-toe, temperature, TodoMVC, trivia, donut, flight, auth) reused without framework-specific business logic
+- A home-screen picker: selecting a machine stops the previous actor, creates a FRESH actor for the chosen machine, and renders its views; "Back to gallery" returns to the picker
+- The five-component demo kit (Page, Panel, Field, Button, Text) defined ONCE as plain DOM factories and registered with every machine's typed `defineRegistry` catalog
+- Routing machines run WITHOUT a router here — navigation happens via their in-view route-action buttons; the actor owns view switching. Auth's login wall still holds: `dashboard`'s `always` guard bounces an unauthenticated visitor to `login` no matter how the entry is attempted
+- A host `onConfirm` (`createConfirmDialog`): [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) is headless, so a confirm-gated action (TodoMVC's clear-completed) would be SKIPPED with a `console.warn` unless the host answers the confirm — the dialog renders the spec's `confirmLabel`/`cancelLabel` verbatim
+- `Field` registering declarative `checks` with the renderer's validation registry and displaying `formErrors` in a `[data-demo-error]` node (the flight machine's date rules)
+- One shared Stately inspector (`createDemoInspector()`) serving every selection — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-dom-gallery-demo run dev
+```
+
+Then open `http://localhost:3020`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` calls `initApp(document.getElementById("app"))`.
+2. `src/App.ts` renders the picker; `openMachine(entry)` stops any previous actor, empties the container, and calls `entry.createRuntime(inspector.inspect)`.
+3. `src/machines.ts` holds one `GalleryMachineEntry` per machine: `createRuntime` builds a fresh started actor via `definePlayer({ machine, options: { inspect } })()` and its `defineRegistry(catalog, { components: demoComponents, actions: create<Prefix>ActionHandlers(actor) })`.
+4. `src/catalogs.ts` builds all nine catalogs with `defineCatalog(schema, <prefix>CatalogDef)` — router demos import theirs from the barrel.
+5. `initShell` writes the demo chrome, connects `createPlayUI(registryResult, { onConfirm: createConfirmDialog })(actor, content)`, and appends the `DebugPanel`; the gallery passes `title` and a `nav` node carrying the "Back to gallery" button. The DOM router demos import this same shell, so the confirm handler serves them too.
+6. Browser tests in `test/browser/` delegate one file per machine to that machine's shared renderer suite.
+
+## Key Files
+
+- `src/main.ts` - DOM entry point that mounts the gallery
+- `src/App.ts` - picker, per-selection actor lifecycle, and `initShell` composition
+- `src/machines.ts` - the machine registry: slug, label, and `createRuntime` per machine
+- `src/catalogs.ts` - the nine built catalogs plus the `KitCatalog` typing alias
+- `src/components/` - the five-component kit (Page, Panel, Field, Button, Text) plus `Shell`, `DebugPanel`, and `ConfirmDialog`
+- `src/index.ts` - barrel exporting `initApp`, the kit, `demoComponents`, `initShell`, `createDebugPanel`, `createConfirmDialog`, and every built catalog for the router demos
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/<slug>-demo.browser.test.ts` - one file per machine, delegating to the shared suites
+- `test/browser/gallery-picker.browser.test.ts` - picker smoke test (open/close roundtrip)
+
+## Architecture Invariants
+
+1. **Actor Authority:** Views dispatch machine events (and `route` actions on routing machines) to the actor. The actor evaluates guards and transitions — the DOM layer never decides which view to render.
+2. **Passive Infrastructure:** The DOM renderer observes the `actor.currentView` atom only. It holds no business state and makes no routing decisions.
+3. **Fresh Actor Per Selection:** Reopening a machine always starts from its initial state, matching the demo inspector's "one live machine" semantics.
+
+## Available Scripts
+
+| Command                                                           | Description                                    |
+| ----------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run dev`          | Start Vite dev server (http://localhost:3020/) |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-dom-gallery-demo run test
+pnpm --filter @xmachines/play-dom-gallery-demo run test:browser
+```
+
+Expected result: library-pattern invariant tests pass and all nine machine suites plus the picker smoke test complete.
+
+## Learn More
+
+- [play-dom](../../../api/@xmachines/play-dom/README.md)
+- [DOM Router auth demo](../play-dom-router-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
+
+## Interfaces
+
+- [GalleryMachineEntry](interfaces/GalleryMachineEntry.md)
+- [GalleryRuntime](interfaces/GalleryRuntime.md)
+- [ShellOptions](interfaces/ShellOptions.md)
+
+## Type Aliases
+
+- [AuthCatalog](type-aliases/AuthCatalog.md)
+- [DonutCatalog](type-aliases/DonutCatalog.md)
+- [FetchCatalog](type-aliases/FetchCatalog.md)
+- [FlightCatalog](type-aliases/FlightCatalog.md)
+- [GalleryActor](type-aliases/GalleryActor.md)
+- [GallerySlug](type-aliases/GallerySlug.md)
+- [KitCatalog](type-aliases/KitCatalog.md)
+- [StopwatchCatalog](type-aliases/StopwatchCatalog.md)
+- [TemperatureCatalog](type-aliases/TemperatureCatalog.md)
+- [TicTacToeCatalog](type-aliases/TicTacToeCatalog.md)
+- [TodoMvcCatalog](type-aliases/TodoMvcCatalog.md)
+- [TriviaCatalog](type-aliases/TriviaCatalog.md)
+
+## Variables
+
+- [authCatalog](variables/authCatalog.md)
+- [Button](variables/Button.md)
+- [demoComponents](variables/demoComponents.md)
+- [donutCatalog](variables/donutCatalog.md)
+- [fetchCatalog](variables/fetchCatalog.md)
+- [Field](variables/Field.md)
+- [flightCatalog](variables/flightCatalog.md)
+- [galleryMachines](variables/galleryMachines.md)
+- [Page](variables/Page.md)
+- [Panel](variables/Panel.md)
+- [stopwatchCatalog](variables/stopwatchCatalog.md)
+- [temperatureCatalog](variables/temperatureCatalog.md)
+- [Text](variables/Text.md)
+- [ticTacToeCatalog](variables/ticTacToeCatalog.md)
+- [todoMvcCatalog](variables/todoMvcCatalog.md)
+- [triviaCatalog](variables/triviaCatalog.md)
+
+## Functions
+
+- [createConfirmDialog](functions/createConfirmDialog.md)
+- [createDebugPanel](functions/createDebugPanel.md)
+- [initApp](functions/initApp.md)
+- [initShell](functions/initShell.md)

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

@@ -0,0 +1,33 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / createConfirmDialog
+
+# Function: createConfirmDialog()
+
+```ts
+function createConfirmDialog(confirm): Promise<boolean>;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/ConfirmDialog.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/ConfirmDialog.ts#L18)
+
+ConfirmDialog — the gallery's `onConfirm` implementation.
+
+The framework packages render json-render's own dialog from their provider,
+but `@xmachines/play-dom` is headless: it only exposes `ctx.onConfirm`, and a
+confirm-gated action with no handler is SKIPPED with a `console.warn`. So the
+host brings the dialog, and `Shell` hands this factory to `createPlayUI` —
+which makes every confirm-gated action (TodoMVC's clear-completed) work in
+the gallery and in the DOM router demos that share that shell.
+
+The buttons carry the spec's `confirmLabel`/`cancelLabel` VERBATIM — the same
+text the framework renderers' ConfirmDialogManager shows — because label text
+is the only handle the shared browser suites have on a dialog whose markup
+differs per renderer.
+
+## Parameters
+
+| Parameter | Type            |
+| --------- | --------------- |
+| `confirm` | `ActionConfirm` |
+
+## Returns
+
+`Promise`\<`boolean`\>

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

@@ -0,0 +1,31 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / createDebugPanel
+
+# Function: createDebugPanel()
+
+```ts
+function createDebugPanel(actor, container, inspector): () => void;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/DebugPanel.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/DebugPanel.ts#L17)
+
+DebugPanel — live debug footer factory. Appends the footer to `container`,
+shows the current state value, renders the button that opens the Stately
+inspector window, and returns a disconnect function that stops the watcher.
+
+The state label is a computed atom rather than a watch of `actor.state`
+directly: `GalleryActor` is a union of nine actor types, so `actor.state` is a
+union of nine atom types that no single `watchAtom<T>` call can accept. Reading
+inside the computed atom collapses the union to the one thing the panel needs —
+a string. A swap of the actor is a dispose and a rebuild of the panel.
+
+## Parameters
+
+| Parameter   | Type                                              |
+| ----------- | ------------------------------------------------- |
+| `actor`     | [`GalleryActor`](../type-aliases/GalleryActor.md) |
+| `container` | `HTMLElement`                                     |
+| `inspector` | `DemoInspector`                                   |
+
+## Returns
+
+() => `void`

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

@@ -0,0 +1,22 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / initApp
+
+# Function: initApp()
+
+```ts
+function initApp(container): () => void;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/App.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/App.ts#L33)
+
+Mount the gallery into `container` and return a cleanup function that stops
+whatever actor is live and empties the container.
+
+## Parameters
+
+| Parameter   | Type          |
+| ----------- | ------------- |
+| `container` | `HTMLElement` |
+
+## Returns
+
+() => `void`

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

@@ -0,0 +1,33 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / initShell
+
+# Function: initShell()
+
+```ts
+function initShell(container, options): () => void;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Shell.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L35)
+
+Shell — DOM shell layout factory.
+
+Writes the standard demo chrome (header + content region + debug footer)
+into `container`, connects the DOM renderer to the content region, wires the
+DebugPanel, and returns a disconnect function. There is no NavBar — every
+ported machine drives its own navigation through in-view buttons (route
+actions on routing machines, plain events elsewhere).
+
+The gallery App and the router demos share this one factory: the gallery
+passes `title`/`nav` (machine label + "Back to gallery" button); router
+demos call it bare with their bridged `router`. Because they share it, the
+`onConfirm` handler wired here serves the router demos too.
+
+## Parameters
+
+| Parameter   | Type                                            |
+| ----------- | ----------------------------------------------- |
+| `container` | `HTMLElement`                                   |
+| `options`   | [`ShellOptions`](../interfaces/ShellOptions.md) |
+
+## Returns
+
+() => `void`

package/examples/@xmachines/play-dom-gallery-demo/interfaces/GalleryMachineEntry.md

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / GalleryMachineEntry
+
+# Interface: GalleryMachineEntry
+
+Defined in: [packages/play-dom/examples/gallery/src/machines.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/machines.ts#L85)
+
+## Properties
+
+| Property                                            | Type                                                 | Description                                                                                                                              | Defined in                                                                                                                                                                    |
+| --------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-createruntime"></a> `createRuntime` | (`inspect`) => [`GalleryRuntime`](GalleryRuntime.md) | Create a fresh, STARTED actor and its registry for one selection. The caller owns the runtime and must stop the actor when done with it. | [packages/play-dom/examples/gallery/src/machines.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/machines.ts#L93) |
+| <a id="property-label"></a> `label`                 | `string`                                             | Picker button label and machine-view title.                                                                                              | [packages/play-dom/examples/gallery/src/machines.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/machines.ts#L88) |
+| <a id="property-slug"></a> `slug`                   | [`GallerySlug`](../type-aliases/GallerySlug.md)      | -                                                                                                                                        | [packages/play-dom/examples/gallery/src/machines.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/machines.ts#L86) |

package/examples/@xmachines/play-dom-gallery-demo/interfaces/GalleryRuntime.md

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / GalleryRuntime
+
+# Interface: GalleryRuntime
+
+Defined in: [packages/play-dom/examples/gallery/src/machines.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/machines.ts#L80)
+
+One live selection: the started actor plus its registry.
+
+## Properties
+
+| Property                                              | Type                                                                                             | Defined in                                                                                                                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`GalleryActor`](../type-aliases/GalleryActor.md)                                                | [packages/play-dom/examples/gallery/src/machines.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/machines.ts#L81) |
+| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](../../../../api/@xmachines/play-dom/interfaces/DefineRegistryResult.md) | [packages/play-dom/examples/gallery/src/machines.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/machines.ts#L82) |

package/examples/@xmachines/play-dom-gallery-demo/interfaces/ShellOptions.md

@@ -0,0 +1,18 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / ShellOptions
+
+# Interface: ShellOptions
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Shell.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L8)
+
+What the shell needs to render one live machine.
+
+## Properties
+
+| Property                                              | Type                                                                                             | Description                                                                      | Defined in                                                                                                                                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`GalleryActor`](../type-aliases/GalleryActor.md)                                                | -                                                                                | [packages/play-dom/examples/gallery/src/components/Shell.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L9)   |
+| <a id="property-inspector"></a> `inspector`           | `DemoInspector`                                                                                  | Stately inspector controller — wires the DebugPanel inspector button.            | [packages/play-dom/examples/gallery/src/components/Shell.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L14) |
+| <a id="property-nav"></a> `nav?`                      | `Node`                                                                                           | Extra header content — the gallery passes its "Back to gallery" button.          | [packages/play-dom/examples/gallery/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L18) |
+| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](../../../../api/@xmachines/play-dom/interfaces/DefineRegistryResult.md) | -                                                                                | [packages/play-dom/examples/gallery/src/components/Shell.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L12) |
+| <a id="property-router"></a> `router?`                | `unknown`                                                                                        | Bridged router instance — accepted for prop parity with router demos but unused. | [packages/play-dom/examples/gallery/src/components/Shell.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L11) |
+| <a id="property-title"></a> `title?`                  | `string`                                                                                         | Header title override — the gallery passes the machine label.                    | [packages/play-dom/examples/gallery/src/components/Shell.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L16) |