@xmachines/docs 5.0.0 → 5.0.2

package/contributing/deployment.md

@@ -88,13 +88,27 @@ That job publishes the JUnit results as `reports/test-results.xml` and the Cober
 
 ### Docs Job
 
-The `docs` job runs `pnpm run docs` — the full build, then TypeDoc, then the formatter. It runs automatically on `main` and it waits for a click on a merge request. It declares `needs: []`, because it compiles what it documents.
+The `docs` job runs `pnpm run docs` — the full build, then TypeDoc, then the formatter. It runs automatically on `main` and on the merge train, and it waits for a click on a merge request. It declares `needs: []`, because it compiles what it documents.
 
 TypeDoc treats a warning as an error. This job is therefore the gate that reports a `@see` or a `{@link}` that names a symbol a rename removed. Before it existed, `node-build` regenerated the reference on every push, which put a second pass over every package on a branch that is pushed to many times.
 
-The click is a gate, not an option. The job is manual with `allow_failure: false`, so a pipeline that nobody starts it from stays BLOCKED, and the merge check "Pipelines must succeed" holds the merge request. The `release-pack-smoke` job below uses the same rules for the same reason.
+The click blocks nothing on a merge request. The merge train starts the job by itself, so the train is the gate. The `release-pack-smoke` job below uses the same rules for the same reason.
 
-The job declares `stage: test`. A blocking manual job holds every later stage until it runs, so `build` would keep the unit suite, the browser suite and `release-pack-smoke` waiting for a click. Jobs in the same stage are not affected.
+The job declares `stage: test`. A manual job that blocks holds every later stage until it runs, so `build` would keep the unit suite, the browser suite and `release-pack-smoke` waiting for a click. Jobs in the same stage are not affected.
+
+The job archives the two trees that TypeDoc writes as `reports/docs-reference.tar.gz`, and it keeps the archive as an artifact.
+
+### Docs Links Job
+
+The `test:docs` job crawls the reference that the `docs` job generated. It declares `needs: [docs]`, so it starts when `docs` passes. On a merge request it shows `skipped` until someone starts `docs`.
+
+The crawl is `packages/docs/test-generated/links.test.mjs`. It follows every relative link of `api/` and `examples/@xmachines/`, and it checks the file and the anchor of each link. TypeDoc cannot hold this rule: the `routeOutput` plugin moves a demo package to the examples tree after the link validator runs. The job publishes the result as a JUnit report.
+
+The job deletes both trees before it unpacks the archive. GitLab unpacks an artifact over the checkout and deletes no file, and the checkout holds the reference of the last release. Without the delete, a page that TypeDoc no longer writes stays in the checkout, and the crawl reads its links.
+
+The job has the rules of `docs` without the click. A job that needs a job which is absent from the pipeline fails the creation of the pipeline, so the two sets of rules must match. `tests/docs-ci-jobs.test.ts` holds the list of trees equal to the list that the release stages.
+
+To run the same check on your machine, run `pnpm run docs` and then `pnpm run test:docs`.
 
 ### Release Job Detail
 
@@ -166,7 +180,7 @@ node scripts/set-workspace-versions.mjs ${nextRelease.version}
 pnpm run build
 pnpm --filter @xmachines/docs run typedoc --gitRevision v${nextRelease.version}
 pnpm --filter @xmachines/docs run format
