@xmachines/docs 6.1.0 → 7.1.0

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

@@ -1,9 +1,9 @@
-[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / authCatalog
+[Examples](../../../README.md) / [@xmachines/play-solid-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-react/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-react/examples/demo/src/catalog.ts#L5)
+Defined in: [packages/play-solid/examples/gallery/src/catalogs.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-solid/examples/gallery/src/catalogs.ts#L34)
+
+Built catalogs, one per machine — router demos import theirs from here.

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

@@ -0,0 +1,129 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-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-solid/examples/gallery/src/catalogs.ts:37](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-solid/examples/gallery/src/catalogs.ts#L37)
+
+Built catalogs, one per machine — router demos import theirs from here.

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

@@ -8,10 +8,11 @@ SolidJS Router adapter demonstration with authentication flow using the XMachine
 
 ## 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 Solid Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Canonical atoms lifecycle integration with Solid's fine-grained reactivity
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md) renderer gallery
+- Atom lifecycle integration with Solid's fine-grained reactivity
 - 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,34 +32,40 @@ Then open `http://localhost:3007`.
 Use this order to understand the implementation:
 
 1. `src/main.tsx` bootstraps the demo and mounts `<App />` onto `#app`.
-2. `src/runtime.ts` sets up the actor, registry, routes, and route map — all shared module-level singletons.
+2. `src/runtime.ts` sets up the actor, registry (built from `authCatalog` + `demoComponents`, both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), routes, and route map — all shared module-level singletons.
 3. `src/App.tsx` wires Solid Router routes and the `PlayRouterProvider` using the runtime exports.
 4. A `routeMap` is created by calling `createRouteMap(authMachine)` in `src/runtime.ts`.
 5. `PlayRouterProvider` forwards navigation intent from `@solidjs/router` to the actor, and reflects actor-approved routes back to the URL.
-6. `Shell` (from [`@xmachines/play-solid-demo`](../play-solid-demo/README.md)) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell, including the debug panel's **Show Inspector** button.
+6. `Shell` (from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)) renders actor-projected views (`PlayRenderer`) and provides the shared UI shell, including the debug panel's **Show Inspector** button.
 7. `test/library-pattern.test.ts` and `test/browser/` verify invariants and runtime routing behavior.
 
-```tsx
+```tsx fragment
 // src/main.tsx (shape)
 render(() => <App />, document.getElementById("app")!);
 ```
 
-```tsx
+```tsx 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);
 ```
 
-```tsx
+```tsx fragment
 // src/App.tsx (shape)
-import { Shell } from "@xmachines/play-solid-demo"; // shared demo shell (workspace-only package)
+import { Shell } from "@xmachines/play-solid-gallery-demo"; // shared demo shell (workspace-only package)
 import { actor, inspector, registryResult, routeMap } from "./runtime.js";
 
 const Layout: ParentComponent = () => {
@@ -90,7 +97,7 @@ const Layout: ParentComponent = () => {
 - `src/App.tsx` - Solid Router wiring, `PlayRouterProvider` integration, and renderer composition
 - `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
 
 ## State Machine & Architecture Details
 
@@ -130,5 +137,6 @@ These commands are defined in `package.json`:
 
 - [Solid Router](../../../api/@xmachines/play-solid-router/README.md)
 - [SolidJS](../../../api/@xmachines/play-solid/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
 - [TanStack Solid Router](../play-tanstack-solid-router-demo/README.md)
 - [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,86 @@
+[Examples](../../README.md) / @xmachines/play-solid-router-donut-demo
+
+# @xmachines/play-solid-router-donut-demo
+
+Solid Router 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 `@solidjs/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 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-solid-router-donut-demo run dev
+```
+
+Then open `http://localhost:3070`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` on `#root` via Solid's `render`.
+2. `src/runtime.ts` creates the actor through `createResumedPlayer()`, starts it, builds the `registryResult` from `donutCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and pre-builds `routes` and `routeMap` — all module-level singletons, so no re-render can recreate them.
+3. `src/App.tsx` declares the machine's routes on `<Router>` and renders `Layout` as the router root.
+4. `Layout` reads `useNavigate()`, `useLocation()`, and `useParams()` and hands them to `PlayRouterProvider` as its `router` prop; `onCleanup` stops the actor when Solid disposes of the layout.
+5. `PlayRouterProvider` creates the `SolidRouterBridge` synchronously, forwards navigation intent to the actor, reflects actor-approved routes back to the URL, and disconnects in `onCleanup`.
+6. `Shell` (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` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `src/runtime.ts` - actor lifecycle with persistence hooks, registry, route extraction, and route map creation
+- `src/App.tsx` - Solid Router wiring, `PlayRouterProvider` integration, renderer composition, and 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
+
+## 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-solid-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3070/) |
+| `pnpm --filter @xmachines/play-solid-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-solid-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-solid-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-solid-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-solid-router-donut-demo run test
+pnpm --filter @xmachines/play-solid-router-donut-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass in Node and the shared donut router browser suite completes.
+
+## Learn More
+
+- [Solid Router adapter](../../../api/@xmachines/play-solid-router/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,75 @@
+[Examples](../../README.md) / @xmachines/play-solid-router-flight-demo
+
+# @xmachines/play-solid-router-flight-demo
+
+Solid Router 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 `@solidjs/router` — the wizard steps map to `/`, `/dates`, `/review`, `/submitting`, and `/booked`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link to `/booked` without a confirmation bounces back to the trip step and the URL is overwritten (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-solid-router-flight-demo run dev
+```
+
+Then open `http://localhost:3071`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` on `#root` via Solid's `render`.
+2. `src/runtime.ts` creates the actor, starts it, builds the `registryResult` from `flightCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and pre-builds `routes` and `routeMap` — all module-level singletons, so no re-render can recreate them.
+3. `src/App.tsx` declares the machine's routes on `<Router>` and renders `Layout` as the router root.
+4. `Layout` reads `useNavigate()`, `useLocation()`, and `useParams()` and hands them to `PlayRouterProvider` as its `router` prop; `onCleanup` stops the actor when Solid disposes of the layout.
+5. `PlayRouterProvider` creates the `SolidRouterBridge` synchronously, forwards navigation intent to the actor, reflects actor-approved routes back to the URL, and disconnects in `onCleanup`.
+6. `Shell` (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` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `src/runtime.ts` - actor lifecycle, registry, route extraction, and route map creation
+- `src/App.tsx` - Solid Router wiring, `PlayRouterProvider` integration, and renderer composition
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared flight router browser suite
+
+## 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 a step the machine has not earned is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                   | Description                                    |
+| ------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-solid-router-flight-demo run dev`          | Start Vite dev server (http://localhost:3071/) |
+| `pnpm --filter @xmachines/play-solid-router-flight-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-solid-router-flight-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-solid-router-flight-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-solid-router-flight-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-solid-router-flight-demo run test
+pnpm --filter @xmachines/play-solid-router-flight-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass in Node and the shared flight router browser suite completes.
+
+## Learn More
+
+- [Solid Router adapter](../../../api/@xmachines/play-solid-router/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,75 @@
+[Examples](../../README.md) / @xmachines/play-solid-router-todomvc-demo
+
+# @xmachines/play-solid-router-todomvc-demo
+
+Solid Router integration demo of the shared **TodoMVC** machine for the XMachines Play architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared TodoMVC machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with `@solidjs/router` — the filter states map to `/`, `/active`, and `/completed`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-solid-router-todomvc-demo run dev
+```
+
+Then open `http://localhost:3068`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` on `#root` via Solid's `render`.
+2. `src/runtime.ts` creates the actor, starts it, builds the `registryResult` from `todoMvcCatalog` + `demoComponents` (both from [`@xmachines/play-solid-gallery-demo`](../play-solid-gallery-demo/README.md)), and pre-builds `routes` and `routeMap` — all module-level singletons, so no re-render can recreate them.
+3. `src/App.tsx` declares the machine's routes on `<Router>` and renders `Layout` as the router root.
+4. `Layout` reads `useNavigate()`, `useLocation()`, and `useParams()` and hands them to `PlayRouterProvider` as its `router` prop; `onCleanup` stops the actor when Solid disposes of the layout.
+5. `PlayRouterProvider` creates the `SolidRouterBridge` synchronously, forwards navigation intent to the actor, reflects actor-approved routes back to the URL, and disconnects in `onCleanup`.
+6. `Shell` (from the renderer gallery) receives `actor`, `router`, `registryResult`, and `inspector`.
+7. Browser tests in `test/browser/` delegate to the shared TodoMVC router suite.
+
+## Key Files
+
+- `src/main.tsx` - Vite bootstrap that mounts `<App />` via Solid's `render`
+- `src/runtime.ts` - actor lifecycle, registry, route extraction, and route map creation
+- `src/App.tsx` - Solid Router wiring, `PlayRouterProvider` integration, and renderer composition
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared TodoMVC router browser suite
+
+## 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-solid-router-todomvc-demo run dev`          | Start Vite dev server (http://localhost:3068/) |
+| `pnpm --filter @xmachines/play-solid-router-todomvc-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-solid-router-todomvc-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-solid-router-todomvc-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-solid-router-todomvc-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-solid-router-todomvc-demo run test
+pnpm --filter @xmachines/play-solid-router-todomvc-demo run test:browser
+```
+
+Expected result: the library-pattern invariants pass in Node and the shared TodoMVC router browser suite completes.
+
+## Learn More
+
+- [Solid Router adapter](../../../api/@xmachines/play-solid-router/README.md)
+- [Solid renderer gallery](../play-solid-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)