@xmachines/docs 7.0.0 → 7.2.0

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

@@ -0,0 +1,127 @@
+[Examples](../../README.md) / @xmachines/play-dom-gallery-demo
+
+# @xmachines/play-dom-gallery-demo
+
+Vanilla DOM renderer gallery for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — all nine shared machines behind one picker, actor + `createPlayUI` without a router.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- All nine shared machines (fetch, stopwatch, tic-tac-toe, temperature, TodoMVC, trivia, donut, flight, auth) reused without framework-specific business logic
+- A home-screen picker: selecting a machine stops the previous actor, creates a FRESH actor for the chosen machine, and renders its views; "Back to gallery" returns to the picker
+- The five-component demo kit (Page, Panel, Field, Button, Text) defined ONCE as plain DOM factories and registered with every machine's typed `defineRegistry` catalog
+- Routing machines run WITHOUT a router here — navigation happens via their in-view route-action buttons; the actor owns view switching. Auth's login wall still holds: `dashboard`'s `always` guard bounces an unauthenticated visitor to `login` no matter how the entry is attempted
+- A host `onConfirm` (`createConfirmDialog`): [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) is headless, so a confirm-gated action (TodoMVC's clear-completed) would be SKIPPED with a `console.warn` unless the host answers the confirm — the dialog renders the spec's `confirmLabel`/`cancelLabel` verbatim
+- `Field` registering declarative `checks` with the renderer's validation registry and displaying `formErrors` in a `[data-demo-error]` node (the flight machine's date rules)
+- One shared Stately inspector (`createDemoInspector()`) serving every selection — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-dom-gallery-demo run dev
+```
+
+Then open `http://localhost:3020`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.ts` calls `initApp(document.getElementById("app"))`.
+2. `src/App.ts` renders the picker; `openMachine(entry)` stops any previous actor, empties the container, and calls `entry.createRuntime(inspector.inspect)`.
+3. `src/machines.ts` holds one `GalleryMachineEntry` per machine: `createRuntime` builds a fresh started actor via `definePlayer({ machine, options: { inspect } })()` and its `defineRegistry(catalog, { components: demoComponents, actions: create<Prefix>ActionHandlers(actor) })`.
+4. `src/catalogs.ts` builds all nine catalogs with `defineCatalog(schema, <prefix>CatalogDef)` — router demos import theirs from the barrel.
+5. `initShell` writes the demo chrome, connects `createPlayUI(registryResult, { onConfirm: createConfirmDialog })(actor, content)`, and appends the `DebugPanel`; the gallery passes `title` and a `nav` node carrying the "Back to gallery" button. The DOM router demos import this same shell, so the confirm handler serves them too.
+6. Browser tests in `test/browser/` delegate one file per machine to that machine's shared renderer suite.
+
+## Key Files
+
+- `src/main.ts` - DOM entry point that mounts the gallery
+- `src/App.ts` - picker, per-selection actor lifecycle, and `initShell` composition
+- `src/machines.ts` - the machine registry: slug, label, and `createRuntime` per machine
+- `src/catalogs.ts` - the nine built catalogs plus the `KitCatalog` typing alias
+- `src/components/` - the five-component kit (Page, Panel, Field, Button, Text) plus `Shell`, `DebugPanel`, and `ConfirmDialog`
+- `src/index.ts` - barrel exporting `initApp`, the kit, `demoComponents`, `initShell`, `createDebugPanel`, `createConfirmDialog`, and every built catalog for the router demos
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/<slug>-demo.browser.test.ts` - one file per machine, delegating to the shared suites
+- `test/browser/gallery-picker.browser.test.ts` - picker smoke test (open/close roundtrip)
+
+## Architecture Invariants
+
+1. **Actor Authority:** Views dispatch machine events (and `route` actions on routing machines) to the actor. The actor evaluates guards and transitions — the DOM layer never decides which view to render.
+2. **Passive Infrastructure:** The DOM renderer observes the `actor.currentView` atom only. It holds no business state and makes no routing decisions.
+3. **Fresh Actor Per Selection:** Reopening a machine always starts from its initial state, matching the demo inspector's "one live machine" semantics.
+
+## Available Scripts
+
+| Command                                                           | Description                                    |
+| ----------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run dev`          | Start Vite dev server (http://localhost:3020/) |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-dom-gallery-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-dom-gallery-demo run test
+pnpm --filter @xmachines/play-dom-gallery-demo run test:browser
+```
+
+Expected result: library-pattern invariant tests pass and all nine machine suites plus the picker smoke test complete.
+
+## Learn More
+
+- [play-dom](../../../api/@xmachines/play-dom/README.md)
+- [DOM Router auth demo](../play-dom-router-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
+
+## Interfaces
+
+- [GalleryMachineEntry](interfaces/GalleryMachineEntry.md)
+- [GalleryRuntime](interfaces/GalleryRuntime.md)
+- [ShellOptions](interfaces/ShellOptions.md)
+
+## Type Aliases
+
+- [AuthCatalog](type-aliases/AuthCatalog.md)
+- [DonutCatalog](type-aliases/DonutCatalog.md)
+- [FetchCatalog](type-aliases/FetchCatalog.md)
+- [FlightCatalog](type-aliases/FlightCatalog.md)
+- [GalleryActor](type-aliases/GalleryActor.md)
+- [GallerySlug](type-aliases/GallerySlug.md)
+- [KitCatalog](type-aliases/KitCatalog.md)
+- [StopwatchCatalog](type-aliases/StopwatchCatalog.md)
+- [TemperatureCatalog](type-aliases/TemperatureCatalog.md)
+- [TicTacToeCatalog](type-aliases/TicTacToeCatalog.md)
+- [TodoMvcCatalog](type-aliases/TodoMvcCatalog.md)
+- [TriviaCatalog](type-aliases/TriviaCatalog.md)
+
+## Variables
+
+- [authCatalog](variables/authCatalog.md)
+- [Button](variables/Button.md)
+- [demoComponents](variables/demoComponents.md)
+- [donutCatalog](variables/donutCatalog.md)
+- [fetchCatalog](variables/fetchCatalog.md)
+- [Field](variables/Field.md)
+- [flightCatalog](variables/flightCatalog.md)
+- [galleryMachines](variables/galleryMachines.md)
+- [Page](variables/Page.md)
+- [Panel](variables/Panel.md)
+- [stopwatchCatalog](variables/stopwatchCatalog.md)
+- [temperatureCatalog](variables/temperatureCatalog.md)
+- [Text](variables/Text.md)
+- [ticTacToeCatalog](variables/ticTacToeCatalog.md)
+- [todoMvcCatalog](variables/todoMvcCatalog.md)
+- [triviaCatalog](variables/triviaCatalog.md)
+
+## Functions
+
+- [createConfirmDialog](functions/createConfirmDialog.md)
+- [createDebugPanel](functions/createDebugPanel.md)
+- [initApp](functions/initApp.md)
+- [initShell](functions/initShell.md)

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

@@ -0,0 +1,33 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / createConfirmDialog
+
+# Function: createConfirmDialog()
+
+```ts
+function createConfirmDialog(confirm): Promise<boolean>;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/ConfirmDialog.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/ConfirmDialog.ts#L18)
+
+ConfirmDialog — the gallery's `onConfirm` implementation.
+
+The framework packages render json-render's own dialog from their provider,
+but `@xmachines/play-dom` is headless: it only exposes `ctx.onConfirm`, and a
+confirm-gated action with no handler is SKIPPED with a `console.warn`. So the
+host brings the dialog, and `Shell` hands this factory to `createPlayUI` —
+which makes every confirm-gated action (TodoMVC's clear-completed) work in
+the gallery and in the DOM router demos that share that shell.
+
+The buttons carry the spec's `confirmLabel`/`cancelLabel` VERBATIM — the same
+text the framework renderers' ConfirmDialogManager shows — because label text
+is the only handle the shared browser suites have on a dialog whose markup
+differs per renderer.
+
+## Parameters
+
+| Parameter | Type            |
+| --------- | --------------- |
+| `confirm` | `ActionConfirm` |
+
+## Returns
+
+`Promise`\<`boolean`\>

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

@@ -0,0 +1,31 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / createDebugPanel
+
+# Function: createDebugPanel()
+
+```ts
+function createDebugPanel(actor, container, inspector): () => void;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/DebugPanel.ts:17](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/DebugPanel.ts#L17)
+
+DebugPanel — live debug footer factory. Appends the footer to `container`,
+shows the current state value, renders the button that opens the Stately
+inspector window, and returns a disconnect function that stops the watcher.
+
+The state label is a computed atom rather than a watch of `actor.state`
+directly: `GalleryActor` is a union of nine actor types, so `actor.state` is a
+union of nine atom types that no single `watchAtom<T>` call can accept. Reading
+inside the computed atom collapses the union to the one thing the panel needs —
+a string. A swap of the actor is a dispose and a rebuild of the panel.
+
+## Parameters
+
+| Parameter   | Type                                              |
+| ----------- | ------------------------------------------------- |
+| `actor`     | [`GalleryActor`](../type-aliases/GalleryActor.md) |
+| `container` | `HTMLElement`                                     |
+| `inspector` | `DemoInspector`                                   |
+
+## Returns
+
+() => `void`

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

@@ -0,0 +1,22 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / initApp
+
+# Function: initApp()
+
+```ts
+function initApp(container): () => void;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/App.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/App.ts#L33)
+
+Mount the gallery into `container` and return a cleanup function that stops
+whatever actor is live and empties the container.
+
+## Parameters
+
+| Parameter   | Type          |
+| ----------- | ------------- |
+| `container` | `HTMLElement` |
+
+## Returns
+
+() => `void`

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

@@ -0,0 +1,33 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / initShell
+
+# Function: initShell()
+
+```ts
+function initShell(container, options): () => void;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Shell.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L35)
+
+Shell — DOM shell layout factory.
+
+Writes the standard demo chrome (header + content region + debug footer)
+into `container`, connects the DOM renderer to the content region, wires the
+DebugPanel, and returns a disconnect function. There is no NavBar — every
+ported machine drives its own navigation through in-view buttons (route
+actions on routing machines, plain events elsewhere).
+
+The gallery App and the router demos share this one factory: the gallery
+passes `title`/`nav` (machine label + "Back to gallery" button); router
+demos call it bare with their bridged `router`. Because they share it, the
+`onConfirm` handler wired here serves the router demos too.
+
+## Parameters
+
+| Parameter   | Type                                            |
+| ----------- | ----------------------------------------------- |
+| `container` | `HTMLElement`                                   |
+| `options`   | [`ShellOptions`](../interfaces/ShellOptions.md) |
+
+## Returns
+
+() => `void`

package/examples/@xmachines/play-dom-gallery-demo/interfaces/GalleryMachineEntry.md

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / GalleryMachineEntry
+
+# Interface: GalleryMachineEntry
+
+Defined in: [packages/play-dom/examples/gallery/src/machines.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L85)
+
+## Properties
+
+| Property                                            | Type                                                 | Description                                                                                                                              | Defined in                                                                                                                                                                    |
+| --------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-createruntime"></a> `createRuntime` | (`inspect`) => [`GalleryRuntime`](GalleryRuntime.md) | Create a fresh, STARTED actor and its registry for one selection. The caller owns the runtime and must stop the actor when done with it. | [packages/play-dom/examples/gallery/src/machines.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L93) |
+| <a id="property-label"></a> `label`                 | `string`                                             | Picker button label and machine-view title.                                                                                              | [packages/play-dom/examples/gallery/src/machines.ts:88](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L88) |
+| <a id="property-slug"></a> `slug`                   | [`GallerySlug`](../type-aliases/GallerySlug.md)      | -                                                                                                                                        | [packages/play-dom/examples/gallery/src/machines.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L86) |

package/examples/@xmachines/play-dom-gallery-demo/interfaces/GalleryRuntime.md

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / GalleryRuntime
+
+# Interface: GalleryRuntime
+
+Defined in: [packages/play-dom/examples/gallery/src/machines.ts:80](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L80)
+
+One live selection: the started actor plus its registry.
+
+## Properties
+
+| Property                                              | Type                                                                                             | Defined in                                                                                                                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`GalleryActor`](../type-aliases/GalleryActor.md)                                                | [packages/play-dom/examples/gallery/src/machines.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L81) |
+| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](../../../../api/@xmachines/play-dom/interfaces/DefineRegistryResult.md) | [packages/play-dom/examples/gallery/src/machines.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L82) |

package/examples/@xmachines/play-dom-gallery-demo/interfaces/ShellOptions.md

@@ -0,0 +1,18 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / ShellOptions
+
+# Interface: ShellOptions
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Shell.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L8)
+
+What the shell needs to render one live machine.
+
+## Properties
+
+| Property                                              | Type                                                                                             | Description                                                                      | Defined in                                                                                                                                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-actor"></a> `actor`                   | [`GalleryActor`](../type-aliases/GalleryActor.md)                                                | -                                                                                | [packages/play-dom/examples/gallery/src/components/Shell.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L9)   |
+| <a id="property-inspector"></a> `inspector`           | `DemoInspector`                                                                                  | Stately inspector controller — wires the DebugPanel inspector button.            | [packages/play-dom/examples/gallery/src/components/Shell.ts:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L14) |
+| <a id="property-nav"></a> `nav?`                      | `Node`                                                                                           | Extra header content — the gallery passes its "Back to gallery" button.          | [packages/play-dom/examples/gallery/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L18) |
+| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](../../../../api/@xmachines/play-dom/interfaces/DefineRegistryResult.md) | -                                                                                | [packages/play-dom/examples/gallery/src/components/Shell.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L12) |
+| <a id="property-router"></a> `router?`                | `unknown`                                                                                        | Bridged router instance — accepted for prop parity with router demos but unused. | [packages/play-dom/examples/gallery/src/components/Shell.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L11) |
+| <a id="property-title"></a> `title?`                  | `string`                                                                                         | Header title override — the gallery passes the machine label.                    | [packages/play-dom/examples/gallery/src/components/Shell.ts:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Shell.ts#L16) |

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / AuthCatalog
+
+# Type Alias: AuthCatalog
+
+```ts
+type AuthCatalog = typeof authCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:47](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L47)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / DonutCatalog
+
+# Type Alias: DonutCatalog
+
+```ts
+type DonutCatalog = typeof donutCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:41](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L41)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / FetchCatalog
+
+# Type Alias: FetchCatalog
+
+```ts
+type FetchCatalog = typeof fetchCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L23)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / FlightCatalog
+
+# Type Alias: FlightCatalog
+
+```ts
+type FlightCatalog = typeof flightCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L44)

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

@@ -0,0 +1,20 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / GalleryActor
+
+# Type Alias: GalleryActor
+
+```ts
+type GalleryActor =
+	| FetchActor
+	| StopwatchActor
+	| TicTacToeActor
+	| TemperatureActor
+	| TodoMvcActor
+	| TriviaActor
+	| DonutActor
+	| FlightActor
+	| AuthActor;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/machines.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L57)
+
+Any of the nine machine actors — what the gallery Shell and DebugPanel accept.

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

