@xmachines/docs 1.0.0-beta.46 → 1.0.0-beta.50

package/contributing/testing.md

@@ -0,0 +1,460 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Testing
+
+This document describes the test framework, test organization, how to run tests, and patterns used across the XMachines JS monorepo.
+
+## Test Framework and Setup
+
+**Runner:** [Vitest](https://vitest.dev/) `^4.1.4`
+
+**Assertion library:** Vitest built-in `expect` + `@testing-library/jest-dom` matchers (auto-injected via shared setup)
+
+**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 },
+		},
+	},
+});
+```
+
+**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     |
+
+**Test environments by package type:**
+
+| 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                                                                                                            |
+
+## Running Tests
+
+### All unit tests (node + jsdom)
+
+```bash
+npm test
+```
+
+Runs `vitest run` across all 30+ package-level projects defined in `vitest.config.ts`.
+
+### Watch mode (development)
+
+```bash
+npm run test:watch
+```
+
+Runs `vitest` in interactive watch mode. Re-runs affected test files on save.
+
+### 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.
+
+### 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
+```
+
+### Type-checking test files
+
+```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.
+
+### Per-package tests (workspace)
+
+```bash
+npm test -w packages/play-xstate
+npm run test:coverage -w packages/play-react
+```
+
+## 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 `npm run test:build`                                        |
+| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                     |
+
+## Writing New Tests
+
+### Unit and integration tests
+
+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.
+
+**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";
+```
+
+**`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
+beforeEach(() => {
+	vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+	vi.restoreAllMocks(); // Always restore spies
+	cleanup(); // For @testing-library/react or equivalent
+});
+```
+
+### Mocking
+
+**Module mocking with `vi.hoisted` (required when mocks are referenced before module evaluation):**
+
+```typescript
+const mocks = vi.hoisted(() => ({
+	machineToGraph: vi.fn(),
+	buildRouteTree: vi.fn(),
+}));
+
+vi.mock("../src/machine-to-graph.js", () => ({
+	machineToGraph: mocks.machineToGraph,
+}));
+```
+
+**Function mocks:**
+
+```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"));
+```
+
+**Spy pattern for console suppression:**
+
+```typescript
+const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+// ... test ...
+expect(warnSpy).toHaveBeenCalled();
+vi.restoreAllMocks(); // in afterEach
+```
+
+**What to mock:**
+
+- 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
+
+**What NOT to mock:**
+
+- 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()`
+
+### Test actor patterns
+
+**Preferred: extend [`AbstractActor`](../api/@xmachines/play-actor/classes/AbstractActor.md) 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;
+}
+```
+
+### 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):**
+
+```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
+```
+
+**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");
+}
+```
+
+**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:
+
+```typescript
+// packages/play-router/test/router-bridge-contract.ts
+export function runBridgeContractTests(opts: ContractSuiteOptions): void;
+
+// Each adapter's test file calls it:
+import { runBridgeContractTests } from "../../play-router/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`](../api/@xmachines/play-router/README.md), `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/test/contract.js";
+import { MyRouterBridge } from "../src/my-router-bridge.js";
+
+assertImplementsRouterBridge<MyRouterBridge>(); // Zero runtime cost
+```
+
+## Coverage Requirements
+
+**Provider:** `@vitest/coverage-v8`
+
+**Reporters:** `text`, `html`, `json-summary`
+
+**Aggregate thresholds** (root `vitest.config.ts` — regression gate for full monorepo run):
+
+| Type       | Threshold |
+| ---------- | --------- |
+| Lines      | 80%       |
+| Functions  | 80%       |
+| Branches   | 75%       |
+| Statements | 80%       |
+
+**Per-package thresholds** (enforced by each package's `vitest.config.ts`):
+
+| 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 includes:** `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
+
+**Coverage excludes:** `test/**/*`, `**/*.test.ts`, `**/*.d.ts`, `dist/**/*`
+
+## CI Integration
+
+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.
+
+The `npm run format:check` and `npm run lint` commands enforce code style and are run separately from tests.
+
+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.
+
+## 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

@@ -2,7 +2,7 @@
 
 # @xmachines/play-dom-demo
 
-Vanilla DOM renderer demo for `@xmachines/play-dom` — actor + `connectRenderer` without a router.
+Vanilla DOM renderer demo for [`@xmachines/play-dom`](../../../api/@xmachines/play-dom/README.md) — actor + `connectRenderer` without a router.
 
 ## What This Demonstrates
 
