@xmachines/docs 5.0.0 → 5.0.2

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

@@ -1,18 +1,19 @@
 [Examples](../../README.md) / @xmachines/play-dom-router-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-dom-router-demo
 
 Pure TypeScript integration demo for [`@xmachines/play-dom-router`](../../../api/@xmachines/play-dom-router/README.md) — actor-authoritative routing with the Browser History API and no framework.
 
+[![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` + `createBrowserHistory` wiring actor ↔ browser History API
 - Shell-driven DOM rendering via `connectRenderer` with actor-authoritative navigation
-- Manual TC39 Signal watcher lifecycle — the mechanism that framework adapters abstract
+- Manual atom watcher lifecycle — the mechanism that framework adapters abstract
 - 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
 
@@ -29,10 +30,10 @@ Then open `http://localhost:3005`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` looks up the host element (throws if absent), calls `initApp(app)` from `src/runtime.ts`, and registers unload cleanup.
-2. `src/runtime.ts` creates the actor from the shared machine via `definePlayer`, starts it, initializes router sync via `initRouter(actor)`, mounts the shared DOM shell via `initShell(actor, host)`, and returns one cleanup function.
+1. `src/main.ts` looks up the host element (throws if absent) and calls `initApp(app)` from `src/runtime.ts`. It tears nothing down at the end of the page, because the browser frees the page.
+2. `src/runtime.ts` creates the page's inspector with `createDemoInspector()`, creates the actor from the shared machine via `definePlayer` with `options.inspect` wired to it, starts it, initializes router sync via `initRouter(actor)`, mounts the shared DOM shell via `initShell(actor, host, inspector)`, and returns one cleanup function.
 3. `initRouter(actor)` from `src/router.ts` extracts route metadata, creates a browser history wrapper, instantiates a router, and calls `connectRouter` to wire bidirectional actor ↔ URL sync.
-4. `initShell(actor, host)` is imported from `@xmachines/play-dom-demo`, so the router demo reuses the shared DOM shell instead of duplicating the scaffold and renderer wiring.
+4. `initShell(actor, host, inspector)` is imported from [`@xmachines/play-dom-demo`](../play-dom-demo/README.md), so the router demo reuses the shared DOM shell — inspector button included — instead of duplicating the scaffold and renderer wiring.
 5. Navigation buttons and links dispatch `play.route`, `auth.login`, and `auth.logout` events directly to the actor — no URL mutations from the shell.
 6. Browser tests in `test/browser/` validate startup rendering and the full auth route flow.
 
@@ -41,16 +42,15 @@ Use this order to understand the implementation:
 const app = document.getElementById("app");
 if (!app) throw new Error("Root element not found");
 
-const cleanup = initApp(app);
-
-window.addEventListener("beforeunload", () => {
-	cleanup();
-});
+// The app lives as long as the page, so the demo never tears it down: the browser frees
+// it with the page. `initApp` returns a cleanup function for a host that removes the app
+// before the page ends.
+initApp(app);
 ```
 
 ```ts
 // src/router.ts (shape)
-export function initRouter(actor) {
+export function initRouter(actor: RoutableActor) {
 	const routeTree = extractMachineRoutes(authMachine);
 	const routeMap = createRouteMap(authMachine);
 	const history = createBrowserHistory({ window });
@@ -67,12 +67,16 @@ export function initRouter(actor) {
 ```ts
 // src/runtime.ts (shape)
 export function initApp(host: HTMLElement): () => void {
-	const createPlayer = definePlayer({ machine: authMachine });
+	const inspector = createDemoInspector();
+	const createPlayer = definePlayer({
+		machine: authMachine,
+		options: { inspect: inspector.inspect },
+	});
 	const actor = createPlayer();
 	actor.start();
 
 	const cleanupRouter = initRouter(actor);
-	const cleanupShell = initShell(actor, host);
+	const cleanupShell = initShell(actor, host, inspector);
 
 	return () => {
 		cleanupShell();
@@ -84,10 +88,10 @@ export function initApp(host: HTMLElement): () => void {
 
 ## Key Files
 
-- `src/main.ts` - host lookup, app bootstrap, and unload cleanup
+- `src/main.ts` - host lookup and app bootstrap
 - `src/runtime.ts` - actor startup, router initialization, and shared shell wiring
 - `src/router.ts` - `createBrowserHistory`, `createRouter`, and `connectRouter` wiring
-- `@xmachines/play-dom-demo` - shared DOM shell, NavBar, DebugPanel, and renderer wiring reused by this router demo
+- [`@xmachines/play-dom-demo`](../play-dom-demo/README.md) - shared DOM shell, NavBar, DebugPanel (including the **Show Inspector** button), and renderer wiring reused by this router demo
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/shared-demo.browser.test.ts` - startup rendering and full auth route browser flow
 
@@ -97,19 +101,17 @@ The demo utilizes XMachines architectural invariants at the lowest level:
 
 1. **Actor Authority:** Intercepting browser `popstate` events or navigation button clicks dispatches a `play.route` event to the actor. The actor processes the request against the current state, ensuring any auth logic is correctly applied.
 2. **Passive Infrastructure:** The router simply updates `window.history` and the DOM solely renders HTML based on what `actor.currentView` yields. Neither holds business state.
-3. **Signal-Only Reactivity:** The integration registers `watchSignal` observers that trigger DOM reconciliation, illustrating the underlying mechanism that framework adapters abstract.
+3. **Atom-Only Reactivity:** The integration registers `watchAtom` observers that trigger DOM reconciliation, illustrating the underlying mechanism that framework adapters abstract.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 Even in the vanilla demo, watcher handling follows the canonical lifecycle:
 
-1. `notify`
-2. `queueMicrotask`
-3. `getPending()`
-4. Read actor signals and project DOM 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 DOM state
 
-Watcher notifications are one-shot, so re-arm is mandatory. Router/shell teardown must explicitly call cleanup (`disconnect`/`unwatch`) and not rely on GC-only behavior. In vanilla TypeScript, this means retaining cleanup functions and calling them on `beforeunload` or during hot-module replacement.
+One subscription lives for the whole watch, and no caller arms a watcher again. Router/shell teardown must explicitly call cleanup (`disconnect`/`unwatch`) and not rely on GC-only behavior. In vanilla TypeScript, keep the cleanup functions, and call them when the app ends before the page does, or during hot-module replacement. Do not call them on `beforeunload`: that event also fires when the page goes into the back/forward cache, and Back then shows a page that does not respond. At the end of the page, the browser frees everything.
 
 ## Adapter Boundaries
 
@@ -127,19 +129,9 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-dom-router-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-dom-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-dom-router-demo run test
-pnpm --filter @xmachines/play-dom-router-demo run test:browser
-```
-
-Expected result: tests pass, including startup rendering and the full browser auth flow in `test/browser/`.
-
 ## Learn More
 
 - [Play DOM Router](../../../api/@xmachines/play-dom-router/README.md)
 - [Play DOM](../play-dom-demo/README.md)
 - [Play Router](../../../api/@xmachines/play-router/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -1,18 +1,24 @@
 [Examples](../../README.md) / @xmachines/play-react-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-react-demo
 
 React renderer demo for [`@xmachines/play-react`](../../../api/@xmachines/play-react/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 `play.route` routing
-- Canonical TC39 Signals lifecycle surfaced through React's rendering model
+- Canonical atoms lifecycle surfaced through React's rendering model
 - 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
 
@@ -30,11 +36,11 @@ Then open `http://localhost:3001`.
 Use this order to understand the implementation:
 
 1. `src/main.tsx` mounts `<App />`.
-2. `src/App.tsx` creates the actor at module scope via `definePlayer({ machine: authMachine })()` — created once when the module is first evaluated.
+2. `src/App.tsx` creates the page's inspector with `createDemoInspector()` and the actor at module scope via `definePlayer({ machine: authMachine, options: { inspect: inspector.inspect }, actor: compose(PlayerActor, withRouting, withView) })()` — both created once when the module is first evaluated.
 3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
 4. `<PlayUIProvider actor={actor} registryResult={registryResult}><PlayRenderer /></PlayUIProvider>` observes `actor.currentView` and renders the active spec.
-5. A `NavBar` component observes `actor` signals directly for nav visibility.
-6. `<DebugPanel actor={actor} />` shows live state, auth status, and current route.
+5. A `NavBar` component observes `actor` atoms directly for nav visibility.
+6. `<DebugPanel actor={actor} inspector={inspector} />` shows live state, auth status, and current route, plus the **Show Inspector** button.
 7. Browser tests in `test/browser/` validate startup and interaction behavior.
 
 ```tsx
@@ -46,39 +52,17 @@ createRoot(document.getElementById("root")!).render(<App />);
 // src/App.tsx (shape)
 // Both actor and registryResult are module-scope singletons — created once,
 // never recreated, no useMemo needed inside the component.
-const actor: AuthActor = definePlayer({ machine: authMachine })();
+const inspector = createDemoInspector();
+const actor: AuthActor = definePlayer({
+	machine: authMachine,
+	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
+})();
 actor.start();
 
 const registryResult = defineRegistry(authCatalog, {
-	components: {
-		Home,
-		About,
-		Contact,
-		Login,
-		Dashboard,
-		Overview,
-		Stats,
-		Profile,
-		Settings,
-		Navigation,
-		NavBar: NavBarView,
-	},
-	actions: {
-		login: async (args) =>
-			actor.send({
-				type: "auth.login",
-				username: assertNonNullable(args, "args").username,
-			}),
-		logout: async () => actor.send({ type: "auth.logout" }),
-		route: async (args) => {
-			const { to, params } = assertNonNullable(args, "args");
-			actor.send({
-				type: "play.route",
-				to,
-				...(params != null && { params }),
-			});
-		},
-	},
+	components: demoComponents, // one shared map — Home…NavBar plus the 0.20 Panel/Field/Button leaves
+	actions: createAuthActionHandlers(actor), // login/logout/route + task events + form actions
 });
 
 export function App() {
@@ -93,7 +77,7 @@ export function App() {
 					<PlayRenderer />
 				</PlayUIProvider>
 			</main>
-			<DebugPanel actor={actor} />
+			<DebugPanel actor={actor} inspector={inspector} />
 		</div>
 	);
 }
@@ -113,20 +97,18 @@ export function App() {
 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 — React 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 React's rendering model to react precisely when actor signals update, without polluting the component tree with `useState` or `useEffect` for business logic.
+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 React's rendering model to react precisely when actor atoms update, without polluting the component tree with `useState` or `useEffect` 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 React 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 React render state
 
-Watcher notifications are one-shot. Cleanup is explicit: `actor.stop()` is called on component unmount via `useEffect`, and `PlayRenderer` handles internal watcher teardown natively.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `actor.stop()` is called on component unmount via `useEffect`, and `PlayRenderer` handles internal watcher teardown natively.
 
 ## Adapter Boundaries
 
@@ -144,21 +126,11 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-react-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-react-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-react-demo run test
-pnpm --filter @xmachines/play-react-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
-
 ## Learn More
 
 - [play-react](../../../api/@xmachines/play-react/README.md)
 - [React Router demo](../play-react-router-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
 
 ## Type Aliases
 
@@ -168,15 +140,19 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 - [About](variables/About.md)
 - [authCatalog](variables/authCatalog.md)
+- [Button](variables/Button.md)
 - [Contact](variables/Contact.md)
 - [Dashboard](variables/Dashboard.md)
 - [DebugPanel](variables/DebugPanel.md)
+- [demoComponents](variables/demoComponents.md)
+- [Field](variables/Field.md)
 - [Home](variables/Home.md)
 - [Login](variables/Login.md)
 - [NavBar](variables/NavBar.md)
 - [NavBarView](variables/NavBarView.md)
 - [Navigation](variables/Navigation.md)
 - [Overview](variables/Overview.md)
+- [Panel](variables/Panel.md)
 - [Profile](variables/Profile.md)
 - [Settings](variables/Settings.md)
 - [Shell](variables/Shell.md)
@@ -184,4 +160,4 @@ Expected result: library-pattern invariant tests pass and the browser renderer s
 
 ## Functions
 
-- [App](functions/App.md)
+- [createAuthActionHandlers](functions/createAuthActionHandlers.md)

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

@@ -0,0 +1,35 @@
+[Examples](../../../README.md) / [@xmachines/play-react-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.2/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.2/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.2/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.2/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.2/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.2/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.2/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.2/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.2/packages/play-actor/examples/shared/src/actions.ts#L92) |

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

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

package/examples/@xmachines/play-react-demo/variables/About.md

@@ -6,9 +6,9 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/About.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/About.tsx#L10)
+Defined in: [packages/play-react/examples/demo/src/components/About.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/About.tsx#L10)
 
 About — Public information page
 
 Uses ComponentFn<AuthCatalog, "About"> for catalog-typed props.
-Navigation is handled by HeaderNav — this component only renders content.
+NavBar handles the navigation — this component only renders content.

package/examples/@xmachines/play-react-demo/variables/Button.md

@@ -0,0 +1,12 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Button
+
+# Variable: Button
+
+```ts
+const Button: ComponentFn<AuthCatalog, "Button">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Button.tsx:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Button.tsx#L8)
+
+Button — emits `press`; the spec's `on.press` binding decides what happens
+(a host action sending a machine event, or a built-in like setState).

package/examples/@xmachines/play-react-demo/variables/Contact.md

@@ -6,9 +6,9 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Contact.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Contact.tsx#L10)
+Defined in: [packages/play-react/examples/demo/src/components/Contact.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Contact.tsx#L10)
 
 Contact — Public contact page
 
 Uses ComponentFn<AuthCatalog, "Contact"> for catalog-typed props.
-Navigation is handled by HeaderNav — this component only renders content.
+NavBar handles the navigation — this component only renders content.

package/examples/@xmachines/play-react-demo/variables/Dashboard.md

@@ -6,10 +6,10 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Dashboard.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Dashboard.tsx#L12)
+Defined in: [packages/play-react/examples/demo/src/components/Dashboard.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Dashboard.tsx#L12)
 
 Dashboard — Protected authenticated home
 
 Uses ComponentFn<AuthCatalog, "Dashboard"> for catalog-typed props.
 Emits "logout" to trigger the auth.logout event via PlayRenderer actions map.
-Navigation is handled by HeaderNav — this component only handles auth actions.
+NavBar handles the navigation — this component only handles auth actions.

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

@@ -5,11 +5,12 @@
 ```ts
 const DebugPanel: FC<{
 	actor: AuthActor;
+	inspector: DemoInspector;
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/DebugPanel.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/DebugPanel.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/DebugPanel.tsx#L12)
 
 DebugPanel — Live debug footer. Observes actor.state and actor.currentRoute
-via useSignalEffect and displays current state value, can-logout status,
-and active route.
+via useAtomEffect and displays current state value, can-logout status,
+and active route, plus the button that opens the Stately inspector window.

package/examples/@xmachines/play-react-demo/variables/Field.md

@@ -0,0 +1,18 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Field
+
+# Variable: Field
+
+```ts
+const Field: ComponentFn<AuthCatalog, "Field">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Field.tsx:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Field.tsx#L15)
+
+Field — labelled input with two-way $bindState binding and declarative
+validation checks.
+
+Registration happens by rendering: useFieldValidation registers the bound
+state path with the ValidationProvider so the `validateForm` built-in sees
+it. The error DISPLAY deliberately reads `props.formErrors` — the result
+object validateForm wrote to state — rather than the local hook, so every
+renderer (DOM included) surfaces errors at the same moment: after submit.

package/examples/@xmachines/play-react-demo/variables/Home.md

@@ -6,9 +6,9 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Home.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Home.tsx#L10)
+Defined in: [packages/play-react/examples/demo/src/components/Home.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Home.tsx#L10)
 
 Home - Public landing page component
 
 Uses ComponentFn<AuthCatalog, "Home"> for catalog-typed props.
-Navigation is handled by HeaderNav — this component only renders content.
+NavBar handles the navigation — this component only renders content.

package/examples/@xmachines/play-react-demo/variables/Login.md

@@ -6,7 +6,7 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Login.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Login.tsx#L14)
+Defined in: [packages/play-react/examples/demo/src/components/Login.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Login.tsx#L14)
 
 Login — Authentication form
 

package/examples/@xmachines/play-react-demo/variables/NavBar.md

@@ -8,7 +8,7 @@ const NavBar: FC<{
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/NavBar.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/NavBar.tsx#L12)
+Defined in: [packages/play-react/examples/demo/src/components/NavBar.tsx:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/NavBar.tsx#L12)
 
 NavBar — App-shell navigation component.
 

package/examples/@xmachines/play-react-demo/variables/NavBarView.md

@@ -6,7 +6,7 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/NavBarView.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/NavBarView.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/NavBarView.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/NavBarView.tsx#L11)
 
 NavBarView — Catalog-typed NavBar for use in defineRegistry components map.
 

package/examples/@xmachines/play-react-demo/variables/Navigation.md

@@ -6,9 +6,9 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Navigation.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Navigation.tsx#L10)
+Defined in: [packages/play-react/examples/demo/src/components/Navigation.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Navigation.tsx#L10)
 
 Navigation - Status display component
 
 Uses ComponentFn<AuthCatalog, "Navigation"> for catalog-typed props.
-This component displays navigation state info. Actual navigation is handled by HeaderNav.
+This component displays navigation state info. NavBar handles the actual navigation.

package/examples/@xmachines/play-react-demo/variables/Overview.md

@@ -6,7 +6,7 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Overview.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Overview.tsx#L10)
+Defined in: [packages/play-react/examples/demo/src/components/Overview.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Overview.tsx#L10)
 
 Overview - Dashboard overview child route component
 

package/examples/@xmachines/play-react-demo/variables/Panel.md

@@ -0,0 +1,15 @@
+[Examples](../../../README.md) / [@xmachines/play-react-demo](../README.md) / Panel
+
+# Variable: Panel
+
+```ts
+const Panel: ComponentFn<AuthCatalog, "Panel">;
+```
+
+Defined in: [packages/play-react/examples/demo/src/components/Panel.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Panel.tsx#L11)
+
+Panel — generic container leaf for the 0.20 showcase.
+
+Renders an optional title and note, then its spec `children` — which is how
+repeat containers work: the element renders ONCE and its children render per
+item, so a Panel is both the list shell and the row.

package/examples/@xmachines/play-react-demo/variables/Profile.md

@@ -6,9 +6,9 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Profile.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Profile.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Profile.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Profile.tsx#L11)
 
 Profile — Protected user profile page
 
 Uses ComponentFn<AuthCatalog, "Profile"> for catalog-typed props.
-Navigation is handled by HeaderNav — this component only renders content.
+NavBar handles the navigation — this component only renders content.

package/examples/@xmachines/play-react-demo/variables/Settings.md

@@ -6,9 +6,9 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Settings.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Settings.tsx#L11)
+Defined in: [packages/play-react/examples/demo/src/components/Settings.tsx:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Settings.tsx#L11)
 
 Settings — Protected settings page
 
 Uses ComponentFn<AuthCatalog, "Settings"> for catalog-typed props.
-Navigation is handled by HeaderNav — this component only renders content.
+NavBar handles the navigation — this component only renders content.

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

@@ -5,12 +5,13 @@
 ```ts
 const Shell: FC<{
 	actor: AuthActor;
+	inspector: DemoInspector;
 	registryResult: DefineRegistryResult;
 	router?: unknown;
 }>;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Shell.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Shell.tsx#L14)
+Defined in: [packages/play-react/examples/demo/src/components/Shell.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Shell.tsx#L14)
 
 Demo Shell layout component.
 

package/examples/@xmachines/play-react-demo/variables/Stats.md

@@ -6,7 +6,7 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [packages/play-react/examples/demo/src/components/Stats.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-react/examples/demo/src/components/Stats.tsx#L10)
+Defined in: [packages/play-react/examples/demo/src/components/Stats.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-react/examples/demo/src/components/Stats.tsx#L10)
 
 Stats - Dashboard stats child route component