@xmachines/docs 4.0.0 → 5.0.1

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

@@ -1,18 +1,19 @@
 [Examples](../../README.md) / @xmachines/play-sveltekit-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-sveltekit-router-demo
 
 Svelte 5 + SvelteKit router adapter integration demo for the XMachines Play architecture using browser pathname URL routing.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
 - `connectRouter` pathname URL ↔ actor sync via [`@xmachines/play-sveltekit-router`](../../../api/@xmachines/play-sveltekit-router/README.md)
 - Shell-driven rendering via `PlayUIProvider` + `PlayRenderer` with actor-authoritative navigation
-- Canonical TC39 Signals lifecycle integrated with Svelte 5 runes
+- Canonical atoms lifecycle integrated with Svelte 5 runes
 - 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
 
 ## Running the Demo
 
@@ -32,13 +33,18 @@ Use this order to understand the implementation:
 1. `src/main.ts` mounts `App.svelte` and registers HMR cleanup via `cleanup`.
 2. `src/runtime.ts` creates the actor, builds the registry, calls `createRouteMap(authMachine)`, and wires `connectRouter({ actor, routeMap })`.
 3. `connectRouter` synchronizes browser pathname changes with the actor via `play.route` events and reflects actor-approved routes back to the pathname URL.
-4. `src/App.svelte` imports the singleton `actor` and `registryResult` from `src/runtime.ts` and delegates to the shared `Shell.svelte`.
-5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel).
+4. `src/App.svelte` imports the singleton `actor`, `registryResult`, and `inspector` from `src/runtime.ts` and delegates to the shared `Shell.svelte`.
+5. `Shell.svelte` renders `<PlayUIProvider>` + `<PlayRenderer />` with the actor and registryResult and provides the shared UI shell (nav, debug panel with the **Show Inspector** button).
 6. Browser tests in `test/browser/` validate startup and auth route transitions.
 
 ```ts
 // src/runtime.ts (shape)
-const createDemoPlayer = definePlayer({ machine: authMachine });
+export const inspector = createDemoInspector();
+const createDemoPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
+});
 export const actor = createDemoPlayer();
 actor.start();
 
@@ -55,10 +61,10 @@ export function cleanup(): void {
 <!-- src/App.svelte (shape) -->
 <script lang="ts">
 	import { Shell } from "@xmachines/play-svelte-demo";
-	import { actor, registryResult } from "./runtime.js";
+	import { actor, inspector, registryResult } from "./runtime.js";
 </script>
 
-<Shell {actor} {registryResult} />
+<Shell {actor} {registryResult} {inspector} />
 ```
 
 ```svelte
@@ -84,19 +90,17 @@ The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** When a user clicks a nav link, the browser pathname changes. `connectRouter` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and transitions to the appropriate state.
 2. **Passive Infrastructure:** The SvelteKit router adapter does not execute business logic. The actor dictates whether navigation is permitted. The Svelte application only renders the state.
-3. **Signal-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor signals update, without ad-hoc `$state` stores for business logic.
+3. **Atom-Only Reactivity:** The bridge leverages Svelte 5 rune reactivity internally to react precisely when actor atoms update, without ad-hoc `$state` stores for business logic.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher lifecycle used across all `@xmachines` framework adapters:
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and project Svelte-local render state
-5. Re-arm with `watch()`/`watch(...signals)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and projects Svelte-local render state
 
-Watcher notifications are one-shot. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `cleanup()` calls `disconnectRouter()` and `actor.stop()` during HMR disposal, preventing memory leaks and ghost subscriptions.
 
 ## Adapter Boundaries
 
