@xmachines/docs 6.0.0 → 7.0.0

package/contributing/development.md

@@ -12,6 +12,7 @@ This guide covers everything you need to set up a local development environment,
 - [Code Style](#code-style)
 - [Writing Style](#writing-style-asd-ste100)
 - [Link a Package That You Name](#link-a-package-that-you-name)
+- [Code Examples in Documents](#code-examples-in-documents)
 - [Branch Conventions](#branch-conventions)
 - [PR Process](#pr-process)
 
@@ -88,7 +89,7 @@ packages/
 ├── play-pattern/                # The route pattern language: one parse, and the path it builds back
 ├── play-url/                    # The URL layer: the URLPattern API, a base path, framework params
 ├── play-actor/                  # The actor contract (PlayActor). It names no engine
-├── play-view/                   # The shared view half (Viewable, PlaySpec, the view store lifecycle)
+├── play-view/                   # The shared view half (Viewable, PlaySpec, the view session)
 ├── play-xstate/                 # XState v5 adapter (definePlayer, PlayerActor)
 ├── play-router/                 # Route extraction and RouterBridgeBase
 ├── play-dom/                    # Vanilla DOM renderer
@@ -135,11 +136,14 @@ All commands are run from the **repository root** unless otherwise noted.
 | `pnpm run build`                           | Incremental build — all packages in dependency order (not a type-check)   |
 | `pnpm --filter @xmachines/<pkg> run build` | Build a single package (and its deps)                                     |
 | `pnpm run clean`                           | Remove coverage, Vite caches, and all `dist/` directories in packages     |
-| `pnpm test`                                | Run all unit/integration tests once                                       |
+| `pnpm test`                                | Run all unit/integration tests once, on the source                        |
+| `pnpm run test:dist`                       | Run the same tests on the build output (run `pnpm run build` first)       |
 | `pnpm run test:watch`                      | Re-run tests on file changes (interactive)                                |
 | `pnpm run test:browser`                    | Run Playwright browser tests                                              |
+| `pnpm run test:browser:dist`               | Run Playwright browser tests on the build output                          |
 | `pnpm run test:coverage`                   | Run tests with V8 coverage reporting                                      |
 | `pnpm run test:browser:coverage`           | Run browser tests with coverage reporting                                 |
+| `pnpm run test:docs:examples`              | Compile and run the code examples of the documentation                    |
 | `pnpm run test:build`                      | Complete type-check of every package and its tests (`tsconfig.test.json`) |
 | `pnpm run lint`                            | Lint all packages with oxlint                                             |
 | `pnpm run lint:fix`                        | Auto-fix lint issues                                                      |
@@ -427,7 +431,7 @@ Use `unknown` with type guards instead of `any`. Prefix unused locals/parameters
 
 1. Always use `.js` extensions in imports, even for TypeScript source files:
 
-    ```typescript
+    ```typescript fragment
     // ✅ Correct
     import { PlayError } from "./errors.js";
 
@@ -437,7 +441,7 @@ Use `unknown` with type guards instead of `any`. Prefix unused locals/parameters
 
 2. Use `import type` for type-only imports (required by `verbatimModuleSyntax`):
 
-    ```typescript
+    ```typescript fragment
     import type { RouteNode, RouteTree } from "../src/types.js";
     ```
 
@@ -493,6 +497,29 @@ Three places keep a plain code span:
 
 ---
 
+## Code Examples in Documents
+
+A reader copies a code example and expects it to work. Two tests therefore read every `ts`, `typescript` and `tsx` block of the hand-written markdown:
+
+- `tests/doc-examples/compile.test.ts` compiles each block against the source of the workspace. It writes the block into the package that can resolve its imports, and it uses the `tsconfig.json` of that package.
+- `tests/doc-examples/run.test.ts` runs each complete block in jsdom. A block is complete when it declares no value that the reader supplies, holds no JSX, and loads no package that needs a compiler of Solid, Vue or Svelte, the runtime of SvelteKit, or a test runner such as `vitest`. A type import loads nothing, so it does not count. A run fails on each `console.error` and `console.warn`, unless the block logs on purpose. The page holds the elements `#app`, `#root`, `#loading` and `#crashed`.
+
+Give an example of a call its imports, so that it compiles. Use `declare const` only for a value that the reader supplies, such as their machine or a DOM element. Two words after the language change what the tests do:
+
+| Fence              | Use it for                                                                     | Compiled | Run |
+| ------------------ | ------------------------------------------------------------------------------ | -------- | --- |
+| ` ```ts `          | An example that a reader can copy                                              | yes      | yes |
+| ` ```ts norun `    | An example that compiles, but runs only in a test or in a component            | yes      | no  |
+| ` ```ts fragment ` | A part of a larger file, such as one state of a machine, or a ✅/❌ comparison | no       | no  |
+
+GitHub, GitLab and TypeDoc read the first word of a fence alone, so the second word changes nothing on a rendered page.
+
+An example for a reader imports published packages alone. A private workspace package, such as a demo or [`@xmachines/shared`](../api/@xmachines/shared/README.md), fails the check, because a reader cannot install it. The contributor guides and the README of a private package can import one.
+
+Check one document with `DOC_EXAMPLES=<part of its path> pnpm vitest run tests/doc-examples/compile.test.ts`, and run its examples with `DOC_EXAMPLES=<part of its path> pnpm vitest run tests/doc-examples/run.test.ts`. `pnpm run test:docs:examples` runs both, for every document. The dist run leaves them out, and CI runs them in the `test:docs:examples` job.
+
+---
+
 ## Branch Conventions
 
 Use a `<type>/` prefix that matches the conventional commit type for the work being done:

package/contributing/migrating-to-play-atom.md

@@ -95,8 +95,14 @@ If you call `subscribe` directly, wrap the body.
 **A DERIVATION must contain its own failures.** A subscriber makes a computed atom eager, so the derivation itself runs inside the `set`, before any observer. No subscriber can wrap that, so the rule belongs to the derivation: report through your error channel, and return the previous value. `currentRoute` and `currentView` of the actor both do this, and a release before this one let `currentRoute` throw — which was safe only while the TC39 watcher read it from a microtask.
 
 ```typescript
+import { createAtom, type ReadonlyAtom } from "@xmachines/play-atom";
+
+declare const source: ReadonlyAtom<string>;
+declare function expensiveDerivation(input: string): number;
+declare function report(error: unknown): void;
+
 // A derivation that a subscriber may watch.
-const derived = createAtom((previous) => {
+const derived = createAtom<number | null>((previous) => {
 	try {
 		return expensiveDerivation(source.get());
 	} catch (error) {
@@ -112,7 +118,7 @@ const derived = createAtom((previous) => {
 
 **Derive the value, and read `previous`.** Almost every `untrack` guarded the same shape: a gate that compares the new value with the last one it emitted. A computed atom is handed that last value, so the gate needs no read and therefore tracks nothing. `withView` of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) is the worked example:
 
-```typescript
+```typescript fragment
 // Before: a written atom, plus untrack to read what it held.
 this.currentView = new Signal.State<View | null>(null);
 const last = Signal.subtle.untrack(() => this.currentView.get());
@@ -136,7 +142,7 @@ A read that already stands outside every computed atom and every effect tracks n
 
 The codemod renames the call, and it cannot write the source list. Add that array yourself, and move the callback one place to the right:
 
-```tsx
+```tsx fragment
 // Before
 useSignalEffect(() => {
 	setView(actor.currentView.get());
@@ -195,7 +201,7 @@ Property 'set' is missing in type 'ReadonlyAtom<T>' but required in type 'Atom<T
 
 Use `createWritableAtom`, which states the one signature:
 
-```typescript
+```typescript fragment
 import { createWritableAtom } from "@xmachines/play-atom";
 
 this.state = createWritableAtom(this.getSnapshot());
@@ -205,6 +211,6 @@ this.state = createWritableAtom(this.getSnapshot());
 
 ## See also
 
-- [Understanding Atoms](../guides/atoms.md) — the concepts, and the invariants
+- [Atoms](../guides/atoms.md) — the concepts, and the invariants
 - [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) — the API reference
 - [Play RFC](../rfc/play.md) — section 5.1.1 defines the reactive substrate

package/contributing/testing.md

@@ -4,11 +4,11 @@ This document describes the test framework, conventions, and CI integration for
 
 ## Test Framework and Setup
 
-The monorepo uses **[Vitest](https://vitest.dev/) `^5.0.1`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
+The monorepo uses **[Vitest](https://vitest.dev/) `^5.0.3`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
 
 All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from [`@xmachines/shared/vitest`](../api/@xmachines/shared/README.md)) which automatically applies:
 
-- `@xmachines/*` source aliases so imports resolve to source during test runs
+- `@xmachines/*` source aliases so imports resolve to source during test runs — or, in the dist run, to the build output (see [Tests on the build output](#tests-on-the-build-output))
 - [`@xmachines/shared/vitest-setup`](../api/@xmachines/shared/README.md) — extends Vitest matchers with `@testing-library/jest-dom`
 - [`@xmachines/shared/vitest-node-setup`](../api/@xmachines/shared/README.md) — enforces Node.js ≥ 24 on non-browser projects
 
@@ -25,7 +25,7 @@ All packages extend the shared Vitest configuration helper `defineXmVitestConfig
 
 `patches/@testing-library__jest-dom@7.0.1.patch` moves the matcher declaration of the library from `Assertion` to `Matchers`. The library declares this:
 
-```ts
+```ts fragment
 declare module "vitest" {
 	interface Assertion<T = any> extends TestingLibraryMatchers<any, T> {}
 }
@@ -35,14 +35,6 @@ Vitest 5 declares `interface Assertion<R extends void | Promise<void> = void, T
 
 Delete the patch, its `patchedDependencies` entry in `pnpm-workspace.yaml`, and `tests/jest-dom-augmentation.test.ts` on the day the library ships a declaration that vitest 5 accepts. See [testing-library/jest-dom#738](https://github.com/testing-library/jest-dom/issues/738).
 
-### The vitest mocker patch
-
-`patches/@vitest__mocker@5.0.1.patch` takes the `configureServer` hook off `vitest:mocks:interceptor` when the caller passes `registerWebSocketEvents: false`, which is how `@vitest/browser` calls it.
-
-Vitest returns that plugin from the `applyToEnvironment` of another plugin, and Vite 8 ignores a `configureServer` that it finds there. Vite reports the fact one time for each environment, so a run of 29 projects wrote 29 lines, in the `test` job and in the `test:browser` job both. The hook returns at once for `registerWebSocketEvents: false`, so the omission changes no behaviour.
-
-Delete the patch and its `patchedDependencies` entry when vitest ships the fix. See [vitest-dev/vitest#11276](https://github.com/vitest-dev/vitest/issues/11276).
-
 Before running any tests, ensure all dependencies are installed:
 
 ```bash
@@ -77,6 +69,33 @@ pnpm run test:browser
 
 Runs `vitest run --config vitest.browser.config.ts`. Launches all browser-mode projects using headless Chromium via Playwright. Includes both package-level browser unit tests and full demo-app integration flows. The browser global setup (`vitest.browser.global-setup.ts`) raises `process.setMaxListeners` to 32 before workers spawn to prevent false-positive `MaxListenersExceededWarning` with multiple parallel browser projects.
 
+### Tests on the build output
+
+```bash
+pnpm run build
+pnpm run test:dist           # the node suites
+pnpm run test:browser:dist   # the browser suites
+```
+
+`pnpm test` runs every suite on the SOURCE of each package. It needs no build, and it cannot see a defect of the build. `pnpm run test:dist` runs the same test files on the BUILD OUTPUT, as a consumer installs it. The 6.0.0 release shows why both runs are necessary. [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md) and [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) shipped compiled for server-side rendering, and neither rendered in a browser. Every source suite was green. The node dist run fails 14 test files on that output, and the browser dist run fails the Vue suites. Run the source suites while you work. CI runs the dist suites alone, so each test counts one time in the merge request.
+
+The two scripts set `XM_TEST_TARGET=dist`, and the config helpers of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md) read it. No package config holds a copy of the dist setup. The variable changes two things:
+
+- **A specifier.** The alias map drops each published package. [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) then resolves through the `exports` map of the package to `dist/with-routing.js`. The `source` condition is not set either, so the resolution is the one that a consumer gets.
+- **A path into `src/`.** A test imports the module under test by path, as `../src/define-player.js`, and that import reaches no exports map. The `xmBuildOutput` plugin moves it to `dist/define-player.js`, which is the file that the package entry imports. The test and the package then share ONE module, and a `vi.mock` of the `src/` path replaces the module of the build. The build keeps the module structure, so each source file has one counterpart.
+
+The private packages — the demos and the `examples/shared` fixtures — reach no consumer, and the build does not compile them for one. Both runs read their source, and that source imports the packages from `dist/`.
+
+The plugin fails an import when the build output holds no counterpart. The import then names both files. A fallback to the source would hide the defect that the dist run exists to find. The plugin also fails the run when anything loads a `src/` file of a published package by another route.
+
+**Keep one file set.** Both runs collect the same files, except the code examples of the documentation. The examples document the API, so the dist run leaves out the `doc-examples` project, and CI runs it in the `test:docs:examples` job. A test that cannot run on the build output imports an internal module that the package does not ship. Import that module through the public entry of the package. If that is not possible, exclude the test from the dist run in its project config, and write the reason beside the exclusion. No other test is excluded today.
+
+**The proof.** `packages/play-xstate/test/test-target.test.ts` (node) and `packages/play-dom/test/browser/test-target.browser.test.ts` (browser) run in both runs. Each reads the target with `inject("xmTestTarget")`, and it asserts which file each kind of import loads. `import.meta.resolve` cannot answer that question, because it asks the resolver of Node. A stack trace cannot answer it either, because Vite applies the source maps of `dist/` and names `src/` in both runs.
+
+Run `pnpm run build` first. The dist run reads whatever `dist/` holds, and it does not build. A change to `src/` reaches the dist run only through a new build.
+
+CI measures the coverage on the dist run. The source maps of `dist/` carry the source, so the report names the files of `src/`. v8 matches `coverage.include` against the file that ran, before it reads the source map. The root config therefore adds `packages/*/dist/**/*.js` to `include` in the dist run, and `excludeAfterRemap` applies the filter again to the files of `src/`. The browser config sets no `include`, so it needs neither setting. A file can show a few statements more or less than in a source run, because the build and the dev transform of Vite emit different code. `pnpm run test:coverage` measures the source, locally.
+
 ### With coverage
 
 ```bash
@@ -242,6 +261,10 @@ The root `vitest.config.ts` needs no edit: it collects `packages/*/vitest.config
 
 ```typescript
 import { describe, it, test, expect, vi, beforeEach, afterEach } from "vitest";
+import type { PlayActor } from "@xmachines/play-actor";
+import type { PlayRouteEvent, Routable } from "@xmachines/play-router";
+
+declare function createMockActor(startRoute: string): PlayActor<unknown, PlayRouteEvent> & Routable;
 
 describe("ClassName or functionName()", () => {
 	describe("feature group or scenario", () => {
@@ -261,13 +284,16 @@ describe("ClassName or functionName()", () => {
 
 **Import style:** Always use `.js` extensions in imports (ESM requirement):
 
-```typescript
-import { PlayActor } from "../src/abstract-actor.js";
+```typescript fragment
+import type { PlayActor } from "../src/play-actor.js";
 ```
 
 ### Lifecycle hooks
 
 ```typescript
+import { cleanup } from "@testing-library/react";
+import { afterEach, beforeEach, vi } from "vitest";
+
 beforeEach(() => {
 	vi.spyOn(console, "error").mockImplementation(() => {});
 });
@@ -285,6 +311,8 @@ afterEach(() => {
 - **Framework router objects** (TanStack Router, Vue Router, React Router, SolidJS Router) — mock with typed `vi.fn()` interfaces because they are external framework dependencies and carry significant setup complexity:
 
     ```typescript
+    import { vi } from "vitest";
+
     const mocks = vi.hoisted(() => ({ goto: vi.fn() }));
 
     vi.mock("$app/navigation", () => ({ goto: mocks.goto }));
@@ -294,7 +322,9 @@ afterEach(() => {
 
 - **`console.warn` / `console.error`** when testing code that legitimately emits warnings — mock to suppress noise and assert call counts:
 
-    ```typescript
+    ```typescript norun
+    import { expect, vi } from "vitest";
+
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     // ... test ...
     expect(warnSpy).toHaveBeenCalled();
@@ -311,10 +341,11 @@ afterEach(() => {
 
 ### Test actor patterns
 
-**Preferred: extend `PlayActor` for full type safety:**
+**Preferred: implement `PlayActor` for full type safety:**
 
 ```typescript
-import { PlayActor } from "@xmachines/play-actor";
+import { createAtom, type Atom, type ReadonlyAtom } from "@xmachines/play-atom";
+import type { PlayActor } from "@xmachines/play-actor";
 import type { Routable } from "@xmachines/play-router";
 
 class MockActor implements PlayActor, Routable {
@@ -329,7 +360,7 @@ class MockActor implements PlayActor, Routable {
 		this.initialRoute = startRoute;
 	}
 
-	override send(_event: { readonly type: string } & Record<string, unknown>): void {
+	send(_event: { readonly type: string } & Record<string, unknown>): void {
 		// no-op or capture events for assertion
 	}
 }
@@ -338,18 +369,16 @@ class MockActor implements PlayActor, Routable {
 **Factory functions for lightweight inline mocks — use `stubOf`, never a double-cast:**
 
 ```typescript
+import { vi } from "vitest";
+import { createAtom } from "@xmachines/play-atom";
+import type { PlaySpec, ViewActor } from "@xmachines/play-view";
 import { stubOf } from "@xmachines/shared/test-support";
 
 function createMockActor(initialView: PlaySpec | null = null) {
 	return stubOf<ViewActor>({
 		currentView: createAtom<PlaySpec | null>(initialView),
 		send: vi.fn(),
-		start: vi.fn(),
-		stop: vi.fn(),
-		getSnapshot: vi.fn(),
-		subscribe: vi.fn(),
 		state: createAtom<unknown>({}),
-		currentRoute: createAtom(() => null),
 	});
 }
 ```
@@ -366,6 +395,11 @@ greppable escape hatch.
 **Flushing the microtask queue (required for `watchAtom` delivery):**
 
 ```typescript
+import { expect, vi } from "vitest";
+
+declare const result: string;
+declare const expected: string;
+
 function waitForMicrotask(): Promise<void> {
 	return new Promise<void>((resolve) => queueMicrotask(resolve));
 }
@@ -378,8 +412,12 @@ await vi.waitFor(() => expect(result).toBe(expected), { timeout: 100 });
 **Atom watch pattern:**
 
 ```typescript
+import { expect } from "vitest";
 import { createAtom, watchAtom } from "@xmachines/play-atom";
 
+const state = createAtom({ path: "/" });
+const actor = { state, currentRoute: createAtom(() => state.get().path) };
+
 let notified: string | null = null;
 const stop = watchAtom(actor.currentRoute, (route) => {
 	notified = route;
@@ -400,12 +438,15 @@ stop(); // Always clean up
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
 
 ```typescript
-const bad: PlaySpec = typedSpec({
+import { expect } from "vitest";
+import { typedSpec, type ViewMeta } from "@xmachines/play-view";
+
+const bad: ViewMeta = typedSpec({
 	root: "root",
 	elements: {},
-	// @ts-expect-error "stat" is not a PlaySpec field — typedSpec flags it on an
+	// @ts-expect-error "stat" is not a ViewMeta field — typedSpec flags it on an
 	// inline literal (excess-property checking does not reach aliased or spread
-	// objects; use `satisfies PlaySpec` at the literal for those)
+	// objects; use `satisfies ViewMeta` at the literal for those)
 	stat: {},
 });
 // At runtime the object exists; only the compile-time error is being tested
@@ -416,6 +457,11 @@ For purely structural type assertions with no runtime test needed, use `.typeche
 
 ```typescript
 // packages/play-xstate/test/define-player.typecheck.ts
+import { createMachine } from "xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+
+const actor = definePlayer({ machine: createMachine({}) })();
+
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type AssertFalse<T extends false> = T;
 
@@ -428,8 +474,17 @@ These files are validated by `pnpm run test:build` (`tsc --build tsconfig.test.j
 ### Error testing
 
 ```typescript
+import { expect } from "vitest";
+import type { AnyStateMachine } from "xstate";
+import type { PlayEvent } from "@xmachines/play";
+import type { PlayActor } from "@xmachines/play-actor";
+import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import { InvalidEventError } from "@xmachines/play-xstate/errors";
 import { unsafeCast } from "@xmachines/shared/test-support";
 
+declare const actor: PlayActor;
+declare const dupMachine: AnyStateMachine;
+
 // Synchronous throws — feed a runtime guard an invalid value through
 // unsafeCast, the named escape hatch (never `null as unknown as PlayEvent`).
 expect(() => actor.send(unsafeCast<PlayEvent>(null))).toThrow(InvalidEventError);
@@ -462,7 +517,7 @@ A report that a spy swallows and no assertion reads is worse than the noise, bec
 
 The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)) because the suite drives a real actor via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) free of any dependency on the actor runtime:
 
-```typescript
+```typescript fragment
 // packages/play-router/examples/shared/test/router-bridge-contract.ts
 export function runBridgeContractTests(opts: ContractSuiteOptions): void;
 
@@ -486,7 +541,7 @@ The contract covers: deep-link sync on connect, router→actor navigation sync,
 
 **Compile-time bridge contract verification:**
 
-```typescript
+```typescript fragment
 import { assertImplementsRouterBridge } from "@xmachines/play-router-shared/test/router-bridge-contract.js";
 import { MyRouterBridge } from "../src/my-router-bridge.js";
 
@@ -528,18 +583,23 @@ Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (ver
 - Pushes to the default branch (`$CI_DEFAULT_BRANCH`)
 - Merge requests (`$CI_MERGE_REQUEST_IID`)
 
-**CI test command** (from `.gitlab-ci.yml`):
+**CI test jobs** (from `.gitlab-ci.yml`):
 
 ```bash
-pnpm run test:coverage
+pnpm run test:dist --coverage           # test:dist
+pnpm run test:browser:dist --coverage   # test:browser:dist, on the Playwright image
+pnpm run test:docs:examples             # test:docs:examples
 ```
 
-The job passes no reporter flag. `vitest.config.ts` owns the reporters, the JUnit file and the coverage directory, and it reads `COVERAGE_REPORTS_DIR` — which the `test` job sets to `reports/`. A new package therefore needs no CI change.
+CI runs the suites on the build output alone. `test:dist` and `test:browser:dist` take `dist/` from `node-build` through `needs:`, so they test the build that the pipeline produced. They block: a failure is a defect of the tarball that a consumer installs, and it holds the release, because `semantic-release` runs in a later stage. `test:docs:examples` reads the source, so it waits for no build.
+
+The jobs pass no reporter flag. `vitest.config.ts` and `vitest.browser.config.ts` own the reporters, the JUnit file and the coverage directory, and they read `COVERAGE_REPORTS_DIR` — which the dist jobs set to `reports/`. A new package therefore needs no CI change. `test:docs:examples` shares the root config with `test:dist`, so it names its own JUnit file on the command line.
 
-**Artifacts:** The `test` job publishes:
+**Artifacts:**
 
-- JUnit XML report at `reports/test-results.xml` (surfaced in GitLab's test results panel)
-- Cobertura coverage XML at `reports/cobertura-coverage.xml` (used for GitLab's coverage percentage badge — extracted from the `All files` line)
+- `test:dist`: JUnit at `reports/test-results.xml`, and Cobertura at `reports/cobertura-coverage.xml`. GitLab reads the coverage percentage from the `All files` line.
+- `test:browser:dist`: JUnit at `reports/browser-results.xml`, and its own Cobertura report. GitLab merges the two Cobertura reports.
+- `test:docs:examples`: JUnit at `reports/docs-examples.xml`.
 
 Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.
 

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

@@ -43,7 +43,7 @@ Use this order to understand the implementation:
 6. `createDebugPanel(actor, shell, inspector)` in `src/components/DebugPanel.ts` uses `watchAtom(actor.state, ...)` and `watchAtom(actor.currentRoute, ...)` to drive live debug panel updates, and renders the **Show Inspector** button that calls `inspector.show()`.
 7. Browser tests in `test/browser/` validate startup rendering and auth interactions.
 
-```ts
+```ts fragment
 // src/main.ts (shape)
 const inspector = createDemoInspector();
 const createPlayer = definePlayer({
@@ -63,7 +63,7 @@ if (!app) throw new Error("Root element not found");
 initShell(actor, app, inspector);
 ```
 
-```ts
+```ts fragment
 // src/components/Shell.ts (shape)
 const registryResult = defineRegistry(authCatalog, {
 	components: demoComponents, // one shared map — Home…NavBar plus the 0.20 Panel/Field/Button leaves

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

@@ -6,7 +6,7 @@
 function createAuthActionHandlers(actor): object;
 ```
 
-Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L48)
+Defined in: [packages/play-actor/examples/shared/src/actions.ts:48](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L48)
 
 Build the demo action handler map for one actor.
 
@@ -25,11 +25,11 @@ framework's `defineRegistry` accepts; spread the result into its `actions`.
 
 | Name             | Type                                                    | Defined in                                                                                                                                                               |
 | ---------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L65) |
-| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L72) |
-| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L50) |
-| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L54) |
-| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L81) |
-| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L99) |
-| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L55) |
-| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-actor/examples/shared/src/actions.ts#L92) |
+| `addTask()`      | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:65](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L65) |
+| `completeTask()` | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L72) |
+| `login()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L50) |
+| `logout()`       | () => `Promise`\<`void`\>                               | [packages/play-actor/examples/shared/src/actions.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L54) |
+| `removeTask()`   | (`params`, `_setState`, `state`) => `Promise`\<`void`\> | [packages/play-actor/examples/shared/src/actions.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L81) |
+| `resetForm()`    | (`params`, `setState`) => `Promise`\<`void`\>           | [packages/play-actor/examples/shared/src/actions.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L99) |
+| `route()`        | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:55](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L55) |
+| `submitForm()`   | (`params?`) => `Promise`\<`void`\>                      | [packages/play-actor/examples/shared/src/actions.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-actor/examples/shared/src/actions.ts#L92) |

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

@@ -6,7 +6,7 @@
 function createConfirmDialog(confirm): Promise<boolean>;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/ConfirmDialog.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/ConfirmDialog.ts#L12)
+Defined in: [packages/play-dom/examples/demo/src/components/ConfirmDialog.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/examples/demo/src/components/ConfirmDialog.ts#L12)
 
 ConfirmDialog — the DOM demo's onConfirm implementation.
 

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

@@ -6,7 +6,7 @@
 function createNavBar(actor, container): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBar.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/examples/demo/src/components/NavBar.ts#L9)
 
 NavBar — App-shell navigation factory. Mounts a reactive nav into
 `container`, observes actor.state via watchAtom, and updates button

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

@@ -6,7 +6,7 @@
 function initShell(actor, appElement, inspector): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
+Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
 
 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: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/About.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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/Button.md

@@ -6,7 +6,7 @@
 const Button: ComponentFn<AuthCatalog, "Button">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Button.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Button.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Button.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/examples/demo/src/components/Button.ts#L8)
 
 Button — emits `press`; the spec's `on.press` binding decides what happens
 (a host action sending a machine event, or a built-in like setState).

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

@@ -6,7 +6,7 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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/Field.md

@@ -6,7 +6,7 @@
 const Field: ComponentFn<AuthCatalog, "Field">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Field.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Field.ts#L15)
+Defined in: [packages/play-dom/examples/demo/src/components/Field.ts:15](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/packages/play-dom/examples/demo/src/components/Field.ts#L15)
 
 Field — labelled input with two-way $bindState binding and declarative
 validation checks.

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

@@ -6,7 +6,7 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Home.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Login.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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: [packages/play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/NavBarView.ts#L12)
+Defined in: [packages/play-dom/examples/demo/src/components/NavBarView.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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: [packages/play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Navigation.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Navigation.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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: [packages/play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Overview.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Overview.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v7.0.0/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