@xmachines/docs 1.0.0-beta.51 → 1.0.0-beta.53

package/contributing/testing.md

@@ -2,38 +2,17 @@
 
 # Testing
 
-This document describes the test framework, test organization, how to run tests, and patterns used across the XMachines JS monorepo.
+This document describes the test framework, conventions, and CI integration for the XMachines JS monorepo.
 
 ## Test Framework and Setup
 
-**Runner:** [Vitest](https://vitest.dev/) `^4.1.4`
+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.
 
-**Assertion library:** Vitest built-in `expect` + `@testing-library/jest-dom` matchers (auto-injected via shared setup)
+All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from `@xmachines/shared/vitest`) which automatically applies:
 
-**Coverage provider:** `@vitest/coverage-v8`
-
-All packages use [`defineXmVitestConfig`](../api/@xmachines/shared/vitest/functions/defineXmVitestConfig.md) from [`@xmachines/shared/vitest`](../api/@xmachines/shared/vitest/README.md) — a factory that wraps `mergeConfig` and automatically injects shared setup files:
-
-```typescript
-// packages/<name>/vitest.config.ts
-import { defineXmVitestConfig } from "@xmachines/shared/vitest";
-
-export default defineXmVitestConfig(import.meta.url, {
-	test: {
-		environment: "node", // or "jsdom" for UI renderer packages
-		include: ["test/**/*.spec.ts", "test/**/*.test.ts"],
-		exclude: ["node_modules/**"],
-		coverage: {
-			provider: "v8",
-			reporter: ["text", "html", "json-summary"],
-			include: ["src/**/*.ts"],
-			exclude: ["test/**/*", "**/*.test.ts", "**/*.d.ts", "dist/**/*"],
-			all: true,
-			thresholds: { lines: 90, functions: 90, branches: 85, statements: 90 },
-		},
-	},
-});
-```
+- `@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:**
 
@@ -42,23 +21,21 @@ export default defineXmVitestConfig(import.meta.url, {
 | `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     |
 
-**Test environments by package type:**
+Before running any tests, ensure all dependencies are installed:
 
-| Environment                   | Packages                                                                                                                                       |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `node`                        | Core logic: [`@xmachines/play`](../api/@xmachines/play/README.md), `play-actor`, `play-signals`, `play-xstate`, `play-router`, router adapters |
-| `jsdom`                       | UI renderers: [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), `play-vue`, `play-solid`, `play-svelte`, `play-dom`           |
-| Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                                                            |
+```bash
+npm ci
+```
 
 ## Running Tests
 
-### All unit tests (node + jsdom)
+### Full test suite (Node environments)
 
 ```bash
 npm test
 ```
 
-Runs `vitest run` across all 30+ package-level projects defined in `vitest.config.ts`.
+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)
 
@@ -66,39 +43,48 @@ Runs `vitest run` across all 30+ package-level projects defined in `vitest.confi
 npm run test:watch
 ```
 
-Runs `vitest` in interactive watch mode. Re-runs affected test files on save.
+Runs `vitest` in interactive watch mode. Re-runs affected tests on file change.
 
-### Browser tests (Playwright/Chromium)
+### Browser tests (Playwright / Chromium)
 
 ```bash
 npm run test:browser
 ```
 
-Runs `vitest run --config vitest.browser.config.ts`. Executes all `*.browser.test.ts(x)` files in real Chromium via `@vitest/browser-playwright`. Covers browser-specific APIs (history, URLPattern, DOM events, real microtask timing) and full-application E2E flows in demo packages.
+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.
 
-### Coverage
+### With coverage
 
 ```bash
-npm run test:coverage          # Run all tests with coverage (text + html + json-summary)
-npm run coverage:report        # HTML coverage report
-npm run coverage:summary       # JSON summary for CI
+npm run test:coverage
 ```
 
-### Type-checking test files
+Produces coverage output in `text`, `html`, and `json-summary` formats.
+
+```bash
+npm run coverage:report   # HTML report
+npm run coverage:summary  # JSON summary only
+```
+
+### Verify TypeScript test graph compiles
 
 ```bash
 npm run test:build
 ```
 
-Runs `tsc --build tsconfig.test.json` — compiles test files (including `.typecheck.ts` files in `src/`) without executing them. This is the mechanism for catching compile-time type safety failures.
+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
 