-git add -A packages/docs/api
+git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md
 ```
 
 Step by step:
@@ -175,9 +189,9 @@ Step by step:
 2. **Install** — `pnpm install --frozen-lockfile` installs the exact dependency versions recorded in the lockfile.
 3. **Sync versions** — `scripts/set-workspace-versions.mjs` sets the same release version across every `package.json` in the workspace (root + all packages), including cross-package workspace dependency ranges.
 4. **Build** — runs `vite build && tsc --build` to produce compiled `dist/` output — JavaScript then declarations — in all packages.
-5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` at the release git revision.
+5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` and `packages/docs/examples/@xmachines/` at the release git revision. TypeDoc also rewrites the demo lists of `packages/docs/examples/README.md`.
 6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
-7. **Stage the generated docs** — `git add -A packages/docs/api`. The git plugin stages what `git ls-files -m -o` reports, and that never reports a DELETION. A page that TypeDoc removed, because an export was renamed or deleted, therefore stayed in git forever while the docs tarball packed from the working tree was correct. `git add -A` stages the removals, and the git plugin commits the index.
+7. **Stage the generated docs** — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`. The git plugin stages what `git ls-files -m -o` reports, and that never reports a DELETION. A page that TypeDoc removed, because an export was renamed or deleted, therefore stayed in git forever while the docs tarball packed from the working tree was correct. `git add -A` stages the removals, and the git plugin commits the index.
 
 ### Publish Phase
 
@@ -202,6 +216,8 @@ This phase runs on the branch, BEFORE the tag pipeline publishes.
     - `package.json`, `pnpm-lock.yaml` and `pnpm-workspace.yaml` (root)
     - The `package.json` of every scanned package, and the `README.md` of every one — the release stamps the version badge of a README at the same moment as the manifest
     - `packages/docs/api/**` (generated API documentation)
+    - `packages/docs/examples/@xmachines/**` (generated demo documentation)
+    - `packages/docs/examples/README.md` (TypeDoc rewrites its demo lists)
 
     The manifest list and the README list both come from the workspace scan, and not from a glob written by hand, so a package that a new `pnpm-workspace` pattern adds cannot be published while its manifest stays behind in git. A test asserts that every scanned package appears in both lists.
 
