@xmachines/docs 7.0.0 → 7.1.0

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-flight-demo
+
+# @xmachines/play-vue-router-flight-demo
+
+Vue 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 Vue Router — the wizard steps map to `/`, `/dates`, `/review`, `/submitting`, and `/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-vue-gallery-demo`](../play-vue-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-vue-router-flight-demo run dev
+```
+
+Then open `http://localhost:3091`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` creates the Vue app, installs the router, mounts it on `#app`, and wires HMR cleanup.
+2. `src/runtime.ts` creates and starts the actor, builds the `routeMap` from the machine, and constructs the `registryResult` from the gallery's `flightCatalog` + `demoComponents`.
+3. `src/router.ts` installs a single catch-all route over `createWebHistory` — `PlayRenderer` selects the actual view from actor state.
+4. `src/App.vue` renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` render function.
+5. `renderShell` composes the gallery `Shell` with `h()`, handing it the actor, the bridged router, the registry, and the inspector.
+6. `PlayRouterProvider` waits for `router.isReady()` before connecting the bridge, so direct URL loads are handled correctly.
+7. Browser tests in `test/browser/` delegate to the shared Flight router suite.
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (router install + mount + HMR cleanup)
+- `src/runtime.ts` - actor startup, route map, and registry wiring
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and `Shell` composition
+- `test/library-pattern.test.ts` - source-level wiring assertions (`tsc` does not read `.vue`)
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Flight router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation changes the URL, `VueRouterBridge` turns that into a `play.route` event, and the actor evaluates it against its own guards.
+2. **Passive Infrastructure:** No Vue Router navigation guard carries business logic. The actor decides whether a navigation is permitted; Vue only renders the result.
+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-vue-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3091/) |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-router-flight-demo run test
+pnpm --filter @xmachines/play-vue-router-flight-demo run test:browser
+```
+
+Expected result: the source-level wiring test passes and the shared Flight router browser suite completes.
+
+## Learn More
+
+- [Vue Router adapter](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-todomvc-demo
+
+# @xmachines/play-vue-router-todomvc-demo
+
+Vue 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 Vue Router — the filter states map to `/`, `/active`, and `/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-vue-gallery-demo`](../play-vue-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-vue-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3088`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` creates the Vue app, installs the router, mounts it on `#app`, and wires HMR cleanup.
+2. `src/runtime.ts` creates and starts the actor, builds the `routeMap` from the machine, and constructs the `registryResult` from the gallery's `todoMvcCatalog` + `demoComponents`.
+3. `src/router.ts` installs a single catch-all route over `createWebHistory` — `PlayRenderer` selects the actual view from actor state.
+4. `src/App.vue` renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` render function.
+5. `renderShell` composes the gallery `Shell` with `h()`, handing it the actor, the bridged router, the registry, and the inspector.
+6. `PlayRouterProvider` waits for `router.isReady()` before connecting the bridge, so direct URL loads are handled correctly.
+7. Browser tests in `test/browser/` delegate to the shared TodoMVC router suite.
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (router install + mount + HMR cleanup)
+- `src/runtime.ts` - actor startup, route map, and registry wiring
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and `Shell` composition
+- `test/library-pattern.test.ts` - source-level wiring assertions (`tsc` does not read `.vue`)
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared TodoMVC router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation changes the URL, `VueRouterBridge` turns that into a `play.route` event, and the actor evaluates it against its own guards.
+2. **Passive Infrastructure:** No Vue Router navigation guard carries business logic. The actor decides whether a navigation is permitted; Vue only renders the result.
+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-vue-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3088/) |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-router-todomvc-demo run test
+pnpm --filter @xmachines/play-vue-router-todomvc-demo run test:browser
+```
+
+Expected result: the source-level wiring test passes and the shared TodoMVC router browser suite completes.
+
+## Learn More
+
+- [Vue Router adapter](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,76 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-trivia-demo
+
+# @xmachines/play-vue-router-trivia-demo
+
+Vue 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 Vue Router — the game states map to `/`, `/trivia`, `/win`, and `/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-vue-gallery-demo`](../play-vue-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-vue-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3089`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` creates the Vue app, installs the router, mounts it on `#app`, and wires HMR cleanup.
+2. `src/runtime.ts` creates and starts the actor, builds the `routeMap` from the machine, and constructs the `registryResult` from the gallery's `triviaCatalog` + `demoComponents`.
+3. `src/router.ts` installs a single catch-all route over `createWebHistory` — `PlayRenderer` selects the actual view from actor state.
+4. `src/App.vue` renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` render function.
+5. `renderShell` composes the gallery `Shell` with `h()`, handing it the actor, the bridged router, the registry, and the inspector.
+6. `PlayRouterProvider` waits for `router.isReady()` before connecting the bridge, so direct URL loads are handled correctly.
+7. Browser tests in `test/browser/` delegate to the shared Trivia router suite.
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (router install + mount + HMR cleanup)
+- `src/runtime.ts` - actor startup, route map, and registry wiring
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and `Shell` composition
+- `test/library-pattern.test.ts` - source-level wiring assertions (`tsc` does not read `.vue`)
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Trivia router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation changes the URL, `VueRouterBridge` turns that into a `play.route` event, and the actor evaluates it against its own guards.
+2. **Passive Infrastructure:** No Vue Router navigation guard carries business logic. The actor decides whether a navigation is permitted; Vue only renders the result.
+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-vue-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3089/) |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-router-trivia-demo run test
+pnpm --filter @xmachines/play-vue-router-trivia-demo run test:browser
+```
+
+Expected result: the source-level wiring test passes and the shared Trivia router browser suite completes.
+
+## Learn More
+
+- [Vue Router adapter](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

package/examples/README.md

@@ -19,7 +19,13 @@ Learn how state machines control navigation:
 - **[Routing Patterns](routing-patterns.md)** — `meta.route`, `play.route` events, `always` auth guards, and parameter routes
 - **[Multi-Router Integration](multi-router-integration.md)** — All 8 router adapters: provider pattern vs `connectRouter` pattern, and `basePath` for sharing a router with the host
 
-### Level 3: Full Applications
+### Level 3: Ported XState Examples
+
+Eight official XState examples, packaged as one renderer gallery per framework plus a router demo per adapter:
+
+- **[XState Example Ports](xstate-example-ports.md)** — What was ported, how it is packaged, and what the cross-framework matrix caught
+
+### Level 4: Full Applications
 
 Complete working implementations of actor-authoritative routing with all architectural invariants enforced.
 
@@ -31,11 +37,11 @@ Every demo below also wires the [Stately inspector](../guides/inspector.md): the
 
 <!-- typedoc:renderer-demos:start -->
 
-- [@xmachines/play-dom-demo](@xmachines/play-dom-demo/README.md)
-- [@xmachines/play-react-demo](@xmachines/play-react-demo/README.md)
-- [@xmachines/play-solid-demo](@xmachines/play-solid-demo/README.md)
-- [@xmachines/play-svelte-demo](@xmachines/play-svelte-demo/README.md)
-- [@xmachines/play-vue-demo](@xmachines/play-vue-demo/README.md)
+- [@xmachines/play-dom-gallery-demo](@xmachines/play-dom-gallery-demo/README.md)
+- [@xmachines/play-react-gallery-demo](@xmachines/play-react-gallery-demo/README.md)
+- [@xmachines/play-solid-gallery-demo](@xmachines/play-solid-gallery-demo/README.md)
+- [@xmachines/play-svelte-gallery-demo](@xmachines/play-svelte-gallery-demo/README.md)
+- [@xmachines/play-vue-gallery-demo](@xmachines/play-vue-gallery-demo/README.md)
 
 <!-- typedoc:renderer-demos:end -->
 
@@ -44,13 +50,45 @@ Every demo below also wires the [Stately inspector](../guides/inspector.md): the
 <!-- typedoc:router-demos:start -->
 
 - [@xmachines/play-dom-router-demo](@xmachines/play-dom-router-demo/README.md)
+- [@xmachines/play-dom-router-donut-demo](@xmachines/play-dom-router-donut-demo/README.md)
+- [@xmachines/play-dom-router-flight-demo](@xmachines/play-dom-router-flight-demo/README.md)
+- [@xmachines/play-dom-router-todomvc-demo](@xmachines/play-dom-router-todomvc-demo/README.md)
+- [@xmachines/play-dom-router-trivia-demo](@xmachines/play-dom-router-trivia-demo/README.md)
 - [@xmachines/play-react-router-demo](@xmachines/play-react-router-demo/README.md)
+- [@xmachines/play-react-router-donut-demo](@xmachines/play-react-router-donut-demo/README.md)
+- [@xmachines/play-react-router-flight-demo](@xmachines/play-react-router-flight-demo/README.md)
+- [@xmachines/play-react-router-todomvc-demo](@xmachines/play-react-router-todomvc-demo/README.md)
+- [@xmachines/play-react-router-trivia-demo](@xmachines/play-react-router-trivia-demo/README.md)
 - [@xmachines/play-solid-router-demo](@xmachines/play-solid-router-demo/README.md)
+- [@xmachines/play-solid-router-donut-demo](@xmachines/play-solid-router-donut-demo/README.md)
+- [@xmachines/play-solid-router-flight-demo](@xmachines/play-solid-router-flight-demo/README.md)
+- [@xmachines/play-solid-router-todomvc-demo](@xmachines/play-solid-router-todomvc-demo/README.md)
+- [@xmachines/play-solid-router-trivia-demo](@xmachines/play-solid-router-trivia-demo/README.md)
 - [@xmachines/play-svelte-spa-router-demo](@xmachines/play-svelte-spa-router-demo/README.md)
+- [@xmachines/play-svelte-spa-router-donut-demo](@xmachines/play-svelte-spa-router-donut-demo/README.md)
+- [@xmachines/play-svelte-spa-router-flight-demo](@xmachines/play-svelte-spa-router-flight-demo/README.md)
+- [@xmachines/play-svelte-spa-router-todomvc-demo](@xmachines/play-svelte-spa-router-todomvc-demo/README.md)
+- [@xmachines/play-svelte-spa-router-trivia-demo](@xmachines/play-svelte-spa-router-trivia-demo/README.md)
 - [@xmachines/play-sveltekit-router-demo](@xmachines/play-sveltekit-router-demo/README.md)
+- [@xmachines/play-sveltekit-router-donut-demo](@xmachines/play-sveltekit-router-donut-demo/README.md)
+- [@xmachines/play-sveltekit-router-flight-demo](@xmachines/play-sveltekit-router-flight-demo/README.md)
+- [@xmachines/play-sveltekit-router-todomvc-demo](@xmachines/play-sveltekit-router-todomvc-demo/README.md)
+- [@xmachines/play-sveltekit-router-trivia-demo](@xmachines/play-sveltekit-router-trivia-demo/README.md)
 - [@xmachines/play-tanstack-react-router-demo](@xmachines/play-tanstack-react-router-demo/README.md)
+- [@xmachines/play-tanstack-react-router-donut-demo](@xmachines/play-tanstack-react-router-donut-demo/README.md)
+- [@xmachines/play-tanstack-react-router-flight-demo](@xmachines/play-tanstack-react-router-flight-demo/README.md)
+- [@xmachines/play-tanstack-react-router-todomvc-demo](@xmachines/play-tanstack-react-router-todomvc-demo/README.md)
+- [@xmachines/play-tanstack-react-router-trivia-demo](@xmachines/play-tanstack-react-router-trivia-demo/README.md)
 - [@xmachines/play-tanstack-solid-router-demo](@xmachines/play-tanstack-solid-router-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-donut-demo](@xmachines/play-tanstack-solid-router-donut-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-flight-demo](@xmachines/play-tanstack-solid-router-flight-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-todomvc-demo](@xmachines/play-tanstack-solid-router-todomvc-demo/README.md)
+- [@xmachines/play-tanstack-solid-router-trivia-demo](@xmachines/play-tanstack-solid-router-trivia-demo/README.md)
 - [@xmachines/play-vue-router-demo](@xmachines/play-vue-router-demo/README.md)
+- [@xmachines/play-vue-router-donut-demo](@xmachines/play-vue-router-donut-demo/README.md)
+- [@xmachines/play-vue-router-flight-demo](@xmachines/play-vue-router-flight-demo/README.md)
+- [@xmachines/play-vue-router-todomvc-demo](@xmachines/play-vue-router-todomvc-demo/README.md)
+- [@xmachines/play-vue-router-trivia-demo](@xmachines/play-vue-router-trivia-demo/README.md)
 
 <!-- typedoc:router-demos:end -->
 

package/examples/routing-patterns.md

@@ -79,7 +79,9 @@ const authSetup = setup({
 	types: {
 		context: {} as AuthContext,
 		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
+			| PlayRouteEvent
+			| { type: "auth.login"; username: string }
+			| { type: "auth.logout" },
 		input: {} as Partial<AuthContext> | undefined,
 	},
 });

package/examples/xstate-example-ports.md

@@ -0,0 +1,106 @@
+[Examples](README.md) / XState Example Ports
+
+# XState Example Ports
+
+The official XState examples ported into XMachines Play demos, and how they are packaged. Every pick exists on the `statelyai/xstate` `next` branch already migrated to XState v6 syntax, so each pick is verified to survive v6. The ports themselves are implemented against the repository's current XState v5 adapter; moving them to v6 later is the same mechanical migration upstream already performed (transition functions returning `{ target, context }`, `createAsyncLogic` / `createCallbackLogic` instead of `fromPromise` / `fromCallback`).
+
+Source catalog: [`statelyai/xstate` `examples/`](https://github.com/statelyai/xstate/tree/next/examples) (`next` branch).
+
+## How The Ports Are Packaged
+
+The eight machines live in [`@xmachines/play-actor-shared`](../../play-actor/examples/shared/README.md), one directory each, with a catalog, action handlers, behavioral tests, view-spec invariant tests, and a reusable browser suite. Every machine declares its views against one five-component vocabulary — `Page`, `Panel`, `Field`, `Button`, `Text` — defined once in `src/components-schema.ts`.
+
+That vocabulary is what makes the packaging cheap:
+
+- **One renderer gallery per framework** (`packages/play-<framework>/examples/gallery`) hosts all eight machines behind a picker. Choosing a machine stops the previous actor and starts a fresh one, so the inspector always shows a single live machine. Each framework implements the five components exactly once, and every machine's views render through them unmodified.
+- **One router demo per adapter and routable machine** (`packages/play-<router>/examples/<machine>`), 32 in total. Each imports its framework's gallery for the catalog, the component kit, and the shell, so the demo itself contains only the router wiring.
+
+The shared browser suites are framework-agnostic: they interact through the DOM contract (`data-page`, `data-demo-id`, `data-demo-shell`) and nothing else, so the same suite drives all five frameworks. That they pass unmodified everywhere is the evidence the machines carry no framework assumptions.
+
+## Selection Criteria
+
+An example qualifies when it:
+
+1. **Survives v6** — present and migrated on the `next` branch, no APIs removed in v6.
+2. **Demonstrates an invariant** — shows Actor Authority, Passive Infrastructure, State-Driven Reset, or Atom-Only Reactivity in a way the shared auth demo does not.
+3. **Maps onto the Play surface** — states become `meta.route` / `meta.view` declarations; UI becomes a JSON-Render catalog; framework code stays out of the machine.
+
+## Common Requirements
+
+Every ported example, routing or not:
+
+- **Wires the Stately inspector.** The actor is created with `options.inspect` from the shared demo controller (`createDemoInspector()`, `packages/play-actor/examples/shared/src/inspector.ts`), and the debug panel exposes the **Show Inspector** button — identical to the existing demos. The shared controller also carries the `@statelyai/inspect` 0.7 → v6 event translation described in the [inspector guide](../guides/inspector.md), so ports get animated transitions for free.
+- Uses the same `setup()` style as the shared auth machine and avoids every API the v6 migration removes, so the later v6 move stays mechanical.
+- Keeps business logic framework-free: views are JSON-Render specs selected via `meta.view`, events are the only input.
+- Ships the standard invariant tests plus browser renderer coverage, mirroring the existing demo test layout.
+
+## Ports With Routing
+
+### 1. TodoMVC — `todomvc-react`
+
+The upstream example already routes its all/active/completed filters, but imperatively through a `useHashChange` hook. The port deletes that hook and makes the filter states routable (`/`, `/active`, `/completed`) via `meta.route` + `formatPlayRouteTransitions` — a direct before/after argument for actor-authoritative routing. The todo list exercises JSON-Render `repeat` / `$item` and per-row actions.
+
+- Demonstrates: INV-01, INV-04 — the router observes, the machine owns the filter.
+- Inspector: high event volume (per-keystroke edits) makes the live machine view genuinely useful.
+
+### 2. Trivia Game — `trivia-game-example`
+
+Home → Trivia → win/lose pages with lives, points, and clues in context. Upstream deliberately keeps navigation out of the machine via `machine.provide(...)`; the port replaces that seam with `meta.route` and guards. Navigating to `/trivia` mid-game or after losing is overwritten by actor-derived state — the clearest INV-05 (State-Driven Reset) showcase in the set.
+
+- Demonstrates: INV-01, INV-05 — guards decide route validity; invalid URLs bounce.
+- Inspector: guard rejections are visible as unhandled `play.route` events.
+
+### 3. Persisted Donut Maker — `persisted-donut-maker`
+
+Multi-step recipe machine, one route per step, combined with `getPersistedSnapshot()` and the factory resume options. Refreshing the browser mid-flow restores machine state and URL together — persistence plus actor-authoritative deep links, which no current demo covers.
+
+- Demonstrates: snapshot persistence, `PlayerFactoryResumeOptions`, deep-link resume.
+- Inspector: attach-after-restore exercises the "turning the inspector on later" flow from the guide.
+
+### 4. Flight Booker — `7guis-flight-booker-react`
+
+Upstream is a single screen; the port stretches it into a wizard (trip type → dates → submitting → booked) with a route per step and query params for the selection. The same date guards that block invalid submissions block `play.route` jumps to `/booked`.
+
+- Demonstrates: wizard routing, param/query routes, guard-gated forward navigation.
+
+## Ports Without Routing
+
+### 5. Fetch — `fetch`
+
+idle/loading/success/failure around an invoked promise actor (`fromPromise`; `createAsyncLogic` in v6). Each state maps to a `meta.view` spec — view selection driven purely by machine state, zero component-level loading logic.
+
+### 6. Stopwatch — `stopwatch`
+
+Callback actor (`fromCallback`; `createCallbackLogic` in v6) ticking every 10 ms while in `running`; cleanup rides on state exit. Stress-tests atom propagation through passive renderers at high frequency.
+
+### 7. Tic-Tac-Toe — `tic-tac-toe-react`
+
+Turn-taking guards and win detection with the whole board in context. The board renders as a JSON-Render `repeat` grid; every move is an inspectable event.
+
+### 8. Temperature Converter — `7guis-temperature-react` / `7guis-2-temperature-vue`
+
+Bidirectional field binding via `$bindState`; complements the [form validation example](form-validation.md) on a tiny, well-known benchmark.
+
+## Stretch Candidates
+
+- **Friends List — `friends-list-react`.** Parent machine spawning a child actor per friend (`spawn` / `stopChild`, refs in context). Exercises the adapter's child-actor behaviour and the [actor model guide](../guides/actor-model.md); scheduled after the core eight because it may surface adapter work.
+- **Express Workflow — `express-workflow`.** Headless: restore snapshot per request, send event, re-persist. A server-side `definePlayer` demo pairing with the WebSocket inspector transport from the guide.
+
+## Not Ported
+
+| Example                             | Reason                                                                      |
+| ----------------------------------- | --------------------------------------------------------------------------- |
+| `store-*` (3 examples)              | `@xstate/store`, not state machines — outside the Play adapter surface      |
+| `snake-react`, `tiles`              | Game-loop and renderer-heavy; little architectural signal                   |
+| `mongodb-*` (2 examples)            | Infrastructure-heavy; persistence is covered by the donut maker             |
+| `workflow-*` (25 examples)          | Headless single-file Serverless Workflow ports; no UI or navigation to show |
+| `counter`, `toggle`, 7GUIs counters | Already covered by [basic state machine](basic-state-machine.md) and guides |
+
+## What The Matrix Caught
+
+Running one machine set across five renderers and eight routers found two defects that a single-framework demo could not:
+
+- **Vue Router lost its history bookkeeping.** The shared suites simulated a manual URL entry with `history.pushState({}, …)`, which nulls `history.state` — where Vue Router keeps its `{ back, current, forward, position }` record. The actor bounced correctly every time, but the router could no longer write the corrected URL back. The suites now carry the existing `history.state` across the synthetic jump, which is also what a real navigation does.
+- **The TanStack bridge dropped a corrective navigation under `<RouterProvider>`.** The provider installs a `Transitioner` that defers `router.latestLocation`, so `commitLocation` saw the pre-change href, decided the URL was unchanged, and skipped the history write. The bridge then synchronized the actor before `router.load()` settled, so the correction landed inside that stale window. [`watchRouterChanges`](../../play-tanstack-router/src/tanstack-router-bridge-base.ts) now waits for the `router.load()` of each event before it synchronizes the actor. Both TanStack demo families still mount a bare navigation-service router, because the actor and not the route tree decides the view.
+
+Neither surfaced while only path-based routers were under test, and the pre-existing auth demo suites had no invalid-URL case at all.

package/guides/getting-started.md

@@ -329,7 +329,9 @@ const appSetup = setup({
 			query: Record<string, string>;
 		},
 		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
+			| PlayRouteEvent
+			| { type: "auth.login"; username: string }
+			| { type: "auth.logout" },
 	},
 });
 

package/guides/inspector.md

@@ -172,13 +172,13 @@ Both transports consume the identical `options.inspect` observer, so switching b
 
 ## Trying it in the demos
 
-Every demo in this repository — all five renderer demos and all eight router demos — wires the inspector the same way, so any of them can be used to see the flow end to end:
+Every demo in this repository — the five renderer galleries and every router demo — wires the inspector the same way, so any of them can be used to see the flow end to end:
 
 ```bash
-pnpm --filter @xmachines/play-react-demo run dev
+pnpm --filter @xmachines/play-react-gallery-demo run dev
 ```
 
-Click **Show Inspector** in the debug panel at the bottom of the page. The inspector opens in its own window with the machine already drawn and the session's history replayed, and it keeps updating as you log in, navigate, and log out.
+Click **Show Inspector** in the debug panel at the bottom of the page. The inspector opens in its own window with the machine already drawn and the session's history replayed, and it keeps updating as you use the machine that you opened in the gallery.
 
 The demos share one controller, `createDemoInspector()`, which each demo passes straight through to `definePlayer`. The controller lives in a private package of this repository, so you cannot install it. The block below shows the same wiring with the public API. It keeps each event from the creation of the actor, and it replays the events when the user opens the inspector:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -56,13 +56,13 @@
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^7.0.1",
-    "@types/node": "^26.6.4",
-    "oxfmt": "^0.71.0",
-    "oxlint": "^1.86.0",
+    "@types/node": "^26.6.6",
+    "oxfmt": "^0.75.0",
+    "oxlint": "^1.90.0",
     "typedoc": "^0.28.20",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.13.1",
-    "vitest": "^5.0.3"
+    "typedoc-plugin-markdown": "^4.14.1",
+    "vitest": "^5.0.5"
   },
   "engines": {
     "node": ">=24.0.0"