-### Per-package tests (workspace)
+From the monorepo root:
 
 ```bash
-npm test -w packages/play-xstate
+npm test -w packages/play
 npm run test:coverage -w packages/play-react
 ```
 
+Or from within a package directory, run `npx 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.
@@ -117,7 +103,7 @@ packages/<name>/
     └── tsconfig.json         # Test-specific tsconfig (extends shared/tsconfig-test)
 ```
 
-**File naming conventions:**
+### File naming conventions
 
 | Extension                                | Purpose                                                                                                                                 |
 | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
@@ -127,13 +113,46 @@ packages/<name>/
 | `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `npm 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
 
-### Unit and integration 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/**"],
+    	},
+    });
+    ```
 
-Place new test files in the package's `test/` directory. Use `.test.ts` for standard tests and `.spec.ts` for protocol/type-safety tests in core packages.
+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:**
+### Basic test structure
 
 ```typescript
 import { describe, it, test, expect, vi, beforeEach, afterEach } from "vitest";
@@ -161,12 +180,6 @@ import { AbstractActor } from "../src/abstract-actor.js";
 import { Signal } from "@xmachines/play-signals";
 ```
 
-**`it` vs `test`:** Both are interchangeable. Some files alias one to the other for consistency within a file:
-
-```typescript
-import { it as test } from "vitest";
-```
-
 ### Lifecycle hooks
 
 ```typescript
@@ -180,57 +193,43 @@ afterEach(() => {
 });
 ```
 
-### Mocking
+### What to mock / what not to mock
 
-**Module mocking with `vi.hoisted` (required when mocks are referenced before module evaluation):**
+**Mock these:**
 
-```typescript
-const mocks = vi.hoisted(() => ({
-	machineToGraph: vi.fn(),
-	buildRouteTree: vi.fn(),
-}));
-
-vi.mock("../src/machine-to-graph.js", () => ({
-	machineToGraph: mocks.machineToGraph,
-}));
-```
+- **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:
 
-**Function mocks:**
+    ```typescript
+    const mocks = vi.hoisted(() => ({
+    	machineToGraph: vi.fn(),
+    	buildRouteTree: vi.fn(),
+    }));
 
-```typescript
-const sendSpy = vi.fn();
-const navigate = vi.fn(({ to }: { to: string }) => {
-	/* side effect */
-});
-const mockReturnValue = vi.fn().mockReturnValue(stubValue);
-const asyncMock = vi.fn().mockResolvedValue(undefined);
-const failingMock = vi.fn().mockRejectedValue(new Error("fail"));
-```
+    vi.mock("../src/machine-to-graph.js", () => ({
+    	machineToGraph: mocks.machineToGraph,
+    }));
+    ```
 
-**Spy pattern for console suppression:**
+- **`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
-```
-
-**What to mock:**
+    ```typescript
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // ... test ...
+    expect(warnSpy).toHaveBeenCalled();
+    vi.restoreAllMocks(); // in afterEach
+    ```
 
-- Framework router objects (TanStack, Vue Router, React Router) — mock with typed `vi.fn()` interfaces
-- `console.warn` / `console.error` when testing code that legitimately logs warnings
-- External module collaborators when testing a unit in isolation
+- **External module collaborators** when testing a unit in isolation.
 
-**What NOT to mock:**
+**Never mock these:**
 
-- Signals (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`) — use real implementations
-- Internal `@xmachines/*` packages — resolved to source via [`xmAliases`](../api/@xmachines/shared/vite-aliases/functions/xmAliases.md) in Vitest config
-- XState — use real `setup()` / `createMachine()` / `createActor()`
+- **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`](../api/@xmachines/play-actor/classes/AbstractActor.md) for full type safety:**
+**Preferred: extend `AbstractActor` for full type safety:**
 
 ```typescript
 import { AbstractActor } from "@xmachines/play-actor";
@@ -274,34 +273,6 @@ function createMockActor(initialView: PlaySpec | null = null) {
 }
 ```
 
-### 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 `npm run test:build` (`tsc --build tsconfig.test.json`) — never executed by Vitest.
-
 ### Async and signal patterns
 
 **Flushing the microtask queue (required for Signal propagation):**
@@ -333,7 +304,35 @@ expect(notified).toBe(true);
 watcher.unwatch(actor.currentRoute); // Always clean up
 ```
 
