@xmachines/docs 1.0.0-beta.45 → 1.0.0-beta.48

package/guides/signals.md

@@ -27,7 +27,7 @@ This model is sometimes called _glitch-free reactivity_: intermediate invalid st
 
 ## The three Signal primitives
 
-XMachines uses three primitives from the [TC39 Signals proposal](https://github.com/tc39/proposal-signals), accessed via `@xmachines/play-signals`:
+XMachines uses three primitives from the [TC39 Signals proposal](https://github.com/tc39/proposal-signals), accessed via [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md):
 
 ### `Signal.State` — writable values
 
@@ -78,13 +78,13 @@ actor.currentRoute.get(); // initial read required to arm the watcher
 
 Watcher notifications are **one-shot**: if you do not call `watch()` again after draining pending signals, you will miss subsequent changes.
 
-Router bridges and renderers use `Signal.subtle.Watcher` internally. For most application code, the `watchSignal()` helper covers the common case.
+Router bridges and renderers use `Signal.subtle.Watcher` internally. For most application code, the [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) helper covers the common case.
 
 ---
 
-## `watchSignal()` — the safe helper
+## [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) — the safe helper
 
-`@xmachines/play-signals` exports `watchSignal(signal, onValue)` as a lifecycle-safe wrapper around the raw watcher pattern. It returns a cleanup function:
+[`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) exports [`watchSignal(signal, onValue)`](../api/@xmachines/play-signals/functions/watchSignal.md) as a lifecycle-safe wrapper around the raw watcher pattern. It returns a cleanup function:
 
 ```typescript
 import { watchSignal } from "@xmachines/play-signals";
@@ -97,15 +97,15 @@ const stop = watchSignal(actor.currentRoute, (route) => {
 stop();
 ```
 
-`watchSignal()` handles three subtle correctness concerns for you:
+[`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) handles three subtle correctness concerns for you:
 
-| Concern                | What happens without it                            | How `watchSignal` handles it                                           |
-| ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
-| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                       |
-| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `needsEnqueue` guard — only one microtask queued per synchronous burst |
-| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                            |
+| Concern                | What happens without it                            | How [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md) handles it |
+| ---------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                                        |
+| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `needsEnqueue` guard — only one microtask queued per synchronous burst                  |
+| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                                             |
 
-Use `watchSignal()` in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
+Use [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
 
 ---
 
@@ -113,7 +113,7 @@ Use `watchSignal()` in framework adapters and application code. Use the raw `Sig
 
 The XMachines architecture chose TC39 Signals over observable libraries and event emitters for three reasons:
 
-**1. Standardization.** Signals are a Stage 1 TC39 proposal. They are not tied to any library, bundler, or framework. Isolating the polyfill behind `@xmachines/play-signals` means the entire ecosystem can migrate to native signals when the proposal lands, with a single package update.
+**1. Standardization.** Signals are a Stage 1 TC39 proposal. They are not tied to any library, bundler, or framework. Isolating the polyfill behind [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) means the entire ecosystem can migrate to native signals when the proposal lands, with a single package update.
 
 **2. Synchronous atomic propagation.** RxJS streams are asynchronous by default. Event emitters fire immediately but serially — a listener registered halfway through a sequence can see inconsistent state. Signals propagate atomically: all computeds update before any watcher fires.
 
@@ -139,7 +139,7 @@ The Play RFC defines five invariants that govern how signals are used:
 
 Signals do not clean themselves up when they go out of scope. Every watcher you create must be explicitly disposed when the consuming component or adapter unmounts.
 
-- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call `unwatch()` or the cleanup returned by `watchSignal()`.
+- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call `unwatch()` or the cleanup returned by [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md).
 - Router bridge `disconnect()` methods must unwatch all signal subscriptions.
 - If you use the raw `Signal.subtle.Watcher` API, pair every `watch()` call with `unwatch()` in teardown.
 
@@ -149,12 +149,12 @@ Failing to clean up watchers causes memory leaks and stale callbacks firing afte
 
 ## Summary
 
-| Primitive               | Role in XMachines                              | Who uses it                        |
-| ----------------------- | ---------------------------------------------- | ---------------------------------- |
-| `Signal.State`          | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
-| `Signal.Computed`       | Lazy derivations: routes, view specs           | Actor defines; adapters read       |
-| `Signal.subtle.Watcher` | Low-level reactive observation                 | Framework adapters, router bridges |
-| `watchSignal()`         | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
+| Primitive                                                                  | Role in XMachines                              | Who uses it                        |
+| -------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |
+| `Signal.State`                                                             | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
+| `Signal.Computed`                                                          | Lazy derivations: routes, view specs           | Actor defines; adapters read       |
+| `Signal.subtle.Watcher`                                                    | Low-level reactive observation                 | Framework adapters, router bridges |
+| [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
 
 ## See also
 

package/guides/state-machines.md

@@ -24,7 +24,7 @@ In traditional component-level state (e.g., boolean flags, `useState` combinatio
 
 ## How XMachines uses XState v5
 
-XMachines wraps XState v5 via `@xmachines/play-xstate`. You define machines using XState's `setup().createMachine()` API:
+XMachines wraps XState v5 via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md). You define machines using XState's `setup().createMachine()` API:
 
 ```typescript
 import { setup } from "xstate";
@@ -124,13 +124,13 @@ const appMachine = setup({
 
 `meta.route` is a string path. When the machine enters a state, `actor.currentRoute` (a `Signal.Computed`) derives this path and emits it. The router bridge reads it and updates the URL.
 
-`meta.view` is a `PlaySpec` — a `@json-render/core` spec object describing what to render. Use `typedSpec<TContext>(...)` from `@xmachines/play-actor` to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
+`meta.view` is a [`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md) — a `@json-render/core` spec object describing what to render. Use `typedSpec<TContext>(...)` from [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md) to validate `contextProps` entries at compile time. When the machine enters a state, `actor.currentView` is updated with this spec. The renderer reads it and projects it through framework components.
 
 **The machine is the single source of truth for both routing and views.** There is no separate route configuration file. There is no switch statement in a component deciding what to render based on the URL. The state machine encodes all of that.
 
 ---
 
-## `formatPlayRouteTransitions` — automatic route event wiring
+## [`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) — automatic route event wiring
 
 For routing to work, the machine must respond to `play.route` events (sent by router bridges when the user navigates). Writing these transitions by hand is mechanical:
 
@@ -150,7 +150,7 @@ states: {
 }
 ```
 
-`formatPlayRouteTransitions` from `@xmachines/play-xstate` generates these transitions automatically from the `id` and `meta.route` fields you already have:
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) generates these transitions automatically from the `id` and `meta.route` fields you already have:
 
 ```typescript
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate";
@@ -170,7 +170,7 @@ const appMachine = setup({
 );
 ```
 
-`formatPlayRouteTransitions` inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
+[`formatPlayRouteTransitions`](../api/@xmachines/play-xstate/functions/formatPlayRouteTransitions.md) inspects all state nodes with a `meta.route` and generates the corresponding `play.route` guard transitions. The machine's context must include `params` and `query` fields (populated by the router bridge when params or query strings are present):
 
 ```typescript
 types: {
@@ -202,16 +202,16 @@ Guards are evaluated by XState before a transition fires. If the guard returns `
 
 This is the **Actor Authority** invariant in practice: the machine decides, infrastructure adjusts.
 
-XMachines provides guard combinators in `@xmachines/play-xstate` for composing complex conditions:
+XMachines provides guard combinators in [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) for composing complex conditions:
 
-| Function                          | What it does                            |
-| --------------------------------- | --------------------------------------- |
-| `composeGuards(...guards)`        | AND — all guards must pass              |
-| `composeGuardsOr(...guards)`      | OR — any guard must pass                |
-| `negateGuard(guard)`              | NOT — inverts the guard result          |
-| `hasContext(key)`                 | Checks that a context field is non-null |
-| `contextFieldMatches(key, value)` | Checks a context field against a value  |
-| `eventMatches(type)`              | Checks the event type                   |
+| Function                                                                                            | What it does                            |
+| --------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| [`composeGuards(...guards)`](../api/@xmachines/play-xstate/functions/composeGuards.md)              | AND — all guards must pass              |
+| [`composeGuardsOr(...guards)`](../api/@xmachines/play-xstate/functions/composeGuardsOr.md)          | OR — any guard must pass                |
+| [`negateGuard(guard)`](../api/@xmachines/play-xstate/functions/negateGuard.md)                      | NOT — inverts the guard result          |
+| [`hasContext(key)`](../api/@xmachines/play-xstate/functions/hasContext.md)                          | Checks that a context field is non-null |
+| [`contextFieldMatches(key, value)`](../api/@xmachines/play-xstate/functions/contextFieldMatches.md) | Checks a context field against a value  |
+| [`eventMatches(type)`](../api/@xmachines/play-xstate/functions/eventMatches.md)                     | Checks the event type                   |
 
 ---
 
@@ -261,7 +261,7 @@ actor.start();
 // Actor resumes from where it left off
 ```
 
-`definePlayer` accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
+[`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md) accepts an optional `restore` argument for this purpose. Restoration is useful for server-side rendering (hydrate with the server's snapshot), session persistence (resume after page reload), and testing (start from a known mid-flow state).
 
 ---
 
@@ -283,6 +283,6 @@ actor.start();
 - [Understanding TC39 Signals](signals.md) — how the actor's state is observed by infrastructure
 - [Getting Started](getting-started.md) — step-by-step walkthrough building your first machine and actor
 - [Routing Patterns](../examples/routing-patterns.md) — worked examples of `meta.route` and guards
-- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — full API reference for `definePlayer`, `PlayerActor`, guard combinators
+- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — full API reference for [`definePlayer`](../api/@xmachines/play-xstate/functions/definePlayer.md), [`PlayerActor`](../api/@xmachines/play-xstate/classes/PlayerActor.md), guard combinators
 - [XState v5 documentation](https://stately.ai/docs/xstate) — upstream state machine library documentation
 - [Play RFC](../rfc/play.md) — complete architectural specification

package/guides/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmachines/docs",
-  "version": "1.0.0-beta.45",
+  "version": "1.0.0-beta.48",
   "description": "Documentation for XMachines",
   "keywords": [
     "documentation",
@@ -49,12 +49,12 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@xmachines/shared": "1.0.0-beta.45",
-    "oxfmt": "^0.45.0",
-    "oxlint": "^1.60.0",
+    "@xmachines/shared": "1.0.0-beta.48",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
     "typedoc": "^0.28.19",
     "typedoc-plugin-llms-txt": "^0.1.2",
     "typedoc-plugin-markdown": "^4.11.0",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.5"
   }
 }