@xmachines/docs 2.2.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
@@ -47,21 +47,22 @@ SEMREL_SKIP_STEPS="@semantic-release/git|@semantic-release/gitlab"
 
 **Location:** `/tsconfig.json`
 
-The root TypeScript config is a **build coordinator only** — it compiles nothing itself. It lists every package and example via `references` so that `tsc --build` can determine the correct build order automatically.
+The root TypeScript config is a **build coordinator only** — it compiles nothing itself. It lists every package and example via `references`, and that array is the whole build order: TypeScript does not inherit `references` through `extends`, so a package declares none of its own. `tests/tsconfig-reference-graph.test.ts` fails when the array misses a project or lists a package before something it imports.
 
 ```json
 {
 	"files": [],
 	"references": [
 		// Layer 0 — no internal deps
-		{ "path": "./packages/play-signals" },
-		{ "path": "./packages/play" },
 		{ "path": "./packages/docs" },
+		{ "path": "./packages/play" },
+		{ "path": "./packages/shared" },
 		// Layer 1 — depends on Layer 0
+		{ "path": "./packages/play-signals" },
+		// Layer 2
 		{ "path": "./packages/play-actor" },
-		// Layer 2 — depends on Layer 0 + 1
-		{ "path": "./packages/play-router" },
-		{ "path": "./packages/play-xstate" }
+		// Layer 3
+		{ "path": "./packages/play-router" }
 		// ...etc.
 	]
 }
@@ -80,7 +81,7 @@ All packages extend this base. Key compiler settings:
 
 | Setting                      | Value        | Notes                                                    |
 | ---------------------------- | ------------ | -------------------------------------------------------- |
-| `target`                     | `ESNext`     | Latest ECMAScript output                                 |
+| `target`                     | `ESNext`     | Latest ECMAScript output. See the two passes below       |
 | `module`                     | `NodeNext`   | ESM with `.js` extension imports required                |
 | `moduleResolution`           | `NodeNext`   | Matches `module` setting                                 |
 | `customConditions`           | `["source"]` | Resolves `@xmachines/*` to TypeScript source in dev/test |
@@ -98,6 +99,31 @@ All packages extend this base. Key compiler settings:
 | `isolatedModules`            | `true`       |                                                          |
 | `removeComments`             | `false`      | Preserves JSDoc in output                                |
 
+**Two passes emit, and `emitDeclarationOnly` decides which one ships.** `build` is
+`vite build && tsc --build`, so tsc runs last.
+
+- **Fourteen publishable packages** let tsc emit JavaScript. tsc overwrites the Vite pass,
+  and `compilerOptions.target` above is what governs the published `dist/*.js`.
+- **Five** — play-vue, play-svelte, play-solid, play-solid-router,
+  play-tanstack-solid-router — set `emitDeclarationOnly`, so tsc emits only `.d.ts` and the
+  Vite pass is the published JavaScript. `build.target` governs theirs.
+
+Vite inherits no target from the tsconfig. It reads `compilerOptions.target` for one
+purpose: to pick the `useDefineForClassFields` default that it gives the transform. The
+syntax level of the Vite pass comes from `build.target`, which
+`packages/shared/config/vite.ts` sets — `"esnext"` for a publishable package, and an
+explicit browser list for a demo app.
+
+Leave both stated, and keep both at ESNext for a library. A package that inherits the Vite
+default builds against a browser baseline, which is a second and lower ceiling than the one
+this table declares — and it is the ceiling that ships for those five.
+
+**A demo states an explicit browser list, and not `baseline-widely-available`.** A target
+controls syntax and adds no method. `baseline-widely-available` of Vite 8 names
+`firefox114`, the demos bundle `play-router`, and `play-router` calls `toSorted()`, which
+shipped in Firefox 115. The list in `vite.ts` therefore raises that one entry, so the
+declared floor is the floor the bundle runs on.
+
 **Per-package `tsconfig.json` pattern:**
 
 ```json
@@ -107,11 +133,12 @@ All packages extend this base. Key compiler settings:
 		"composite": true,
 		"rootDir": "./src",
 		"outDir": "./dist"
-	},
-	"references": [{ "path": "../dependency-package" }]
+	}
 }
 ```
 
+A package declares no `references`. Its dependencies live in `package.json`, and the root array orders the build.
+
 **Test tsconfig (`@xmachines/shared/tsconfig-test`):**
 
 **Location:** `packages/shared/config/tsconfig.test.json`
@@ -154,6 +181,20 @@ export default defineConfig({
 | `typescript/no-explicit-any` | —             | `error`                              |
 | `typescript/no-unused-vars`  | —             | `error` (ignores `_` prefixed names) |
 | `unicorn/filename-case`      | —             | `off`                                |
+| `unicorn/no-array-sort`      | —             | `error`                              |
+| `no-underscore-dangle`       | —             | `off`                                |
+
+`unicorn/no-array-sort` is an error and not the warning of its category. The workspace
+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.
+
+`no-underscore-dangle` is off because it contradicts `typescript/no-unused-vars`, which
+declares `^_` as the mark of a binding that exists on purpose and that nothing reads. A
+`using` declaration is the case that makes the contradiction concrete: the scope reads the
+binding through `Symbol.dispose`, the linter sees no read, and the `_` that answers one rule
+trips the other.
 
 **Per-package override pattern:**
 
@@ -211,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`
@@ -232,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`):
 
@@ -326,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.
 
 ---
 
@@ -344,14 +444,15 @@ The only environment-specific distinction is between **local development** (dev
 
 ## Required vs Optional Settings Summary
 
-| Config                               | Required to Work                      | Optional / Has Default        |
-| ------------------------------------ | ------------------------------------- | ----------------------------- |
-| `SEMREL_SKIP_STEPS`                  | No                                    | Default: `""` (run all steps) |
-| Root `tsconfig.json` `references`    | Yes — must list all packages          | —                             |
-| Per-package `composite: true`        | Yes — required for project references | —                             |
-| `@xmachines/shared/tsconfig` extends | Yes — all packages must extend it     | —                             |
-| `@xmachines/shared/oxlint` extends   | Yes — all packages must extend it     | —                             |
-| `@xmachines/shared/oxfmt` extends    | Yes — all packages must extend it     | —                             |
+| Config                               | Required to Work                        | Optional / Has Default        |
+| ------------------------------------ | --------------------------------------- | ----------------------------- |
+| `SEMREL_SKIP_STEPS`                  | No                                      | Default: `""` (run all steps) |
+| Root `tsconfig.json` `references`    | Yes — the whole build order             | —                             |
+| Per-package `references`             | No — TypeScript drops them on `extends` | —                             |
+| Per-package `composite: true`        | Yes — required for project references   | —                             |
+| `@xmachines/shared/tsconfig` extends | Yes — all packages must extend it       | —                             |
+| `@xmachines/shared/oxlint` extends   | Yes — all packages must extend it       | —                             |
+| `@xmachines/shared/oxfmt` extends    | Yes — all packages must extend it       | —                             |
 
 ---
 

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

@@ -20,7 +20,7 @@ This guide covers everything you need to set up a local development environment,
 
 ### Prerequisites
 
-- **Node.js** `>= 22.0.0`
+- **Node.js** `>= 24.0.0` (the suite writes `using`, which needs V8 13.4)
 - **pnpm** via corepack (`corepack enable`; version pinned by the `packageManager` field — the project uses pnpm workspaces)
 - **Git**
 
@@ -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
@@ -198,52 +216,73 @@ The monorepo uses **TypeScript project references** for correct build-order mana
 
 Packages are grouped into dependency layers as defined in the root `tsconfig.json`:
 
-| Layer | Packages                                                                                                                                                                                                                                                                  | Depends on         |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
-| 0     | `play-signals`, `play`, `docs`                                                                                                                                                                                                                                            | External libs only |
-| 1     | `play-actor`                                                                                                                                                                                                                                                              | Layer 0            |
-| 2     | `play-router`, `play-dom-router`, `play-sveltekit-router`, `play-xstate`, `play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-svelte-spa-router`, `play-tanstack-solid-router` | Layers 0–1         |
-| 3     | `play-react-router`, example demo apps                                                                                                                                                                                                                                    | Layer 2            |
+| Layer | Packages                                                                         | Depends on         |
+| ----- | -------------------------------------------------------------------------------- | ------------------ |
+| 0     | `docs`, `play`, `shared`                                                         | External libs only |
+| 1     | `play-signals`, `play-url`                                                       | Layer 0            |
+| 2     | `play-actor`                                                                     | Layers 0–1         |
+| 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.
 
 #### Mermaid Diagram
 
 ```mermaid
 flowchart LR
-    subgraph L0["Layer 0 — no internal deps"]
-        play-signals
+    subgraph L0["Layer 0 — no workspace deps"]
         play
+        shared
         docs
     end
 
     subgraph L1["Layer 1"]
+        play-signals
+    end
+
+    subgraph L2["Layer 2"]
         play-actor
     end
 
-    subgraph L2["Layer 2 — view renderers & router adapters"]
-        play-router
-        play-dom-router
-        play-sveltekit-router
-        play-xstate
+    subgraph L3["Layer 3 — view renderers, and the router core"]
+        play-dom
         play-react
-        play-vue
+        play-router
         play-solid
         play-svelte
-        play-dom
-        play-tanstack-react-router
-        play-vue-router
-        play-solid-router
-        play-svelte-spa-router
-        play-tanstack-solid-router
+        play-vue
     end
 
-    subgraph L3["Layer 3 — application layer"]
-        play-react-router
-        examples["example demo apps"]
+    subgraph L4["Layer 4"]
+        play-tanstack-router
+        play-xstate
     end
 
-    L0 --> L1
-    L1 --> L2
-    L2 --> L3
+    subgraph L5["Layer 5"]
+        actorshared["play-actor/examples/shared"]
+    end
+
+    subgraph L6["Layer 6"]
+        renderdemos["renderer demo apps"]
+    end
+
+    subgraph L7["Layer 7 — the eight router adapters"]
+        adapters["play-dom-router, play-react-router, play-solid-router,
+        play-svelte-spa-router, play-sveltekit-router,
+        play-tanstack-react-router, play-tanstack-solid-router,
+        play-vue-router"]
+    end
+
+    subgraph L8["Layer 8"]
+        routerdemos["router demo apps"]
+    end
+
+    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8
 ```
 
 ### Adding a New Package
@@ -351,6 +390,8 @@ Active plugins: `typescript`, `unicorn`, `import`. Key rules:
 | `typescript/no-explicit-any` | error                          |
 | `import/no-cycle`            | error                          |
 | `typescript/no-unused-vars`  | error (prefix unused with `_`) |
+| `unicorn/no-array-sort`      | error (use `toSorted()`)       |
+| `no-underscore-dangle`       | off (clashes with `^_` unused) |
 | `correctness` category       | error                          |
 | `suspicious` category        | warn                           |
 
@@ -478,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:
 
@@ -501,7 +564,7 @@ feat(play-react): add PlayRenderer suspense boundary
 
 3. **Write tests** — new code must meet coverage thresholds (80% lines/functions/statements and 75% branches at the monorepo level; core packages enforce higher per-package thresholds)
 4. **Add JSDoc** — all new public exports require JSDoc with `@param`, `@returns`, and `@see` RFC links
-5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `pnpm run docs`
+5. **Never edit `packages/docs/api/`** — API docs are auto-generated; edit source JSDoc and regenerate with `pnpm run docs`. Keep the result out of your branch: the release regenerates and commits it (see [deployment.md](deployment.md)), so a branch that carries its own regeneration churns hundreds of files and conflicts with the next one.
 
 ### Merge Request Checklist