@xmachines/docs 3.0.0 → 5.0.0

package/contributing/testing.md

@@ -4,13 +4,13 @@ This document describes the test framework, conventions, and CI integration for
 
 ## Test Framework and Setup
 
-The monorepo uses **[Vitest](https://vitest.dev/) `^4.1.5`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
+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.
 
-All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from `@xmachines/shared/vitest`) which automatically applies:
+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/shared/vitest-setup` — extends Vitest matchers with `@testing-library/jest-dom`
-- `@xmachines/shared/vitest-node-setup` — enforces Node.js ≥ 24 on non-browser projects
+- [`@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
 
 **Auto-injected setup files:**
 
@@ -19,6 +19,30 @@ All packages extend the shared Vitest configuration helper `defineXmVitestConfig
 | `packages/shared/config/vitest.node.setup.ts` | All non-browser projects | Validates Node.js ≥ 24 runtime; throws if wrong runtime |
 | `packages/shared/config/vitest.setup.ts`      | All projects             | Imports `@testing-library/jest-dom/vitest` matchers     |
 
+`vitest.setup.ts` is also the one file that [`@xmachines/shared/tsconfig-test`](../api/@xmachines/shared/README.md) names in `files`, so its import puts the matcher TYPES in every test program. Each package overrides `include`, and `files` survives that.
+
+### The jest-dom patch
+
+`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
+declare module "vitest" {
+	interface Assertion<T = any> extends TestingLibraryMatchers<any, T> {}
+}
+```
+
+Vitest 5 declares `interface Assertion<R extends void | Promise<void> = void, T = unknown>`. A module augmentation merges only when the type parameters are IDENTICAL, and TypeScript reports nothing when they differ — it simply does not apply. Every matcher therefore left the type of `expect(...)` while the runtime kept working. `Matchers` is the interface that vitest publishes for an extension, and `Assertion` extends it, so the patched declaration reaches every assertion and restates no interface whose shape vitest owns.
+
+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
@@ -33,7 +57,7 @@ pnpm install --frozen-lockfile
 pnpm test
 ```
 
