@xmachines/docs 3.0.0 → 4.0.0

package/contributing/configuration.md

@@ -22,23 +22,23 @@ The dev container currently defines no workspace-specific environment variables;
 
 **Examples:**
 
-```bash
-# Skip one package publish
-SEMREL_SKIP_STEPS="@semantic-release/npm:packages/play-xstate"
+A step ID is the name of the plugin, and a name that the entry declares extends it: `@semantic-release/exec:build`.
 
-# Skip all demo publish steps
-SEMREL_SKIP_STEPS="examples/demo"
+```bash
+# Skip one prepare step
+SEMREL_SKIP_STEPS="@semantic-release/exec:build$"
 
-# Skip all exec steps (build, typedoc, etc.)
+# Skip every prepare step
 SEMREL_SKIP_STEPS="@semantic-release/exec"
 
-# Publish-only retry (skip build + demos)
-SEMREL_SKIP_STEPS="@semantic-release/exec|examples/demo"
-
-# Skip git commit and GitLab release
-SEMREL_SKIP_STEPS="@semantic-release/git|@semantic-release/gitlab"
+# Leave CHANGELOG.md alone
+SEMREL_SKIP_STEPS="@semantic-release/changelog"
 ```
 
+A pattern that removes `@semantic-release/git` throws instead of running: semantic-release would still tag and push, and the tag would then name a commit that carries no version bump.
+
+The variable reaches the publish never. `scripts/publish-release.mjs` runs on the tag pipeline, outside semantic-release — see [deployment.md](deployment.md).
+
 ---
 
 ## Configuration Files
@@ -185,8 +185,8 @@ export default defineConfig({
 | `no-underscore-dangle`       | —             | `off`                                |
 
 `unicorn/no-array-sort` is an error and not the warning of its category. The workspace
-targets ESNext, and Node 22 — the lowest runtime a published package supports — has
-`toSorted()`, so the method is always available. As a warning the rule kept
+targets ESNext, and Node 24 — the floor of every package — has `toSorted()`, so the
+method is always available. As a warning the rule kept
 the lint job green while the Code Quality report showed the degradation, and `sort()` stayed
 behind a suppression for a ceiling that had already gone.
 
@@ -252,6 +252,64 @@ export default defineConfig({
 | `useTabs`  | `false` |
 | `tabWidth` | `2`     |
 
+### Developer Tools — Vite DevTools
+
+**Tool:** [Vite DevTools](https://devtools.vite.dev/guide/) `^0.7.1`
+**Run:** `Shift+Alt+D` in any demo dev server
+
+`@vitejs/devtools` hosts four integrations, and each one reads a tool this repository already
+uses:
+
+| Integration                                                        | Panel                                                            |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| [`@vitejs/devtools-oxc`](https://devtools.vite.dev/oxc/)           | oxlint diagnostics, the resolved rules, and the oxfmt version    |
+| [`@vitejs/devtools-vite`](https://devtools.vite.dev/vite/)         | the plugin pipeline of the dev server, and each module transform |
+| [`@vitejs/devtools-rolldown`](https://devtools.vite.dev/rolldown/) | the rolldown build that Vite 8 runs, and the modules it bundles  |
+| [`@vitejs/devtools-vitest`](https://devtools.vite.dev/vitest/)     | the Vitest UI, inside the dock                                   |
+
+`defineXmDemoConfig` adds the dock to every demo dev server, therefore the four panels need no
+script and no separate command:
+
+```bash
+pnpm --filter @xmachines/play-vue-router-demo run dev
+# then press Shift+Alt+D in the browser
+```
+
+The dock starts hidden (`embeddedVisibility: "passive"`), and the browser remembers the choice
+after the first `Shift+Alt+D`. The demos are the subjects of the browser suites and of the
+screenshots of the documentation, and a panel above them helps neither.
+
+The root manifest declares `@vitest/ui`, because the Vitest panel embeds it. Without it the panel
+shows an "Install @vitest/ui & start" button, and that button writes the dependency into the root
+manifest and installs it while the dev server runs. It installs the newest version, which is 5.x,
+and `vitest` names `@vitest/ui` as a peer at its own exact version. The declared `^4.1.11` keeps
+the whole vitest family on one range, which `tests/vitest-version-lockstep.test.ts` holds true.
+
+Only the 13 demo apps declare the five packages, because only they run a dev server. The Oxc panel
+reads the same shared configuration from any of them: all 23 per-package `oxlint.config.ts`
+files hold `extends: [sharedConfig]` and add nothing, and the packages under `examples/` hold no
+config of their own. To read the configuration of a package that has no demo, run the inspector
+without installing it:
+
+```bash
+pnpm --filter @xmachines/docs exec npx @vitejs/devtools-oxc
+```
+
+`defineXmDemoConfig` hands `DevTools()` the demo directory as `cwd`. Without it the lookup starts
+at `process.cwd()`, and the set of panels then depends on the directory a person typed the command
+in.
+
+Every DevTools plugin carries `apply: "serve"`. A demo is a release asset, therefore
+`pnpm --filter <demo> run build` emits the same files as before the dock existed, and no devtools
+code reaches a published demo.
+
+A Vitest run gets no dock. `apply: "serve"` does not cover that case, because Vitest browser mode
+serves the app and therefore counts as `serve`. `defineXmDemoConfig` reads the `VITEST` variable
+that the Vitest CLI sets, and it adds no plugin when that variable is present. This gate is a
+guard, and it is not a fix for a failure that reproduces: the browser suite also passes and exits
+with the gate removed. A dock belongs to a dev server that a person opened, therefore the gate
+stays.
+
 ### Editor — `.editorconfig`
 
 **Location:** `/.editorconfig`
@@ -273,15 +331,15 @@ export default defineConfig({
 
 Root Vitest config is a **workspace coordinator** that lists all per-package configs under `test.projects`. It sets conservative monorepo-wide defaults:
 
-| Setting           | Value      | Notes                                                  |
-| ----------------- | ---------- | ------------------------------------------------------ |
-| `pool`            | `"forks"`  | Process-isolated workers                               |
-| `maxWorkers`      | `4`        | Root default; per-project configs may override         |
-| `isolate`         | `true`     |                                                        |
-| `fileParallelism` | `false`    | Conservative default; safe packages opt in with `true` |
-| `teardownTimeout` | `30000` ms |                                                        |
-| `hookTimeout`     | `30000` ms |                                                        |
-| `testTimeout`     | `10000` ms |                                                        |
+| Setting           | Value      | Notes                                                                                |
+| ----------------- | ---------- | ------------------------------------------------------------------------------------ |
+| `pool`            | `"forks"`  | Process-isolated workers; `defineXmVitestConfig` gives a jsdom project `"vmThreads"` |
+| `maxWorkers`      | `4`        | Root default; per-project configs may override                                       |
+| `isolate`         | `true`     |                                                                                      |
+| `fileParallelism` | `false`    | Conservative default; safe packages opt in with `true`                               |
+| `teardownTimeout` | `30000` ms |                                                                                      |
+| `hookTimeout`     | `30000` ms |                                                                                      |
+| `testTimeout`     | `10000` ms |                                                                                      |
 
 **Coverage thresholds** (monorepo aggregate — `vitest run --coverage`):
 
@@ -367,11 +425,12 @@ Only `main` is a protected branch today. That works because `GITLAB_TOKEN` — w
     - `build` — `pnpm run build`
     - `typedoc` — `pnpm --filter @xmachines/docs run typedoc`
     - `format-docs` — `pnpm --filter @xmachines/docs run format`
-5. `@semantic-release/npm` — one entry per published package (20 packages) + pack-only for demo apps
-6. `@semantic-release/git` — commits `CHANGELOG.md`, updated `package.json` files, and generated API docs
-7. `@semantic-release/gitlab` — creates a GitLab release with tarball assets
+    - `stage-generated-docs` — `git add -A packages/docs/api`, so a page that TypeDoc deleted leaves git too
+5. `@semantic-release/git` — commits the changelog, the manifests, the READMEs and the generated API docs, then pushes the commit and the tag
+
+The list ends there. semantic-release publishes nothing and creates no GitLab release: `scripts/publish-release.mjs` does both, on the pipeline of the tag. [deployment.md](deployment.md) states the whole sequence and the reason.
 
-Any step can be skipped via the `SEMREL_SKIP_STEPS` CI variable (see [Environment Variables](#environment-variables)).
+Any step above can be skipped with the `SEMREL_SKIP_STEPS` CI variable, which the CI / Release Pipeline Variable section at the top of this page states.
 
 ---
 

package/contributing/deployment.md

@@ -8,11 +8,11 @@ This document describes how `@xmachines/xmachines-js` packages are built, versio
 
 All `@xmachines/*` packages are published to the **public npm registry** (`registry.npmjs.org`). Every package uses `"publishConfig": { "access": "public" }` so scoped packages are accessible without an npm org subscription. See the [Published Packages](#published-packages) table for the full list.
 
-| Target          | Config File                                                               | Purpose                                                |
-| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------ |
-| npm registry    | `release.config.mjs` (npm plugin entries derived from the workspace scan) | Publish all public packages                            |
-| GitLab Releases | `release.config.mjs` (`@semantic-release/gitlab` plugin)                  | Attach tarball artifacts to the GitLab release tag     |
-| GitLab CI       | `.gitlab-ci.yml`                                                          | Trigger builds, tests, and releases on push / MR / tag |
+| Target          | Config File                                        | Purpose                                                |
+| --------------- | -------------------------------------------------- | ------------------------------------------------------ |
+| npm registry    | `scripts/publish-release.mjs`, on the tag pipeline | Publish all public packages                            |
+| GitLab Releases | `scripts/publish-release.mjs`, on the tag pipeline | Attach tarball artifacts to the GitLab release tag     |
+| GitLab CI       | `.gitlab-ci.yml`                                   | Trigger builds, tests, and releases on push / MR / tag |
 
 The root `package.json` is marked `"private": true` and is **never published** to npm.
 
@@ -116,7 +116,7 @@ node scripts/release-pack-smoke.mjs
 
 `scripts/release-pack-smoke.mjs`:
 
-1. Reads `release.config.mjs` to find all `@semantic-release/npm` plugin entries where `npmPublish` is not `false`.
+1. Asks `scripts/lib/release-packages.mjs` which packages a release publishes. `publish-release.mjs` and `release.config.mjs` ask the same module, so the three cannot disagree.
 2. For each publishable package: runs `npm pack --json` in the package directory.
 3. Creates a temporary directory, runs `npm init -y`, and installs the local tarball with `--ignore-scripts`.
 4. Asserts the install succeeds — any missing files, broken exports, or pack-time errors surface here.
@@ -155,6 +155,7 @@ node scripts/set-workspace-versions.mjs ${nextRelease.version}
 pnpm run build
 pnpm --filter @xmachines/docs run typedoc --gitRevision v${nextRelease.version}
 pnpm --filter @xmachines/docs run format
+git add -A packages/docs/api
 ```
 
 Step by step:
@@ -165,44 +166,45 @@ Step by step:
 4. **Build** — runs `vite build && tsc --build` to produce compiled `dist/` output — JavaScript then declarations — in all packages.
 5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` at the release git revision.
 6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
+7. **Stage the generated docs** — `git add -A packages/docs/api`. The git plugin stages what `git ls-files -m -o` reports, and that never reports a DELETION. A page that TypeDoc removed, because an export was renamed or deleted, therefore stayed in git forever while the docs tarball packed from the working tree was correct. `git add -A` stages the removals, and the git plugin commits the index.
 
 ### Publish Phase
 
-Each publishable package is published in sequence via individual `@semantic-release/npm` plugin entries. Each entry specifies:
+semantic-release publishes nothing. It stops at the tag, and `scripts/publish-release.mjs` publishes from a pipeline that runs ON that tag:
 
-- `pkgRoot` — the package directory relative to the workspace root
-- `tarballDir` — `dist/releases/` where the packed `.tgz` is saved
+```bash
+node scripts/publish-release.mjs
+```
 
-Example (from `release.config.mjs`, where these entries are generated rather than
-hand-written):
+The tag pipeline is what makes the provenance attestation meaningful. npm records the commit of the pipeline in the attestation. On a tag pipeline that commit IS the commit that the tag names, and it is the commit whose manifests declare this version. A publish from the branch pipeline attests the PARENT of the release commit instead: a revision that the tag does not name, and whose manifests still carry the previous version.
 
-```js
-["@semantic-release/npm", { pkgRoot: "packages/play", tarballDir: "dist/releases" }];
-```
+The script pins the internal dependencies, strips the `source` export condition, packs every workspace package into `dist/releases/`, publishes each publishable tarball with `--provenance` under the dist-tag of the version, and verifies that every one reached the registry. It then creates the GitLab release with the tarballs attached, and it restores the working tree.
+
+The script is idempotent. It skips every package that the registry already serves at this version, so one retry of the job finishes a run that died partway — which is how the publish of 1.1.0 recovered from a credential that expired mid-run. Nothing to untag, nothing to force-push.
 
 ### Post-Release Phase
 
-After all packages are published:
+This phase runs on the branch, BEFORE the tag pipeline publishes.
 
 1. **`@semantic-release/git`** commits updated files back to the repository:
     - `CHANGELOG.md`
-    - `package.json` and `package-lock.json` (root)
-    - `packages/*/{package.json,examples/*/package.json}` (all workspace packages)
+    - `package.json`, `pnpm-lock.yaml` and `pnpm-workspace.yaml` (root)
+    - The `package.json` of every scanned package, and the `README.md` of every one — the release stamps the version badge of a README at the same moment as the manifest
     - `packages/docs/api/**` (generated API documentation)
 
+    The manifest list and the README list both come from the workspace scan, and not from a glob written by hand, so a package that a new `pnpm-workspace` pattern adds cannot be published while its manifest stays behind in git. A test asserts that every scanned package appears in both lists.
+
     Commit message format:
 
     ```
     chore(release): <version>
-
-    <release notes>
-
-    [skip ci]
     ```
 
-2. **`@semantic-release/gitlab`** creates a GitLab Release entry attached to the version tag, with all `dist/releases/*.tgz` tarballs as downloadable assets labelled "Release tarballs".
+    The release notes are NOT interpolated into the message. `@semantic-release/git` runs `git commit -m <message>`, and the notes of the first stable release aggregate about 1600 commits — an `-m` value of several megabytes overflows the argument limit of the OS. The notes land in `CHANGELOG.md`, which the same commit carries.
+
+    The message carries no `[skip ci]`. The release commit needs no pipeline of its own, but the TAG that points at it does: that pipeline is where the publish happens.
 
-3. **`@semantic-release/changelog`** updates `CHANGELOG.md` with generated release notes.
+2. **The git plugin pushes the commit and the tag.** semantic-release stops there. The GitLab release entry, with every `dist/releases/*.tgz` attached, is created later by `scripts/publish-release.mjs` on the tag pipeline — after the publish succeeded, so a release entry never advertises a tarball that npm refused.
 
 ---
 
@@ -219,11 +221,11 @@ This means packages always depend on the exact same version of sibling packages
 
 ## Credentials and Protected Variables
 
-| Variable                    | Source                                  | Purpose                                                                         |
-| --------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
-| `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates `semantic-release` to npm registry via OIDC token exchange        |
-| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (unprotected)  | Authenticates `@semantic-release/gitlab` for release creation and git push back |
-| `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                  |
+| Variable                    | Source                                  | Purpose                                                                                                        |
+| --------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates `semantic-release` to npm registry via OIDC token exchange                                       |
+| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (unprotected)  | Authenticates the git push back of semantic-release, and the GitLab release that `publish-release.mjs` creates |
+| `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                                                 |
 
 **No static npm token is committed to the repository.** The `NPM_ID_TOKEN` is a short-lived OIDC token generated for each CI job with audience `npm:registry.npmjs.org`.
 

package/contributing/development.md

@@ -83,13 +83,15 @@ packages/
 ├── shared/                      # Shared configs (tsconfig, oxlint, oxfmt, vitest)
 ├── play/                        # Core protocol (PlayEvent, PlayError)
 ├── play-signals/                # TC39 Signals polyfill wrapper
-├── play-actor/                  # Abstract actor base (AbstractActor, Routable, Viewable)
+├── play-url/                    # The URL language: the grammar, 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-xstate/                 # XState v5 adapter (definePlayer, PlayerActor)
 ├── play-router/                 # Route extraction and RouterBridgeBase
 ├── play-dom/                    # Vanilla DOM renderer
 ├── play-dom-router/             # DOM router adapter
 ├── play-react/                  # React renderer (PlayRenderer)
-├── play-react-router/           # React Router v7 adapter
+├── play-react-router/           # React Router 7/8 adapter
 ├── play-vue/                    # Vue 3 renderer
 ├── play-vue-router/             # Vue Router adapter
 ├── play-solid/                  # SolidJS renderer
@@ -181,6 +183,22 @@ What that costs is worth stating plainly: **CI only ever exercises the dev versi
 
 React 18 and vue-router 4 are supported by intent — nothing known depends on 19-only or 5-only behaviour — but neither is installed by any job, so a regression there would surface as a consumer's bug report rather than a red pipeline. Narrowing either range to what is tested would be a breaking change for consumers and needs a major release; adding a floor-install job would close the gap instead. Until one of those happens, treat the lower major as untested.
 
+### The packages that must exist one time
+
+`@xmachines/play` and `@xmachines/play-signals` are a peer of every package that reads them, and a dependency of none.
+
+`@xmachines/play-signals` wraps `signal-polyfill`, and the polyfill holds its dependency graph in the state of its own module. Two copies build two graphs. A `Signal.Computed` of the first copy and a `Signal.subtle.Watcher` of the second copy therefore never meet: the watcher stays silent, and no error reports the fault. Every propagation of state in this architecture goes through a signal, so the second copy stops the reactivity of a whole application.
+
+`@xmachines/play` holds `PlayError`, and the documentation sends a consumer to `err instanceof PlayError`. That check answers `false` for an error of the second copy.
+
+A dependency invites that second copy. `scripts/lib/workspace-deps.mjs` pins a `workspace:*` range to an EXACT version, so two packages of two releases name two versions, and an installer resolves both. A peer moves the choice to the consumer, who brings one copy. The `@xmachines/json-render-*` packages carry the same rule for the same reason.
+
+Each of the two needs a `devDependency` beside the peer, because the workspace installs no peer. Without that entry a package resolves the specifier through the hoisting of another package, and it compiles until that other package stops declaring it.
+
+`tests/singleton-peers.test.ts` holds the three rules true: no dependency, a dev entry beside each peer, and a peer for each one that `src/` imports. A package that reads one of the two in its TESTS alone needs the dev entry alone — `@xmachines/play-tanstack-router` is that case.
+
+The rule reads in both directions. A peer that the `src/` directory never imports is a peer that a consumer installs for nothing, and four router adapters carried one. A package declares the peer when it reads the package, and a `devDependency` alone when its tests read it.
+
 ---
 
 ## TypeScript Composite Build System
@@ -201,14 +219,15 @@ Packages are grouped into dependency layers as defined in the root `tsconfig.jso
 | Layer | Packages                                                                         | Depends on         |
 | ----- | -------------------------------------------------------------------------------- | ------------------ |
 | 0     | `docs`, `play`, `shared`                                                         | External libs only |
-| 1     | `play-signals`                                                                   | Layer 0            |
+| 1     | `play-signals`, `play-url`                                                       | Layer 0            |
 | 2     | `play-actor`                                                                     | Layers 0–1         |
-| 3     | `play-dom`, `play-react`, `play-router`, `play-solid`, `play-svelte`, `play-vue` | Layers 0–2         |
-| 4     | `play-tanstack-router`, `play-xstate`                                            | Layers 0–3         |
-| 5     | `play-actor/examples/shared`                                                     | Layers 0–4         |
-| 6     | renderer demo apps                                                               | Layers 0–5         |
-| 7     | the eight router adapters                                                        | Layers 0–6         |
-| 8     | router demo apps                                                                 | Layers 0–7         |
+| 3     | `play-view`                                                                      | Layers 0–2         |
+| 4     | `play-dom`, `play-react`, `play-router`, `play-solid`, `play-svelte`, `play-vue` | Layers 0–3         |
+| 5     | `play-tanstack-router`, `play-xstate`                                            | Layers 0–4         |
+| 6     | `play-actor/examples/shared`                                                     | Layers 0–5         |
+| 7     | renderer demo apps                                                               | Layers 0–6         |
+| 8     | the eight router adapters                                                        | Layers 0–7         |
+| 9     | router demo apps                                                                 | Layers 0–8         |
 
 The layer of an entry is its longest path to a package with no workspace dependency, and `tests/tsconfig-reference-graph.test.ts` computes it from the manifests.
 
@@ -500,7 +519,29 @@ This project uses **Conventional Commits** — changelogs and version bumps are
 | `perf`     | No bump (unless breaking) | Performance improvements                 |
 | `ci`       | No bump                   | CI/CD pipeline changes                   |
 
-Breaking changes: append `!` after the type (`feat!:`) or add `BREAKING CHANGE:` in the footer.
+Breaking changes: append `!` after the type (`feat!:`) AND write a `BREAKING CHANGE:`
+footer. The two do different work, and neither one replaces the other:
+
+- The `!` decides the BUMP. `release.config.mjs` gives both semantic-release plugins a
+  `breakingHeaderPattern`, because the angular preset reads `!` not at all: without that
+  pattern, `feat!: …` parses with no type, and a release made of nothing but such commits
+  is no release.
+- The footer writes the NOTE. The changelog lists a breaking change from the footer alone,
+  so a `!` commit with no footer bumps the major and tells a reader nothing about what
+  broke. Seven commits shipped that way once, and none of them appears in `CHANGELOG.md`.
+
+Write the footer as one paragraph that names the old form and the new one:
+
+```
+refactor(play-actor)!: make the actor contract an interface
+
+BREAKING CHANGE: `AbstractActor` is removed. Use the `PlayActor` interface, and extend
+the actor class of your engine directly.
+```
+
+Keep every other line of the body from starting with a `word: ` prefix. The parser reads
+such a line as a footer token, and a line that opens with "BREAKING CHANGE" inside a
+wrapped paragraph therefore announces a major that nobody intended.
 
 Use the package short-name as scope when the change is isolated to one package:
 

package/contributing/testing.md

@@ -4,7 +4,7 @@ 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:
 
@@ -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` 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.
 
@@ -133,11 +157,38 @@ packages/<name>/
 | `jsdom`                       | UI renderers: `@xmachines/play-react`, `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` 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` 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` 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`.
 - **`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,7 +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 { PlayActor } from "../src/abstract-actor.js";
 import { Signal } from "@xmachines/play-signals";
 ```
 
@@ -235,16 +286,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
@@ -264,22 +312,20 @@ afterEach(() => {
 
 ### 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 { PlayActor } from "@xmachines/play-actor";
+import type { Routable } from "@xmachines/play-router";
 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);
+class MockActor implements PlayActor, Routable {
+	readonly 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;
@@ -297,7 +343,7 @@ 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>({
+	return stubOf<ViewActor>({
 		currentView: new Signal.State<PlaySpec | null>(initialView),
 		send: vi.fn(),
 		start: vi.fn(),
@@ -365,10 +411,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,6 +446,17 @@ 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` 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`, 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:
@@ -448,11 +505,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`, `@xmachines/play-actor`, `@xmachines/play-view`) | 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%        |
+
+`@xmachines/play-router` 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`
 

package/examples/README.md

@@ -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-signals`](../api/@xmachines/play-signals/README.md)      | TC39 Signals polyfill, `watchSignal`                        |
+| [`@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) |