@@ -116,18 +120,8 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-sveltekit-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-sveltekit-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-sveltekit-router-demo run test
-pnpm --filter @xmachines/play-sveltekit-router-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser demo suite validates startup rendering and auth navigation.
-
 ## Learn More
 
 - [SvelteKit Router](../../../api/@xmachines/play-sveltekit-router/README.md)
 - [Svelte](../../../api/@xmachines/play-svelte/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -1,17 +1,18 @@
 [Examples](../../README.md) / @xmachines/play-tanstack-react-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-tanstack-react-router-demo
 
 React + TanStack Router integration demo for the XMachines Play architecture with actor-authoritative routing.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine 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
+- 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
 
@@ -30,13 +31,16 @@ Use this order to understand the implementation:
 
 1. `src/main.tsx` mounts `<App />`.
 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 `createPlayer` (via `definePlayer`), `routeMap` (via `createRouteMap(authMachine)`), and `createRegistryResult` which binds UI components and actor event actions.
+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` renders `PlayRenderer`, header/nav, and debug panel from actor state.
+5. `Shell` is the shared demo layout component imported from `@xmachines/play-react-demo` (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.
 6. Tests in `test/` and `test/browser/` validate invariant and runtime behavior.
 
 ```tsx
 // src/App.tsx (shape)
+import { Shell } from "@xmachines/play-react-demo"; // shared demo shell (workspace-only package)
+import { createPlayer, inspector, routeMap, createRegistryResult } from "./runtime.js";
+
 function createAppRuntime() {
 	const actor = createPlayer();
 	actor.start();
@@ -57,7 +61,12 @@ return (
 		router={router}
 		routeMap={routeMap}
 		renderer={(currentActor, currentRouter) => (
-			<Shell actor={currentActor} router={currentRouter} registryResult={registryResult} />
+			<Shell
+				actor={currentActor}
+				router={currentRouter}
+				registryResult={registryResult}
+				inspector={inspector}
+			/>
 		)}
 	/>
 );
@@ -65,16 +74,17 @@ return (
 
 ```tsx
 // src/runtime.ts (shape)
-export const createPlayer = definePlayer({ machine: authMachine });
+export const inspector = createDemoInspector();
+export const createPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+});
 export const routeMap = createRouteMap(authMachine);
 
-export function createRegistryResult(actor) {
+export function createRegistryResult(actor: ReturnType<typeof createPlayer>) {
 	return defineRegistry(authCatalog, {
-		actions: {
-			login: async (args) => actor.send({ type: "auth.login", username: args.username }),
-			logout: async () => actor.send({ type: "auth.logout" }),
-			route: async (args) => actor.send({ type: "play.route", to: args.to, ...args.params }),
-		},
+		components: demoComponents,
+		actions: createAuthActionHandlers(actor),
 	});
 }
 ```
@@ -87,7 +97,7 @@ export function createRegistryResult(actor) {
 - `test/actor-authority.test.ts` - actor authority and guarded navigation behavior
 - `test/passive-infra.test.ts` - passive infrastructure separation contracts
 - `test/strict-separation.test.ts` - machine/view infrastructure separation contracts
-- `test/signal-only.test.ts` - signal-only reactivity invariant
+- `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
@@ -108,19 +118,17 @@ The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** When a user navigates to a protected route, TanStack Router updates the URL. The `PlayRouterProvider` intercepts this, translates it to a `play.route` event, and sends it to the actor. The actor evaluates guards (e.g. `isAuthenticated`) and executes 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. **Signal-Only Reactivity:** The bridge leverages React's internal mechanisms combined with TanStack's `router.subscribe` to react precisely when signals update, without relying on `useEffect` synchronization inside the application codebase.
+3. **Atom-Only Reactivity:** The bridge leverages React's internal mechanisms combined with TanStack's `router.subscribe` to react precisely when atoms update, without relying on `useEffect` synchronization inside the application codebase.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher lifecycle:
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and trigger React state updates
-5. Re-arm with `watch()`/`watch(...signals)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and triggers React state updates
 
-Watcher notifications are one-shot. Cleanup is explicit and lifecycle-bound: the provider automatically triggers `bridge.disconnect()` when the component tree unmounts to prevent memory leaks and zombie subscriptions.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit and lifecycle-bound: the provider automatically triggers `bridge.disconnect()` when the component tree unmounts to prevent memory leaks and zombie subscriptions.
 
 ## Adapter Boundaries
 
@@ -138,19 +146,9 @@ 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: invariant test suite and the browser shared-demo suite both pass, confirming actor authority, route sync, and guard-driven redirection.
-
 ## Learn More
 
 - [TanStack React Router](../../../api/@xmachines/play-tanstack-react-router/README.md)
 - [React](../../../api/@xmachines/play-react/README.md)
 - [TanStack Solid Router](../play-tanstack-solid-router-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -1,11 +1,11 @@
 [Examples](../../README.md) / @xmachines/play-tanstack-solid-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-tanstack-solid-router-demo
 
 Solid + `@tanstack/solid-router` integration demo for the XMachines Play architecture with actor-authoritative routing.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
@@ -13,6 +13,7 @@ Solid + `@tanstack/solid-router` integration demo for the XMachines Play archite
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
 - 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
 
 ## Running the Demo
 
@@ -33,7 +34,7 @@ Use this order to understand the implementation:
 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`.
 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`) renders actor-projected state (`PlayRenderer`) and emits actor events via the `registryResult` actions.
+5. `Shell` (from `@xmachines/play-solid-demo`) 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
@@ -43,7 +44,11 @@ render(() => <App />, document.getElementById("app")!);
 
 ```ts
 // src/runtime.ts (shape)
-const createPlayer = definePlayer({ machine: authMachine });
+export const inspector = createDemoInspector();
+const createPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+});
 export const actor = createPlayer();
 actor.start();
 
@@ -54,25 +59,30 @@ export const routes = getRoutableRoutes(routeTree);
 
 ```tsx
 // src/App.tsx (shape)
-import { actor, registryResult, routeMap, routes } from "./runtime.js";
+import { Shell } from "@xmachines/play-solid-demo"; // shared demo shell (workspace-only package)
+import { actor, inspector, registryResult, routeMap, routes } from "./runtime.js";
 
+// router: the TanStack router built below in src/App.tsx from `routes`
 return (
 	<PlayRouterProvider
 		actor={actor}
 		router={router}
 		routeMap={routeMap}
 		renderer={(currentActor, currentRouter) => (
-			<Shell actor={currentActor} router={currentRouter} registryResult={registryResult} />
+			<Shell
+				actor={currentActor}
+				router={currentRouter}
+				registryResult={registryResult}
+				inspector={inspector}
+			/>
 		)}
 	/>
 );
 ```
 
 ```ts
-// src/runtime.ts — actor events wired via registryResult actions
-login: async (args) => actor.send({ type: "auth.login", username: args.username }),
-logout: async () => actor.send({ type: "auth.logout" }),
-route: async (args) => actor.send({ type: "play.route", to: args.to, ...params }),
+// src/runtime.ts — actor events wired via the shared handler factory
+actions: createAuthActionHandlers(actor), // login/logout/route + task events + form actions
 ```
 
 ## Key Files
@@ -90,17 +100,15 @@ 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. **Signal-Only Reactivity:** The bridge leverages Solid's `createEffect` and TanStack's `router.subscribe` to observe location changes and signal updates without polling.
+3. **Atom-Only Reactivity:** The bridge leverages Solid's `createEffect` and TanStack's `router.subscribe` to observe location changes and atom updates without polling.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher lifecycle:
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and trigger state updates
-5. Re-arm with `watch()`/`watch(...signals)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and triggers state updates
 
 In Solid, this is largely abstracted by `createEffect` within the bridge adapter. Cleanup remains explicit: the provider executes `bridge.disconnect()` on unmount (`onCleanup`) to prevent ghost subscriptions, ensuring safe component teardown and hot module replacement.
 
@@ -120,20 +128,10 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-tanstack-solid-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-tanstack-solid-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-solid-router-demo run test
-pnpm --filter @xmachines/play-tanstack-solid-router-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests and the browser shared-demo suite both pass, confirming actor-driven route and view updates including protected route redirection.
-
 ## Learn More
 
 - [TanStack Solid Router](../../../api/@xmachines/play-tanstack-solid-router/README.md)
 - [SolidJS](../../../api/@xmachines/play-solid/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-vue-demo/README.md

@@ -1,18 +1,24 @@
 [Examples](../../README.md) / @xmachines/play-vue-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-vue-demo
 
 Vue 3 renderer demo for [`@xmachines/play-vue`](../../../api/@xmachines/play-vue/README.md) — actor + `PlayRenderer` without a router.
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
 - `PlayRenderer` rendering actor-projected views with a typed `defineRegistry` catalog
 - Auth machine states drive view switching via `auth.login` / `auth.logout` events only — no URL routing
-- Vue Composition API mapping to TC39 Signals lifecycle
+- Vue Composition API mapping to atoms lifecycle
 - Non-browser invariant tests plus browser renderer coverage
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+- json-render 0.20 showcase pages driven purely by spec:
+    - **Overview** — two data planes side by side: `/context/tasks` (machine context via the read-only `/context` projection; `repeat` + `key`, `$item`-filtered lists, per-row actions sending inspectable machine events) next to ephemeral store state (`pushState`/`removeState`/`setState` built-ins driving filter chips and toggles that survive context updates)
+    - **Stats** — nested repeats (`repeat.statePath: { $item: "members" }`) over `/context/teams`
+    - **Settings** — declarative field validation, the `validateForm` built-in, a confirm-gated `resetForm` host action, and `onSuccess`/`onError` chains
+    - **Contact** — a chained named action: submit validates, then routes home on success or writes `"$error.message"` to state on failure
 
 ## Running the Demo
 
@@ -29,23 +35,29 @@ Then open `http://localhost:3004`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` calls `definePlayer({ machine: authMachine })`, starts the actor, and mounts the Vue app.
+1. `src/main.ts` creates the page's inspector with `createDemoInspector()`, calls `definePlayer({ machine: authMachine, options: { inspect: inspector.inspect } })`, starts the actor, provides both `actor` and `inspector` to the app, and mounts it.
 2. The actor is provided to all components via `app.provide("actor", actor)`.
-3. `src/App.vue` injects the actor, declares a typed `ComponentsMap<typeof authCatalog>` for `demoViews`, and builds the `registryResult` with `defineRegistry(authCatalog, { components: demoViews, actions })` inside `computed` — action handlers use `satisfies ActionFn` for catalog-typed safety and dispatch to `actor.send()`.
+3. `src/App.vue` injects the actor and builds the `registryResult` inside `computed` with `defineRegistry(authCatalog, { components: demoComponents, actions: createAuthActionHandlers(typedActor) })` — the component map lives once in `src/components/demo-components.ts` (shared with the router demos) and the handlers dispatch to `actor.send()`.
 4. `<PlayUIProvider :actor="typedActor" :registryResult="registryResult"><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
-5. A `NavBar` SFC observes `actor` signals directly for nav visibility.
-6. `<DebugPanel :actor="typedActor" />` shows live state, auth status, and current route.
+5. A `NavBar` SFC observes `actor` atoms directly for nav visibility.
+6. `<DebugPanel :actor="typedActor" :inspector="inspector" />` shows live state, auth status, and current route, plus the **Show Inspector** button.
 7. HMR cleanup calls `actor.stop()` via `import.meta.hot.dispose`.
 8. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```ts
 // src/main.ts
-const createPlayer = definePlayer({ machine: authMachine });
+const inspector = createDemoInspector();
+const createPlayer = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
+});
 const actor = createPlayer() as AuthActor;
 actor.start();
 
 const app = createApp(App);
 app.provide("actor", actor);
+app.provide("inspector", inspector);
 app.mount("#app");
 ```
 
@@ -56,41 +68,12 @@ import type { ComponentsMap } from "@xmachines/play-vue";
 import type { ActionFn } from "@xmachines/json-render-vue";
 
 const typedActor = assertNonNullable(inject<AuthActor>("actor"), "actor");
-
-const demoViews: ComponentsMap<typeof authCatalog> = {
-	Home: HomeSFC,
-	About: AboutSFC,
-	Contact: ContactSFC,
-	Login: LoginSFC,
-	Dashboard: DashboardSFC,
-	Overview: OverviewSFC,
-	Stats: StatsSFC,
-	Profile: ProfileSFC,
-	Settings: SettingsSFC,
-	Navigation: NavigationSFC,
-	NavBar: NavBarViewSFC,
-};
+const inspector = assertNonNullable(inject<DemoInspector>("inspector"), "inspector");
 
 const registryResult = computed(() =>
 	defineRegistry(authCatalog, {
-		components: demoViews,
-		actions: {
-			login: (async (args) => {
-				typedActor.send({
-					type: "auth.login",
-					username: assertNonNullable(args, "args").username,
-				});
-			}) satisfies ActionFn<typeof authCatalog, "login">,
-			logout: async () => typedActor.send({ type: "auth.logout" }),
-			route: (async (args) => {
-				const { to, params } = assertNonNullable(args, "args");
-				typedActor.send({
-					type: "play.route",
-					to,
-					...(params != null && { params }),
-				});
-			}) satisfies ActionFn<typeof authCatalog, "route">,
-		},
+		components: demoComponents, // one shared map — Home…NavBar plus the 0.20 Panel/Field/Button leaves
+		actions: createAuthActionHandlers(typedActor), // login/logout/route + task events + form actions
 	}),
 );
 </script>
@@ -106,7 +89,7 @@ const registryResult = computed(() =>
 				<PlayRenderer />
 			</PlayUIProvider>
 		</main>
-		<DebugPanel :actor="typedActor" />
+		<DebugPanel :actor="typedActor" :inspector="inspector" />
 	</div>
 </template>
 ```
@@ -126,20 +109,18 @@ const registryResult = computed(() =>
 The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** View components dispatch `auth.login` and `auth.logout` events to the actor. The actor evaluates guards and transitions — Vue never decides which view to render.
-2. **Passive Infrastructure:** `PlayRenderer` observes `actor.currentView` signals only. It holds no business state and makes no routing decisions.
-3. **Signal-Only Reactivity:** The bridge leverages Vue's reactivity model internally to react precisely when actor signals update, without polluting the component tree with reactive refs holding business state.
+2. **Passive Infrastructure:** `PlayRenderer` observes `actor.currentView` atoms only. It holds no business state and makes no routing decisions.
+3. **Atom-Only Reactivity:** The bridge leverages Vue's reactivity model internally to react precisely when actor atoms update, without polluting the component tree with reactive refs holding business state.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher lifecycle used across all `@xmachines` framework adapters:
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and sync Vue-local render state
-5. Re-arm with `watch()`/`watch(...signals)`
+1. The atom notifies the subscription, synchronously, from the `set` that changed it
+2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
+3. The microtask reads the actor atoms and syncs Vue-local render state
 
-Watcher notifications are one-shot. Cleanup is explicit: `actor.stop()` is called during HMR disposal, and `PlayRenderer` handles internal watcher teardown natively on component unmount.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `actor.stop()` is called during HMR disposal, and `PlayRenderer` handles internal watcher teardown natively on component unmount.
 
 ## Adapter Boundaries
 
@@ -157,21 +138,11 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-vue-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-vue-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-vue-demo run test
-pnpm --filter @xmachines/play-vue-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
-
 ## Learn More
 
 - [Vue](../../../api/@xmachines/play-vue/README.md)
 - [Vue Router](../play-vue-router-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
 
 ## Type Aliases
 
@@ -181,3 +152,8 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 - [App](variables/App.md)
 - [authCatalog](variables/authCatalog.md)
+- [demoComponents](variables/demoComponents.md)
+
+## Functions
+
+- [createAuthActionHandlers](functions/createAuthActionHandlers.md)

package/examples/@xmachines/play-vue-demo/functions/createAuthActionHandlers.md

@@ -0,0 +1,35 @@
+[Examples](../../../README.md) / [@xmachines/play-vue-demo](../README.md) / createAuthActionHandlers
+
+# Function: createAuthActionHandlers()
+
+```ts
+function createAuthActionHandlers(actor): object;
+```
+
+Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L48)
+
+Build the demo action handler map for one actor.
+
+Returned functions use the `(params, setState) => Promise<void>` shape every
+framework's `defineRegistry` accepts; spread the result into its `actions`.
+
+## Parameters
+
+| Parameter | Type        |
+| --------- | ----------- |
+| `actor`   | `AuthActor` |
+
+## Returns
+
+`object`
+
+| Name             | Type                                                    | Defined in                                                                                                                                                               |
+| ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L65) |
+| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L72) |
+| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L50) |
+| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L54) |
+| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L81) |
+| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L99) |
+| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L55) |
+| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-actor/examples/shared/src/actions.ts#L92) |

package/examples/@xmachines/play-vue-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-vue/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-vue/examples/demo/src/catalog.ts#L6)

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

@@ -6,4 +6,4 @@
 const App: DefineComponent<{}, {}, unknown>;
 ```
 
-Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-vue/examples/demo/src/env.d.ts#L5)
+Defined in: [packages/play-vue/examples/demo/src/env.d.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-vue/examples/demo/src/env.d.ts#L5)