-Runs `vitest run` across every project that the root `vitest.config.ts` collects — 36 of them today: one for each package, one for each demo that holds node tests, and `infrastructure` for the repository tests in `tests/`. Uses the `forks` pool (up to 4 workers) with process-level isolation between test files.
+Runs `vitest run` across every project that the root `vitest.config.ts` collects — 38 of them today: one for each package, one for each demo that holds node tests, and `infrastructure` for the repository tests in `tests/`. A node project uses the `forks` pool (up to 4 workers) and reuses a worker across test files — see [Isolation](#isolation). A jsdom project uses the `vmThreads` pool — see [Test environments](#test-environments).
 
 The root config finds those projects by glob, so a new package or demo joins the run with no edit. Each test file must belong to **one** project: a package config that reaches into its own `examples/` collects the demo tests that the demo config collects already, and the run then executes them two times, under two different environments. `tests/project-collection-overlap.test.ts` asks Vitest for the whole collection and fails on any file that two projects claim.
 
@@ -82,7 +106,7 @@ Individual packages may enforce higher per-package thresholds in their own `vite
 pnpm run test:build
 ```
 
-Runs `tsc --build tsconfig.test.json --force`. This validates that all test TypeScript files across the monorepo type-check correctly without running the tests themselves. Also compiles `.typecheck.ts` files in `src/` directories.
+Runs `tsc --build tsconfig.test.json --force`. This validates that all test TypeScript files across the monorepo type-check correctly without running the tests themselves. Also compiles the `.typecheck.ts` files of the `test/` directories.
 
 This is the command that answers "does this tree type-check?". Use it rather than `pnpm run build` for that question. `tsc --build` skips a project whose dependencies have unchanged `.d.ts` files, so an error inside the source of a library that changes no exported declaration can leave every consumer of that library up to date and never be reported — and consumers here compile library **source**, through the `source` export condition. `--force` costs about a second and takes that decision away from tsc; `tests/typecheck-staleness.test.ts` holds it, and the two other properties the complete check rests on, in place: no project of the gate is `composite`, and the CI job starts with no build state on disk. The job gets that second property by DELETING every `*.tsbuildinfo` before it runs the gate. It does not inherit it: most of the caching of the pipeline arrives through the included node component, and no test in this repository can read that component's cache paths, so a claim about them would be prose that nothing verifies.
 
@@ -117,27 +141,54 @@ packages/<name>/
 
 ### File naming conventions
 
-| Extension                                | Purpose                                                                                                                                 |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `.spec.ts`                               | Protocol enforcement tests; compile-time type safety tests; used in core packages (`play`, `play-actor`, `play-signals`, `play-xstate`) |
-| `.test.ts`                               | Unit, integration, and behavioral tests; used across all packages                                                                       |
-| `.browser.test.ts` / `.browser.test.tsx` | Playwright browser environment tests; excluded from standard `vitest.config.ts`, only run via `vitest.browser.config.ts`                |
-| `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `pnpm run test:build`                                       |
-| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                     |
+| Extension                                | Purpose                                                                                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `.spec.ts`                               | Protocol enforcement tests; compile-time type safety tests; used in core packages (`play`, `play-actor`, `play-atom`, `play-xstate`) |
+| `.test.ts`                               | Unit, integration, and behavioral tests; used across all packages                                                                    |
+| `.browser.test.ts` / `.browser.test.tsx` | Playwright browser environment tests; excluded from standard `vitest.config.ts`, only run via `vitest.browser.config.ts`             |
+| `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `pnpm run test:build`                                    |
+| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                  |
 
 ### Test environments
 
-| Environment                   | Packages                                                                                                   |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `node`                        | Core logic: `@xmachines/play`, `play-actor`, `play-signals`, `play-xstate`, `play-router`, router adapters |
-| `jsdom`                       | UI renderers: `@xmachines/play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`                 |
-| Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                        |
+| Environment                   | Packages                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node`                        | Core logic: [`@xmachines/play`](../api/@xmachines/play/README.md), `play-actor`, `play-atom`, `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                                                                                                         |
+
+`defineXmVitestConfig` gives a jsdom project the `vmThreads` pool. The `forks` pool builds one jsdom for each test file, and a jsdom costs about 0.4 s. The `vmThreads` pool gives each file its own VM context in a worker that keeps the environment, so a worker builds one jsdom for all the files that it runs. Each file still gets a fresh module registry and fresh globals. The full `pnpm test` run takes 94 s with `vmThreads` and 160 s with `forks`, and the environment share of the tracked time drops from 42% to 14%.
+
+A project that declares its own `pool` keeps it.
+
+### Isolation
+
+`defineXmVitestConfig` gives a node project `isolate: false`, and it keeps isolation for a jsdom project, for a browser project, and for a project that declares `environmentMatchGlobs`.
+
+Isolation gives each test FILE its own worker: Vitest spawns a process, builds the environment, and evaluates the module graph one more time. That costs about 110 ms for each file, and the full `pnpm test` run takes 90 s with isolation on every project and 62 s with this rule.
+
+A jsdom project keeps isolation and loses no time by it, because `vmThreads` above already gives one worker to many files. It also needs isolation: `isolate: false` shares the globals between the files of one worker, and three [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) tests fail under it.
+
+A worker that runs without isolation keeps ONE module registry for all the files that it runs, so `vi.mock` applies only while the worker has not yet loaded the real module. The order that the pool picks decides the winner, and the suite then fails on some runs and passes on others. [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) showed it: one file mocked `machine-to-graph.js` while twenty-five sibling files called the real module, and the package failed three tests on one run of the whole suite and twenty-five on the next. The file now builds a real machine, the package needs no isolation, and it runs in 1.0 s rather than 5.4 s.
+
+**A project whose test files call `vi.mock`, `vi.doMock`, `vi.stubGlobal`, or `vi.stubEnv` declares `isolate: true` in its own `vitest.config.ts`, with the reason.** `tests/isolate-policy.test.ts` holds this rule true: it asks `vitest list` which project collects which file, reads `isolate` from the config module, and names the file and the config when the two disagree. The scan follows the relative imports of each test file and reads the setup files of the project, so a fixture that mocks a module cannot hide, and it reads each `@vitest-environment` docblock, which reaches no config. Two projects declare it today: the `play-sveltekit-router` demo, which mocks `$app/navigation`, and the `play-actor` shared example, which stubs `window`.
+
+Prefer the other answer where you can reach it. A test that builds the real collaborator needs no isolation, and it costs the whole project nothing.
+
+A project that gives SOME of its files another environment isolates for the same reason. Vitest builds and tears down that environment inside a worker that keeps its module registry, so a module evaluated against the jsdom of one file stays cached for the next one and holds a `window` that no longer exists. [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md) runs three React files that way.
+
+A spy needs no isolation, and neither do fake timers. Each patches something that the test itself owns and restores, and neither depends on a fresh module registry.
+
+To check a project that you move off isolation, run the suite with a shuffled file order — the same check that `vitest doctor` applies:
+
+```bash
+pnpm exec vitest run --sequence.shuffle.files
+```
 
 ### Test helpers and shared setup
 
-- **`@xmachines/shared/vitest-setup`** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
-- **`@xmachines/shared/vitest-node-setup`** — Enforces Node ≥ 24 at runtime. Auto-injected for non-browser configs.
-- **`@xmachines/shared/vitest-urlpattern-setup`** — Polyfills `URLPattern` for packages that need it (e.g. `@xmachines/play-router`). Must be declared explicitly in `setupFiles`.
+- **[`@xmachines/shared/vitest-setup`](../api/@xmachines/shared/README.md)** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
+- **[`@xmachines/shared/vitest-node-setup`](../api/@xmachines/shared/README.md)** — Enforces Node ≥ 24 at runtime. Auto-injected for non-browser configs.
 - **`packages/play-react/test/test-utils.ts`** — React-specific test utilities for the `play-react` package.
 - **`packages/play-router/examples/shared/`** and **`packages/play-actor/examples/shared/`** — Shared test fixtures for router and actor integration tests.
 
@@ -211,8 +262,7 @@ describe("ClassName or functionName()", () => {
 **Import style:** Always use `.js` extensions in imports (ESM requirement):
 
 ```typescript
-import { AbstractActor } from "../src/abstract-actor.js";
-import { Signal } from "@xmachines/play-signals";
+import { PlayActor } from "../src/abstract-actor.js";
 ```
 
 ### Lifecycle hooks
@@ -235,16 +285,13 @@ 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
-    const mocks = vi.hoisted(() => ({
-    	machineToGraph: vi.fn(),
-    	buildRouteTree: vi.fn(),
-    }));
-
-    vi.mock("../src/machine-to-graph.js", () => ({
-    	machineToGraph: mocks.machineToGraph,
-    }));
+    const mocks = vi.hoisted(() => ({ goto: vi.fn() }));
+
+    vi.mock("$app/navigation", () => ({ goto: mocks.goto }));
     ```
 
+    A mock of a module costs the WHOLE project its isolation — see [Isolation](#isolation). Mock the framework module, and not a module of the package under test: a test that builds the real collaborator is both cheaper and stronger.
+
 - **`console.warn` / `console.error`** when testing code that legitimately emits warnings — mock to suppress noise and assert call counts:
 
     ```typescript
@@ -258,30 +305,27 @@ afterEach(() => {
 
 **Never mock these:**
 
-- **TC39 Signals** (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`) — always use real implementations from `@xmachines/play-signals`. Signals have precise reactive semantics (synchronous propagation, lazy computation) that mocks cannot replicate accurately.
+- **Atoms** (`createAtom`, `watchAtom`) — always use real implementations from [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md). Atoms have precise reactive semantics (synchronous propagation, memoized derivation) that mocks cannot replicate accurately.
 - **Internal `@xmachines/*` packages** — these are resolved directly to source via the `xmAliases` Vite plugin in the Vitest config. Mocking them would hide integration bugs and defeat the purpose of cross-package testing.
 - **XState** — always use real `setup()` / `createMachine()` / `createActor()`. XState's actor lifecycle (start, stop, snapshot, subscription) is a behavioral contract that mocks cannot reliably emulate.
 
 ### Test actor patterns
 
-**Preferred: extend `AbstractActor` for full type safety:**
+**Preferred: extend `PlayActor` 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>;
+import { PlayActor } from "@xmachines/play-actor";
+import type { Routable } from "@xmachines/play-router";
+
+class MockActor implements PlayActor, Routable {
+	readonly state = createAtom({} as unknown);
+	private _routeState: Atom<string | null>;
+	readonly currentRoute: ReadonlyAtom<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._routeState = createAtom<string | null>(startRoute);
+		this.currentRoute = createAtom(() => this._routeState.get());
 		this.initialRoute = startRoute;
 	}
 
@@ -297,15 +341,15 @@ class MockActor extends AbstractActor<AnyActorLogic> implements Routable {
 import { stubOf } from "@xmachines/shared/test-support";
 
 function createMockActor(initialView: PlaySpec | null = null) {
-	return stubOf<AbstractActor<AnyActorLogic> & Viewable>({
-		currentView: new Signal.State<PlaySpec | null>(initialView),
+	return stubOf<ViewActor>({
+		currentView: createAtom<PlaySpec | null>(initialView),
 		send: vi.fn(),
 		start: vi.fn(),
 		stop: vi.fn(),
 		getSnapshot: vi.fn(),
 		subscribe: vi.fn(),
-		state: new Signal.State<unknown>({}),
-		currentRoute: new Signal.Computed(() => null),
+		state: createAtom<unknown>({}),
+		currentRoute: createAtom(() => null),
 	});
 }
 ```
@@ -317,9 +361,9 @@ sites. `X as unknown as T` is banned in this repo; if `stubOf` cannot express
 the case, `unsafeCast<T>(value)` from the same module is the deliberate,
 greppable escape hatch.
 
-### Async and signal patterns
+### Async and atom patterns
 
-**Flushing the microtask queue (required for Signal propagation):**
+**Flushing the microtask queue (required for `watchAtom` delivery):**
 
 ```typescript
 function waitForMicrotask(): Promise<void> {
@@ -331,23 +375,26 @@ await waitForMicrotask();
 await vi.waitFor(() => expect(result).toBe(expected), { timeout: 100 });
 ```
 
-**Signal watcher pattern:**
+**Atom watch pattern:**
 
 ```typescript
-let notified = false;
-const watcher = new Signal.subtle.Watcher(() => {
-	notified = true;
+import { createAtom, watchAtom } from "@xmachines/play-atom";
+
+let notified: string | null = null;
+const stop = watchAtom(actor.currentRoute, (route) => {
+	notified = route;
 });
-watcher.watch(actor.currentRoute);
-actor.currentRoute.get(); // Initial read required to prime computed signals
 
 actor.state.set({ path: "/dashboard" });
-watcher.getPending(); // Process notifications synchronously
+// `watchAtom` coalesces into a microtask, so flush before the assertion.
+await new Promise((resolve) => setTimeout(resolve, 0));
 
-expect(notified).toBe(true);
-watcher.unwatch(actor.currentRoute); // Always clean up
+expect(notified).toBe("/dashboard");
+stop(); // Always clean up
 ```
 
+`atom.subscribe` delivers SYNCHRONOUSLY, inside the `set`, and it needs no flush. Use it when a test must observe the notification at the moment of the write. Use `watchAtom` everywhere else, because it is what the renderers and the bridges use.
+
 ### Compile-time type tests
 
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
@@ -365,10 +412,10 @@ const bad: PlaySpec = typedSpec({
 expect(bad.root).toBe("root");
 ```
 
-For purely structural type assertions with no runtime test needed, use `.typecheck.ts` files in `src/`:
+For purely structural type assertions with no runtime test needed, use `.typecheck.ts` files in `test/`:
 
 ```typescript
-// packages/play-xstate/src/define-player.typecheck.ts
+// packages/play-xstate/test/define-player.typecheck.ts
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type AssertFalse<T extends false> = T;
 
@@ -400,9 +447,20 @@ try {
 }
 ```
 
+### An expected report in the log
+
+A test that makes a component fail gets a report of the framework for free. React writes the error and a component stack to `console.error` when the root declares no `onCaughtError`, and [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md) writes a line of its own when the caller gives no `onError`. Both reports are correct, and both reach the log of the pipeline, where 29 of them once filled more than half of the `test` job.
+
+Claim the report in the test that expects it, and assert it:
+
+- **React.** Take `render` from `test/test-utils.js` of [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), and not from `@testing-library/react`. It gives an `onCaughtError` to the root, which stops the print, and the result carries `caughtErrors` for an assertion. Keep the `render` of the library for a test that holds the DEFAULT report: the print of React IS the report of play-react for a caller that gives no `onError`.
+- **Any framework.** Call `vi.spyOn(console, "error").mockImplementation(() => {})` before the render, and `expect(spy).toHaveBeenCalled()` after it. An `afterEach` with `vi.restoreAllMocks()` returns the console to the next test.
+
+A report that a spy swallows and no assertion reads is worse than the noise, because it hides the day that the renderer stops to report.
+
 ## Contract Tests
 
-The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in `@xmachines/play-router`) because the suite drives a real actor via `@xmachines/play-xstate` and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps `@xmachines/play-router` free of any dependency on the actor runtime:
+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
 // packages/play-router/examples/shared/test/router-bridge-contract.ts
@@ -424,7 +482,7 @@ runBridgeContractTests({
 
 The contract covers: deep-link sync on connect, router→actor navigation sync, actor→router sync, guard redirect flows, duplicate event deduplication, and restore-from-snapshot behavior.
 
-**Used by:** `@xmachines/play-router`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-react-router`, and other adapter packages.
+**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:**
 
@@ -448,11 +506,13 @@ Coverage is collected using the **v8** provider. The root `vitest.config.ts` def
 
 Individual packages enforce their own (typically stricter) thresholds inside their `vitest.config.ts`:
 
-| Package tier                                                               | Lines | Functions | Branches | Statements |
-| -------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
-| Core packages (`@xmachines/play`, `@xmachines/play-actor`)                 | 90%   | 90%       | 85%      | 90%        |
-| Complex logic (`@xmachines/play-xstate`, `@xmachines/play-router`)         | 85%   | 85%       | 80%      | 85%        |
-| Integration packages (e.g. `@xmachines/play-react`, `@xmachines/play-dom`) | 80%   | 80%       | 80%      | 80%        |
+| Package tier                                                                                                                                                                                              | Lines | Functions | Branches | Statements |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
+| Core packages ([`@xmachines/play`](../api/@xmachines/play/README.md), [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md), [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)) | 90%   | 90%       | 85%      | 90%        |
+| Complex logic ([`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md), [`@xmachines/play-router`](../api/@xmachines/play-router/README.md))                                                  | 85%   | 85%       | 80%      | 85%        |
+| Integration packages (e.g. [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md))                                              | 80%   | 80%       | 80%      | 80%        |
+
+[`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries the lower numbers for a reason that its `vitest.config.ts` states: the bridge and the provider lifecycle are the mass of that package, and neither is measured by its own project. `@xmachines/play-router-shared` drives them through 3032 lines of contract suite, and each of the nine router adapters drives them again from its own project. The root `pnpm run test:coverage` is what measures the package whole.
 
 Coverage includes: `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
 
@@ -471,23 +531,19 @@ Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (ver
 **CI test command** (from `.gitlab-ci.yml`):
 
 ```bash
-pnpm run test:coverage -- \
-  --coverage.reporter=text \
-  --coverage.reporter=cobertura \
-  --coverage.reportsDirectory=reports/coverage \
-  --reporter=default \
-  --reporter=junit \
-  --outputFile.junit=reports/junit.xml
+pnpm run test:coverage
 ```
 
-**Artifacts:** The CI job (`node-build`) publishes:
+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.
+
+**Artifacts:** The `test` job publishes:
 
-- JUnit XML report at `reports/junit.xml` (surfaced in GitLab's test results panel)
-- Cobertura coverage XML at `reports/coverage/cobertura-coverage.xml` (used for GitLab's coverage percentage badge — extracted from the `All files` line)
+- 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)
 
 Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.
 
-The `pnpm run format:check` and `pnpm run lint` commands enforce code style and are run separately from tests (via the `lint-enabled: true` input to the pipeline component).
+The `pnpm run format:check` and `pnpm run lint` commands enforce code style. They run as the separate `format` and `lint` jobs: the component's own lint job is turned off with `lint-enabled: "false"`, because it runs ESLint.
 
 ## Test Types Reference
 

package/examples/README.md

@@ -8,7 +8,7 @@ Practical code examples demonstrating current XMachines Play patterns and use ca
 
 Start with the fundamental machine + actor pattern:
 
-- **[Basic State Machine](basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + TC39 Signals
+- **[Basic State Machine](basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + atoms
 - **[Traffic Light](traffic-light.md)** — Multi-state machine with `meta.route` and `formatPlayRouteTransitions`
 - **[Form Validation](form-validation.md)** — Typed context mutations with `setup.assign`, guards, and `$bindState`
 
@@ -60,7 +60,7 @@ The conceptual examples in this directory are TypeScript snippets. To run them:
 
 ```bash
 # Install dependencies (from the monorepo root)
-pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
+pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom xstate
 
 # Run with tsx
 pnpm dlx tsx my-example.ts
@@ -76,12 +76,14 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 
 ### Core
 
-| Package                                                               | Role                                                        |
-| --------------------------------------------------------------------- | ----------------------------------------------------------- |
-| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)   | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
-| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)     | `AbstractActor`, `typedSpec`                                |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) | TC39 Signals polyfill, `watchSignal`                        |
-| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)   | `extractMachineRoutes`, `getRoutableRoutes`                 |
+| Package                                                                    | Role                                                        |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)        | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)          | `PlayActor`                                                 |
+| [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)            | `Viewable`, `PlaySpec`, `typedSpec`                         |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)            | The atom primitives, `watchAtom`                            |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)        | `RouterBridgeBase`, `RouteMap`, `Routable`                  |
+| [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) | `extractMachineRoutes`, `getRoutableRoutes`                 |
 
 ### Renderers
 
@@ -98,7 +100,7 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 | Package                                                                                           | Router                  |
 | ------------------------------------------------------------------------------------------------- | ----------------------- |
 | [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | Vanilla browser history |
-| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router v7         |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8        |
 | [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack Router (React) |
 | [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router          |
 | [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack Router (Solid) |

package/examples/basic-state-machine.md

@@ -63,7 +63,7 @@ actor.start();
 console.log(actor.getSnapshot().value); // "off"
 console.log(actor.getSnapshot().context.toggleCount); // 0
 
-// 6. Read state via TC39 Signal
+// 6. Read state from the atom
 console.log(actor.state.get().value); // "off"
 
 // 7. Send events
@@ -87,13 +87,13 @@ actor.stop();
 
 3. **`toggleSetup.assign(...)`** — Assigns context mutations using the typed setup's `assign` helper. This provides full inference from the declared context type — no manual type assertions needed.
 
-4. **`definePlayer({ machine })`** — Wraps the machine in a factory. Calling `createPlayer()` returns a `PlayerActor` — XMachines' actor type that extends XState's actor with TC39 Signal reactivity and Play Architecture hooks.
+4. **`definePlayer({ machine })`** — Wraps the machine in a factory. Calling `createPlayer()` returns a `PlayerActor` — XMachines' actor type that extends XState's actor with atom reactivity and Play Architecture hooks.
 
 5. **`actor.start()`** — Activates the machine. Always call `start()` before sending events.
 
 6. **`actor.getSnapshot()`** — Returns the current XState snapshot synchronously. `.value` is the state name; `.context` is the typed context object.
 
-7. **`actor.state.get()`** — TC39 Signal access to the current snapshot. Useful when wiring infrastructure that observes signals (renderers, router bridges). Equivalent to `actor.getSnapshot()` for one-time reads.
+7. **`actor.state.get()`** — atom access to the current snapshot. Useful when wiring infrastructure that observes atoms (renderers, router bridges). Equivalent to `actor.getSnapshot()` for one-time reads.
 
 8. **Event types use dot-separated lowercase** — `"toggle"` not `"TOGGLE"`. This matches the XMachines convention used throughout the codebase (e.g. `"auth.login"`, `"auth.logout"`, `"play.route"`).
 
@@ -101,7 +101,7 @@ actor.stop();
 
 - **`setup({ types })`**: The XState v5 typed entry point. Declares context, event, and input shapes before machine creation.
 - **`definePlayer({ machine })`**: Creates a factory function that returns `PlayerActor` instances.
-- **`actor.state`**: A `Signal.State<Snapshot>` — TC39 Signals-based reactive handle on the machine snapshot.
+- **`actor.state`**: An `Atom<Snapshot>` — an atom-based reactive handle on the machine snapshot.
 - **`actor.getSnapshot()`**: Synchronous snapshot access — use for one-time reads and TypeScript-typed context inspection.
 - **Typed `assign`**: Always call `setup.assign(...)` (not the bare `assign` from xstate) for context mutations.
 

package/examples/form-validation.md

@@ -15,7 +15,8 @@ This example mirrors the `authMachine` login pattern: a form state with a local
 
 ```typescript
 import { setup } from "xstate";
-import { definePlayer, formatPlayRouteTransitions } from "@xmachines/play-xstate";
+import { definePlayer } from "@xmachines/play-xstate";
+import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 
 // Context shape
 interface LoginContext {
@@ -223,7 +224,7 @@ view: {
 
 ## Connecting the Renderer
 
-The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from `@xmachines/play-dom`:
+The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md):
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";
@@ -304,5 +305,5 @@ window.addEventListener("beforeunload", () => {
 
 - **[Basic State Machine](basic-state-machine.md)** — Foundational concepts without a view layer
 - **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
-- **[`PlaySpec`](../api/@xmachines/play-actor/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
+- **[`PlaySpec`](../api/@xmachines/play-view/index/interfaces/PlaySpec.md)** — Spec type governing `meta.view`, `$bindState`, and `$state`
 - **[`@xmachines/play-router`](../api/@xmachines/play-router/README.md)** — Route extraction and tree building