@xmachines/docs 6.1.0 → 7.1.0

package/examples/@xmachines/play-vue-gallery-demo/variables/temperatureCatalog.md

@@ -0,0 +1,122 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / temperatureCatalog
+
+# Variable: temperatureCatalog
+
+```ts
+const temperatureCatalog: 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: {
+     setCelsius: {
+        description: "Convert a Celsius value (sends temp.setCelsius to the machine)";
+        params: ZodObject<{
+           value: ZodString;
+        }, $strip>;
+     };
+     setFahrenheit: {
+        description: "Convert a Fahrenheit value (sends temp.setFahrenheit to the machine)";
+        params: ZodObject<{
+           value: ZodString;
+        }, $strip>;
+     };
+  };
+  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-vue/examples/gallery/src/catalogs.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-vue/examples/gallery/src/catalogs.ts#L32)
+
+Built catalogs, one per machine — router demos import theirs from here.

package/examples/@xmachines/play-vue-gallery-demo/variables/ticTacToeCatalog.md

@@ -0,0 +1,119 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / ticTacToeCatalog
+
+# Variable: ticTacToeCatalog
+
+```ts
+const ticTacToeCatalog: 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: {
+     play: {
+        description: "Claim a board cell for the current player (sends ttt.play to the machine)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     reset: {
+        description: "Start a fresh game (sends ttt.reset to the machine)";
+     };
+  };
+  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-vue/examples/gallery/src/catalogs.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-vue/examples/gallery/src/catalogs.ts#L29)
+
+Built catalogs, one per machine — router demos import theirs from here.

package/examples/@xmachines/play-vue-gallery-demo/variables/todoMvcCatalog.md

@@ -0,0 +1,151 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-gallery-demo](../README.md) / todoMvcCatalog
+
+# Variable: todoMvcCatalog
+
+```ts
+const todoMvcCatalog: 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: {
+     add: {
+        description: "Add a todo (sends todo.add to the machine)";
+        params: ZodObject<{
+           title: ZodString;
+        }, $strip>;
+     };
+     clearCompleted: {
+        description: "Remove every completed todo (sends todo.clearCompleted)";
+     };
+     edit: {
+        description: "Open one todo in the edit view (routes to '#todo' with the id param)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     remove: {
+        description: "Remove a todo (sends todo.remove)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+     rename: {
+        description: "Rename a todo (sends todo.rename; rejects a blank title)";
+        params: ZodObject<{
+           id: ZodString;
+           title: ZodString;
+        }, $strip>;
+     };
+     route: {
+        description: "Navigate to a filter route (e.g. '#all', '#active', '#completed')";
+        params: ZodObject<{
+           params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+           to: ZodString;
+        }, $strip>;
+     };
+     toggle: {
+        description: "Toggle a todo between open and done (sends todo.toggle)";
+        params: ZodObject<{
+           id: ZodString;
+        }, $strip>;
+     };
+  };
+  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-vue/examples/gallery/src/catalogs.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.1.0/packages/play-vue/examples/gallery/src/catalogs.ts#L35)
+
+Built catalogs, one per machine — router demos import theirs from here.

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

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

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

@@ -8,10 +8,11 @@ Vue Router integration demo for the XMachines Play architecture using Vue Compos
 
 ## What This Demonstrates
 
-- Shared auth machine reused without framework-specific business logic
+- The shared auth machine — a login wall — reused without framework-specific business logic
 - `PlayRouterProvider` renderer-based integration with Vue Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
 - Vue Composition API mapping to atoms lifecycle
+- The Shell, five-component kit, and built `authCatalog` imported from the [Vue renderer gallery](../play-vue-gallery-demo/README.md) rather than duplicated here
 - 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,21 +32,21 @@ Then open `http://localhost:3010`.
 Use this order to understand how the demo is wired:
 
 1. `src/main.ts` creates the Vue app, installs Vue Router, mounts, and wires HMR cleanup.
-2. `src/runtime.ts` creates the actor, starts it, builds the shared `registryResult`, and creates the `routeMap`.
+2. `src/runtime.ts` creates the actor, starts it, builds the `registryResult` from the gallery's `authCatalog` + `demoComponents`, and creates the `routeMap`.
 3. `src/router.ts` installs a single catch-all route; `PlayRenderer` selects the actual view from actor state.
 4. `src/App.vue` renders `<PlayRouterProvider>` with the shared actor, routeMap, router instance, and a `renderShell` renderer function.
-5. The renderer function creates the shared `Shell` component with actor, router, registry, and inspector as props — the last of which drives the debug panel's **Show Inspector** button.
+5. The renderer function creates the gallery's `Shell` component with actor, router, registry, and inspector as props — the last of which drives the debug panel's **Show Inspector** button.
 6. `PlayRouterProvider` waits for `router.isReady()` so direct URL loads are handled correctly.
 7. Browser tests in `test/browser/` validate startup and auth route transitions.
 
-```ts
+```ts fragment
 // src/main.ts (shape)
 const app = createApp(App);
 app.use(router);
 app.mount("#app");
 ```
 
-```ts
+```ts fragment
 // src/router.ts (shape)
 export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", component: RouteHost }];
 ```
