@xmachines/docs 7.0.0 → 7.2.0

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

@@ -0,0 +1,74 @@
+[Examples](../../README.md) / @xmachines/play-react-router-trivia-demo
+
+# @xmachines/play-react-router-trivia-demo
+
+React Router v7 integration demo of the shared **trivia** machine for the XMachines Play architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What This Demonstrates
+
+- Shared trivia machine reused without framework-specific business logic
+- `PlayRouterProvider` renderer-based integration with React Router — the quiz states map to `/`, `/trivia`, `/win`, and `/lose`
+- Shell, catalog, and component kit imported from the workspace-only [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md) renderer gallery
+- Actor-authoritative navigation: only `/` is reachable from a cold start, and a deep link to `/trivia` while idle is overwritten back (State-Driven Reset)
+- Stately inspector attached at creation via `options.inspect` — the debug panel's **Show Inspector** button opens the live machine in its own window
+
+## Running the Demo
+
+From the repository root:
+
+```bash
+pnpm install
+pnpm --filter @xmachines/play-react-router-trivia-demo run dev
+```
+
+Then open `http://localhost:3065`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />`.
+2. `src/App.tsx` calls `useMemo(createAppRuntime, [])` to create the actor and browser router, starting the actor once per mounted app.
+3. `src/runtime.ts` pre-builds the `routeMap` (via `createRouteMap(triviaMachine)`) and exports `createPlayer`, `routeMap`, and `createRegistryResult` — keeping runtime setup separate from React lifecycle concerns.
+4. `createAppRuntime()` creates the actor, builds a `registryResult` from `triviaCatalog` + `demoComponents` (both imported from [`@xmachines/play-react-gallery-demo`](../play-react-gallery-demo/README.md)), and constructs a React Router data router with a `RoutedShell` wrapper.
+5. `PlayRouterProvider` wires actor navigation and router changes in both directions, using the pre-built `routeMap`.
+6. `Shell` (imported from the renderer gallery) receives `actor`, `router`, `registryResult`, and `inspector`.
+7. Browser tests in `test/browser/` delegate to the shared trivia router suite.
+
+## Key Files
+
+- `src/main.tsx` - React entry point that mounts `<App />`
+- `src/runtime.ts` - actor factory (`createPlayer`), pre-built `routeMap`, and `createRegistryResult` registry wiring
+- `src/App.tsx` - actor lifecycle, provider wiring, and `RoutedShell` composition
+- `test/browser/shared-demo.browser.test.tsx` - delegates to the shared trivia router browser suite
+
+## Architecture Invariants
+
+1. **Actor Authority:** Navigation triggers URL changes, which the `PlayRouterProvider` intercepts and converts into `play.route` events. The actor evaluates these events against its internal guards and transitions.
+2. **Passive Infrastructure:** The router does not execute business logic. The actor dictates whether navigation is permitted.
+3. **State-Driven Reset:** An external history change to an invalid route is overwritten back from actor state — the URL always reflects the machine.
+
+## Available Scripts
+
+| Command                                                                   | Description                                    |
+| ------------------------------------------------------------------------- | ---------------------------------------------- |
+| `pnpm --filter @xmachines/play-react-router-trivia-demo run dev`          | Start Vite dev server (http://localhost:3065/) |
+| `pnpm --filter @xmachines/play-react-router-trivia-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-react-router-trivia-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-react-router-trivia-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-react-router-trivia-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-react-router-trivia-demo run test
+pnpm --filter @xmachines/play-react-router-trivia-demo run test:browser
+```
+
+Expected result: the shared trivia router browser suite completes (the node suite passes with no tests).
+
+## Learn More
+
+- [React Router adapter](../../../api/@xmachines/play-react-router/README.md)
+- [React renderer gallery](../play-react-gallery-demo/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)

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

@@ -0,0 +1,123 @@
+[Examples](../../README.md) / @xmachines/play-solid-gallery-demo
+
+# @xmachines/play-solid-gallery-demo
+
+Solid renderer gallery for [`@xmachines/play-solid`](../../../api/@xmachines/play-solid/README.md) — all nine shared machines behind one picker, actor + `PlayRenderer` 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 and registered with every machine's typed `defineRegistry` catalog — `Field` also registers declarative `checks` with the ValidationProvider and renders `formErrors` in a `[data-demo-error]` node
+- Solid reactivity idioms throughout: `createSignal` for the selection, `<Show keyed>` / `<For>` for the picker and machine subtree, `ctx.props` accessors in every kit component, `watchSignal` + `onCleanup` in the debug panel
+- Routing machines run WITHOUT a router here — navigation happens via their in-view route-action buttons; the actor owns view switching
+- 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-solid-gallery-demo run dev
+```
+
+Then open `http://localhost:3022`.
+
+## Step-by-Step Code Flow
+
+1. `src/main.tsx` mounts `<App />` with `render()` from `solid-js/web`.
+2. `src/App.tsx` renders the picker; `openMachine(entry)` stops any previous actor 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. `Shell` wraps `<PlayUIProvider actor registryResult><PlayRenderer /></PlayUIProvider>` in the standard demo chrome plus the `DebugPanel`; the gallery passes `title` and a `nav` slot carrying the "Back to gallery" button.
+6. Browser tests in `test/browser/` delegate one file per machine to that machine's shared renderer suite.
+
+## Key Files
+
+- `src/main.tsx` - Solid entry point that mounts `<App />`
+- `src/App.tsx` - picker, per-selection actor lifecycle, and `Shell` 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` and `DebugPanel`
+- `src/index.ts` - barrel exporting `App`, the kit, `demoComponents`, `Shell`, `DebugPanel`, and every built catalog for the router demos
+- `test/library-pattern.test.ts` - architecture boundary and invariant assertions
+- `test/browser/<slug>-demo.browser.test.tsx` - one file per machine, delegating to the shared suites
+- `test/browser/gallery-picker.browser.test.tsx` - 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 — Solid never decides which view to render.
+2. **Passive Infrastructure:** `PlayRenderer` 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-solid-gallery-demo run dev`          | Start Vite dev server (http://localhost:3022/) |
+| `pnpm --filter @xmachines/play-solid-gallery-demo run build`        | Build production bundle                        |
+| `pnpm --filter @xmachines/play-solid-gallery-demo run preview`      | Preview built bundle                           |
+| `pnpm --filter @xmachines/play-solid-gallery-demo run test`         | Run Vitest test suite                          |
+| `pnpm --filter @xmachines/play-solid-gallery-demo run test:browser` | Run browser-focused Vitest suite               |
+
+## Verification
+
+```bash
+pnpm --filter @xmachines/play-solid-gallery-demo run test
+pnpm --filter @xmachines/play-solid-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-solid](../../../api/@xmachines/play-solid/README.md)
+- [Inspecting a Running Actor](../../../guides/inspector.md)
+
+## Interfaces
+
+- [GalleryMachineEntry](interfaces/GalleryMachineEntry.md)
+- [GalleryRuntime](interfaces/GalleryRuntime.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)
+- [DebugPanel](variables/DebugPanel.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)
+- [Shell](variables/Shell.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
+
+- [App](functions/App.md)

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / App
+
+# Function: App()
+
+```ts
+function App(): Element;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/App.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/App.tsx#L28)
+
+## Returns
+
+`Element`

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

@@ -0,0 +1,13 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / GalleryMachineEntry
+
+# Interface: GalleryMachineEntry
+
+Defined in: [packages/play-solid/examples/gallery/src/machines.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/machines.ts#L86)
+
+## 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-solid/examples/gallery/src/machines.ts:94](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/machines.ts#L94) |
+| <a id="property-label"></a> `label`                 | `string`                                             | Picker button label and machine-view title.                                                                                              | [packages/play-solid/examples/gallery/src/machines.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/machines.ts#L89) |
+| <a id="property-slug"></a> `slug`                   | [`GallerySlug`](../type-aliases/GallerySlug.md)      | -                                                                                                                                        | [packages/play-solid/examples/gallery/src/machines.ts:87](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/machines.ts#L87) |

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

@@ -0,0 +1,14 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / GalleryRuntime
+
+# Interface: GalleryRuntime
+
+Defined in: [packages/play-solid/examples/gallery/src/machines.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/machines.ts#L81)
+
+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-solid/examples/gallery/src/machines.ts:82](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/machines.ts#L82) |
+| <a id="property-registryresult"></a> `registryResult` | [`DefineRegistryResult`](../../../../api/@xmachines/play-solid/interfaces/DefineRegistryResult.md) | [packages/play-solid/examples/gallery/src/machines.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/machines.ts#L83) |

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,16 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / KitCatalog
+
+# Type Alias: KitCatalog
+
+```ts
+type KitCatalog = FetchCatalog;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/catalogs.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/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-solid-gallery-demo/type-aliases/StopwatchCatalog.md

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,11 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / Button
+
+# Variable: Button
+
+```ts
+const Button: ComponentFn<KitCatalog, "Button">;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/components/Button.tsx:10](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/components/Button.tsx#L10)
+
+Button — action leaf: emits 'press'; the spec binding decides what happens.

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

@@ -0,0 +1,22 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / DebugPanel
+
+# Variable: DebugPanel
+
+```ts
+const DebugPanel: Component<{
+  actor: GalleryActor;
+  inspector: DemoInspector;
+}>;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/components/DebugPanel.tsx:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/components/DebugPanel.tsx#L18)
+
+DebugPanel — live debug footer. Observes the state of the actor through a computed
+label atom and mirrors it into a Solid signal. Also renders the button that opens the
+Stately inspector window. Works with any of the nine gallery actors.
+
+The label atom collapses the union of nine snapshot types into one string, so one
+`watchAtom` call can watch it. The watch lives inside a `createEffect` that reads
+`props.actor`, so it arms again when the gallery hands the panel another actor: a
+watch in the component body reads the prop one time and reports a machine that has
+gone.

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

@@ -0,0 +1,11 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / Field
+
+# Variable: Field
+
+```ts
+const Field: ComponentFn<KitCatalog, "Field">;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/components/Field.tsx:28](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/components/Field.tsx#L28)
+
+Field — input leaf: $bindState two-way binding plus declarative `checks`/`formErrors` display.

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

@@ -0,0 +1,11 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / Page
+
+# Variable: Page
+
+```ts
+const Page: ComponentFn<KitCatalog, "Page">;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/components/Page.tsx:14](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/components/Page.tsx#L14)
+
+Page — root of every view: renders data-page={page} plus an h2 title.

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

@@ -0,0 +1,11 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / Panel
+
+# Variable: Panel
+
+```ts
+const Panel: ComponentFn<KitCatalog, "Panel">;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/components/Panel.tsx:16](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/components/Panel.tsx#L16)
+
+Panel — titled section rendering its spec children (also the repeat container/row).

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

@@ -0,0 +1,26 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / Shell
+
+# Variable: Shell
+
+```ts
+const Shell: Component<{
+  actor: GalleryActor;
+  inspector: DemoInspector;
+  nav?: JSX.Element;
+  registryResult: DefineRegistryResult;
+  router?: unknown;
+  title?: string;
+}>;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/components/Shell.tsx:19](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/components/Shell.tsx#L19)
+
+Demo Shell layout component.
+
+Wraps PlayRenderer and DebugPanel in the standard demo chrome. 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 Shell: the gallery
+passes `title`/`nav` (machine label + "Back to gallery" button); router
+demos render it bare with their bridged `router`.

package/examples/@xmachines/play-solid-gallery-demo/variables/Text.md

@@ -0,0 +1,11 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / Text
+
+# Variable: Text
+
+```ts
+const Text: ComponentFn<KitCatalog, "Text">;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/components/Text.tsx:13](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/components/Text.tsx#L13)
+
+Text — live text leaf: renders String(ctx.props.value) so numeric $state values are safe.

package/examples/@xmachines/play-solid-gallery-demo/variables/authCatalog.md

@@ -0,0 +1,126 @@
+[Examples](../../../README.md) / [@xmachines/play-solid-gallery-demo](../README.md) / authCatalog
+
+# Variable: authCatalog
+
+```ts
+const authCatalog: Catalog<{
+  catalog: SchemaType<"object", {
+     actions: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        params: SchemaType<"zod", unknown>;
+     }>;
+     components: SchemaType<"map", {
+        description: SchemaType<"string", unknown>;
+        example: SchemaType<"any", unknown>;
+        props: SchemaType<"zod", unknown>;
+        slots: SchemaType<"array", SchemaType<"string", unknown>>;
+     }>;
+  }>;
+  spec: SchemaType<"object", {
+     elements: SchemaType<"record", SchemaType<"object", {
+        children: SchemaType<"array", SchemaType<"string", unknown>>;
+        props: SchemaType<"propsOf", string>;
+        repeat: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+        slots: {
+           inner?: SchemaType<"array", SchemaType<..., ...>>;
+           kind: "record";
+           optional: true;
+        };
+        type: SchemaType<"ref", string>;
+        visible: {
+           inner?: unknown;
+           kind: "any";
+           optional: true;
+        };
+     }>>;
+     root: SchemaType<"string", unknown>;
+  }>;
+}, {
+  actions: {
+     login: {
+        description: "Log in with a username (sends auth.login to the machine)";
+        params: ZodObject<{
+           username: ZodString;
+        }, $strip>;
+     };
+     logout: {
+        description: "Log out and return to home (sends auth.logout)";
+     };
+     route: {
+        description: "Navigate to a route by state id (e.g. '#home', '#login', '#dashboard')";
+        params: ZodObject<{
+           params: ZodOptional<ZodRecord<ZodString, ZodString>>;
+           to: ZodString;
+        }, $strip>;
+     };
+  };
+  components: {
+     Button: {
+        props: ZodObject<{
+           disabled: ZodOptional<ZodBoolean>;
+           label: ZodString;
+           testId: ZodOptional<ZodString>;
+           variant: ZodOptional<ZodEnum<{
+              danger: "danger";
+              primary: "primary";
+              secondary: "secondary";
+           }>>;
+        }, $strip>;
+     };
+     Field: {
+        props: ZodObject<{
+           checks: ZodOptional<ZodArray<ZodCustom<ValidationCheck, ValidationCheck>>>;
+           formErrors: ZodOptional<ZodRecord<ZodString, ZodArray<ZodString>>>;
+           inputType: ZodOptional<ZodEnum<{
+              email: "email";
+              text: "text";
+              textarea: "textarea";
+           }>>;
+           label: ZodString;
+           placeholder: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           value: ZodOptional<ZodString>;
+        }, $strip>;
+     };
+     Page: {
+        props: ZodObject<{
+           page: ZodString;
+           title: ZodString;
+        }, $strip>;
+     };
+     Panel: {
+        props: ZodObject<{
+           note: ZodOptional<ZodString>;
+           testId: ZodOptional<ZodString>;
+           title: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+        }, $strip>;
+     };
+     Text: {
+        props: ZodObject<{
+           testId: ZodOptional<ZodString>;
+           tone: ZodOptional<ZodEnum<{
+              danger: "danger";
+              default: "default";
+              muted: "muted";
+              success: "success";
+           }>>;
+           value: ZodString;
+        }, $strip>;
+     };
+  };
+}>;
+```
+
+Defined in: [packages/play-solid/examples/gallery/src/catalogs.ts:46](https://gitlab.com/xmachin-es/xmachines-js/-/blob/docs-v7.2.0/packages/play-solid/examples/gallery/src/catalogs.ts#L46)
+
+Built catalogs, one per machine — router demos import theirs from here.