@@ -101,7 +101,7 @@ 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.
-3. **Signal-Only Reactivity:** `watchSignal` (from `@xmachines/play-signals`) wraps the canonical TC39 Signals watcher lifecycle, keeping all reactivity in the actor signal layer rather than in ad-hoc DOM event listeners.
+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
 
@@ -117,7 +117,7 @@ Watcher notifications are one-shot. Cleanup is explicit: both `disconnectRendere
 
 ## Adapter Boundaries
 
-`connectRenderer` (from `@xmachines/play-dom`) 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.
+`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.
 
 ## 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.46/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.50/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.46/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.50/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.46/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.50/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.46/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.50/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.46/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.50/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.

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

@@ -6,7 +6,7 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
 
 Dashboard — Protected authenticated home. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Dashboard'>). Renders welcome message; logout

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

@@ -6,7 +6,7 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Home.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Home.ts#L9)
 
 Home — Public landing page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Home'>). Renders static welcome content from

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

@@ -6,7 +6,7 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Login.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Login.ts#L9)
 
 Login — Authentication form. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Login'>). Binds username input to ctx.store via

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

@@ -6,7 +6,7 @@
 const NavBarView: ComponentFn<AuthCatalog, "NavBar">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
+Defined in: [play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
 
 NavBarView — Catalog-typed NavBar component for DOM renderer.
 

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

@@ -6,7 +6,7 @@
 const Navigation: ComponentFn<AuthCatalog, "Navigation">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
 
 Navigation — Navigation status display. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Navigation'>). Renders current path and auth

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

@@ -6,7 +6,7 @@
 const Overview: ComponentFn<AuthCatalog, "Overview">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
 
 Overview — Dashboard overview child route. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Overview'>). Relative route resolves to

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

@@ -6,7 +6,7 @@
 const Profile: ComponentFn<AuthCatalog, "Profile">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Profile.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Profile.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Profile.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Profile.ts#L9)
 
 Profile — Protected user profile page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Profile'>). Renders username from route params

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

@@ -6,7 +6,7 @@
 const Settings: ComponentFn<AuthCatalog, "Settings">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Settings.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Settings.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Settings.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Settings.ts#L9)
 
 Settings — Protected settings page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Settings'>). Renders active section and username

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

@@ -6,7 +6,7 @@
 const Stats: ComponentFn<AuthCatalog, "Stats">;
 ```
 
-Defined in: [play-dom/examples/demo/src/components/Stats.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/components/Stats.ts#L9)
+Defined in: [play-dom/examples/demo/src/components/Stats.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/components/Stats.ts#L9)
 
 Stats — Dashboard stats child route. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Stats'>). Relative route resolves to

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

@@ -169,4 +169,4 @@ const authCatalog: Catalog<
 >;
 ```
 
-Defined in: [play-dom/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.46/packages/play-dom/examples/demo/src/catalog.ts#L5)
+Defined in: [play-dom/examples/demo/src/catalog.ts:5](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v1.0.0-beta.50/packages/play-dom/examples/demo/src/catalog.ts#L5)

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

@@ -2,7 +2,7 @@
 
 # @xmachines/play-dom-router-demo
 
-Pure TypeScript integration demo for `@xmachines/play-dom-router` — actor-authoritative routing with the Browser History API and no framework.
+Pure TypeScript integration demo for [`@xmachines/play-dom-router`](../../../api/@xmachines/play-dom-router/README.md) — actor-authoritative routing with the Browser History API and no framework.
 
 ## What This Demonstrates
 
@@ -108,7 +108,7 @@ Watcher notifications are one-shot, so re-arm is mandatory. Router/shell teardow
 
 ## Adapter Boundaries
 
-`connectRouter` and browser-history wiring (from `@xmachines/play-dom-router`) are passive infrastructure. Actor logic remains authoritative for route validity, and shared synchronization policy stays in `RouterBridgeBase` for framework bridges. This demo proves frameworks are not required for Play Architecture to work.
+`connectRouter` and browser-history wiring (from [`@xmachines/play-dom-router`](../../../api/@xmachines/play-dom-router/README.md)) are passive infrastructure. Actor logic remains authoritative for route validity, and shared synchronization policy stays in `RouterBridgeBase` for framework bridges. This demo proves frameworks are not required for Play Architecture to work.
 
 ## Available Scripts