@xmachines/docs 7.0.0 → 7.2.0

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

@@ -0,0 +1,91 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-solid-router-donut-demo
+
+# @xmachines/play-tanstack-solid-router-donut-demo
+
+TanStack Solid Router integration demo of the shared **donut** machine for the XMachines Play architecture.
+
+[![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
+- `PlayRouterProvider` renderer-based integration with `@tanstack/solid-router` — 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-solid-gallery-demo`](../play-solid-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Snapshot persistence: the actor snapshot is stored on every transition and resumed on reload, with a **Reset saved donut** header button to drop it
+- 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-tanstack-solid-router-donut-demo run dev
+```
+
+Then open `http://localhost:3086`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` onto `#root` via Solid's `render`.
+2. `src/runtime.ts` creates the inspector, starts the single donut actor, builds the `registryResult` from `donutCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and derives the `routeMap` with `createRouteMap(donutMachine)`.
+3. `src/App.tsx` creates a bare TanStack router (`createRouter({ routeTree: createRootRoute() })`) — a navigation service, not a renderer — and wires `PlayRouterProvider`.
+4. `PlayRouterProvider` constructs the `TanStackSolidRouterBridge` synchronously and disconnects it in `onCleanup`; the App's own `onCleanup` stops the actor.
+5. `Shell` (from the renderer gallery) receives `actor`, `router`, `registryResult`, `inspector`, and the **Reset saved donut** button as its `nav` slot.
+6. `test/library-pattern.test.ts` pins the library pattern; `test/browser/shared-demo.browser.test.ts` delegates to the shared donut router browser suite.
+
+## Snapshot Persistence
+
+The gallery creates a fresh actor per selection, so persistence belongs to this demo, which owns exactly one donut actor:
+
+- `definePlayer({ machine: donutMachine, options: { inspect, onTransition } })` — `onTransition` calls `saveDonutSnapshot(actor)`, writing `actor.getPersistedSnapshot()` to `localStorage` after every processed event.
+- `createResumedPlayer()` reads `loadDonutSnapshot()` and passes it through the player factory's resume options — `createPlayer(undefined, { snapshot })`. An absent snapshot (`null`) becomes `undefined`, which starts the machine from its initial state.
+- `resetSavedDonut()` calls `clearDonutSnapshot()` and reloads, wired to the `data-demo-id="reset-snapshot"` header button.
+
+All three helpers come from `@xmachines/play-actor-shared` and degrade to no-ops outside a browser.
+
+## Key Files
+
+- `src/main.tsx` - Solid entry point that mounts `<App />`
+- `src/runtime.ts` - actor lifecycle with persistence hooks, registry, and route map
+- `src/App.tsx` - TanStack router construction and `PlayRouterProvider` wiring, plus the reset-snapshot button
+- `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
+
+## Why No `<RouterProvider>`
+
+TanStack is wired as a navigation service: `createRouter({ routeTree: createRootRoute() })`, and `PlayRouterProvider` renders the gallery `Shell` itself.
+
+The actor, and not a route tree, decides the view, so the demo needs no `<RouterProvider>`. The bridge also works under a mounted provider: it synchronizes the actor after the `router.load()` of each navigation settles, so the provider does not drop the corrective navigation of a refused URL.
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation updates TanStack's location, the `PlayRouterProvider` converts it into a `play.route` event, and the actor evaluates its guards before any view changes.
+2. **Passive Infrastructure:** TanStack gets a bare root route — no loaders, no guards, no machine routes. It only moves the URL and reports where the URL went; the actor decides whether navigation is permitted.
+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-tanstack-solid-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3086/) |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-solid-router-donut-demo run test
+pnpm --filter @xmachines/play-tanstack-solid-router-donut-demo run test:browser
+```
+
+Expected result: the library-pattern node test and the shared donut router browser suite both pass.
+
+## Learn More
+
+- [TanStack Solid Router adapter](../../../api/@xmachines/play-tanstack-solid-router/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,80 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-solid-router-flight-demo
+
+# @xmachines/play-tanstack-solid-router-flight-demo
+
+TanStack Solid Router integration demo of the shared **flight** machine for the XMachines Play architecture.
+
+[![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
+- `PlayRouterProvider` renderer-based integration with `@tanstack/solid-router` — the wizard steps map to `/`, `/dates`, `/review`, `/submitting`, and `/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-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-tanstack-solid-router-flight-demo run dev
+```
+
+Then open `http://localhost:3087`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` onto `#root` via Solid's `render`.
+2. `src/runtime.ts` creates the inspector, starts the single flight actor, builds the `registryResult` from `flightCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and derives the `routeMap` with `createRouteMap(flightMachine)`.
+3. `src/App.tsx` creates a bare TanStack router (`createRouter({ routeTree: createRootRoute() })`) — a navigation service, not a renderer — and wires `PlayRouterProvider`.
+4. `PlayRouterProvider` constructs the `TanStackSolidRouterBridge` synchronously and disconnects it in `onCleanup`; the App's own `onCleanup` stops the actor.
+5. `Shell` (from the renderer gallery) receives `actor`, `router`, `registryResult`, and `inspector`.
+6. `test/library-pattern.test.ts` pins the library pattern; `test/browser/shared-demo.browser.test.ts` delegates to the shared flight router browser suite.
+
+## Key Files
+
+- `src/main.tsx` - Solid entry point that mounts `<App />`
+- `src/runtime.ts` - actor lifecycle, registry, and route map
+- `src/App.tsx` - TanStack router construction and `PlayRouterProvider` 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
+
+## Why No `<RouterProvider>`
+
+TanStack is wired as a navigation service: `createRouter({ routeTree: createRootRoute() })`, and `PlayRouterProvider` renders the gallery `Shell` itself.
+
+The actor, and not a route tree, decides the view, so the demo needs no `<RouterProvider>`. The bridge also works under a mounted provider: it synchronizes the actor after the `router.load()` of each navigation settles, so the provider does not drop the corrective navigation of a refused URL.
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation updates TanStack's location, the `PlayRouterProvider` converts it into a `play.route` event, and the actor evaluates its guards before any view changes.
+2. **Passive Infrastructure:** TanStack gets a bare root route — no loaders, no guards, no machine routes. It only moves the URL and reports where the URL went; the actor decides whether navigation is permitted.
+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-tanstack-solid-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3087/) |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-solid-router-flight-demo run test
+pnpm --filter @xmachines/play-tanstack-solid-router-flight-demo run test:browser
+```
+
+Expected result: the library-pattern node test and the shared flight router browser suite both pass.
+
+## Learn More
+
+- [TanStack Solid Router adapter](../../../api/@xmachines/play-tanstack-solid-router/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,80 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-solid-router-todomvc-demo
+
+# @xmachines/play-tanstack-solid-router-todomvc-demo
+
+TanStack Solid Router integration demo of the shared **TodoMVC** machine for the XMachines Play architecture.
+
+[![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
+- `PlayRouterProvider` renderer-based integration with `@tanstack/solid-router` — the filter states map to `/`, `/active`, and `/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-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-tanstack-solid-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3084`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` onto `#root` via Solid's `render`.
+2. `src/runtime.ts` creates the inspector, starts the single TodoMVC actor, builds the `registryResult` from `todoMvcCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and derives the `routeMap` with `createRouteMap(todoMvcMachine)`.
+3. `src/App.tsx` creates a bare TanStack router (`createRouter({ routeTree: createRootRoute() })`) — a navigation service, not a renderer — and wires `PlayRouterProvider`.
+4. `PlayRouterProvider` constructs the `TanStackSolidRouterBridge` synchronously and disconnects it in `onCleanup`; the App's own `onCleanup` stops the actor.
+5. `Shell` (from the renderer gallery) receives `actor`, `router`, `registryResult`, and `inspector`.
+6. `test/library-pattern.test.ts` pins the library pattern; `test/browser/shared-demo.browser.test.ts` delegates to the shared TodoMVC router browser suite.
+
+## Key Files
+
+- `src/main.tsx` - Solid entry point that mounts `<App />`
+- `src/runtime.ts` - actor lifecycle, registry, and route map
+- `src/App.tsx` - TanStack router construction and `PlayRouterProvider` 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
+
+## Why No `<RouterProvider>`
+
+TanStack is wired as a navigation service: `createRouter({ routeTree: createRootRoute() })`, and `PlayRouterProvider` renders the gallery `Shell` itself.
+
+The actor, and not a route tree, decides the view, so the demo needs no `<RouterProvider>`. The bridge also works under a mounted provider: it synchronizes the actor after the `router.load()` of each navigation settles, so the provider does not drop the corrective navigation of a refused URL.
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation updates TanStack's location, the `PlayRouterProvider` converts it into a `play.route` event, and the actor evaluates its guards before any view changes.
+2. **Passive Infrastructure:** TanStack gets a bare root route — no loaders, no guards, no machine routes. It only moves the URL and reports where the URL went; the actor decides whether navigation is permitted.
+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-tanstack-solid-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3084/) |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-solid-router-todomvc-demo run test
+pnpm --filter @xmachines/play-tanstack-solid-router-todomvc-demo run test:browser
+```
+
+Expected result: the library-pattern node test and the shared TodoMVC router browser suite both pass.
+
+## Learn More
+
+- [TanStack Solid Router adapter](../../../api/@xmachines/play-tanstack-solid-router/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,80 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-solid-router-trivia-demo
+
+# @xmachines/play-tanstack-solid-router-trivia-demo
+
+TanStack Solid Router integration demo of the shared **trivia** machine for the XMachines Play architecture.
+
+[![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
+- `PlayRouterProvider` renderer-based integration with `@tanstack/solid-router` — the quiz states map to `/`, `/trivia`, `/win`, and `/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-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-tanstack-solid-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3085`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` onto `#root` via Solid's `render`.
+2. `src/runtime.ts` creates the inspector, starts the single trivia actor, builds the `registryResult` from `triviaCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and derives the `routeMap` with `createRouteMap(triviaMachine)`.
+3. `src/App.tsx` creates a bare TanStack router (`createRouter({ routeTree: createRootRoute() })`) — a navigation service, not a renderer — and wires `PlayRouterProvider`.
+4. `PlayRouterProvider` constructs the `TanStackSolidRouterBridge` synchronously and disconnects it in `onCleanup`; the App's own `onCleanup` stops the actor.
+5. `Shell` (from the renderer gallery) receives `actor`, `router`, `registryResult`, and `inspector`.
+6. `test/library-pattern.test.ts` pins the library pattern; `test/browser/shared-demo.browser.test.ts` delegates to the shared trivia router browser suite.
+
+## Key Files
+
+- `src/main.tsx` - Solid entry point that mounts `<App />`
+- `src/runtime.ts` - actor lifecycle, registry, and route map
+- `src/App.tsx` - TanStack router construction and `PlayRouterProvider` 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
+
+## Why No `<RouterProvider>`
+
+TanStack is wired as a navigation service: `createRouter({ routeTree: createRootRoute() })`, and `PlayRouterProvider` renders the gallery `Shell` itself.
+
+The actor, and not a route tree, decides the view, so the demo needs no `<RouterProvider>`. The bridge also works under a mounted provider: it synchronizes the actor after the `router.load()` of each navigation settles, so the provider does not drop the corrective navigation of a refused URL.
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation updates TanStack's location, the `PlayRouterProvider` converts it into a `play.route` event, and the actor evaluates its guards before any view changes.
+2. **Passive Infrastructure:** TanStack gets a bare root route — no loaders, no guards, no machine routes. It only moves the URL and reports where the URL went; the actor decides whether navigation is permitted.
+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-tanstack-solid-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3085/) |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-solid-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-solid-router-trivia-demo run test
+pnpm --filter @xmachines/play-tanstack-solid-router-trivia-demo run test:browser
+```
+
+Expected result: the library-pattern node test and the shared trivia router browser suite both pass.
+
+## Learn More
+
+- [TanStack Solid Router adapter](../../../api/@xmachines/play-tanstack-solid-router/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,120 @@
+[Examples](../../README.md) / @xmachines/play-vue-gallery-demo
+
+# @xmachines/play-vue-gallery-demo
+
+Vue 3 renderer gallery for [`@xmachines/play-vue`](../../../api/@xmachines/play-vue/README.md) — all nine demo 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, and the auth login wall) 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 SFCs and registered with every machine's typed `defineRegistry` catalog
+- `Field` registering declarative `checks` with `useFieldValidation` and rendering the `formErrors` map the `validateForm` built-in writes back, in a `[data-demo-error]` node
+- 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-vue-gallery-demo run dev
+```
+
+Then open `http://localhost:3024`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `<App />` — no actor is created here, `App` owns the per-selection lifecycle.
+2. `src/App.vue` renders the picker; `openMachine(entry)` stops any previous actor and calls `entry.createRuntime(inspector.inspect)`, storing the result in a `shallowRef` so Vue never proxies the actor.
+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.vue` wraps `<PlayUIProvider :actor :registryResult><PlayRenderer /></PlayUIProvider>` in the standard demo chrome plus the `DebugPanel`; the gallery passes `title` and fills the `nav` slot with 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.ts` - Vue entry point that mounts `<App />`
+- `src/App.vue` - 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.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 — Vue 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.
+
+## Vue Specifics
+
+- The live selection lives in a `shallowRef`, so the actor and its registry are handed to `Shell` raw — Vue reactivity only triggers the re-render, the atoms stay the source of truth.
+- The react gallery's `nav?: ReactNode` prop is a named `nav` **slot** on `Shell.vue`; router demos simply leave it empty.
+- `defineRegistry` from [`@xmachines/play-vue`](../../../api/@xmachines/play-vue/README.md) wraps each SFC with `h()`, so every kit component can use composables such as `useBoundProp` inside `<script setup>`.
+
+## Available Scripts
+
+| Command                                                           | Description                                    |
+| ----------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-gallery-demo run dev`          | Start Vite dev server (http://localhost:3024/) |
+| `pnpm --filter @xmachines/play-vue-gallery-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-gallery-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-gallery-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-gallery-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-gallery-demo run test
+pnpm --filter @xmachines/play-vue-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-vue](../../../api/@xmachines/play-vue/README.md)
+- [Vue Router demo](../play-vue-router-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
+
+- [App](variables/App.md)
+- [authCatalog](variables/authCatalog.md)
+- [demoComponents](variables/demoComponents.md)
+- [donutCatalog](variables/donutCatalog.md)
+- [fetchCatalog](variables/fetchCatalog.md)
+- [flightCatalog](variables/flightCatalog.md)
+- [galleryMachines](variables/galleryMachines.md)
+- [stopwatchCatalog](variables/stopwatchCatalog.md)
+- [temperatureCatalog](variables/temperatureCatalog.md)
+- [ticTacToeCatalog](variables/ticTacToeCatalog.md)
+- [todoMvcCatalog](variables/todoMvcCatalog.md)
+- [triviaCatalog](variables/triviaCatalog.md)

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

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

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

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

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

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

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

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

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/FetchCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / FetchCatalog
+
+# Type Alias: FetchCatalog
+
+```ts
+type FetchCatalog = typeof fetchCatalog;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/catalogs.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/catalogs.ts#L24)

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/FlightCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / FlightCatalog
+
+# Type Alias: FlightCatalog
+
+```ts
+type FlightCatalog = typeof flightCatalog;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/catalogs.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/catalogs.ts#L45)

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/GalleryActor.md

@@ -0,0 +1,20 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / GalleryActor
+
+# Type Alias: GalleryActor
+
+```ts
+type GalleryActor =
+	| FetchActor
+	| StopwatchActor
+	| TicTacToeActor
+	| TemperatureActor
+	| TodoMvcActor
+	| TriviaActor
+	| DonutActor
+	| FlightActor
+	| AuthActor;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/machines.ts:59](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/machines.ts#L59)
+
+Any of the nine machine actors — what the gallery Shell and DebugPanel accept.

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/GallerySlug.md

@@ -0,0 +1,18 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / GallerySlug
+
+# Type Alias: GallerySlug
+
+```ts
+type GallerySlug =
+	| "fetch"
+	| "stopwatch"
+	| "tictactoe"
+	| "temperature"
+	| "todomvc"
+	| "trivia"
+	| "donut"
+	| "flight"
+	| "auth";
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/machines.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/machines.ts#L70)

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/KitCatalog.md

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / KitCatalog
+
+# Type Alias: KitCatalog
+
+```ts
+type KitCatalog = FetchCatalog;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/catalogs.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/catalogs.ts#L58)
+
+The catalog the shared component KIT is typed against.
+
+ComponentContext only constrains a component through the catalog's component
+schemas, and those are identical across all nine catalogs — so the kit is
+typed once against this representative and registers cleanly with every
+machine's defineRegistry call.

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/StopwatchCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / StopwatchCatalog
+
+# Type Alias: StopwatchCatalog
+
+```ts
+type StopwatchCatalog = typeof stopwatchCatalog;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/catalogs.ts:27](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/catalogs.ts#L27)

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/TemperatureCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / TemperatureCatalog
+
+# Type Alias: TemperatureCatalog
+
+```ts
+type TemperatureCatalog = typeof temperatureCatalog;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/catalogs.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/catalogs.ts#L33)

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/TicTacToeCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / TicTacToeCatalog
+
+# Type Alias: TicTacToeCatalog
+
+```ts
+type TicTacToeCatalog = typeof ticTacToeCatalog;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/catalogs.ts:30](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/catalogs.ts#L30)

package/examples/@xmachines/play-vue-gallery-demo/type-aliases/TodoMvcCatalog.md

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / TodoMvcCatalog
+
+# Type Alias: TodoMvcCatalog
+
+```ts
+type TodoMvcCatalog = typeof todoMvcCatalog;
+```
+
+Defined in: [packages/play-vue/examples/gallery/src/catalogs.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-vue/examples/gallery/src/catalogs.ts#L36)