@xmachines/docs 7.0.0 → 7.2.0

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

@@ -0,0 +1,86 @@
+[Examples](../../README.md) / @xmachines/play-sveltekit-router-todomvc-demo
+
+# @xmachines/play-sveltekit-router-todomvc-demo
+
+Svelte 5 + SvelteKit router integration demo of the shared **TodoMVC** machine for the XMachines Play architecture, using browser pathname URL routing.
+
+[![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
+- `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md) — the filter states map to `/`, `/active`, and `/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Atom lifecycle integrated with Svelte 5 runes
+- 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-sveltekit-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3076`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor, builds the registry from `todoMvcCatalog` + `demoComponents`, calls `createRouteMap(todoMvcMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates SvelteKit `afterNavigate` notifications into `play.route` events and reflects actor-approved routes back through `goto`.
+4. `src/App.svelte` imports the singleton `actor`, `registryResult`, and `inspector` from `src/runtime.ts` and delegates to the gallery's `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the `DebugPanel` with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared todomvc router browser suite.
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<Shell {actor} {registryResult} {inspector} />
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
+- `src/App.svelte` - minimal root component delegating to the shared gallery `Shell.svelte`
+- `src/lib/navigation.ts` - History API shim implementing SvelteKit's `$app/navigation` contract for Vite dev and production builds
+- `src/app-navigation.d.ts` - TypeScript ambient declaration for the `$app/navigation` module
+- `test/library-pattern.test.ts` - architecture boundary and route-map invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared todomvc router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A URL change becomes a `play.route` event. The actor evaluates it against its own guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** The SvelteKit router adapter executes no business logic — it only translates and reflects.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state; the URL always reflects the machine.
+
+## Adapter Boundaries
+
+`connectRouter` (from [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)) is passive infrastructure. The `$app/navigation` module is shimmed by `src/lib/navigation.ts` using the History API, so the demo runs outside a full SvelteKit project (plain Vite dev server and production build).
+
+## Available Scripts
+
+| Command                                                                        | Description                                    |
+| ------------------------------------------------------------------------------ | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-sveltekit-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3076/) |
+| `pnpm --filter @xmachines/play-sveltekit-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-sveltekit-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-sveltekit-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-sveltekit-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-sveltekit-router-todomvc-demo run test
+pnpm --filter @xmachines/play-sveltekit-router-todomvc-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared todomvc router browser suite completes.
+
+## Learn More
+
+- [SvelteKit Router adapter](../../../api/@xmachines/play-sveltekit-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,86 @@
+[Examples](../../README.md) / @xmachines/play-sveltekit-router-trivia-demo
+
+# @xmachines/play-sveltekit-router-trivia-demo
+
+Svelte 5 + SvelteKit router integration demo of the shared **trivia** machine for the XMachines Play architecture, using browser pathname URL routing.
+
+[![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
+- `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md) — the quiz states map to `/`, `/trivia`, `/win`, and `/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-svelte-gallery-demo`](../play-svelte-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link to a status the actor has not earned (`/trivia` while idle) is bounced home and the URL is rewritten (State-Driven Reset)
+- Atom lifecycle integrated with Svelte 5 runes
+- 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-sveltekit-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3077`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
+2. `src/runtime.ts` creates the actor, builds the registry from `triviaCatalog` + `demoComponents`, calls `createRouteMap(triviaMachine)`, and wires `connectRouter({ actor, routeMap })`.
+3. `connectRouter` translates SvelteKit `afterNavigate` notifications into `play.route` events and reflects actor-approved routes back through `goto`.
+4. `src/App.svelte` imports the singleton `actor`, `registryResult`, and `inspector` from `src/runtime.ts` and delegates to the gallery's `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` plus the `DebugPanel` with the **Show Inspector** button.
+6. Browser tests in `test/browser/` delegate to the shared trivia router browser suite.
+
+```svelte
+<!-- src/App.svelte (shape) -->
+<Shell {actor} {registryResult} {inspector} />
+```
+
+## Key Files
+
+- `src/main.ts` - Svelte app mount and HMR cleanup registration
+- `src/runtime.ts` - actor creation, registry construction, route map, and `connectRouter` wiring
+- `src/App.svelte` - minimal root component delegating to the shared gallery `Shell.svelte`
+- `src/lib/navigation.ts` - History API shim implementing SvelteKit's `$app/navigation` contract for Vite dev and production builds
+- `src/app-navigation.d.ts` - TypeScript ambient declaration for the `$app/navigation` module
+- `test/library-pattern.test.ts` - architecture boundary and route-map invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared trivia router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** A URL change becomes a `play.route` event. The actor evaluates it against its own guards and decides whether the navigation happens.
+2. **Passive Infrastructure:** The SvelteKit router adapter executes no business logic — it only translates and reflects.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state; the URL always reflects the machine.
+
+## Adapter Boundaries
+
+`connectRouter` (from [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)) is passive infrastructure. The `$app/navigation` module is shimmed by `src/lib/navigation.ts` using the History API, so the demo runs outside a full SvelteKit project (plain Vite dev server and production build).
+
+## Available Scripts
+
+| Command                                                                       | Description                                    |
+| ----------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-sveltekit-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3077/) |
+| `pnpm --filter @xmachines/play-sveltekit-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-sveltekit-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-sveltekit-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-sveltekit-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-sveltekit-router-trivia-demo run test
+pnpm --filter @xmachines/play-sveltekit-router-trivia-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass and the shared trivia router browser suite completes.
+
+## Learn More
+
+- [SvelteKit Router adapter](../../../api/@xmachines/play-sveltekit-router/README.md)
+- [Svelte renderer gallery](../play-svelte-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -8,7 +8,7 @@ React + TanStack Router integration demo for the XMachines Play architecture wit
 
 ## What This Demonstrates
 
-- Shared auth machine reused without framework-specific business logic
+- The shared auth machine (the login wall) reused without framework-specific business logic
 - `PlayRouterProvider` renderer-based integration with TanStack Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
 - Non-browser invariant tests plus browser E2E coverage
@@ -33,12 +33,12 @@ Use this order to understand the implementation:
 2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor from the shared machine and start it once per mounted app.
 3. `src/runtime.ts` exports `inspector` (via `createDemoInspector()`), `createPlayer` (via `definePlayer`, with `options.inspect` wired to the inspector), `routeMap` (via `createRouteMap(authMachine)`), and `createRegistryResult` which binds UI components and actor event actions.
 4. `createAppRuntime()` constructs a TanStack `createRootRoute`/`createRouter` instance, then `PlayRouterProvider` bridges it to the actor and renders `Shell` via `renderer(actor, router)`.
-5. `Shell` is the shared demo layout component imported from [`@xmachines/play-react-demo`](../play-react-demo/README.md) (defined in `packages/play-react/examples/demo/src/components/Shell.tsx`, a workspace-only package). It renders `PlayUIProvider` + `PlayRenderer`, header/nav, and the debug panel — including the **Show Inspector** button — from actor state.
+5. `Shell` is the shared demo layout component imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md) (defined in `packages/play-react/examples/gallery/src/components/Shell.tsx`, a workspace-only package). It renders `PlayUIProvider` + `PlayRenderer`, header/nav, and the debug panel — including the **Show Inspector** button — from actor state. The views it renders come from the gallery's five-component kit (Page, Panel, Field, Button, Text).
 6. Tests in `test/` and `test/browser/` validate invariant and runtime behavior.
 
 ```tsx fragment
 // src/App.tsx (shape)
-import { Shell } from "@xmachines/play-react-demo"; // shared demo shell (workspace-only package)
+import { Shell } from "@xmachines/play-react-gallery-demo"; // shared demo shell (workspace-only package)
 import { createPlayer, inspector, routeMap, createRegistryResult } from "./runtime.js";
 
 function createAppRuntime() {
@@ -99,18 +99,12 @@ export function createRegistryResult(actor: ReturnType<typeof createPlayer>) {
 - `test/passive-infra.test.ts` - passive infrastructure separation contracts
 - `test/strict-separation.test.ts` - machine/view infrastructure separation contracts
 - `test/atom-only.test.ts` - atom-only reactivity invariant
-- `test/route-parameters.test.ts` - route parameter handling
 - `test/invalid-route-redirect.test.ts` - invalid route redirect behavior
-- `test/xstate-route-events.test.ts` - XState route event contracts
-- `test/browser/shared-demo.browser.test.tsx` - canonical browser auth flow
-- `test/browser/auth-flow.browser.test.tsx` - extended browser auth flow checks
-- `test/browser/back-forward-sync.browser.test.tsx` - URL sync and history behavior
-- `test/browser/dashboard-logout.browser.test.tsx` - logout and redirection flow
-- `test/browser/guard-rejection.browser.test.tsx` - guard-driven rejection in browser
-- `test/browser/login-flow.browser.test.tsx` - login flow browser coverage
-- `test/browser/navigation.browser.test.tsx` - navigation behavior in browser
-- `test/browser/settings-parameter.browser.test.tsx` - parameterized route in browser
-- `test/browser/invalid-route-redirect.browser.test.tsx` - invalid route redirect in browser
+- `test/browser-back-view-rendering.test.ts` - `currentView` atom propagation on navigation
+- `test/xstate-route-events.test.ts` - XState route event contracts against a mock router
+- `test/uat-xstate-route-regression.test.ts` - cold-load, back/forward, and login-wall bridge regressions
+- `test/browser/shared-demo.browser.test.tsx` - delegates to the shared `defineAuthRouterDemoBrowserSuite`
+- `test/browser/back-forward-sync.browser.test.tsx` - history back/forward URL + view sync
 - `test/browser/tanstack-integration.browser.test.tsx` - TanStack Router integration checks
 
 ## State Machine & Architecture Details
@@ -147,6 +141,17 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-tanstack-react-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-tanstack-react-router-demo run test:browser` | Run browser-focused Vitest suite               |
 
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router-demo run test
+pnpm --filter @xmachines/play-tanstack-react-router-demo run test:browser
+```
+
+Expected result: the invariant test suite and the browser suites both pass, confirming actor authority, route sync, history back/forward, and the login wall's guard-driven redirection.
+
 ## Learn More
 
 - [TanStack React Router](../../../api/@xmachines/play-tanstack-react-router/README.md)

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

@@ -0,0 +1,78 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-react-router-donut-demo
+
+# @xmachines/play-tanstack-react-router-donut-demo
+
+TanStack Router (React) 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 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-react-gallery-demo`](../play-react-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: `options.onTransition` saves `actor.getPersistedSnapshot()` to `localStorage`, and the stored snapshot is passed back through the factory's resume options (`createPlayer(undefined, { snapshot })`) so a reload continues the wizard
+- A **Reset saved donut** button (`data-demo-id="reset-snapshot"`) clears the stored snapshot and reloads
+- 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-react-router-donut-demo run dev
+```
+
+Then open `http://localhost:3082`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and the TanStack Router instance, starting the actor once per mounted app.
+3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(donutMachine)`) and exports `createPlayer`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
+4. `createAppRuntime()` builds a `registryResult` from `donutCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)) and a router over a bare `createRootRoute()` tree.
+5. `PlayRouterProvider` creates the `TanStackReactRouterBridge`, connects it on mount, and disconnects it on unmount — actor state drives `router.navigate`, and every router history change becomes a `play.route` event.
+6. The provider's `renderer(actor, router)` callback renders `Shell` directly. TanStack's own `RouterProvider` is not used: the actor, not the route tree, decides which view is current.
+7. Browser tests in `test/browser/` delegate to the shared Donut router suite.
+8. `resetSavedDonut()` (header button) clears the stored snapshot and reloads the page.
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult` registry wiring
+- `src/runtime.ts` also owns persistence: `onTransition` → `saveDonutSnapshot`, `createResumedPlayer()` → `loadDonutSnapshot`
+- `src/App.tsx` - actor lifecycle, TanStack Router creation, and provider wiring
+- `test/browser/shared-demo.browser.test.tsx` - delegates to the shared Donut router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation triggers URL changes, which the bridge intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** TanStack Router runs no loaders or `beforeLoad` guards for business logic — it only reports and applies history changes.
+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-react-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3082/) |
+| `pnpm --filter @xmachines/play-tanstack-react-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-react-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-react-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-react-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router-donut-demo run test
+pnpm --filter @xmachines/play-tanstack-react-router-donut-demo run test:browser
+```
+
+Expected result: the shared Donut router browser suite completes (the node suite passes with no tests).
+
+## Learn More
+
+- [TanStack React Router adapter](../../../api/@xmachines/play-tanstack-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,74 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-react-router-flight-demo
+
+# @xmachines/play-tanstack-react-router-flight-demo
+
+TanStack Router (React) 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 Router — the booking steps map to `/`, `/dates`, `/review`, `/submitting`, and `/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-react-gallery-demo`](../play-react-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-react-router-flight-demo run dev
+```
+
+Then open `http://localhost:3083`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and the TanStack Router instance, starting the actor once per mounted app.
+3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(flightMachine)`) and exports `createPlayer`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
+4. `createAppRuntime()` builds a `registryResult` from `flightCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)) and a router over a bare `createRootRoute()` tree.
+5. `PlayRouterProvider` creates the `TanStackReactRouterBridge`, connects it on mount, and disconnects it on unmount — actor state drives `router.navigate`, and every router history change becomes a `play.route` event.
+6. The provider's `renderer(actor, router)` callback renders `Shell` directly. TanStack's own `RouterProvider` is not used: the actor, not the route tree, decides which view is current.
+7. Browser tests in `test/browser/` delegate to the shared Flight router suite.
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult` registry wiring
+- `src/App.tsx` - actor lifecycle, TanStack Router creation, and provider wiring
+- `test/browser/shared-demo.browser.test.tsx` - delegates to the shared Flight router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation triggers URL changes, which the bridge intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** TanStack Router runs no loaders or `beforeLoad` guards for business logic — it only reports and applies history changes.
+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-react-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3083/) |
+| `pnpm --filter @xmachines/play-tanstack-react-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-react-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-react-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-react-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router-flight-demo run test
+pnpm --filter @xmachines/play-tanstack-react-router-flight-demo run test:browser
+```
+
+Expected result: the shared Flight router browser suite completes (the node suite passes with no tests).
+
+## Learn More
+
+- [TanStack React Router adapter](../../../api/@xmachines/play-tanstack-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,74 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-react-router-todomvc-demo
+
+# @xmachines/play-tanstack-react-router-todomvc-demo
+
+TanStack Router (React) 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 Router — the filter states map to `/`, `/active`, and `/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-react-gallery-demo`](../play-react-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-react-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3080`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and the TanStack Router instance, starting the actor once per mounted app.
+3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(todoMvcMachine)`) and exports `createPlayer`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
+4. `createAppRuntime()` builds a `registryResult` from `todoMvcCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)) and a router over a bare `createRootRoute()` tree.
+5. `PlayRouterProvider` creates the `TanStackReactRouterBridge`, connects it on mount, and disconnects it on unmount — actor state drives `router.navigate`, and every router history change becomes a `play.route` event.
+6. The provider's `renderer(actor, router)` callback renders `Shell` directly. TanStack's own `RouterProvider` is not used: the actor, not the route tree, decides which view is current.
+7. Browser tests in `test/browser/` delegate to the shared TodoMVC router suite.
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult` registry wiring
+- `src/App.tsx` - actor lifecycle, TanStack Router creation, and provider wiring
+- `test/browser/shared-demo.browser.test.tsx` - delegates to the shared TodoMVC router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation triggers URL changes, which the bridge intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** TanStack Router runs no loaders or `beforeLoad` guards for business logic — it only reports and applies history changes.
+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-react-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3080/) |
+| `pnpm --filter @xmachines/play-tanstack-react-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-react-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-react-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-react-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router-todomvc-demo run test
+pnpm --filter @xmachines/play-tanstack-react-router-todomvc-demo run test:browser
+```
+
+Expected result: the shared TodoMVC router browser suite completes (the node suite passes with no tests).
+
+## Learn More
+
+- [TanStack React Router adapter](../../../api/@xmachines/play-tanstack-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,74 @@
+[Examples](../../README.md) / @xmachines/play-tanstack-react-router-trivia-demo
+
+# @xmachines/play-tanstack-react-router-trivia-demo
+
+TanStack Router (React) 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 Router — the game states map to `/`, `/trivia`, `/win`, and `/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-react-gallery-demo`](../play-react-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-react-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3081`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and the TanStack Router instance, starting the actor once per mounted app.
+3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(triviaMachine)`) and exports `createPlayer`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
+4. `createAppRuntime()` builds a `registryResult` from `triviaCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)) and a router over a bare `createRootRoute()` tree.
+5. `PlayRouterProvider` creates the `TanStackReactRouterBridge`, connects it on mount, and disconnects it on unmount — actor state drives `router.navigate`, and every router history change becomes a `play.route` event.
+6. The provider's `renderer(actor, router)` callback renders `Shell` directly. TanStack's own `RouterProvider` is not used: the actor, not the route tree, decides which view is current.
+7. Browser tests in `test/browser/` delegate to the shared Trivia router suite.
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult` registry wiring
+- `src/App.tsx` - actor lifecycle, TanStack Router creation, and provider wiring
+- `test/browser/shared-demo.browser.test.tsx` - delegates to the shared Trivia router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation triggers URL changes, which the bridge intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** TanStack Router runs no loaders or `beforeLoad` guards for business logic — it only reports and applies history changes.
+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-react-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3081/) |
+| `pnpm --filter @xmachines/play-tanstack-react-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-tanstack-react-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-tanstack-react-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-tanstack-react-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-tanstack-react-router-trivia-demo run test
+pnpm --filter @xmachines/play-tanstack-react-router-trivia-demo run test:browser
+```
+
+Expected result: the shared Trivia router browser suite completes (the node suite passes with no tests).
+
+## Learn More
+
+- [TanStack React Router adapter](../../../api/@xmachines/play-tanstack-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -8,9 +8,10 @@ Solid + `@tanstack/solid-router` integration demo for the XMachines Play archite
 
 ## What This Demonstrates
 
-- Shared auth machine reused without framework-specific business logic
+- Shared auth machine (the login wall: `/`, `/login`, `/dashboard`) reused without framework-specific business logic
 - `PlayRouterProvider` renderer-based integration with TanStack Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md) renderer gallery
 - Object-based routing and deep location observation using TanStack's Solid primitives
 - 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
@@ -31,10 +32,10 @@ Then open `http://localhost:3012`.
 Use this order to understand the implementation:
 
 1. `src/main.tsx` bootstraps the demo app and mounts `<App />` onto `#app`.