-**Error testing:**
+### 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 `npm run test:build` (`tsc --build tsconfig.test.json`) — never executed by Vitest.
+
+### Error testing
 
 ```typescript
 // Synchronous throws
@@ -352,34 +351,9 @@ try {
 }
 ```
 
-**Testing-library pattern (React/Vue/Solid/Svelte):**
-
-```typescript
-// React
-const { getByTestId } = render(withRenderer({ actor, registryResult }));
-expect(getByTestId("fallback")).toBeTruthy();
-await waitFor(() => expect(screen.getByRole("heading")).toBeInTheDocument());
-
-// Vue
-const wrapper = mount(ActorProvider, { props: { actor, registryResult }, slots: { ... } });
-await flushPromises();
-expect(wrapper.find("[data-testid='message']").text()).toBe("Hello");
-```
-
-**Performance/timing assertions:**
-
-```typescript
-const start = performance.now();
-for (let i = 0; i < iterations; i++) {
-	actor.send({ type: "play.route", to: `#route${i}` });
-}
-const duration = performance.now() - start;
-expect(duration / iterations).toBeLessThan(2.5); // ms per operation
-```
-
 ## Contract Tests
 
-The [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) package exports a shared behavioral contract suite that all router bridge adapters must satisfy:
+The `@xmachines/play-router` package exports a shared behavioral contract suite that all router bridge adapters must satisfy:
 
 ```typescript
 // packages/play-router/test/router-bridge-contract.ts
