@xmachines/docs 7.0.0 → 7.1.0

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

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

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

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

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

@@ -8,7 +8,7 @@ React Router 7/8 integration demo for the XMachines Play architecture.
 
 ## 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 React Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
 - Canonical atoms lifecycle mapped to React's rendering loop
@@ -35,9 +35,9 @@ Use this order to understand the implementation:
 3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(authMachine)`) and exports `createPlayer`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
 4. `createAppRuntime()` creates the actor, builds a `registryResult` from the registry, and constructs a React Router data router with a `RoutedShell` wrapper.
 5. `PlayRouterProvider` wires actor navigation and router changes in both directions, using the pre-built `routeMap`.
-6. `Shell` (imported from the workspace-only [`@xmachines/play-react-demo`](../play-react-demo/README.md)) receives `actor`, `router`, `registryResult`, and `inspector`, matching the other router demos.
+6. `Shell` (imported from the workspace-only [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)) receives `actor`, `router`, `registryResult`, and `inspector`, matching the other router demos.
 7. The `renderer` prop renders `<RouterProvider router={currentRouter} />` directly — no intermediate `ReactRouterApp` wrapper is needed.
-8. Browser tests in `test/browser/` validate startup and auth navigation flow via a shared demo suite.
+8. `test/browser/shared-demo.browser.test.tsx` delegates to `defineAuthRouterDemoBrowserSuite` — the shared login-wall routing suite.
 
 ```tsx fragment
 // src/main.tsx (shape)
@@ -56,7 +56,7 @@ export const routeMap = createRouteMap(authMachine);
 
 export function createRegistryResult(actor: ReturnType<typeof createPlayer>) {
 	return defineRegistry(authCatalog, {
-		components: demoComponents, // from @xmachines/play-react-demo
+		components: demoComponents, // from @xmachines/play-react-gallery-demo
 		actions: createAuthActionHandlers(actor),
 	});
 }
@@ -64,7 +64,7 @@ export function createRegistryResult(actor: ReturnType<typeof createPlayer>) {
 
 ```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)
 
 type BrowserRouterInstance = ReturnType<typeof createBrowserRouter>;
 
@@ -109,7 +109,7 @@ return (
 - `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, provider wiring, and `RoutedShell` composition
-- `test/browser/shared-demo.browser.test.tsx` - browser E2E suite for startup and auth navigation flow
+- `test/browser/shared-demo.browser.test.tsx` - delegates to the shared `defineAuthRouterDemoBrowserSuite`
 
 ## State Machine & Architecture Details
 
@@ -145,6 +145,17 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-react-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-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-react-router-demo run test
+pnpm --filter @xmachines/play-react-router-demo run test:browser
+```
+
+Expected result: the shared auth router suite passes — protected deep link bounced to `/login`, login opening `/dashboard`, logout returning to `/`, in-view route actions moving both view and URL, and an invalid external URL overwritten back by the actor.
+
 ## Learn More
 
 - [React Router](../../../api/@xmachines/play-react-router/README.md)

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

@@ -0,0 +1,85 @@
+[Examples](../../README.md) / @xmachines/play-react-router-donut-demo
+
+# @xmachines/play-react-router-donut-demo
+
+React Router v7 integration demo of the shared **donut** wizard 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 React 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 to a step whose prerequisites are unmet cascades back through the guard chain and the URL is overwritten (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-react-router-donut-demo run dev
+```
+
+Then open `http://localhost:3066`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and browser router, starting the actor once per mounted app.
+3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(donutMachine)`) and exports `createResumedPlayer`, `resetSavedDonut`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
+4. `createAppRuntime()` creates the actor, builds a `registryResult` from `donutCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)), and constructs a React Router data router with a `RoutedShell` wrapper.
+5. `PlayRouterProvider` wires actor navigation and router changes in both directions, using the pre-built `routeMap`.
+6. `Shell` (imported from the renderer gallery) receives `actor`, `router`, `registryResult`, `inspector`, and the **Reset saved donut** button as its `nav` slot.
+7. Browser tests in `test/browser/` delegate to the shared donut router 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` - React entry point that mounts `<App />`
+- `src/runtime.ts` - actor factory with persistence hooks, pre-built `routeMap`, and `createRegistryResult` registry wiring
+- `src/App.tsx` - actor lifecycle, provider wiring, `RoutedShell` composition, and the reset-snapshot button
+- `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 `PlayRouterProvider` intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** The router does not execute business logic. The actor dictates 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-react-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3066/) |
+| `pnpm --filter @xmachines/play-react-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-react-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-react-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-react-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-react-router-donut-demo run test
+pnpm --filter @xmachines/play-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
+
+- [React Router adapter](../../../api/@xmachines/play-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,74 @@
+[Examples](../../README.md) / @xmachines/play-react-router-flight-demo
+
+# @xmachines/play-react-router-flight-demo
+
+React Router v7 integration demo of the shared **flight** booking wizard 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 React Router — the wizard 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: `/dates` is honored as a direct entry, while `/booked` without a confirmation is overwritten back to `/` (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-react-router-flight-demo run dev
+```
+
+Then open `http://localhost:3067`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and browser router, 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()` creates the actor, builds a `registryResult` from `flightCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)), and constructs a React Router data router with a `RoutedShell` wrapper.
+5. `PlayRouterProvider` wires actor navigation and router changes in both directions, using the pre-built `routeMap`.
+6. `Shell` (imported from the renderer gallery) receives `actor`, `router`, `registryResult`, and `inspector`.
+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, provider wiring, and `RoutedShell` composition
+- `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 `PlayRouterProvider` intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** The router does not execute business logic. The actor dictates 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-react-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3067/) |
+| `pnpm --filter @xmachines/play-react-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-react-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-react-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-react-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-react-router-flight-demo run test
+pnpm --filter @xmachines/play-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
+
+- [React Router adapter](../../../api/@xmachines/play-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,74 @@
+[Examples](../../README.md) / @xmachines/play-react-router-todomvc-demo
+
+# @xmachines/play-react-router-todomvc-demo
+
+React Router v7 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 React 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-react-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3064`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and browser router, 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()` creates the actor, builds a `registryResult` from `todoMvcCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)), and constructs a React Router data router with a `RoutedShell` wrapper.
+5. `PlayRouterProvider` wires actor navigation and router changes in both directions, using the pre-built `routeMap`.
+6. `Shell` (imported from the renderer demo) receives `actor`, `router`, `registryResult`, and `inspector`.
+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, provider wiring, and `RoutedShell` composition
+- `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 `PlayRouterProvider` intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** The router does not execute business logic. The actor dictates 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-react-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3064/) |
+| `pnpm --filter @xmachines/play-react-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-react-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-react-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-react-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-react-router-todomvc-demo run test
+pnpm --filter @xmachines/play-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
+
+- [React Router adapter](../../../api/@xmachines/play-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)