@xmachines/docs 5.0.0 → 5.0.2

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/examples/form-validation.md

@@ -288,11 +288,14 @@ actor.start();
 
 const disconnect = mount(actor, document.getElementById("app")!);
 
-// Cleanup
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnect();
 	actor.stop();
-});
+}
 ```
 
 **Key points:**

package/examples/multi-router-integration.md

@@ -300,13 +300,16 @@ const registryResult = defineRegistry(authCatalog, {
 const mount = createPlayUI(registryResult);
 const disconnectRenderer = mount(actor, document.getElementById("app")!);
 
-// Cleanup
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnect();
 	router.destroy();
 	disconnectRenderer();
 	actor.stop();
-});
+}
 ```
 
 ### SvelteKit (`@xmachines/play-sveltekit-router`)

package/examples/routing-patterns.md

@@ -256,11 +256,14 @@ const router = createRouter({ routeTree: authMachine, history });
 // - browser URL changes → play.route event sent to actor
 const disconnect = connectRouter({ actor, router, routeMap });
 
-// Cleanup on unload
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnect();
 	router.destroy();
-});
+}
 ```
 
 ## React Router Setup

package/guides/getting-started.md

@@ -457,12 +457,15 @@ actor.start();
 
 const disconnectRouter = connectRouter({ actor, router, routeMap });
 
-// Cleanup on unload
-window.addEventListener("beforeunload", () => {
+// Call teardown() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
+// A teardown on `beforeunload` also runs when the page goes into the back/forward cache,
+// and Back then shows a page that does not respond.
+function teardown(): void {
 	disconnectRouter();
 	router.destroy();
 	actor.stop();
-});
+}
 ```
 
 ---
@@ -634,7 +637,8 @@ const registryResult = defineRegistry(catalog, {
 const mount = createPlayUI(registryResult);
 const disconnect = mount(actor, document.getElementById("app")!);
 
-window.addEventListener("beforeunload", () => disconnect());
+// Call disconnect() when the app ends before the page does, for example when the component
+// that holds it unmounts. At the end of the page, do nothing: the browser frees the page.
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -50,6 +50,7 @@
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "typedoc": "typedoc",
+    "test:generated": "vitest run --config vitest.generated.config.ts",
     "test": "vitest run",
     "clean": "rm -rf coverage node_modules/.vite*"
   },

package/examples/@xmachines/play-react-demo/functions/App.md

@@ -1,13 +0,0 @@
-[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / App
-
-# Function: App()
-
-```ts
-function App(): Element;
-```
-
-Defined in: [packages/play-react/examples/demo/src/App.tsx:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/App.tsx#L68)
-
-## Returns
-
-`Element`

package/examples/@xmachines/play-react-demo/functions/DebugPanel.md

@@ -1,20 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-react-demo](../README.md) / DebugPanel
-
-# Function: DebugPanel()
-
-```ts
-function DebugPanel(__namedParameters): Element;
-```
-
-Defined in: [components/DebugPanel.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L5)
-
-## Parameters
-
-| Parameter                 | Type                        |
-| ------------------------- | --------------------------- |
-| `__namedParameters`       | \{ `actor`: `AuthActor`; \} |
-| `__namedParameters.actor` | `AuthActor`                 |
-
-## Returns
-
-`Element`

package/examples/@xmachines/play-react-demo/functions/HeaderNav.md

@@ -1,20 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-react-demo](../README.md) / HeaderNav
-
-# Function: HeaderNav()
-
-```ts
-function HeaderNav(__namedParameters): Element;
-```
-
-Defined in: [components/HeaderNav.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-react/examples/demo/src/components/HeaderNav.tsx#L13)
-
-## Parameters
-
-| Parameter                 | Type                        |
-| ------------------------- | --------------------------- |
-| `__namedParameters`       | \{ `actor`: `AuthActor`; \} |
-| `__namedParameters.actor` | `AuthActor`                 |
-
-## Returns
-
-`Element`

package/examples/@xmachines/play-react-demo/functions/Shell.md

@@ -1,22 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Shell
-
-# Function: Shell()
-
-```ts
-function Shell(__namedParameters): Element;
-```
-
-Defined in: [components/Shell.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-react/examples/demo/src/components/Shell.tsx#L14)
-
-## Parameters
-
-| Parameter                    | Type                                                                               | Description                                                                      |
-| ---------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `__namedParameters`          | \{ `actor`: `AuthActor`; `registry`: `ComponentRegistry`; `router?`: `unknown`; \} | -                                                                                |
-| `__namedParameters.actor`    | `AuthActor`                                                                        | -                                                                                |
-| `__namedParameters.registry` | `ComponentRegistry`                                                                | -                                                                                |
-| `__namedParameters.router?`  | `unknown`                                                                          | Bridged router instance — accepted for prop parity with router demos but unused. |
-
-## Returns
-
-`Element`

package/examples/@xmachines/play-solid-demo/functions/App.md

@@ -1,13 +0,0 @@
-[Examples](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / App
-
-# Function: App()
-
-```ts
-function App(): Element;
-```
-
-Defined in: [packages/play-solid/examples/demo/src/App.tsx:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-solid/examples/demo/src/App.tsx#L34)
-
-## Returns
-
-`Element`

package/examples/@xmachines/play-solid-demo/functions/DebugPanel.md

@@ -1,20 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / DebugPanel
-
-# Function: DebugPanel()
-
-```ts
-function DebugPanel(props): Element;
-```
-
-Defined in: [components/DebugPanel.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-solid/examples/demo/src/components/DebugPanel.tsx#L5)
-
-## Parameters
-
-| Parameter     | Type                        |
-| ------------- | --------------------------- |
-| `props`       | \{ `actor`: `AuthActor`; \} |
-| `props.actor` | `AuthActor`                 |
-
-## Returns
-
-`Element`

package/examples/@xmachines/play-solid-demo/functions/HeaderNav.md

@@ -1,20 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / HeaderNav
-
-# Function: HeaderNav()
-
-```ts
-function HeaderNav(props): Element;
-```
-
-Defined in: [components/HeaderNav.tsx:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-solid/examples/demo/src/components/HeaderNav.tsx#L5)
-
-## Parameters
-
-| Parameter     | Type                        |
-| ------------- | --------------------------- |
-| `props`       | \{ `actor`: `AuthActor`; \} |
-| `props.actor` | `AuthActor`                 |
-
-## Returns
-
-`Element`

package/examples/@xmachines/play-solid-demo/functions/Shell.md

@@ -1,22 +0,0 @@
-[Documentation](../../../README.md) / [@xmachines/play-solid-demo](../README.md) / Shell
-
-# Function: Shell()
-
-```ts
-function Shell(props): Element;
-```
-
-Defined in: [components/Shell.tsx:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/c1160fb00ac900a09815213d9ed6bef8b9f03da6/packages/play-solid/examples/demo/src/components/Shell.tsx#L7)
-
-## Parameters
-
-| Parameter        | Type                                                                               | Description                                                                      |
-| ---------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `props`          | \{ `actor`: `AuthActor`; `registry`: `ComponentRegistry`; `router?`: `unknown`; \} | -                                                                                |
-| `props.actor`    | `AuthActor`                                                                        | -                                                                                |
-| `props.registry` | `ComponentRegistry`                                                                | -                                                                                |
-| `props.router?`  | `unknown`                                                                          | Bridged router instance — accepted for prop parity with router demos but unused. |
-
-## Returns
-
-`Element`