@@ -53,10 +54,11 @@ export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", compo
 ```vue
 <!-- src/App.vue (shape) -->
 <script setup lang="ts">
+import { Shell } from "@xmachines/play-vue-gallery-demo";
 import { actor, routeMap, registryResult } from "./runtime.js";
 
-const renderShell = (currentActor, currentRouter) =>
-	h(SharedShell, { actor: currentActor, router: currentRouter, registryResult, inspector });
+const renderShell = (_actor, currentRouter) =>
+	h(Shell, { actor, router: currentRouter, registryResult, inspector });
 </script>
 
 <template>
@@ -69,21 +71,24 @@ const renderShell = (currentActor, currentRouter) =>
 </template>
 ```
 
-```ts
+```ts fragment
 // src/runtime.ts (shape)
 export const actor = createPlayer();
 actor.start();
 
 export const routeMap = createRouteMap(authMachine);
-export const registryResult = defineRegistry(authCatalog, { components, actions });
+export const registryResult = defineRegistry(authCatalog, {
+	components: demoComponents,
+	actions: createAuthActionHandlers(actor),
+});
 ```
 
 ## Key Files
 
 - `src/main.ts` - Vue app bootstrap (mount + router install + HMR cleanup)
-- `src/runtime.ts` - actor startup, routeMap creation, and registry construction
+- `src/runtime.ts` - actor startup, routeMap creation, and registry construction from the gallery kit
 - `src/router.ts` - single catch-all route record
-- `src/App.vue` - `PlayRouterProvider` wiring and renderer composition using the shared runtime
+- `src/App.vue` - `PlayRouterProvider` wiring and renderer composition around the gallery's `Shell`
 - `test/reactivity.test.ts` - reactive integration assertions
 - `test/browser/shared-demo.browser.test.ts` - browser startup and full auth flow coverage
 
@@ -125,4 +130,5 @@ These commands are defined in `package.json`:
 
 - [Vue Router](../../../api/@xmachines/play-vue-router/README.md)
 - [Vue](../../../api/@xmachines/play-vue/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md) — the Shell, kit, and catalogs this demo imports
 - [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,78 @@
+[Examples](../../README.md) / @xmachines/play-vue-router-donut-demo
+
+# @xmachines/play-vue-router-donut-demo
+
+Vue 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 Vue 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-vue-gallery-demo`](../play-vue-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: a deep link is honored when valid and overwritten back when invalid (State-Driven Reset)
+- Snapshot persistence: `onTransition` saves after every processed event and the actor resumes through the player factory's resume options
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-vue-router-donut-demo run dev
+```
+
+Then open `http://localhost:3090`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` creates the Vue app, installs the router, mounts it on `#app`, and wires HMR cleanup.
+2. `src/runtime.ts` creates and starts the actor, builds the `routeMap` from the machine, and constructs the `registryResult` from the gallery's `donutCatalog` + `demoComponents`.
+3. `src/runtime.ts` also owns persistence: `createResumedPlayer()` passes a stored snapshot through the factory's resume options, and `options.onTransition` saves after every processed event.
+4. `src/router.ts` installs a single catch-all route over `createWebHistory` — `PlayRenderer` selects the actual view from actor state.
+5. `src/App.vue` renders `<PlayRouterProvider>` with the actor, route map, router instance, and a `renderShell` render function.
+6. `renderShell` composes the gallery `Shell` with `h()`, handing it the actor, the bridged router, the registry, and the inspector, plus the **Reset saved donut** button in the `nav` slot.
+7. `PlayRouterProvider` waits for `router.isReady()` before connecting the bridge, so direct URL loads are handled correctly.
+8. Browser tests in `test/browser/` delegate to the shared Donut router suite.
+
+## Key Files
+
+- `src/main.ts` - Vue app bootstrap (router install + mount + HMR cleanup)
+- `src/runtime.ts` - actor startup, route map, and registry wiring plus snapshot persistence
+- `src/router.ts` - single catch-all route record
+- `src/App.vue` - `PlayRouterProvider` wiring and `Shell` composition
+- `test/library-pattern.test.ts` - source-level wiring assertions (`tsc` does not read `.vue`)
+- `test/browser/shared-demo.browser.test.ts` - delegates to the shared Donut router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation changes the URL, `VueRouterBridge` turns that into a `play.route` event, and the actor evaluates it against its own guards.
+2. **Passive Infrastructure:** No Vue Router navigation guard carries business logic. The actor decides whether a navigation is permitted; Vue only renders the result.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                | Description                                    |
+| ---------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-vue-router-donut-demo run dev`          | Start Vite dev server (http://localhost:3090/) |
+| `pnpm --filter @xmachines/play-vue-router-donut-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-vue-router-donut-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-vue-router-donut-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-vue-router-donut-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-vue-router-donut-demo run test
+pnpm --filter @xmachines/play-vue-router-donut-demo run test:browser
+```
+
+Expected result: the source-level wiring test passes and the shared Donut router browser suite completes.
+
+## Learn More
+
+- [Vue Router adapter](../../../api/@xmachines/play-vue-router/README.md)
+- [Vue renderer gallery](../play-vue-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)