@@ -401,7 +375,7 @@ runBridgeContractTests({
 
 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`](../api/@xmachines/play-router/README.md), `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-react-router`, and other adapter packages.
+**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:**
 
@@ -414,38 +388,57 @@ assertImplementsRouterBridge<MyRouterBridge>(); // Zero runtime cost
 
 ## Coverage Requirements
 
-**Provider:** `@vitest/coverage-v8`
+Coverage is collected using the **v8** provider. The root `vitest.config.ts` defines monorepo-wide regression thresholds:
 
-**Reporters:** `text`, `html`, `json-summary`
+| Type       | Monorepo threshold |
+| ---------- | ------------------ |
+| Lines      | 80%                |
+| Functions  | 80%                |
+| Branches   | 75%                |
+| Statements | 80%                |
 
-**Aggregate thresholds** (root `vitest.config.ts` — regression gate for full monorepo run):
+Individual packages enforce their own (typically stricter) thresholds inside their `vitest.config.ts`:
 
-| Type       | Threshold |
-| ---------- | --------- |
-| Lines      | 80%       |
-| Functions  | 80%       |
-| Branches   | 75%       |
-| Statements | 80%       |
+| 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%        |
 
-**Per-package thresholds** (enforced by each package's `vitest.config.ts`):
+Coverage includes: `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
 
-| Package category                                                                                                   | Lines | Functions | Branches | Statements |
-| ------------------------------------------------------------------------------------------------------------------ | ----- | --------- | -------- | ---------- |
-| Core packages ([`@xmachines/play`](../api/@xmachines/play/README.md), `play-actor`)                                | 90%   | 90%       | 85%      | 90%        |
-| Complex logic ([`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md), `play-router`)                 | 85%   | 85%       | 80%      | 85%        |
-| Integration/adapter packages ([`@xmachines/play-react`](../api/@xmachines/play-react/README.md), `play-vue`, etc.) | 80%   | 80%       | 80%      | 80%        |
+Coverage is excluded for: `test/**/*`, `**/*.test.ts`, `**/*.test.tsx`, `**/*.d.ts`, `dist/**/*`.
 
-**Coverage includes:** `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
+## CI Integration
 
-**Coverage excludes:** `test/**/*`, `**/*.test.ts`, `**/*.d.ts`, `dist/**/*`
+Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (version `5.1.2`).
 
-## CI Integration
+**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
+npm 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:
 
-Tests are expected to run in CI against Node.js ≥ 22. The `vitest.node.setup.ts` setup file enforces this at runtime — tests will fail immediately with a descriptive error if run on an older Node version.
+- 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)
 
-The `npm run format:check` and `npm run lint` commands enforce code style and are run separately from tests.
+Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.
 
-Browser tests (`npm run test:browser`) require Playwright/Chromium and are run via `vitest.browser.config.ts`. 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.
+The `npm run format:check` and `npm 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
 

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

@@ -1,13 +1,15 @@
 [Examples](../../README.md) / @xmachines/play-dom-demo
 
+<!-- generated-by: gsd-doc-writer -->
+
 # @xmachines/play-dom-demo
 
-Vanilla DOM renderer demo for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — actor + `connectRenderer` without a router.
+Vanilla DOM renderer demo for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — actor + `createPlayUI` without a router.
 
 ## What This Demonstrates
 
 - Shared auth machine reused without framework-specific business logic
-- `connectRenderer` wiring `PlayRenderer`-equivalent DOM rendering without a framework
+- `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
@@ -28,23 +30,27 @@ Then open `http://localhost:5173`.
 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/shell.ts` builds the HTML scaffold, mounts a reactive `NavBar`, and wires the debug panel.
+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. `connectRenderer({ actor, registry, container, registryResult })` wires the registry to the actor — view switches happen automatically when `actor.currentView` changes.
-5. `watchSignal(actor.state, ...)` and `watchSignal(actor.currentRoute, ...)` drive the debug panel updates.
-6. Browser tests in `test/browser/` validate startup rendering and auth interactions.
+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 actor = definePlayer({ machine: authMachine })();
+const createPlayer = definePlayer({ machine: authMachine });
+const actor = createPlayer();
 actor.start();
 
 const app = document.getElementById("app");
-if (app) initShell(actor, app);
+if (!app) throw new Error("Root element not found");
+
+initShell(actor, app);
 ```
 
 ```ts
-// src/shell.ts (shape)
+// src/components/Shell.ts (shape)
 const registryResult = defineRegistry(authCatalog, {
 	components: {
 		Home,
@@ -77,21 +83,24 @@ const registryResult = defineRegistry(authCatalog, {
 	},
 });
 
-const disconnectRenderer = connectRenderer({
-	actor,
-	registry: registryResult.registry,
-	container: viewContent,
-	registryResult,
-});
+const disconnectNavBar = createNavBar(actor, headerEl);
+const mount = createPlayUI(registryResult);
+const disconnectRenderer = mount(actor, viewContent);
+const disconnectDebugPanel = createDebugPanel(actor, shell);
 
-const unwatchState = watchSignal(actor.state, () => updateDebugPanel(actor));
-const unwatchRoute = watchSignal(actor.currentRoute, () => updateDebugPanel(actor));
+return () => {
+	disconnectNavBar();
+	disconnectRenderer();
+	disconnectDebugPanel();
+};
 ```
 
 ## Key Files
 
 - `src/main.ts` - actor creation and shell bootstrap
-- `src/shell.ts` - DOM scaffold, `DomRegistry` construction, `connectRenderer` wiring, and `watchSignal` for reactive nav and debug panel
+- `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
 
@@ -100,7 +109,7 @@ const unwatchRoute = watchSignal(actor.currentRoute, () => updateDebugPanel(acto
 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:** `connectRenderer` and `watchSignal` only react to actor signals. They do not hold business state or make routing decisions.
+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
@@ -113,11 +122,11 @@ This demo follows the canonical watcher lifecycle:
 4. Read actor signals and project DOM state
 5. Re-arm with `watch()`/`watch(...signals)`
 
-Watcher notifications are one-shot. Cleanup is explicit: both `disconnectRenderer()` and `unwatchState()` must be called to avoid memory leaks. In this demo, cleanup is returned from `initShell` and called on `beforeunload`.
+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
 
-`connectRenderer` (from [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md)) is passive infrastructure. It translates actor view signals into DOM mutations but holds no business logic. The `DomRegistry` maps catalog component keys to factory functions — the actor owns which key is active.
+`createPlayUI` (from [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md)) is passive infrastructure. It translates actor view 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
 

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

@@ -6,7 +6,7 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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

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

@@ -6,7 +6,7 @@
 function initShell(actor, appElement): () => void;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.51/packages/play-dom/examples/demo/src/components/Shell.ts#L24)
+Defined in: [play-dom/examples/demo/src/components/Shell.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.53/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.

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

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

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

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

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

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