@xmachines/docs 5.0.0 → 5.0.1

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

@@ -1,18 +1,19 @@
 [Examples](../../README.md) / @xmachines/play-vue-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-vue-router-demo
 
 Vue Router integration demo for the XMachines Play architecture using Vue Composition API.
 
+[![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 Vue Router
 - Shell-driven rendering via `PlayRenderer` with actor-authoritative navigation
-- Vue Composition API mapping to TC39 Signals lifecycle
+- Vue Composition API mapping to atoms lifecycle
 - 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 how the demo is wired:
 2. `src/runtime.ts` creates the actor, starts it, builds the shared `registryResult`, 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, and registry as props.
+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.
 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.
 
@@ -55,7 +56,7 @@ export const routes = [{ path: "/:pathMatch(.*)*", name: "xmachines-play", compo
 import { actor, routeMap, registryResult } from "./runtime.js";
 
 const renderShell = (currentActor, currentRouter) =>
-	h(SharedShell, { actor: currentActor, router: currentRouter, registryResult });
+	h(SharedShell, { actor: currentActor, router: currentRouter, registryResult, inspector });
 </script>
 
 <template>
@@ -92,19 +93,17 @@ The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** When a user navigates to a protected route via a link, Vue Router updates the location. 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 transitions.
 2. **Passive Infrastructure:** The router does not execute Vue route guards for business logic. The actor dictates whether navigation is permitted. The Vue application only renders the state.
-3. **Signal-Only Reactivity:** The bridge leverages Vue's `watch` and `triggerRef` internally to react precisely when signals update, without polluting the Vue component tree with reactive refs that hold business state.
+3. **Atom-Only Reactivity:** The bridge leverages Vue's `watch` and `triggerRef` internally to react precisely when atoms update, without polluting the Vue component tree with reactive refs that hold business state.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher lifecycle:
 
-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
 
-Notifications are one-shot, so re-arm is required. Teardown is explicit: provider/bridge cleanup must flow through `disconnect` and watcher `unwatch`, not GC-only assumptions. The `PlayRouterProvider` wires this seamlessly into the component's `onUnmounted` hook.
+One subscription lives for the whole watch, and no caller arms a watcher again. Teardown is explicit: provider/bridge cleanup must flow through `disconnect` and watcher `unwatch`, not GC-only assumptions. The `PlayRouterProvider` wires this seamlessly into the component's `onUnmounted` hook.
 
 ## Adapter Boundaries
 
@@ -122,18 +121,8 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-vue-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-vue-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-vue-router-demo run test
-pnpm --filter @xmachines/play-vue-router-demo run test:browser
-```
-
-Expected result: reactivity integration tests and the browser shared-demo suite both pass, confirming login/logout transitions update both view and URL correctly.
-
 ## Learn More
 
 - [Vue Router](../../../api/@xmachines/play-vue-router/README.md)
 - [Vue](../../../api/@xmachines/play-vue/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",