@@ -257,7 +273,7 @@ dist/releases/*.tgz
 
 The same tarballs are attached to the GitLab Release entry as permanent downloadable assets. Tarballs are **not committed** to git (the `dist/` directory is gitignored).
 
-The API documentation (`packages/docs/api/`) **is committed** to git by the post-release git commit and is the only generated artifact tracked in version control.
+The post-release git commit **commits** the generated documentation (`packages/docs/api/` and `packages/docs/examples/@xmachines/`) to git. The same commit holds the demo lists that TypeDoc writes into the hand-written `packages/docs/examples/README.md`. It also holds `CHANGELOG.md`, which `@semantic-release/changelog` writes.
 
 ---
 

package/contributing/development.md

@@ -145,6 +145,7 @@ All commands are run from the **repository root** unless otherwise noted.
 | `pnpm run format`                          | Format all files with oxfmt                                               |
 | `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                    |
 | `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                    |
+| `pnpm run test:docs`                       | Check every link of the generated docs (run `pnpm run docs` first)        |
 
 ---
 

package/contributing/migrating-to-play-atom.md

@@ -32,7 +32,7 @@ node codemod-play-atom.mjs --dry-run .
 node codemod-play-atom.mjs .
 ```
 
-The codemod reads `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.vue`, `.svelte`, `.md` and `.json`, so it covers a manifest and a single-file component too. It skips `node_modules`, `dist`, `coverage` and every generated API directory.
+The codemod reads `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.vue`, `.svelte`, `.md` and `.json`, so it covers a manifest and a single-file component too. It skips `node_modules`, `dist`, `coverage` and every directory of generated documentation.
 
 It exits non-zero when it finds a site that needs a human, and it names each one.
 

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

@@ -1,18 +1,24 @@
 [Examples](../../README.md) / @xmachines/play-dom-demo
 
-<!-- generated-by: gsd-doc-writer -->
-
 # @xmachines/play-dom-demo
 
 Vanilla DOM renderer demo for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — actor + `createPlayUI` 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
 - `createPlayUI` wiring `PlayRenderer`-equivalent DOM rendering without a framework
-- Auth machine states (home → login → dashboard) drive DOM updates via TC39 Signal watchers
-- `watchSignal` for reactive nav visibility and debug panel updates
+- Auth machine states (home → login → dashboard) drive DOM updates via atom watchers
+- `watchAtom` for reactive nav visibility and debug panel updates
 - 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,64 +35,45 @@ Then open `http://localhost:3000`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` calls `definePlayer({ machine: authMachine })` and starts the actor.
-2. `initShell(actor, app)` from `src/components/Shell.ts` builds the HTML scaffold, mounts a reactive `NavBar`, wires the debug panel, and returns a disconnect function.
+1. `src/main.ts` creates the page's inspector with `createDemoInspector()`, calls `definePlayer({ machine: authMachine, options: { inspect: inspector.inspect }, actor: compose(PlayerActor, withRouting, withView) })`, and starts the actor.
+2. `initShell(actor, app, inspector)` from `src/components/Shell.ts` builds the HTML scaffold, mounts a reactive `NavBar`, wires the debug panel, and returns a disconnect function.
 3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
 4. `createPlayUI(registryResult)` produces a `mount` function; `mount(actor, container)` wires the registry to the actor — view switches happen automatically when `actor.currentView` changes.
-5. `createNavBar(actor, headerEl)` in `src/components/NavBar.ts` uses `watchSignal(actor.state, ...)` to update nav button visibility based on auth state.
-6. `createDebugPanel(actor, shell)` in `src/components/DebugPanel.ts` uses `watchSignal(actor.state, ...)` and `watchSignal(actor.currentRoute, ...)` to drive live debug panel updates.
+5. `createNavBar(actor, headerEl)` in `src/components/NavBar.ts` uses `watchAtom(actor.state, ...)` to update nav button visibility based on auth state.
+6. `createDebugPanel(actor, shell, inspector)` in `src/components/DebugPanel.ts` uses `watchAtom(actor.state, ...)` and `watchAtom(actor.currentRoute, ...)` to drive live debug panel updates, and renders the **Show Inspector** button that calls `inspector.show()`.
 7. Browser tests in `test/browser/` validate startup rendering and auth interactions.
 
 ```ts
 // src/main.ts (shape)
-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();
 actor.start();
 
 const app = document.getElementById("app");
 if (!app) throw new Error("Root element not found");
 
-initShell(actor, app);
+// The shell and the actor live as long as the page, so the demo never tears them down:
+// the browser frees them with the page. `initShell` returns a disconnect function for a
+// host that removes the shell before the page ends, and the browser tests call it.
+initShell(actor, app, inspector);
 ```
 
 ```ts
 // src/components/Shell.ts (shape)
 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
 });
 
 const disconnectNavBar = createNavBar(actor, headerEl);
-const mount = createPlayUI(registryResult);
+const mount = createPlayUI(registryResult, { onConfirm: createConfirmDialog });
 const disconnectRenderer = mount(actor, viewContent);
-const disconnectDebugPanel = createDebugPanel(actor, shell);
+const disconnectDebugPanel = createDebugPanel(actor, shell, inspector);
 
 return () => {
 	disconnectNavBar();
@@ -99,8 +86,8 @@ return () => {
 
 - `src/main.ts` - actor creation and shell bootstrap
 - `src/components/Shell.ts` - DOM scaffold, `DomRegistry` construction, `createPlayUI` wiring, `createNavBar`, and `createDebugPanel`
-- `src/components/NavBar.ts` - reactive nav bar using `watchSignal(actor.state, ...)` for auth-driven button visibility
-- `src/components/DebugPanel.ts` - live debug footer using `watchSignal` on both `actor.state` and `actor.currentRoute`
+- `src/components/NavBar.ts` - reactive nav bar using `watchAtom(actor.state, ...)` for auth-driven button visibility
+- `src/components/DebugPanel.ts` - live debug footer using `watchAtom` on both `actor.state` and `actor.currentRoute`, plus the **Show Inspector** button
 - `test/library-pattern.test.ts` - architecture boundary and invariant assertions
 - `test/browser/renderer-demo.browser.test.ts` - browser-mode renderer coverage
 
@@ -109,24 +96,22 @@ return () => {
 The demo utilizes XMachines architectural invariants:
 
 1. **Actor Authority:** Navigation buttons dispatch `play.route` events to the actor. The actor evaluates guards and transitions to the correct state — the DOM never decides which view to show.
-2. **Passive Infrastructure:** `createPlayUI` and `watchSignal` only react to actor signals. They do not hold business state or make routing decisions.
-3. **Signal-Only Reactivity:** `watchSignal` (from [`@xmachines/play-signals`](../../../api/@xmachines/play-signals/README.md)) wraps the canonical TC39 Signals watcher lifecycle, keeping all reactivity in the actor signal layer rather than in ad-hoc DOM event listeners.
+2. **Passive Infrastructure:** `createPlayUI` and `watchAtom` only react to actor atoms. They do not hold business state or make routing decisions.
+3. **Atom-Only Reactivity:** `watchAtom` (from [`@xmachines/play-atom`](../../../api/@xmachines/play-atom/README.md)) wraps the canonical atoms watcher lifecycle, keeping all reactivity in the actor atom layer rather than in ad-hoc DOM event listeners.
 
 ## Watcher Lifecycle and Cleanup Contract
 
 This demo follows the canonical watcher 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. Cleanup is explicit: `disconnectNavBar()`, `disconnectRenderer()`, and `disconnectDebugPanel()` are all called from the disconnect function returned by `initShell`. In this demo, cleanup is called on `beforeunload` via `actor.stop()`.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: the disconnect function that `initShell` returns calls `disconnectNavBar()`, `disconnectRenderer()`, and `disconnectDebugPanel()`. This demo does not call that function at the end of the page, because the browser frees the page. The browser tests call it, and then they call `actor.stop()`. Do not tear down 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.
 
 ## Adapter Boundaries
 
-`createPlayUI` (from [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md)) is passive infrastructure. It translates actor view signals into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
+`createPlayUI` (from [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md)) is passive infrastructure. It translates actor view atoms into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
 
 ## Available Scripts
 
@@ -140,21 +125,11 @@ These commands are defined in `package.json`:
 | `pnpm --filter @xmachines/play-dom-demo run test`         | Run Vitest test suite                          |
 | `pnpm --filter @xmachines/play-dom-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-demo run test
-pnpm --filter @xmachines/play-dom-demo run test:browser
-```
-
-Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
-
 ## Learn More
 
 - [Play DOM](../../../api/@xmachines/play-dom/README.md)
 - [Play DOM Router](../play-dom-router-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
 
 ## Type Aliases
 
@@ -164,18 +139,24 @@ 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)
+- [demoComponents](variables/demoComponents.md)
+- [Field](variables/Field.md)
 - [Home](variables/Home.md)
 - [Login](variables/Login.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)
 - [Stats](variables/Stats.md)
 
 ## Functions
 
+- [createAuthActionHandlers](functions/createAuthActionHandlers.md)
+- [createConfirmDialog](functions/createConfirmDialog.md)
 - [createNavBar](functions/createNavBar.md)
 - [initShell](functions/initShell.md)

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

@@ -0,0 +1,35 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-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-dom-demo/functions/createConfirmDialog.md

@@ -0,0 +1,27 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / createConfirmDialog
+
+# Function: createConfirmDialog()
+
+```ts
+function createConfirmDialog(confirm): Promise<boolean>;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/ConfirmDialog.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/ConfirmDialog.ts#L12)
+
+ConfirmDialog — the DOM demo's onConfirm implementation.
+
+The DOM package ships no dialog of its own (it only exposes `ctx.onConfirm`),
+so the demo renders one. The buttons carry the spec's
+`confirmLabel`/`cancelLabel` verbatim — the same text the framework
+renderers' ConfirmDialogManager shows — so the shared browser suite drives
+every demo's dialog by label text.
+
+## Parameters
+
+| Parameter | Type            |
+| --------- | --------------- |
+| `confirm` | `ActionConfirm` |
+
+## Returns
+
+`Promise`\<`boolean`\>

package/examples/@xmachines/play-dom-demo/functions/createNavBar.md

@@ -6,10 +6,10 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
 
 NavBar — App-shell navigation factory. Mounts a reactive nav into
-`container`, observes actor.state via watchSignal, and updates button
+`container`, observes actor.state via watchAtom, and updates button
 visibility based on auth state. Returns a disconnect function.
 
 ## Parameters

package/examples/@xmachines/play-dom-demo/functions/initShell.md

@@ -3,10 +3,10 @@
 # Function: initShell()
 
 ```ts
-function initShell(actor, appElement): () => void;
+function initShell(actor, appElement, inspector): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
+Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
 
 Shell — DOM shell layout factory. Renders demo chrome (header + main +
 debug panel), mounts NavBar, connects DOM renderer, and wires DebugPanel.
@@ -14,10 +14,11 @@ Returns a disconnect function.
 
 ## Parameters
 
-| Parameter    | Type          |
-| ------------ | ------------- |
-| `actor`      | `AuthActor`   |
-| `appElement` | `HTMLElement` |
+| Parameter    | Type            |
+| ------------ | --------------- |
+| `actor`      | `AuthActor`     |
+| `appElement` | `HTMLElement`   |
+| `inspector`  | `DemoInspector` |
 
 ## Returns
 

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

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

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

@@ -6,7 +6,7 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/About.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/About.ts#L8)
 
 About — Public information page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'About'>). Renders static content from props.

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

@@ -0,0 +1,12 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Button
+
+# Variable: Button
+
+```ts
+const Button: ComponentFn<AuthCatalog, "Button">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Button.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Button.ts#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-dom-demo/variables/Contact.md

@@ -6,7 +6,7 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
 
 Contact — Public contact page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Contact'>). Renders static content from props.

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

@@ -6,7 +6,7 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
 
 Dashboard — Protected authenticated home. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Dashboard'>). Renders welcome message; logout

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

@@ -0,0 +1,19 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / Field
+
+# Variable: Field
+
+```ts
+const Field: ComponentFn<AuthCatalog, "Field">;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/Field.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Field.ts#L15)
+
+Field — labelled input with two-way $bindState binding and declarative
+validation checks.
+
+ctx.validation.registerField registers the bound state path with the DOM
+renderer's validation registry so the `validateForm` built-in sees it (the
+incremental renderer releases the registration when the element unmounts).
+Error DISPLAY deliberately reads `props.formErrors` — the result
+validateForm wrote to state — so every renderer surfaces errors at the same
+moment: after submit.

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

@@ -6,7 +6,7 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Home.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Home.ts#L9)
 
 Home — Public landing page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Home'>). Renders static welcome content from

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

@@ -6,7 +6,7 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Login.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Login.ts#L9)
 
 Login — Authentication form. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Login'>). Binds username input to ctx.store via

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

@@ -6,7 +6,7 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
 
 NavBarView — Catalog-typed NavBar component for DOM renderer.
 

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

@@ -6,7 +6,7 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
 
 Navigation — Navigation status display. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Navigation'>). Renders current path and auth

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

@@ -6,7 +6,7 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
 
 Overview — Dashboard overview child route. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Overview'>). Relative route resolves to

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

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

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

@@ -6,7 +6,7 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Profile.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Profile.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Profile.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Profile.ts#L9)
 
 Profile — Protected user profile page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Profile'>). Renders username from route params

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

@@ -6,7 +6,7 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Settings.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Settings.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Settings.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Settings.ts#L9)
 
 Settings — Protected settings page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Settings'>). Renders active section and username

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

@@ -6,7 +6,7 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Stats.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.56/packages/play-dom/examples/demo/src/components/Stats.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Stats.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.2/packages/play-dom/examples/demo/src/components/Stats.ts#L9)
 
 Stats — Dashboard stats child route. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Stats'>). Relative route resolves to