@xmachines/docs 6.1.0 → 7.1.0

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
+```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() {
@@ -72,12 +72,13 @@ return (
 );
 ```
 
-```tsx
+```tsx fragment
 // src/runtime.ts (shape)
 export const inspector = createDemoInspector();
 export const createPlayer = definePlayer({
 	machine: authMachine,
 	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
 });
 export const routeMap = createRouteMap(authMachine);
 
@@ -98,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
@@ -146,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,38 +32,43 @@ 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
+```tsx fragment
 // src/main.tsx (shape)
 render(() => <App />, document.getElementById("app")!);
 ```
 
-```ts
+```ts fragment
 // src/runtime.ts (shape)
 export const inspector = createDemoInspector();
 const createPlayer = definePlayer({
 	machine: authMachine,
 	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
 });
 export const actor = createPlayer();
 actor.start();
 
+export const registryResult = defineRegistry(authCatalog, {
+	components: demoComponents,
+	actions: createAuthActionHandlers(actor), // login/logout/route + task events + form actions
+});
+
 export const routeMap = createRouteMap(authMachine);
-const routeTree = extractMachineRoutes(authMachine);
-export const routes = getRoutableRoutes(routeTree);
 ```
 
-```tsx
+```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}
@@ -80,18 +86,18 @@ return (
 );
 ```
 
-```ts
+```ts fragment
 // src/runtime.ts — actor events wired via the shared handler factory
-actions: createAuthActionHandlers(actor), // login/logout/route + task events + form actions
+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
@@ -100,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
 
@@ -132,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)

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)