@@ -0,0 +1,18 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / GallerySlug
+
+# Type Alias: GallerySlug
+
+```ts
+type GallerySlug =
+	| "fetch"
+	| "stopwatch"
+	| "tictactoe"
+	| "temperature"
+	| "todomvc"
+	| "trivia"
+	| "donut"
+	| "flight"
+	| "auth";
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/machines.ts:68](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/machines.ts#L68)

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

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / KitCatalog
+
+# Type Alias: KitCatalog
+
+```ts
+type KitCatalog = FetchCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L57)
+
+The catalog the shared component KIT is typed against.
+
+ComponentFn only constrains a component through the catalog's component
+schemas, and those are identical across all nine catalogs — so the kit is
+typed once against this representative and registers cleanly with every
+machine's defineRegistry call.

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / StopwatchCatalog
+
+# Type Alias: StopwatchCatalog
+
+```ts
+type StopwatchCatalog = typeof stopwatchCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L26)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / TemperatureCatalog
+
+# Type Alias: TemperatureCatalog
+
+```ts
+type TemperatureCatalog = typeof temperatureCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:32](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L32)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / TicTacToeCatalog
+
+# Type Alias: TicTacToeCatalog
+
+```ts
+type TicTacToeCatalog = typeof ticTacToeCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:29](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L29)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / TodoMvcCatalog
+
+# Type Alias: TodoMvcCatalog
+
+```ts
+type TodoMvcCatalog = typeof todoMvcCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:35](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L35)

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

