@xmachines/docs 6.1.0 → 7.1.0

package/guides/views.md

@@ -68,6 +68,9 @@ The view is an OPTIONAL capability of the actor. Compose it with `withView` of [
 ```ts
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { withView } from "@xmachines/play-xstate/view";
+import type { AnyStateMachine } from "xstate";
+
+declare const machine: AnyStateMachine; // your machine
 
 const actor = definePlayer({ machine, actor: compose(PlayerActor, withView) })();
 actor.start();
@@ -81,7 +84,7 @@ The actor then holds `currentView`, a `ReadonlyAtom<PlaySpec | null>`. An applic
 
 **The deepest active state that declares a view supplies it**, unless a parent composes it. A state that declares no view shows the view of its nearest ancestor that declares one. An ancestor view without `outlets` does not show, because the view of its descendant replaces it:
 
-```ts
+```ts fragment
 states: {
 	dashboard: {
 		meta: { view: dashboardView },   // shows in dashboard.overview
@@ -96,13 +99,13 @@ states: {
 
 When no active state declares a view, `currentView` holds `null`, and the renderer shows its `fallback` content.
 
-A **parallel** state follows the same region as the route derivation: the first region whose active states declare a `meta.route`, or the first region when no region does. The view on the screen therefore belongs to the region of the URL. When that region holds no view, the view comes from another active region, so one region can own the URL and another region can own the view. Keep the routes in one region: the [State Machines](state-machines.md#a-layout-and-its-pages-outlets) guide shows what a second routed region does to the URL.
+A **parallel** state follows the same region as the route derivation: the first region whose active states declare a `meta.route`, else the first region that declares a route in any state, else the first region. A region that owns the routes therefore keeps the screen while it sits in a state without a route, such as a load. The view on the screen therefore belongs to the region of the URL. When that region holds no view, the view comes from another active region, so one region can own the URL and another region can own the view. Keep the routes in one region: the [State Machines](state-machines.md#a-layout-and-its-pages-outlets) guide shows what a second routed region does to the URL.
 
 ### A layout and its pages: `outlets`
 
 A parent view that declares `outlets` shows itself AND the view of its active child. Each outlet names an element of the parent view, and the view of the child goes into that element:
 
-```ts
+```ts fragment
 const shell = typedSpec({
 	root: "shell",
 	state: { collapsed: false },
@@ -130,6 +133,7 @@ states: {
 - `slot` names a named slot of the element. Omit it, and the renderer appends the child view to the `children` of the element.
 - The view of a child is the deepest view below it. A child view can declare `outlets` of its own, for a nested layout.
 - An outlet that names an element that its view does not hold throws `InvalidViewOutletError`. The actor reports it through `onError`, and it keeps the last valid view.
+- The keys of the outer view carry no prefix, and each key of a child view gets the id of its state and a `/` as a prefix. A key of the outer view such as `"page/root"` equals the key of the element `root` of the child state `page`, and the composition throws `ViewElementKeyCollisionError`. Do not start a key of the outer view with the id of a state and a `/`.
 
 The derived spec is ONE flat spec. The keys of the outer view stay as you wrote them. Each key of a child view gets the id of its state as a prefix: the `root` element of the view of the state `app.search` becomes `app.search/root`. Two views therefore never collide. The [State Machines](state-machines.md#a-layout-and-its-pages-outlets) guide shows a parallel layout with a named slot.
 
@@ -149,7 +153,7 @@ derived state = { ...meta.view.state, context: <the machine context> }
 
 A spec reads the context through the ordinary state grammar of json-render. The same path works in a prop, in a `visible` condition, and in `repeat.statePath`:
 
-```ts
+```ts fragment
 elements: {
 	greeting: { type: "Text", props: { text: { $state: "/context/username" } }, children: [] },
 	tasks: {
@@ -189,7 +193,7 @@ Domain state is the state of the application. Each change of it is an event, so
 
 This login form uses both. The field binds to `/username`, and the submit sends the value to the machine:
 
-```ts
+```ts fragment
 view: typedSpec({
 	root: "form",
 	state: { username: "" },
@@ -215,10 +219,26 @@ Keep high-frequency data in the ephemeral state or in a child actor, and not in
 A component emits a named event of json-render, such as `submit` or `press`. The `on` field of its element maps that name to an ACTION, with params that the renderer resolves from the store. The registry holds the handler of each action, and a handler of a domain action sends a machine event:
 
 ```ts
+import { defineCatalog } from "@xmachines/json-render-core";
+import { defineRegistry, schema, type ComponentFn } from "@xmachines/play-dom";
+import type { ViewActor } from "@xmachines/play-view";
+import { z } from "zod";
+
+declare const actor: ViewActor<unknown, { type: "auth.login"; username: string }>;
+
+const catalog = defineCatalog(schema, {
+	components: { Login: { props: z.object({ username: z.string() }) } },
+	actions: { login: { params: z.object({ username: z.string() }) } },
+});
+
+declare const Login: ComponentFn<typeof catalog, "Login">; // your component
+
 const registryResult = defineRegistry(catalog, {
 	components: { Login },
 	actions: {
-		login: async ({ username }) => actor.send({ type: "auth.login", username }),
+		login: async (params) => {
+			if (params) actor.send({ type: "auth.login", username: params.username });
+		},
 	},
 });
 ```
@@ -227,7 +247,7 @@ The guards of the machine then decide. The renderer changes no state of the mach
 
 The renderer implements four built-in actions over the ephemeral state: `setState`, `pushState`, `removeState` and `validateForm`. They need no handler in the registry. An `on` entry can hold an array of bindings, and the renderer runs them in order. For example, it sends the event, and then it clears the draft:
 
-```ts
+```ts fragment
 on: {
 	press: [
 		{ action: "addTask", params: { title: { $state: "/newTaskTitle" } } },
@@ -255,18 +275,18 @@ A renderer holds one view store for each view, and the `viewKey` decides its lif
 
 With the same `viewKey`, every renderer keeps the DOM nodes, the focus and the ephemeral state. A context change therefore updates a list under a field that has the focus, and the draft in the field stays.
 
-With a new `viewKey`, the ephemeral state starts again from `spec.state`. Two sibling states that each declare a view therefore reset a draft on each transition between them, also when their two specs are equal.
+With a new `viewKey`, the ephemeral state starts again from `spec.state`, and every renderer builds the view again. The state that a component keeps for itself, such as the text of an unbound input, goes with the old view. Two sibling states that each declare a view therefore reset a draft on each transition between them, also when their two specs are equal.
 
 A parent keeps the ephemeral state across a move between its children in one of two ways:
 
 - **Declare the view on the parent**, and no view on the children. The `viewKey` stays the id of the parent.
 - **Declare `outlets` on the parent.** The `viewKey` stays the id of the parent, and each child still shows its own view. A change of the page keeps the store of the layout, so the `collapsed` value of the [layout above](#a-layout-and-its-pages-outlets) does not change.
 
-In a composed view, all the views of one layout share ONE store. The first time that a page shows, the renderer writes each key of its authored `state` that the store does not hold. A page that comes back finds the values that it left. Two pages that declare the same key therefore share one value: give each page its own keys. When two composed views declare the same key, the outer view wins, and a warning names the key.
+In a composed view, all the views of one layout share ONE store. The first time that a page shows, the renderer writes each key of its authored `state` that the store does not hold. A page that comes back finds the values that it left. Two pages that declare the same key therefore share one value: give each page its own keys. When two composed views declare the same key, the outer view wins. play-xstate reads the states of the machine one time, and it writes one warning for each layout that names every key that two of its views declare.
 
 `currentView` also emits only on a real change of the view on the screen. An event that changes no context field and moves to no other view keeps the previous reference, and no subscriber runs. The gate compares the top-level fields of the context. It does not enter a value, so a new object in a field emits again, also when its contents are equal.
 
-In the **controlled mode**, you give the provider a `store`. The provider then ignores `spec.state`, and you own the seed and the lifetime of that store. The renderer still owns `/context`, and it refreshes the subtree in your store on each emission.
+In the **controlled mode**, you give the provider a `store`. The provider then ignores `spec.state`, and you own the seed and the lifetime of that store. The renderer still owns `/context`, and it refreshes the subtree in your store on each emission. The tree lives as long as its store, so a new `viewKey` keeps the tree in the controlled mode, and a new store builds it again.
 
 ---
 
@@ -274,16 +294,16 @@ In the **controlled mode**, you give the provider a `store`. The provider then i
 
 A failure of the DERIVATION stays inside the actor. `currentView` catches it, it keeps the last valid view, and it reports the error to the `onError` hook of the actor in a microtask. The transition continues for every other observer.
 
-A failure of the RENDER stays inside the provider. When a component throws, or the store does not resolve, the provider shows its `fallback` and it calls its own `onError` prop:
+A failure of the RENDER stays inside the provider. When a component throws, when the store does not resolve, or when the root of the view fails, the provider shows its `fallback` and it calls its own `onError` prop:
 
 | Renderer                                                          | The `onError` prop of the provider |
 | ----------------------------------------------------------------- | ---------------------------------- |
-| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) | `(error, info, reset) => void`     |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) | `(error, reset, info) => void`     |
 | the four other renderers                                          | `(error, reset) => void`           |
 
 The provider reports one failure one time for one set of inputs — the actor, the view and the store — and not one time for each render. A new emission, or a call of `reset`, makes the next failure report again. Without `onError`, the provider writes the failure to `console.error`, so that no failure is silent. A handler that throws does not break the containment: the provider writes that failure to `console.error` too.
 
-`onRenderError` receives the failure of one catalog component, with the name of the component, and it replaces every handler of `defineRegistry`.
+`onRenderError` receives each failure that json-render reports, with `(error, name, info)`, and it replaces every handler of `defineRegistry`. `info.kind` names the failure: a catalog component that throws (`"element"`), a prop or a `visible` condition of a child (`"props"`, `"visible"`), an action chain or a watch chain (`"action"`, `"watch"`), or the root (`"root"`). A failure of the ROOT — its component, a prop, or its `visible` condition — leaves no view on the screen. json-render gives it to no error boundary of the host, so each of the five providers contains it as a failure of the view: it shows its `fallback`, it calls `onError` one time, and the next view renders again. `onRenderError` also receives it, with the kind `"root"`. A failure below the root reaches `onRenderError` alone, and the rest of the view stays. Without a handler of the host, the provider writes one console line for a failure of the root, and not two.
 
 ---
 
@@ -319,7 +339,7 @@ A provider takes a `ViewActor`: the actor contract and the `Viewable` capability
 
 Each one exports `schema` for `defineCatalog`, and `defineRegistry` for its own components. `PlayUIProvider` takes the `actor`, the `registryResult`, and the optional `store`, `fallback`, `onError` and `onRenderError`. The [Getting Started](getting-started.md#connecting-a-view-renderer) guide shows a complete mount for each framework.
 
-[`@xmachines/play-view`](../api/@xmachines/play-view/README.md) holds the part that the five share: the store lifecycle, the `/context` guard and the report rules. A shared contract suite runs the same scenarios against each renderer, so the five agree on what a viewer sees.
+[`@xmachines/play-view`](../api/@xmachines/play-view/README.md) holds the part that the five share: the view session, which resolves the store of each view outside a render, the `/context` guard and the report guard. A shared contract suite runs the same scenarios against each renderer, so the five agree on what a viewer sees.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "6.1.0",
+  "version": "7.1.0",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -56,13 +56,13 @@
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^7.0.1",
-    "@types/node": "^26.6.2",
-    "oxfmt": "^0.70.0",
-    "oxlint": "^1.85.0",
+    "@types/node": "^26.6.6",
+    "oxfmt": "^0.75.0",
+    "oxlint": "^1.90.0",
     "typedoc": "^0.28.20",
     "typedoc-plugin-llms-txt": "^0.1.2",
-    "typedoc-plugin-markdown": "^4.13.0",
-    "vitest": "^5.0.1"
+    "typedoc-plugin-markdown": "^4.14.1",
+    "vitest": "^5.0.5"
   },
   "engines": {
     "node": ">=24.0.0"

package/rfc/play.md

@@ -260,7 +260,7 @@ Wraps XState v5 to satisfy the `PlayActor` contract. Provides the primary API fo
 - Support snapshot restore for resumable sessions
 - Provide XState DevTools compatibility
 
-```ts
+```ts fragment
 import type { AnyStateMachine, InputFrom } from "xstate";
 
 interface PlayerConfig<TMachine extends AnyStateMachine> {
@@ -380,7 +380,7 @@ Each view renderer provides a `PlayRenderer` component that passively observes t
 
 **[`@xmachines/play-react`](../api/@xmachines/play-react/README.md) exports (representative):**
 
-```ts
+```ts fragment
 // Batteries-included composite — standard entry point
 // Props: actor, registryResult, store?, fallback?, onError?, onRenderError?,
 //        validationFunctions?, navigate?, functions?
@@ -438,13 +438,18 @@ The original RFC proposed an `@xmachines/play-ui` package for this purpose. The
 Defines the **UI vocabulary** — available components and their prop schemas. No framework code.
 
 ```ts
-import { defineCatalog, z } from "@xmachines/json-render-core";
+import { defineCatalog } from "@xmachines/json-render-core";
+import { schema } from "@xmachines/json-render-react/schema";
+import { z } from "zod";
 
-export const catalog = defineCatalog({
+export const catalog = defineCatalog(schema, {
 	components: {
 		Dashboard: { props: z.object({ title: z.string() }) },
 		Metric: { props: z.object({ value: z.number(), label: z.string() }) },
 	},
+	actions: {
+		submit: { description: "Submit the form" },
+	},
 });
 ```
 
@@ -454,12 +459,17 @@ Defines **Logic**. No framework code. No routing library imports.
 
 ```ts
 import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import { typedSpec } from "@xmachines/play-view";
 
 export const machine = setup({/* types, guards, actions */}).createMachine({
+	id: "dashboard",
 	initial: "overview",
 	states: {
 		overview: {
+			id: "overview",
 			meta: {
 				route: "/dashboard",
 				view: typedSpec({
@@ -478,20 +488,27 @@ export const machine = setup({/* types, guards, actions */}).createMachine({
 	},
 });
 
-// definePlayer returns a factory function
-export const createDashboard = definePlayer({ machine });
+// definePlayer returns a factory function. The router and the renderer need both capabilities
+export const createDashboard = definePlayer({
+	machine,
+	actor: compose(PlayerActor, withRouting, withView),
+});
 ```
 
 ### 6.3 Application (`App.tsx`)
 
 Binds Logic to a View Renderer and Router Adapter.
 
-```tsx
-import { createDashboard, machine } from "./features/dashboard/player";
-import { catalog } from "./catalog";
+```tsx fragment
+import { createRootRoute, createRouter } from "@tanstack/react-router";
+import { createDashboard, machine } from "./dashboard.player.js";
+import { catalog } from "./catalog.js";
 import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
-import { TanStackReactRouterBridge } from "@xmachines/play-tanstack-react-router";
-import { extractMachineRoutes, createRouteMap } from "@xmachines/play-router/xstate";
+import {
+	createRouteMapFromTree,
+	TanStackReactRouterBridge,
+} from "@xmachines/play-tanstack-react-router";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
 
 // 1. Create the actor
 const actor = createDashboard();
@@ -516,7 +533,8 @@ const routeTree = extractMachineRoutes(machine);
 const routeMap = createRouteMapFromTree(routeTree);
 
 // 4. Connect router adapter (router, actor, routeMap)
-const bridge = new TanStackReactRouterBridge(tanstackRouter, actor, routeMap);
+const router = createRouter({ routeTree: createRootRoute() });
+const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
 bridge.connect();
 
 // 5. Render — PlayUIProvider is the batteries-included composite; PlayRenderer is the zero-prop leaf

package/api/@xmachines/play-view/index/functions/createFailureLatch.md

@@ -1,20 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / createFailureLatch
-
-# Function: createFailureLatch()
-
-```ts
-function createFailureLatch(): FailureLatch;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:202](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L202)
-
-Makes a [FailureLatch](../interfaces/FailureLatch.md).
-
-The latch holds the three inputs BESIDE the flag. Clearing on each emission would be
-enough for a provider that can hook every emission, and the identity check covers the
-one that cannot: a render that runs again with nothing changed reports nothing, whether
-or not the provider noticed that it ran.
-
-## Returns
-
-[`FailureLatch`](../interfaces/FailureLatch.md)

package/api/@xmachines/play-view/index/functions/sameViewInputs.md

@@ -1,25 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / sameViewInputs
-
-# Function: sameViewInputs()
-
-```ts
-function sameViewInputs(a, b): boolean;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:45](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L45)
-
-Answers whether two sets of inputs are the SAME attempt.
-
-Identity, and not a deep compare: a provider holds the references that it rendered, and
-a new spec object is a new attempt even when it holds equal fields.
-
-## Parameters
-
-| Parameter | Type                                        |
-| --------- | ------------------------------------------- |
-| `a`       | [`ViewInputs`](../interfaces/ViewInputs.md) |
-| `b`       | [`ViewInputs`](../interfaces/ViewInputs.md) |
-
-## Returns
-
-`boolean`

package/api/@xmachines/play-view/index/interfaces/FailureLatch.md

@@ -1,60 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / FailureLatch
-
-# Interface: FailureLatch
-
-Defined in: [packages/play-view/src/failure-latch.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L174)
-
-The record of what a provider reported. See [createFailureLatch](../functions/createFailureLatch.md).
-
-## Methods
-
-### clear()
-
-```ts
-clear(): void;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:191](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L191)
-
-Forgets the record, so the next failure reports again.
-
-A caller clears it on EVERY emission of a view, the null emission included: a view,
-then null, then the same view is a real sequence of an actor, and the second failure
-of that view is a second attempt that the host must hear about. It also clears it on
-a resolution that works, and on a retry that the host starts — the host asked for
-that attempt, so it must hear the result.
-
-#### Returns
-
-`void`
-
----
-
-### shouldReport()
-
-```ts
-shouldReport(
-   actor,
-   view,
-   store
-): boolean;
-```
-
-Defined in: [packages/play-view/src/failure-latch.ts:181](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L181)
-
-Answers whether a failure of these three inputs is new, and records it.
-
-#### Parameters
-
-| Parameter | Type      |
-| --------- | --------- |
-| `actor`   | `unknown` |
-| `view`    | `unknown` |
-| `store`   | `unknown` |
-
-#### Returns
-
-`boolean`
-
-`true` the first time for one set of inputs, and `false` for every repeat
-of the same set. A caller reports only when it returns `true`.

package/api/@xmachines/play-view/index/interfaces/ViewInputs.md

@@ -1,19 +0,0 @@
-[API](../../../../README.md) / [@xmachines/play-view](../../README.md) / [index](../README.md) / ViewInputs
-
-# Interface: ViewInputs
-
-Defined in: [packages/play-view/src/failure-latch.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L33)
-
-The three inputs that a provider resolves a store from.
-
-`ViewStoreLifecycle.resolve` takes exactly these, and every provider names all three in
-its reset rule. The type gives the rule one name, so the comparison below stands one
-time instead of once for each renderer that needs it.
-
-## Properties
-
-| Property                            | Type      | Defined in                                                                                                                                         |
-| ----------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-actor"></a> `actor` | `unknown` | [packages/play-view/src/failure-latch.ts:34](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L34) |
-| <a id="property-store"></a> `store` | `unknown` | [packages/play-view/src/failure-latch.ts:36](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L36) |
-| <a id="property-view"></a> `view`   | `unknown` | [packages/play-view/src/failure-latch.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.1.0/packages/play-view/src/failure-latch.ts#L35) |

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

@@ -1,162 +0,0 @@
-[Examples](../../README.md) / @xmachines/play-dom-demo
-
-# @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 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
-
-From the repository root:
-
-```bash
-pnpm install
-pnpm --filter @xmachines/play-dom-demo run dev
-```
-
-Then open `http://localhost:3000`.
-
-## Step-by-Step Code Flow
-
-Use this order to understand the implementation:
-
-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 `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 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");
-
-// 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: 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, { onConfirm: createConfirmDialog });
-const disconnectRenderer = mount(actor, viewContent);
-const disconnectDebugPanel = createDebugPanel(actor, shell, inspector);
-
-return () => {
-	disconnectNavBar();
-	disconnectRenderer();
-	disconnectDebugPanel();
-};
-```
-
-## Key Files
-
-- `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 `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
-
-## State Machine & Architecture Details
-
-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 `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. 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
-
-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 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
-
-These commands are defined in `package.json`:
-
-| Command                                                   | Description                                    |
-| --------------------------------------------------------- | ---------------------------------------------- |
-| `pnpm --filter @xmachines/play-dom-demo run dev`          | Start Vite dev server (http://localhost:3000/) |
-| `pnpm --filter @xmachines/play-dom-demo run build`        | Build production bundle                        |
-| `pnpm --filter @xmachines/play-dom-demo run preview`      | Preview built bundle                           |
-| `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               |
-
-## 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
-
-- [AuthCatalog](type-aliases/AuthCatalog.md)
-
-## Variables
-
-- [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

@@ -1,35 +0,0 @@
-[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/v6.1.0/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/v6.1.0/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/v6.1.0/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/v6.1.0/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/v6.1.0/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/v6.1.0/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/v6.1.0/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/v6.1.0/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/v6.1.0/packages/play-actor/examples/shared/src/actions.ts#L92) |

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

@@ -1,27 +0,0 @@
-[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/v6.1.0/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`\>