-2. `src/runtime.ts` initializes the actor, builds the registry, and creates the route map using `createRouteMap(authMachine)`.
-3. `src/App.tsx` constructs the TanStack Router route tree from machine routes and wires `PlayRouterProvider` with the actor, router, and route map from `runtime.ts`.
+2. `src/runtime.ts` initializes the actor, builds the registry from `authCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and creates the route map using `createRouteMap(authMachine)`.
+3. `src/App.tsx` creates the router from a bare `createRootRoute()` and wires `PlayRouterProvider` with the actor, router, and route map from `runtime.ts` — TanStack is a navigation service here, not a renderer, so no `<RouterProvider>` is mounted (see the note below).
 4. Router infrastructure stays passive: it forwards navigation intent to the actor via the `PlayRouterProvider` and reflects actor-approved route changes back to TanStack.
-5. `Shell` (from [`@xmachines/play-solid-demo`](../play-solid-demo/README.md)) renders actor-projected state (`PlayRenderer`), emits actor events via the `registryResult` actions, and shows the debug panel's **Show Inspector** button.
+5. `Shell` (from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)) renders actor-projected state (`PlayRenderer`), emits actor events via the `registryResult` actions, and shows the debug panel's **Show Inspector** button.
 6. `test/library-pattern.test.ts` plus `test/browser/` verify invariants and browser routing behavior.
 
 ```tsx fragment