@@ -0,0 +1,9 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / TriviaCatalog
+
+# Type Alias: TriviaCatalog
+
+```ts
+type TriviaCatalog = typeof triviaCatalog;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/catalogs.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/catalogs.ts#L38)

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

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

@@ -0,0 +1,30 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / Field
+
+# Variable: Field
+
+```ts
+const Field: ComponentFn<KitCatalog, "Field">;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Field.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Field.ts#L26)
+
+Field — labelled input with two-way $bindState binding and declarative
+validation checks.
+
+The DOM renderer resolves `{ $bindState: "/path" }` into `bindings.value`
+and hands the current value in through `props.value`; writing back is the
+component's job, so every `input` event pushes into `ctx.store` at that
+path. A Button then reads the draft with `{ $state: "/path" }` params and
+clears it with a chained `setState` built-in.
+
+The incremental renderer skips re-rendering a bound element while it holds
+focus, so typing never loses the caret — external writes (the setState
+clear) still land because the element is unfocused by then.
+
+`ctx.validation.registerField` registers the bound state path with the DOM
+renderer's validation registry so the `validateForm` built-in sees this
+field's `checks` (the incremental renderer releases the registration when the
+element unmounts). Error DISPLAY deliberately reads `props.formErrors` — the
+`{ path: messages }` map validateForm wrote back to state — so every renderer
+surfaces errors at the same moment: after submit. The error node carries
+`data-demo-error={testId}`, the handle the shared suites assert on.

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

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / Page
+
+# Variable: Page
+
+```ts
+const Page: ComponentFn<KitCatalog, "Page">;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Page.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Page.ts#L12)
+
+Page — the root of every view.
+
+Renders `data-page={page}` (the state name) so the browser suites can wait
+for a specific view, plus an `h2` title and the spec children. Title and
+children go through the DOM API rather than innerHTML: props are
+$state-resolved machine data, never trusted markup.

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

@@ -0,0 +1,15 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / Panel
+
+# Variable: Panel
+
+```ts
+const Panel: ComponentFn<KitCatalog, "Panel">;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Panel.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Panel.ts#L11)
+
+Panel — generic container leaf.
+
+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-gallery-demo/variables/Text.md

@@ -0,0 +1,15 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-gallery-demo](../README.md) / Text
+
+# Variable: Text
+
+```ts
+const Text: ComponentFn<KitCatalog, "Text">;
+```
+
+Defined in: [packages/play-dom/examples/gallery/src/components/Text.ts:11](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-dom/examples/gallery/src/components/Text.ts#L11)
+
+Text — one paragraph of live text.
+
+`String(props.value)` on purpose: $state-resolved values may arrive as
+numbers (counts, elapsed millis) even though the schema declares a string —
+the DOM contract promises text, so coerce once here.