@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/contributing/testing.md

@@ -0,0 +1,461 @@
+# Testing
+
+This document describes the test framework, conventions, and CI integration for the XMachines JS monorepo.
+
+## Test Framework and Setup
+
+The monorepo uses **[Vitest](https://vitest.dev/) `^4.1.5`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
+
+All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from `@xmachines/shared/vitest`) which automatically applies:
+
+- `@xmachines/*` source aliases so imports resolve to source during test runs
+- `@xmachines/shared/vitest-setup` — extends Vitest matchers with `@testing-library/jest-dom`
+- `@xmachines/shared/vitest-node-setup` — enforces Node.js ≥ 22 on non-browser projects
+
+**Auto-injected setup files:**
+
+| File                                          | When injected            | Purpose                                                 |
+| --------------------------------------------- | ------------------------ | ------------------------------------------------------- |
+| `packages/shared/config/vitest.node.setup.ts` | All non-browser projects | Validates Node.js ≥ 22 runtime; throws if wrong runtime |
+| `packages/shared/config/vitest.setup.ts`      | All projects             | Imports `@testing-library/jest-dom/vitest` matchers     |
+
+Before running any tests, ensure all dependencies are installed:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+## Running Tests
+
+### Full test suite (Node environments)
+
+```bash
+pnpm test
+```
+
+Runs `vitest run` across all 30 package-level projects defined in the root `vitest.config.ts`. Uses the `forks` pool (up to 4 workers) with process-level isolation between test files.
+
+### Watch mode (development)
+
+```bash
+pnpm run test:watch
+```
+
+Runs `vitest` in interactive watch mode. Re-runs affected tests on file change.
+
+### Browser tests (Playwright / Chromium)
+
+```bash
+pnpm run test:browser
+```
+
+Runs `vitest run --config vitest.browser.config.ts`. Launches all browser-mode projects using headless Chromium via Playwright. Includes both package-level browser unit tests and full demo-app integration flows. The browser global setup (`vitest.browser.global-setup.ts`) raises `process.setMaxListeners` to 32 before workers spawn to prevent false-positive `MaxListenersExceededWarning` with multiple parallel browser projects.
+
+### With coverage
+
+```bash
+pnpm run test:coverage
+```
+
+Produces coverage output in `text`, `html`, and `json-summary` formats.
+
+```bash
+pnpm run test:browser:coverage   # browser suite, with coverage
+```
+
+Root-level coverage thresholds (regression gate):
+
+| Metric     | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Statements | 80%       |
+| Branches   | 75%       |
+
+Individual packages may enforce higher per-package thresholds in their own `vitest.config.ts`.
+
+### Verify TypeScript test graph compiles
+
+```bash
+pnpm run test:build
+```
+
+Runs `tsc --build tsconfig.test.json`. This validates that all test TypeScript files across the monorepo type-check correctly without running the tests themselves. Also compiles `.typecheck.ts` files in `src/` directories.
+
+### Running tests for a single package
+
+From the monorepo root:
+
+```bash
+pnpm --filter @xmachines/play test
+pnpm --filter @xmachines/play-react run test:coverage
+```
+
+Or from within a package directory, run `pnpm exec vitest run` directly after building the workspace.
+
+## Test File Organization
+
+Tests live in a separate `test/` directory within each package — never co-located with source files.
+
+```
+packages/<name>/
+├── src/
+│   ├── *.ts
+│   └── *.typecheck.ts       # Compile-time-only type assertions (not Vitest tests)
+└── test/
+    ├── *.spec.ts             # Protocol enforcement and type-safety tests
+    ├── *.test.ts             # Unit, integration, and behavioral tests
+    ├── browser/
+    │   └── *.browser.test.ts(x)   # Playwright browser environment tests
+    ├── fixtures/             # Shared test actors, helpers, mock data
+    └── tsconfig.json         # Test-specific tsconfig (extends shared/tsconfig-test)
+```
+
+### File naming conventions
+
+| Extension                                | Purpose                                                                                                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `.spec.ts`                               | Protocol enforcement tests; compile-time type safety tests; used in core packages (`play`, `play-actor`, `play-signals`, `play-xstate`) |
+| `.test.ts`                               | Unit, integration, and behavioral tests; used across all packages                                                                       |
+| `.browser.test.ts` / `.browser.test.tsx` | Playwright browser environment tests; excluded from standard `vitest.config.ts`, only run via `vitest.browser.config.ts`                |
+| `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `pnpm run test:build`                                       |
+| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                     |
+
+### Test environments
+
+| Environment                   | Packages                                                                                                   |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `node`                        | Core logic: `@xmachines/play`, `play-actor`, `play-signals`, `play-xstate`, `play-router`, router adapters |
+| `jsdom`                       | UI renderers: `@xmachines/play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`                 |
+| Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                        |
+
+### Test helpers and shared setup
+
+- **`@xmachines/shared/vitest-setup`** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
+- **`@xmachines/shared/vitest-node-setup`** — Enforces Node ≥ 22 at runtime. Auto-injected for non-browser configs.
+- **`@xmachines/shared/vitest-urlpattern-setup`** — Polyfills `URLPattern` for packages that need it (e.g. `@xmachines/play-router`). Must be declared explicitly in `setupFiles`.
+- **`packages/play-react/test/test-utils.ts`** — React-specific test utilities for the `play-react` package.
+- **`packages/play-router/examples/shared/`** and **`packages/play-actor/examples/shared/`** — Shared test fixtures for router and actor integration tests.
+
+## Writing New Tests
+
+### Adding a new package test config
+
+1. Place test files under `packages/<pkg>/test/`.
+2. Name them following the convention above.
+3. Import `defineXmVitestConfig` in the package's `vitest.config.ts`:
+
+    ```typescript
+    import { defineXmVitestConfig } from "@xmachines/shared/vitest";
+
+    export default defineXmVitestConfig(import.meta.url, {
+    	test: {
+    		environment: "node",
+    		include: ["test/**/*.test.ts"],
+    		exclude: ["node_modules/**"],
+    	},
+    });
+    ```
+
+4. Register the new config in the root `vitest.config.ts` `projects` array.
+5. Add the package's `tsconfig.test.json` to `tsconfig.test.json` references in the root.
+
+### Basic test structure
+
+```typescript
+import { describe, it, test, expect, vi, beforeEach, afterEach } from "vitest";
+
+describe("ClassName or functionName()", () => {
+	describe("feature group or scenario", () => {
+		test("specific behavior being verified", () => {
+			// arrange
+			const actor = createMockActor("/");
+
+			// act
+			actor.send({ type: "play.route", to: "#about" });
+
+			// assert
+			expect(actor.currentRoute.get()).toBe("/about");
+		});
+	});
+});
+```
+
+**Import style:** Always use `.js` extensions in imports (ESM requirement):
+
+```typescript
+import { AbstractActor } from "../src/abstract-actor.js";
+import { Signal } from "@xmachines/play-signals";
+```
+
+### Lifecycle hooks
+
+```typescript
+beforeEach(() => {
+	vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+	vi.restoreAllMocks(); // Always restore spies
+	cleanup(); // For @testing-library/react or equivalent
+});
+```
+
+### What to mock / what not to mock
+
+**Mock these:**
+
+- **Framework router objects** (TanStack Router, Vue Router, React Router, SolidJS Router) — mock with typed `vi.fn()` interfaces because they are external framework dependencies and carry significant setup complexity:
+
+    ```typescript
+    const mocks = vi.hoisted(() => ({
+    	machineToGraph: vi.fn(),
+    	buildRouteTree: vi.fn(),
+    }));
+
+    vi.mock("../src/machine-to-graph.js", () => ({
+    	machineToGraph: mocks.machineToGraph,
+    }));
+    ```
+
+- **`console.warn` / `console.error`** when testing code that legitimately emits warnings — mock to suppress noise and assert call counts:
+
+    ```typescript
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // ... test ...
+    expect(warnSpy).toHaveBeenCalled();
+    vi.restoreAllMocks(); // in afterEach
+    ```
+
+- **External module collaborators** when testing a unit in isolation.
+
+**Never mock these:**
+
+- **TC39 Signals** (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`) — always use real implementations from `@xmachines/play-signals`. Signals have precise reactive semantics (synchronous propagation, lazy computation) that mocks cannot replicate accurately.
+- **Internal `@xmachines/*` packages** — these are resolved directly to source via the `xmAliases` Vite plugin in the Vitest config. Mocking them would hide integration bugs and defeat the purpose of cross-package testing.
+- **XState** — always use real `setup()` / `createMachine()` / `createActor()`. XState's actor lifecycle (start, stop, snapshot, subscription) is a behavioral contract that mocks cannot reliably emulate.
+
+### Test actor patterns
+
+**Preferred: extend `AbstractActor` for full type safety:**
+
+```typescript
+import { AbstractActor } from "@xmachines/play-actor";
+import type { Routable } from "@xmachines/play-actor";
+import { Signal } from "@xmachines/play-signals";
+import type { AnyActorLogic } from "xstate";
+
+class MockActor extends AbstractActor<AnyActorLogic> implements Routable {
+	override state = new Signal.State({} as unknown);
+	private _routeState: Signal.State<string | null>;
+	readonly currentRoute: Signal.Computed<string | null>;
+	readonly initialRoute: string | null;
+
+	constructor(startRoute: string | null = "/") {
+		super({} as AnyActorLogic, {}); // {} as AnyActorLogic is the standard stub
+		this._routeState = new Signal.State<string | null>(startRoute);
+		this.currentRoute = new Signal.Computed(() => this._routeState.get());
+		this.initialRoute = startRoute;
+	}
+
+	override send(_event: { readonly type: string } & Record<string, unknown>): void {
+		// no-op or capture events for assertion
+	}
+}
+```
+
+**Factory functions for lightweight inline mocks:**
+
+```typescript
+function createMockActor(initialView: PlaySpec | null = null) {
+	return {
+		currentView: new Signal.State<PlaySpec | null>(initialView),
+		send: vi.fn(),
+		start: vi.fn(),
+		stop: vi.fn(),
+		getSnapshot: vi.fn(),
+		subscribe: vi.fn(),
+		state: new Signal.State({} as unknown),
+		currentRoute: new Signal.Computed(() => null),
+	} as unknown as AbstractActor<AnyActorLogic> & Viewable;
+}
+```
+
+### Async and signal patterns
+
+**Flushing the microtask queue (required for Signal propagation):**
+
+```typescript
+function waitForMicrotask(): Promise<void> {
+	return new Promise<void>((resolve) => queueMicrotask(resolve));
+}
+await waitForMicrotask();
+
+// Or use Vitest's helper:
+await vi.waitFor(() => expect(result).toBe(expected), { timeout: 100 });
+```
+
+**Signal watcher pattern:**
+
+```typescript
+let notified = false;
+const watcher = new Signal.subtle.Watcher(() => {
+	notified = true;
+});
+watcher.watch(actor.currentRoute);
+actor.currentRoute.get(); // Initial read required to prime computed signals
+
+actor.state.set({ path: "/dashboard" });
+watcher.getPending(); // Process notifications synchronously
+
+expect(notified).toBe(true);
+watcher.unwatch(actor.currentRoute); // Always clean up
+```
+
+### Compile-time type tests
+
+For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
+
+```typescript
+const bad: PlaySpec = typedSpec<MyCtx>({
+	root: "root",
+	// @ts-expect-error "typo" is not a key of MyCtx — typedSpec enforces this
+	contextProps: ["typo"],
+	elements: {},
+});
+// At runtime the object exists; only the compile-time error is being tested
+expect(bad.contextProps).toEqual(["typo"]);
+```
+
+For purely structural type assertions with no runtime test needed, use `.typecheck.ts` files in `src/`:
+
+```typescript
+// packages/play-xstate/src/define-player.typecheck.ts
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type AssertFalse<T extends false> = T;
+
+const actorNotAny: AssertFalse<IsAny<typeof actor>> = false;
+void actorNotAny;
+```
+
+These files are validated by `pnpm run test:build` (`tsc --build tsconfig.test.json`) — never executed by Vitest.
+
+### Error testing
+
+```typescript
+// Synchronous throws
+expect(() => actor.send(null as unknown as PlayEvent)).toThrow(InvalidEventError);
+
+// Error with message pattern
+expect(() => extractMachineRoutes(dupMachine)).toThrow(/Duplicate route paths detected/);
+
+// Inspect error properties
+try {
+	extractMachineRoutes(dupMachine);
+	expect.fail("Should have thrown");
+} catch (error: unknown) {
+	const message = error instanceof Error ? error.message : String(error);
+	expect(message.toLowerCase()).toContain("duplicate");
+}
+```
+
+## Contract Tests
+
+The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in `@xmachines/play-router`) because the suite drives a real actor via `@xmachines/play-xstate` and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps `@xmachines/play-router` free of any dependency on the actor runtime:
+
+```typescript
+// packages/play-router/examples/shared/test/router-bridge-contract.ts
+export function runBridgeContractTests(opts: ContractSuiteOptions): void;
+
+// Each adapter's test file calls it:
+import { runBridgeContractTests } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
+
+runBridgeContractTests({
+	name: "TanStackReactRouterBridge",
+	createHarness(initialPath) {
+		/* ... */
+	},
+	createRestoredHarness(routedPath) {
+		/* ... */
+	},
+});
+```
+
+The contract covers: deep-link sync on connect, router→actor navigation sync, actor→router sync, guard redirect flows, duplicate event deduplication, and restore-from-snapshot behavior.
+
+**Used by:** `@xmachines/play-router`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-react-router`, and other adapter packages.
+
+**Compile-time bridge contract verification:**
+
+```typescript
+import { assertImplementsRouterBridge } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
+import { MyRouterBridge } from "../src/my-router-bridge.js";
+
+assertImplementsRouterBridge<MyRouterBridge>(); // Zero runtime cost
+```
+
+## Coverage Requirements
+
+Coverage is collected using the **v8** provider. The root `vitest.config.ts` defines monorepo-wide regression thresholds:
+
+| Type       | Monorepo threshold |
+| ---------- | ------------------ |
+| Lines      | 80%                |
+| Functions  | 80%                |
+| Branches   | 75%                |
+| Statements | 80%                |
+
+Individual packages enforce their own (typically stricter) thresholds inside their `vitest.config.ts`:
+
+| Package tier                                                               | Lines | Functions | Branches | Statements |
+| -------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
+| Core packages (`@xmachines/play`, `@xmachines/play-actor`)                 | 90%   | 90%       | 85%      | 90%        |
+| Complex logic (`@xmachines/play-xstate`, `@xmachines/play-router`)         | 85%   | 85%       | 80%      | 85%        |
+| Integration packages (e.g. `@xmachines/play-react`, `@xmachines/play-dom`) | 80%   | 80%       | 80%      | 80%        |
+
+Coverage includes: `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
+
+Coverage is excluded for: `test/**/*`, `**/*.test.ts`, `**/*.test.tsx`, `**/*.d.ts`, `dist/**/*`.
+
+## CI Integration
+
+Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (version `5.1.2`).
+
+**Workflow:** The pipeline runs on:
+
+- Tag pushes (`$CI_COMMIT_TAG`)
+- Pushes to the default branch (`$CI_DEFAULT_BRANCH`)
+- Merge requests (`$CI_MERGE_REQUEST_IID`)
+
+**CI test command** (from `.gitlab-ci.yml`):
+
+```bash
+pnpm run test:coverage -- \
+  --coverage.reporter=text \
+  --coverage.reporter=cobertura \
+  --coverage.reportsDirectory=reports/coverage \
+  --reporter=default \
+  --reporter=junit \
+  --outputFile.junit=reports/junit.xml
+```
+
+**Artifacts:** The CI job (`node-build`) publishes:
+
+- JUnit XML report at `reports/junit.xml` (surfaced in GitLab's test results panel)
+- Cobertura coverage XML at `reports/coverage/cobertura-coverage.xml` (used for GitLab's coverage percentage badge — extracted from the `All files` line)
+
+Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.
+
+The `pnpm run format:check` and `pnpm run lint` commands enforce code style and are run separately from tests (via the `lint-enabled: true` input to the pipeline component).
+
+## Test Types Reference
+
+| Test type              | Extension                   | Environment           | Scope                                          |
+| ---------------------- | --------------------------- | --------------------- | ---------------------------------------------- |
+| Unit                   | `.test.ts`                  | `node` or `jsdom`     | Single module in isolation                     |
+| Protocol/type safety   | `.spec.ts`                  | `node`                | Compile-time type correctness + RFC invariants |
+| Integration            | `.test.ts`                  | `node`                | Multiple modules working together              |
+| Performance/regression | `.spec.ts`                  | `node`                | Timing budgets for critical paths              |
+| Browser unit           | `.browser.test.ts(x)`       | Chromium (Playwright) | Browser-specific APIs, real microtask timing   |
+| E2E demo               | `.browser.test.tsx`         | Chromium (Playwright) | Full application flows in demo packages        |
+| Type-only              | `.typecheck.ts` (in `src/`) | `tsc` only            | Structural type assertions; no Vitest runner   |

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

@@ -0,0 +1,181 @@
+[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 TC39 Signal watchers
+- `watchSignal` for reactive nav visibility and debug panel updates
+- Non-browser invariant tests plus browser renderer coverage
+
+## 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` calls `definePlayer({ machine: authMachine })` and starts the actor.
+2. `initShell(actor, app)` from `src/components/Shell.ts` builds the HTML scaffold, mounts a reactive `NavBar`, wires the debug panel, and returns a disconnect function.
+3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
+4. `createPlayUI(registryResult)` produces a `mount` function; `mount(actor, container)` wires the registry to the actor — view switches happen automatically when `actor.currentView` changes.
+5. `createNavBar(actor, headerEl)` in `src/components/NavBar.ts` uses `watchSignal(actor.state, ...)` to update nav button visibility based on auth state.
+6. `createDebugPanel(actor, shell)` in `src/components/DebugPanel.ts` uses `watchSignal(actor.state, ...)` and `watchSignal(actor.currentRoute, ...)` to drive live debug panel updates.
+7. Browser tests in `test/browser/` validate startup rendering and auth interactions.
+
+```ts
+// src/main.ts (shape)
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
+actor.start();
+
+const app = document.getElementById("app");
+if (!app) throw new Error("Root element not found");
+
+initShell(actor, app);
+```
+
+```ts
+// src/components/Shell.ts (shape)
+const registryResult = defineRegistry(authCatalog, {
+	components: {
+		Home,
+		About,
+		Contact,
+		Login,
+		Dashboard,
+		Overview,
+		Stats,
+		Profile,
+		Settings,
+		Navigation,
+		NavBar: NavBarView,
+	},
+	actions: {
+		login: async (args) =>
+			actor.send({
+				type: "auth.login",
+				username: assertNonNullable(args, "args").username,
+			}),
+		logout: async () => actor.send({ type: "auth.logout" }),
+		route: async (args) => {
+			const { to, params } = assertNonNullable(args, "args");
+			actor.send({
+				type: "play.route",
+				to,
+				...(params != null && { params }),
+			});
+		},
+	},
+});
+
+const disconnectNavBar = createNavBar(actor, headerEl);
+const mount = createPlayUI(registryResult);
+const disconnectRenderer = mount(actor, viewContent);
+const disconnectDebugPanel = createDebugPanel(actor, shell);
+
+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 `watchSignal(actor.state, ...)` for auth-driven button visibility
+- `src/components/DebugPanel.ts` - live debug footer using `watchSignal` on both `actor.state` and `actor.currentRoute`
+- `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 `watchSignal` only react to actor signals. They do not hold business state or make routing decisions.
+3. **Signal-Only Reactivity:** `watchSignal` (from [`@xmachines/play-signals`](../../../api/@xmachines/play-signals/README.md)) wraps the canonical TC39 Signals watcher lifecycle, keeping all reactivity in the actor signal layer rather than in ad-hoc DOM event listeners.
+
+## Watcher Lifecycle and Cleanup Contract
+
+This demo follows the canonical watcher lifecycle:
+
+1. `notify`
+2. `queueMicrotask`
+3. `getPending()`
+4. Read actor signals and project DOM state
+5. Re-arm with `watch()`/`watch(...signals)`
+
+Watcher notifications are one-shot. Cleanup is explicit: `disconnectNavBar()`, `disconnectRenderer()`, and `disconnectDebugPanel()` are all called from the disconnect function returned by `initShell`. In this demo, cleanup is called on `beforeunload` via `actor.stop()`.
+
+## Adapter Boundaries
+
+`createPlayUI` (from [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md)) is passive infrastructure. It translates actor view signals into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
+
+## 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               |
+
+## Verification
+
+Use these checks to validate README claims against the current demo implementation:
+
+```bash
+pnpm --filter @xmachines/play-dom-demo run test
+pnpm --filter @xmachines/play-dom-demo run test:browser
+```
+
+Expected result: library-pattern invariant tests pass and the browser renderer suite completes.
+
+## Learn More
+
+- [Play DOM](../../../api/@xmachines/play-dom/README.md)
+- [Play DOM Router](../play-dom-router-demo/README.md)
+
+## Type Aliases
+
+- [AuthCatalog](type-aliases/AuthCatalog.md)
+
+## Variables
+
+- [About](variables/About.md)
+- [authCatalog](variables/authCatalog.md)
+- [Contact](variables/Contact.md)
+- [Dashboard](variables/Dashboard.md)
+- [Home](variables/Home.md)
+- [Login](variables/Login.md)
+- [NavBarView](variables/NavBarView.md)
+- [Navigation](variables/Navigation.md)
+- [Overview](variables/Overview.md)
+- [Profile](variables/Profile.md)
+- [Settings](variables/Settings.md)
+- [Stats](variables/Stats.md)
+
+## Functions
+
+- [createNavBar](functions/createNavBar.md)
+- [initShell](functions/initShell.md)

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

@@ -0,0 +1,24 @@
+[Examples](../../../README.md) / [@xmachines/play-dom-demo](../README.md) / createNavBar
+
+# Function: createNavBar()
+
+```ts
+function createNavBar(actor, container): () => void;
+```
+
+Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.1.0/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+
+NavBar — App-shell navigation factory. Mounts a reactive nav into
+`container`, observes actor.state via watchSignal, and updates button
+visibility based on auth state. Returns a disconnect function.
+
+## Parameters
+
+| Parameter   | Type          |
+| ----------- | ------------- |
+| `actor`     | `AuthActor`   |
+| `container` | `HTMLElement` |
+
+## Returns
+
+() => `void`

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

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