@xmachines/docs 6.1.0 → 7.1.0

package/examples/@xmachines/{play-dom-demo/variables/authCatalog.md → play-dom-gallery-demo/variables/todoMvcCatalog.md}

@@ -1,9 +1,9 @@
-[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / authCatalog
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / todoMvcCatalog
 
-# Variable: authCatalog
+# Variable: todoMvcCatalog
 
 ```ts
-const authCatalog: Catalog<{
+const todoMvcCatalog: Catalog<{
   catalog: SchemaType<"object", {
      actions: SchemaType<"map", {
         description: SchemaType<"string", unknown>;
@@ -41,60 +41,49 @@ const authCatalog: Catalog<{
   }>;
 }, {
   actions: {
-     addTask: {
-        description: "Add a task (sends task.add to the machine)";
+     add: {
+        description: "Add a todo (sends todo.add to the machine)";
         params: ZodObject<{
            title: ZodString;
         }, $strip>;
      };
-     completeTask: {
-        description: "Mark a task done (sends task.complete to the machine)";
-        params: ZodObject<{
-           id: ZodString;
-        }, $strip>;
+     clearCompleted: {
+        description: "Remove every completed todo (sends todo.clearCompleted)";
      };
-     login: {
-        description: "Login with username";
+     edit: {
+        description: "Open one todo in the edit view (routes to '#todo' with the id param)";
         params: ZodObject<{
-           username: ZodString;
+           id: ZodString;
         }, $strip>;
      };
-     logout: {
-        description: "Logout and return to home";
-     };
-     removeTask: {
-        description: "Remove a task (sends task.remove to the machine)";
+     remove: {
+        description: "Remove a todo (sends todo.remove)";
         params: ZodObject<{
            id: ZodString;
         }, $strip>;
      };
-     resetForm: {
-        description: "Reset a demo form to its defaults (confirm-gated in the spec)";
+     rename: {
+        description: "Rename a todo (sends todo.rename; rejects a blank title)";
         params: ZodObject<{
-           form: ZodString;
+           id: ZodString;
+           title: ZodString;
         }, $strip>;
      };
      route: {
-        description: "Navigate to a route by path (e.g. '#home', '#login', '#dashboard')";
+        description: "Navigate to a filter route (e.g. '#all', '#active', '#completed')";
         params: ZodObject<{
            params: ZodOptional<ZodRecord<ZodString, ZodString>>;
            to: ZodString;
         }, $strip>;
      };
-     submitForm: {
-        description: "Submit a demo form; rejects when the form did not pass validation";
+     toggle: {
+        description: "Toggle a todo between open and done (sends todo.toggle)";
         params: ZodObject<{
-           form: ZodString;
-           valid: ZodOptional<ZodNullable<ZodBoolean>>;
+           id: ZodString;
         }, $strip>;
      };
   };
   components: {
-     About: {
-        props: ZodObject<{
-           title: ZodString;
-        }, $strip>;
-     };
      Button: {
         props: ZodObject<{
            disabled: ZodOptional<ZodBoolean>;
@@ -107,17 +96,6 @@ const authCatalog: Catalog<{
            }>>;
         }, $strip>;
      };
-     Contact: {
-        props: ZodObject<{
-           title: ZodString;
-        }, $strip>;
-     };
-     Dashboard: {
-        props: ZodObject<{
-           username: ZodString;
-           welcome: ZodBoolean;
-        }, $strip>;
-     };
      Field: {
         props: ZodObject<{
            checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
@@ -133,39 +111,17 @@ const authCatalog: Catalog<{
            value: ZodOptional<ZodString>;
         }, $strip>;
      };
-     Home: {
-        props: ZodObject<{
-           title: ZodString;
-        }, $strip>;
-     };
-     Login: {
-        props: ZodObject<{
-           title: ZodString;
-           username: ZodOptional<ZodString>;
-        }, $strip>;
-     };
-     NavBar: {
-        props: ZodObject<{
-           isAuthenticated: ZodBoolean;
-           username: ZodNullable<ZodString>;
-        }, $strip>;
-     };
-     Navigation: {
-        props: ZodObject<{
-           currentPath: ZodString;
-           isAuthenticated: ZodBoolean;
-        }, $strip>;
-     };
-     Overview: {
+     Page: {
         props: ZodObject<{
+           page: ZodString;
            title: ZodString;
         }, $strip>;
      };
      Panel: {
         props: ZodObject<{
-           note: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean, ZodNull]>>;
+           note: ZodOptional<ZodString>;
            testId: ZodOptional<ZodString>;
-           title: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber]>>;
+           title: ZodOptional<ZodString>;
            tone: ZodOptional<ZodEnum<{
               danger: "danger";
               default: "default";
@@ -174,24 +130,22 @@ const authCatalog: Catalog<{
            }>>;
         }, $strip>;
      };
-     Profile: {
-        props: ZodObject<{
-           username: ZodString;
-        }, $strip>;
-     };
-     Settings: {
+     Text: {
         props: ZodObject<{
-           section: ZodOptional<ZodString>;
-           username: ZodString;
-        }, $strip>;
-     };
-     Stats: {
-        props: ZodObject<{
-           title: ZodString;
+           testId: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+           value: ZodString;
         }, $strip>;
      };
   };
 }>;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-dom/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/catalogs.ts#L34)
+
+Built catalogs, one per machine — router demos import theirs from here.

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

@@ -0,0 +1,129 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / triviaCatalog
+
+# Variable: triviaCatalog
+
+```ts
+const triviaCatalog: Catalog<{
+  catalog: SchemaType<"object", {
+     actions: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        params: SchemaType<"zod", unknown>;
+     }>;
+     components: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        example: SchemaType<"any", unknown>;
+        props: SchemaType<"zod", unknown>;
+        slots: SchemaType<"array", SchemaType<"string", unknown>>;
+     }>;
+  }>;
+  spec: SchemaType<"object", {
+     elements: SchemaType<"record", SchemaType<"object", {
+        children: SchemaType<"array", SchemaType<"string", unknown>>;
+        props: SchemaType<"propsOf", string>;
+        repeat: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+        slots: {
+           inner?: SchemaType<"array", SchemaType<..., ...>>;
+           kind: "record";
+           optional: true;
+        };
+        type: SchemaType<"ref", string>;
+        visible: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+     }>>;
+     root: SchemaType<"string", unknown>;
+  }>;
+}, {
+  actions: {
+     answer: {
+        description: "Answer the current question by option id (sends trivia.answer)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     restart: {
+        description: "Return to the home screen for a fresh game (sends trivia.restart)";
+     };
+     route: {
+        description: "Navigate to a route by path (e.g. '#home', '#game')";
+        params: ZodObject<{
+           params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+           to: ZodString;
+        }, $strip>;
+     };
+     start: {
+        description: "Start a new trivia game (sends trivia.start)";
+     };
+  };
+  components: {
+     Button: {
+        props: ZodObject<{
+           disabled: ZodOptional<ZodBoolean>;
+           label: ZodString;
+           testId: ZodOptional<ZodString>;
+           variant: ZodOptional<ZodEnum<{
+              danger: "danger";
+              primary: "primary";
+              secondary: "secondary";
+           }>>;
+        }, $strip>;
+     };
+     Field: {
+        props: ZodObject<{
+           checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+           formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+           inputType: ZodOptional<ZodEnum<{
+              email: "email";
+              text: "text";
+              textarea: "textarea";
+           }>>;
+           label: ZodString;
+           placeholder: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           value: ZodOptional<ZodString>;
+        }, $strip>;
+     };
+     Page: {
+        props: ZodObject<{
+           page: ZodString;
+           title: ZodString;
+        }, $strip>;
+     };
+     Panel: {
+        props: ZodObject<{
+           note: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           title: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+        }, $strip>;
+     };
+     Text: {
+        props: ZodObject<{
+           testId: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+           value: ZodString;
+        }, $strip>;
+     };
+  };
+}>;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-dom/examples/gallery/src/catalogs.ts#L37)
+
+Built catalogs, one per machine — router demos import theirs from here.

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,14 +31,15 @@ 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
+```ts fragment
 // src/main.ts (shape)
 const app = document.getElementById("app");
 if (!app) throw new Error("Root element not found");
@@ -48,39 +50,44 @@ if (!app) throw new Error("Root element not found");
 initApp(app);
 ```
 
-```ts
+```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
-// src/runtime.ts (shape)
-export function initApp(host: HTMLElement): () => void {
-	const inspector = createDemoInspector();
-	const createPlayer = definePlayer({
-		machine: authMachine,
-		options: { inspect: inspector.inspect },
-	});
+```ts fragment
+// 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();
 	};
 }
@@ -88,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.
 
@@ -132,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)