@@ -59,16 +60,15 @@ export const registryResult = defineRegistry(authCatalog, {
 });
 
 export const routeMap = createRouteMap(authMachine);
-const routeTree = extractMachineRoutes(authMachine);
-export const routes = getRoutableRoutes(routeTree);
 ```
 
 ```tsx fragment
 // src/App.tsx (shape)
-import { Shell } from "@xmachines/play-solid-demo"; // shared demo shell (workspace-only package)
-import { actor, inspector, registryResult, routeMap, routes } from "./runtime.js";
+import { Shell } from "@xmachines/play-solid-gallery-demo"; // shared demo shell (workspace-only package)
+import { actor, inspector, registryResult, routeMap } from "./runtime.js";
+
+const router = createRouter({ routeTree: createRootRoute() });
 
-// router: the TanStack router built below in src/App.tsx from `routes`
 return (
 	<PlayRouterProvider
 		actor={actor}
@@ -86,13 +86,18 @@ return (
 );
 ```
 
+```ts fragment
+// src/runtime.ts — actor events wired via the shared handler factory
+actions: createAuthActionHandlers(actor), // login / logout / route
+```
+
 ## Key Files
 
-- `src/runtime.ts` - actor lifecycle, registry, route map, and routable routes setup
+- `src/runtime.ts` - actor lifecycle, registry, and route map setup
 - `src/App.tsx` - TanStack router construction and `PlayRouterProvider` wiring
 - `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
-- `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared auth router browser suite
 - `test/browser/xstate-route-events.browser.test.ts` - actor route event behavior in the browser
 
 ## State Machine & Architecture Details
@@ -101,7 +106,8 @@ The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** When a user clicks a link, TanStack Router updates the location object. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards and applies state transitions.
 2. **Passive Infrastructure:** The router does not execute route loaders or guards for business logic. The actor dictates whether navigation is permitted.
-3. **Atom-Only Reactivity:** The bridge leverages Solid's `createEffect` and TanStack's `router.subscribe` to observe location changes and atom updates without polling.
+3. **Atom-Only Reactivity:** The bridge leverages Solid's `createEffect` and TanStack's `router.history.subscribe` to observe location changes and atom updates without polling.
+4. **No `<RouterProvider>`:** the actor, and not a route tree, decides the view, so the demo mounts a bare navigation-service router. 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 a corrective navigation.
 
 ## Watcher Lifecycle and Cleanup Contract
 
@@ -133,6 +139,7 @@ These commands are defined in `package.json`:
 
 - [TanStack Solid Router](../../../api/@xmachines/play-tanstack-solid-router/README.md)
 - [SolidJS](../../../api/@xmachines/play-solid/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
 - [Solid Router](../play-solid-router-demo/README.md)
 - [TanStack React Router](../play-tanstack-react-router-demo/README.md)
 - [Inspecting a Running Actor](../../../guides/inspector.md)