@xmachines/docs 7.0.0 → 7.1.0

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

@@ -8,9 +8,10 @@ Pure TypeScript integration demo for [`@xmachines/play-dom-router`](../../../api
 
 ## What This Demonstrates
 
-- Shared auth machine reused without framework-specific business logic
+- Shared auth machine (the login wall) reused without framework-specific business logic
+- The renderer gallery reused wholesale for the catalog, the five-component kit, and the shell — this demo adds routing and nothing else
 - `connectRouter` + `createBrowserHistory` wiring actor ↔ browser History API
-- Shell-driven DOM rendering via `connectRenderer` with actor-authoritative navigation
+- A PROTECTED deep link (`/dashboard`) bounced to `/login` by the machine's `always` guard, with the bridge rewriting the URL from actor state
 - Manual atom watcher lifecycle — the mechanism that framework adapters abstract
 - Non-browser invariant tests plus browser E2E coverage
 - Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
@@ -30,12 +31,13 @@ Then open `http://localhost:3005`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` looks up the host element (throws if absent) and calls `initApp(app)` from `src/runtime.ts`. It tears nothing down at the end of the page, because the browser frees the page.
-2. `src/runtime.ts` creates the page's inspector with `createDemoInspector()`, creates the actor from the shared machine via `definePlayer` with `options.inspect` wired to it, starts it, initializes router sync via `initRouter(actor)`, mounts the shared DOM shell via `initShell(actor, host, inspector)`, and returns one cleanup function.
-3. `initRouter(actor)` from `src/router.ts` extracts route metadata, creates a browser history wrapper, instantiates a router, and calls `connectRouter` to wire bidirectional actor ↔ URL sync.
-4. `initShell(actor, host, inspector)` is imported from [`@xmachines/play-dom-demo`](../play-dom-demo/README.md), so the router demo reuses the shared DOM shell — inspector button included — instead of duplicating the scaffold and renderer wiring.
-5. Navigation buttons and links dispatch `play.route`, `auth.login`, and `auth.logout` events directly to the actor — no URL mutations from the shell.
-6. Browser tests in `test/browser/` validate startup rendering and the full auth route flow.
+1. `src/main.ts` looks up the host element (throws if absent), calls `initApp(app)` from `src/runtime.ts`, and registers unload cleanup.
+2. `src/runtime.ts` is the pure wiring layer: the page's inspector (`createDemoInspector()`), the player factory (`definePlayer` with `options.inspect`), the `routeMap` built from the machine alone, and `createRegistryResult(actor)` pairing the gallery's `authCatalog` and `demoComponents` with `createAuthActionHandlers(actor)`.
+3. `src/App.ts` starts the actor, builds the registry, connects the router, and mounts the shell — in that order, because the bridge reads the entry URL on connect. It returns one cleanup function that tears down in reverse.
+4. `initRouter(actor)` from `src/router.ts` extracts route metadata, creates a browser history wrapper, instantiates a router, and calls `connectRouter` to wire bidirectional actor ↔ URL sync.
+5. `initShell(container, { actor, router, registryResult, inspector, title })` is imported from [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md), so the router demo reuses the gallery's shell — the debug panel's inspector button and the host `onConfirm` included — instead of duplicating the scaffold and renderer wiring.
+6. The views dispatch `route`, `login`, and `logout` catalog actions, which the shared handlers turn into `play.route`, `auth.login`, and `auth.logout` machine events — no URL mutations from the demo.
+7. Browser tests in `test/browser/` validate the protected deep link, login, logout, and the State-Driven Reset of an invalid URL.
 
 ```ts fragment
 // src/main.ts (shape)
@@ -50,38 +52,42 @@ initApp(app);
 
 ```ts fragment
 // src/router.ts (shape)
-export function initRouter(actor: RoutableActor) {
+export function initRouter(actor: RoutableActor): RouterConnection {
 	const routeTree = extractMachineRoutes(authMachine);
-	const routeMap = createRouteMap(authMachine);
 	const history = createBrowserHistory({ window });
 	const router = createRouter({ routeTree, history });
 	const disconnect = connectRouter({ actor, router, routeMap });
 
-	return () => {
-		disconnect();
-		router.destroy();
+	return {
+		router,
+		disconnect: () => {
+			disconnect();
+			router.destroy();
+		},
 	};
 }
 ```
 
 ```ts fragment
-// src/runtime.ts (shape)
-export function initApp(host: HTMLElement): () => void {
-	const inspector = createDemoInspector();
-	const createPlayer = definePlayer({
-		machine: authMachine,
-		options: { inspect: inspector.inspect },
-		actor: compose(PlayerActor, withRouting, withView),
-	});
+// src/App.ts (shape)
+export function initApp(container: HTMLElement): () => void {
 	const actor = createPlayer();
 	actor.start();
 
-	const cleanupRouter = initRouter(actor);
-	const cleanupShell = initShell(actor, host, inspector);
+	const registryResult = createRegistryResult(actor);
+	const { router, disconnect: disconnectRouter } = initRouter(actor);
+
+	const disconnectShell = initShell(container, {
+		actor,
+		router,
+		registryResult,
+		inspector,
+		title: "XMachines Play DOM Router — Auth",
+	});
 
 	return () => {
-		cleanupShell();
-		cleanupRouter();
+		disconnectShell();
+		disconnectRouter();
 		actor.stop();
 	};
 }
@@ -89,18 +95,19 @@ export function initApp(host: HTMLElement): () => void {
 
 ## Key Files
 
-- `src/main.ts` - host lookup and app bootstrap
-- `src/runtime.ts` - actor startup, router initialization, and shared shell wiring
+- `src/main.ts` - host lookup, app bootstrap, and unload cleanup
+- `src/runtime.ts` - inspector, player factory, route map, and registry wiring (no DOM, no `window`)
+- `src/App.ts` - startup order (actor → registry → router → shell) and the single cleanup function
 - `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
-- [`@xmachines/play-dom-demo`](../play-dom-demo/README.md) - shared DOM shell, NavBar, DebugPanel (including the **Show Inspector** button), and renderer wiring reused by this router demo
+- [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md) - the built `authCatalog`, the five-component kit, and the shell (DebugPanel with the **Show Inspector** button, plus the host `onConfirm`) reused by this router demo
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
-- `test/browser/shared-demo.browser.test.ts` - startup rendering and full auth route browser flow
+- `test/browser/shared-demo.browser.test.ts` - the shared auth router browser suite (protected deep link, login, logout, State-Driven Reset)
 
 ## State Machine & Architecture Details
 
 The demo utilizes XMachines architectural invariants at the lowest level:
 
-1. **Actor Authority:** Intercepting browser `popstate` events or navigation button clicks dispatches a `play.route` event to the actor. The actor processes the request against the current state, ensuring any auth logic is correctly applied.
+1. **Actor Authority:** Intercepting browser `popstate` events or navigation button clicks dispatches a `play.route` event to the actor. The actor processes the request against the current state, so the login wall (`dashboard`'s `always` guard) applies to a deep link exactly as it does to an in-view button.
 2. **Passive Infrastructure:** The router simply updates `window.history` and the DOM solely renders HTML based on what `actor.currentView` yields. Neither holds business state.
 3. **Atom-Only Reactivity:** The integration registers `watchAtom` observers that trigger DOM reconciliation, illustrating the underlying mechanism that framework adapters abstract.
 
@@ -133,6 +140,6 @@ These commands are defined in `package.json`:
 ## Learn More
 
 - [Play DOM Router](../../../api/@xmachines/play-dom-router/README.md)
-- [Play DOM](../play-dom-demo/README.md)
+- [Play DOM renderer gallery](../play-dom-gallery-demo/README.md)
 - [Play Router](../../../api/@xmachines/play-router/README.md)
 - [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,78 @@
+[Examples](../../README.md) / @xmachines/play-dom-router-donut-demo
+
+# @xmachines/play-dom-router-donut-demo
+
+Vanilla DOM Router integration demo of the shared **donut wizard** machine — actor-authoritative routing over the browser History API, with snapshot persistence and no framework.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared donut machine reused without framework-specific business logic
+- `createBrowserHistory` + `createRouter` + `connectRouter` wiring actor ↔ `window.history` — the wizard steps map to `/`, `/bake/mix`, `/bake/fry`, `/bake/decorate`, and `/done`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md) renderer gallery
+- Snapshot persistence: `options.onTransition` saves after every processed event, and `createResumedPlayer()` restores through the player factory's resume options — a reload resumes the wizard where the visitor left it
+- Actor-authoritative navigation: the wizard's guard chain cascades a deep link back to the first unmet prerequisite, and the bridge rewrites the URL (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — 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-router-donut-demo run dev
+```
+
+Then open `http://localhost:3062`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` looks up `#app` (throws if absent), calls `initApp(app)`, and registers unload cleanup.
+2. `src/App.ts` creates the actor through `createResumedPlayer()`, connects the router, mounts the shell with a "Reset saved donut" button in its `nav` slot, and returns one cleanup function. There is no component tree — `initApp(container) => cleanup` is the DOM family's top-level unit.
+3. `src/runtime.ts` creates the inspector, the `createPlayer` factory (`definePlayer` with `options.inspect` **and** `options.onTransition: (actor) => saveDonutSnapshot(actor)`), the resume helper, the reset helper, the pre-built `routeMap` (`createRouteMap(donutMachine)`), and `createRegistryResult`.
+4. `src/router.ts` extracts the route tree with `extractMachineRoutes`, wraps `window.history` with `createBrowserHistory`, pairs the two through `createRouter`, and installs the bridge with `connectRouter`.
+5. `initShell` (from [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md)) writes the demo chrome, connects `createPlayUI(registryResult)(actor, content)`, and appends the debug panel.
+6. Browser tests in `test/browser/` delegate to the shared donut router suite, which clears the persisted snapshot before mounting.
+
+## Key Files
+
+- `src/main.ts` - host lookup, app bootstrap, and unload cleanup
+- `src/App.ts` - actor lifecycle, router connection, the reset-snapshot button, and `initShell` composition
+- `src/runtime.ts` - actor factory, snapshot resume/save/reset helpers, pre-built `routeMap`, and `createRegistryResult`
+- `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared donut router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A `popstate` event or an in-view `route` action becomes a `play.route` event. The actor evaluates it against its guards and decides — the URL never decides.
+2. **Passive Infrastructure:** The bridge writes `window.history` and the DOM renders `actor.currentView`. Neither holds business state.
+3. **State-Driven Reset:** Entering `/done` with nothing prepared cascades done → decorate → fry → mix → recipe, and the bridge rewrites the URL back to `/`.
+4. **Persistence Is Not Authority:** The stored snapshot restores the actor at creation; from then on the actor decides. Dropping it (**Reset saved donut**) restarts the wizard from `/`.
+
+## Available Scripts
+
+| Command                                                                | Description                                    |
+| ---------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-dom-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3062/) |
+| `pnpm --filter @xmachines/play-dom-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-dom-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-dom-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-dom-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-dom-router-donut-demo run test
+pnpm --filter @xmachines/play-dom-router-donut-demo run test:browser
+```
+
+Expected result: the library-pattern assertions pass, and the shared donut router browser suite completes.
+
+## Learn More
+
+- [Play DOM Router](../../../api/@xmachines/play-dom-router/README.md)
+- [DOM renderer gallery](../play-dom-gallery-demo/README.md)
+- [Play Router](../../../api/@xmachines/play-router/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-dom-router-flight-demo
+
+# @xmachines/play-dom-router-flight-demo
+
+Vanilla DOM Router integration demo of the shared **flight booking** wizard — actor-authoritative routing over the browser History API, with no framework.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared flight machine reused without framework-specific business logic
+- `createBrowserHistory` + `createRouter` + `connectRouter` wiring actor ↔ `window.history` — the wizard steps map to `/`, `/dates`, `/review`, `/submitting`, and `/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: `/dates` is honored as a direct entry, while `/booked` without a confirmation is overwritten back (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — 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-router-flight-demo run dev
+```
+
+Then open `http://localhost:3063`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` looks up `#app` (throws if absent), calls `initApp(app)`, and registers unload cleanup.
+2. `src/App.ts` starts the actor, connects the router, mounts the shell, and returns one cleanup function. There is no component tree — `initApp(container) => cleanup` is the DOM family's top-level unit.
+3. `src/runtime.ts` creates the inspector, the `createPlayer` factory (`definePlayer` with `options.inspect`), the pre-built `routeMap` (`createRouteMap(flightMachine)`), and `createRegistryResult` — the demo's DOM-free wiring layer.
+4. `src/router.ts` extracts the route tree with `extractMachineRoutes`, wraps `window.history` with `createBrowserHistory`, pairs the two through `createRouter`, and installs the bridge with `connectRouter`.
+5. `initShell` (from [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md)) writes the demo chrome, connects `createPlayUI(registryResult)(actor, content)`, and appends the debug panel.
+6. Browser tests in `test/browser/` delegate to the shared flight router suite.
+
+## Key Files
+
+- `src/main.ts` - host lookup, app bootstrap, and unload cleanup
+- `src/App.ts` - actor lifecycle, router connection, and `initShell` composition
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult`
+- `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared flight router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A `popstate` event or an in-view `route` action becomes a `play.route` event. The actor evaluates it against its guards and decides — the URL never decides.
+2. **Passive Infrastructure:** The bridge writes `window.history` and the DOM renders `actor.currentView`. Neither holds business state.
+3. **State-Driven Reset:** The wizard's always-transitions cascade back to the first unmet prerequisite, and the bridge rewrites the URL the actor refused.
+
+## Available Scripts
+
+| Command                                                                 | Description                                    |
+| ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-dom-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3063/) |
+| `pnpm --filter @xmachines/play-dom-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-dom-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-dom-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-dom-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-dom-router-flight-demo run test
+pnpm --filter @xmachines/play-dom-router-flight-demo run test:browser
+```
+
+Expected result: the library-pattern assertions pass, and the shared flight router browser suite completes.
+
+## Learn More
+
+- [Play DOM Router](../../../api/@xmachines/play-dom-router/README.md)
+- [DOM renderer gallery](../play-dom-gallery-demo/README.md)
+- [Play Router](../../../api/@xmachines/play-router/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-dom-router-todomvc-demo
+
+# @xmachines/play-dom-router-todomvc-demo
+
+Vanilla DOM Router integration demo of the shared **TodoMVC** machine — actor-authoritative routing over the browser History API, with no framework.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared TodoMVC machine reused without framework-specific business logic
+- `createBrowserHistory` + `createRouter` + `connectRouter` wiring actor ↔ `window.history` — the filter states map to `/`, `/active`, and `/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — 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-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3060`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` looks up `#app` (throws if absent), calls `initApp(app)`, and registers unload cleanup.
+2. `src/App.ts` starts the actor, connects the router, mounts the shell, and returns one cleanup function. There is no component tree — `initApp(container) => cleanup` is the DOM family's top-level unit.
+3. `src/runtime.ts` creates the inspector, the `createPlayer` factory (`definePlayer` with `options.inspect`), the pre-built `routeMap` (`createRouteMap(todoMvcMachine)`), and `createRegistryResult` — the demo's DOM-free wiring layer.
+4. `src/router.ts` extracts the route tree with `extractMachineRoutes`, wraps `window.history` with `createBrowserHistory`, pairs the two through `createRouter`, and installs the bridge with `connectRouter`.
+5. `initShell` (from [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md)) writes the demo chrome, connects `createPlayUI(registryResult)(actor, content)`, and appends the debug panel.
+6. Browser tests in `test/browser/` delegate to the shared TodoMVC router suite.
+
+## Key Files
+
+- `src/main.ts` - host lookup, app bootstrap, and unload cleanup
+- `src/App.ts` - actor lifecycle, router connection, and `initShell` composition
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult`
+- `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared TodoMVC router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A `popstate` event or an in-view `route` action becomes a `play.route` event. The actor evaluates it against its guards and decides — the URL never decides.
+2. **Passive Infrastructure:** The bridge writes `window.history` and the DOM renders `actor.currentView`. Neither holds business state.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                  | Description                                    |
+| ------------------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-dom-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3060/) |
+| `pnpm --filter @xmachines/play-dom-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-dom-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-dom-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-dom-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-dom-router-todomvc-demo run test
+pnpm --filter @xmachines/play-dom-router-todomvc-demo run test:browser
+```
+
+Expected result: the library-pattern assertions pass, and the shared TodoMVC router browser suite completes.
+
+## Learn More
+
+- [Play DOM Router](../../../api/@xmachines/play-dom-router/README.md)
+- [DOM renderer gallery](../play-dom-gallery-demo/README.md)
+- [Play Router](../../../api/@xmachines/play-router/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-dom-router-trivia-demo
+
+# @xmachines/play-dom-router-trivia-demo
+
+Vanilla DOM Router integration demo of the shared **trivia** machine — actor-authoritative routing over the browser History API, with no framework.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared trivia machine reused without framework-specific business logic
+- `createBrowserHistory` + `createRouter` + `connectRouter` wiring actor ↔ `window.history` — the quiz states map to `/`, `/trivia`, `/win`, and `/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: only `/` is reachable from a cold start, and a deep link to `/trivia` while idle is overwritten back (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — 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-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3061`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` looks up `#app` (throws if absent), calls `initApp(app)`, and registers unload cleanup.
+2. `src/App.ts` starts the actor, connects the router, mounts the shell, and returns one cleanup function. There is no component tree — `initApp(container) => cleanup` is the DOM family's top-level unit.
+3. `src/runtime.ts` creates the inspector, the `createPlayer` factory (`definePlayer` with `options.inspect`), the pre-built `routeMap` (`createRouteMap(triviaMachine)`), and `createRegistryResult` — the demo's DOM-free wiring layer.
+4. `src/router.ts` extracts the route tree with `extractMachineRoutes`, wraps `window.history` with `createBrowserHistory`, pairs the two through `createRouter`, and installs the bridge with `connectRouter`.
+5. `initShell` (from [`@xmachines/play-dom-gallery-demo`](../play-dom-gallery-demo/README.md)) writes the demo chrome, connects `createPlayUI(registryResult)(actor, content)`, and appends the debug panel.
+6. Browser tests in `test/browser/` delegate to the shared trivia router suite.
+
+## Key Files
+
+- `src/main.ts` - host lookup, app bootstrap, and unload cleanup
+- `src/App.ts` - actor lifecycle, router connection, and `initShell` composition
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult`
+- `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared trivia router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A `popstate` event or an in-view `route` action becomes a `play.route` event. The actor evaluates it against its guards and decides — the URL never decides.
+2. **Passive Infrastructure:** The bridge writes `window.history` and the DOM renders `actor.currentView`. Neither holds business state.
+3. **State-Driven Reset:** A jump to `/trivia` or `/win` whose status prerequisite does not hold bounces the actor home, and the bridge writes the URL back to `/`.
+
+## Available Scripts
+
+| Command                                                                 | Description                                    |
+| ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-dom-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3061/) |
+| `pnpm --filter @xmachines/play-dom-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-dom-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-dom-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-dom-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-dom-router-trivia-demo run test
+pnpm --filter @xmachines/play-dom-router-trivia-demo run test:browser
+```
+
+Expected result: the library-pattern assertions pass, and the shared trivia router browser suite completes.
+
+## Learn More
+
+- [Play DOM Router](../../../api/@xmachines/play-dom-router/README.md)
+- [DOM renderer gallery](../play-dom-gallery-demo/README.md)
+- [Play Router](../../../api/@xmachines/play-router/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,123 @@
+[Examples](../../README.md) / @xmachines/play-react-gallery-demo
+
+# @xmachines/play-react-gallery-demo
+
+React renderer gallery for [`@xmachines/play-react`](../../../api/@xmachines/play-react/README.md) — all nine shared machines behind one picker, actor + `PlayRenderer` 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 and registered with every machine's typed `defineRegistry` catalog — `Field` also renders the declarative `checks`/`formErrors` contract behind `[data-demo-error]`
+- Routing machines run WITHOUT a router here — navigation happens via their in-view route-action buttons; the actor owns view switching
+- 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-react-gallery-demo run dev
+```
+
+Then open `http://localhost:3021`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` renders the picker; `openMachine(entry)` stops any previous actor 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. `Shell` wraps `<PlayUIProvider actor registryResult><PlayRenderer /></PlayUIProvider>` in the standard demo chrome plus the `DebugPanel`; the gallery passes `title` and a `nav` slot carrying the "Back to gallery" button.
+6. Browser tests in `test/browser/` delegate one file per machine to that machine's shared renderer suite.
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/App.tsx` - picker, per-selection actor lifecycle, and `Shell` 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` and `DebugPanel`
+- `src/index.ts` - barrel exporting `App`, the kit, `demoComponents`, `Shell`, `DebugPanel`, and every built catalog for the router demos
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/<slug>-demo.browser.test.tsx` - one file per machine, delegating to the shared suites
+- `test/browser/gallery-picker.browser.test.tsx` - 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 — React never decides which view to render.
+2. **Passive Infrastructure:** `PlayRenderer` 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-react-gallery-demo run dev`          | Start Vite dev server (http://localhost:3021/) |
+| `pnpm --filter @xmachines/play-react-gallery-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-react-gallery-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-react-gallery-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-react-gallery-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-react-gallery-demo run test
+pnpm --filter @xmachines/play-react-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-react](../../../api/@xmachines/play-react/README.md)
+- [React Router TodoMVC demo](../play-react-router-todomvc-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
+
+## Interfaces
+
+- [GalleryMachineEntry](interfaces/GalleryMachineEntry.md)
+- [GalleryRuntime](interfaces/GalleryRuntime.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)
+- [DebugPanel](variables/DebugPanel.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)
+- [Shell](variables/Shell.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
+
+- [App](functions/App.md)

package/examples/@xmachines/play-react-gallery-demo/functions/App.md

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-react-gallery-demo](../README.md) / App
+
+# Function: App()
+
+```ts
+function App(): Element;
+```
+
+Defined in: [packages/play-react/examples/gallery/src/App.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/App.tsx#L28)
+
+## Returns
+
+`Element`

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-react-gallery-demo](../README.md) / GalleryMachineEntry
+
+# Interface: GalleryMachineEntry
+
+Defined in: [packages/play-react/examples/gallery/src/machines.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/machines.ts#L86)
+
+## 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-react/examples/gallery/src/machines.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/machines.ts#L94) |
+| <a id="property-label"></a> `label`                 | `string`                                             | Picker button label and machine-view title.                                                                                              | [packages/play-react/examples/gallery/src/machines.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/machines.ts#L89) |
+| <a id="property-slug"></a> `slug`                   | [`GallerySlug`](../type-aliases/GallerySlug.md)      | -                                                                                                                                        | [packages/play-react/examples/gallery/src/machines.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/machines.ts#L87) |

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-react-gallery-demo](../README.md) / GalleryRuntime
+
+# Interface: GalleryRuntime
+
+Defined in: [packages/play-react/examples/gallery/src/machines.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/machines.ts#L81)
+
+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-react/examples/gallery/src/machines.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/machines.ts#L82) |
+| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](../../../../api/@xmachines/play-react/interfaces/DefineRegistryResult.md) | [packages/play-react/examples/gallery/src/machines.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/machines.ts#L83) |

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-react-gallery-demo](../README.md) / AuthCatalog
+
+# Type Alias: AuthCatalog
+
+```ts
+type AuthCatalog = typeof authCatalog;
+```
+
+Defined in: [packages/play-react/examples/gallery/src/catalogs.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/catalogs.ts#L47)

package/examples/@xmachines/play-react-gallery-demo/type-aliases/DonutCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-react-gallery-demo](../README.md) / DonutCatalog
+
+# Type Alias: DonutCatalog
+
+```ts
+type DonutCatalog = typeof donutCatalog;
+```
+
+Defined in: [packages/play-react/examples/gallery/src/catalogs.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-react/examples/gallery/src/catalogs.ts#L41)