@xmachines/docs 5.0.1 → 6.0.0

package/contributing/architecture.md

@@ -20,21 +20,25 @@ XMachines JS is the JavaScript/TypeScript reference implementation of the **Univ
 
 ```mermaid
 graph TD
-    subgraph Layer0["Layer 0 — Protocol / Primitives"]
+    subgraph Foundation["Foundation"]
+        core["@xmachines/core\n(BaseError, asDisposable, cache)"]
+        shared["@xmachines/shared\n(tsconfig, oxlint, oxfmt)"]
+    end
+
+    subgraph Protocol["Protocol / Primitives"]
         play["@xmachines/play\n(PlayEvent, PlayError)"]
         atoms["@xmachines/play-atom\n(atoms, watchAtom)"]
-        shared["@xmachines/shared\n(tsconfig, oxlint, oxfmt)"]
     end
 
-    subgraph Layer1["Layer 1 — Abstract Actor Base"]
+    subgraph ActorBase["Abstract Actor Base"]
         actor["@xmachines/play-actor\n(PlayActor)"]
     end
 
-    subgraph Layer2v["Layer 2 — The View Half"]
+    subgraph ViewHalf["The View Half"]
         view["@xmachines/play-view\n(Viewable, PlaySpec, the view store lifecycle)"]
     end
 
-    subgraph Layer2["Layer 2 — Concrete Implementations"]
+    subgraph Concrete["Concrete Implementations"]
         xstate["@xmachines/play-xstate\n(PlayerActor, definePlayer, routing)"]
         router["@xmachines/play-router\n(RouterBridgeBase, RouteMap, Routable)"]
         routerxstate["@xmachines/play-router/xstate\n(extractMachineRoutes, createRouteMap)"]
@@ -59,7 +63,7 @@ graph TD
         end
     end
 
-    play --> actor
+    core --> play
     atoms --> actor
     actor --> xstate
     actor --> router
@@ -72,6 +76,8 @@ graph TD
     xstate -.->|"play.route events"| router
 ```
 
+The diagram groups the packages by role. The build order is a separate view: each package sits one layer above its deepest workspace dependency, and [Build Layers](development.md#build-layers) lists them.
+
 ## Component Responsibilities
 
 | Package                                                                                           | Responsibility                                          | Key File                                                            |
@@ -100,6 +106,7 @@ graph TD
 | [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | SvelteKit router bridge                                 | `packages/play-sveltekit-router/src/sveltekit-router-bridge.ts`     |
 | [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | Svelte SPA Router bridge                                | `packages/play-svelte-spa-router/src/svelte-spa-router-bridge.ts`   |
 | [`@xmachines/shared`](../api/@xmachines/shared/README.md)                                         | Shared configs: tsconfig, oxlint, oxfmt, vitest         | `packages/shared/config/`                                           |
+| [`@xmachines/core`](../api/@xmachines/core/README.md)                                             | `BaseError`, the release protocol, a cache, helpers     | `packages/core/src/`                                                |
 | `@xmachines/docs`                                                                                 | API docs and RFC documentation                          | `packages/docs/`                                                    |
 
 ## Data Flow
@@ -213,7 +220,7 @@ type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;
 
 ### [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md)
 
-Base class for all `@xmachines/*` typed runtime errors. Carries `scope` (throwing class/module) and `code` (stable machine-readable identifier, e.g. `"PLAY_ROUTER_SYNC_FAILED"`). Subclassed per package, exported from each package's `./errors` subpath. Never match on `.message` — always match on `.code` or the subclass.
+Base class for the typed runtime errors of every Play package. It extends [`BaseError`](../api/@xmachines/core/errors/classes/BaseError.md) of [`@xmachines/core/errors`](../api/@xmachines/core/README.md). Carries `scope` (throwing class/module) and `code` (stable machine-readable identifier, e.g. `"PLAY_ROUTER_SYNC_FAILED"`). Subclassed per package, exported from each package's `./errors` subpath. Never match on `.message` — always match on `.code` or the subclass.
 
 ```typescript
 import { PlayError } from "@xmachines/play/errors";
@@ -306,7 +313,7 @@ interface PlayRouteEvent {
 
 ### [`watchAtom(atom, callback)`](../api/@xmachines/play-atom/functions/watchAtom.md)
 
-Subscribe to a single atom with microtask coalescing and memory-safe cleanup. It builds one `subscribe` for the life of the watch, so no code arms anything again. The `disposed` flag guards post-cleanup callbacks, and the `scheduled` guard deduplicates rapid synchronous atom changes. Returns a `Cleanup` function.
+Subscribe to a single atom with microtask coalescing and memory-safe cleanup. It builds one `subscribe` for the life of the watch, so no code arms anything again. The `disposed` flag guards post-cleanup callbacks, and the `scheduled` guard deduplicates rapid synchronous atom changes. Returns a plain release function.
 
 ### [`formatPlayRouteTransitions(machineConfig)`](../api/@xmachines/play-xstate/with-routing/functions/formatPlayRouteTransitions.md)
 
@@ -368,22 +375,23 @@ Each adapter also exports a framework-integrated provider component (e.g. `PlayR
 ```
 packages/
 ├── shared/                     # Zero-dependency shared configs (tsconfig, oxlint, oxfmt, vitest)
-├── play/                       # Layer 0: Core protocol: PlayEvent, PlayError, assertNonNullable
-├── play-atom/                  # Layer 1: the atom primitives — all atom imports go here
+├── core/                       # Layer 0: BaseError, the release protocol, the cache, helpers; no module state
+├── play/                       # Layer 1: Core protocol: PlayEvent, PlayError, assertNonNullable
+├── play-atom/                  # Layer 0: the atom primitives — all atom imports go here
 │   └── src/                    # Declares the atom contract, binds the engine; watchAtom utility
-├── play-actor/                 # Layer 2: the PlayActor contract — state and send, and nothing else
+├── play-actor/                 # Layer 1: the PlayActor contract — state and send, and nothing else
 ├── play-pattern/               # Layer 1: the route pattern language — one parse, and the path it builds back
 ├── play-url/                   # Layer 2: the URL layer — the URLPattern API, a base path, framework params
-├── play-view/                  # Layer 3: Viewable, PlaySpec, the view store lifecycle, the context projection
+├── play-view/                  # Layer 2: Viewable, PlaySpec, the view store lifecycle, the context projection
 │
-├── play-xstate/                # Layer 5: Concrete XState v5 actor: definePlayer, PlayerActor
+├── play-xstate/                # Layer 4: Concrete XState v5 actor: definePlayer, PlayerActor
 │   └── src/
 │       ├── player-actor.ts              # PlayerActor — concrete actor
 │       ├── define-player.ts             # definePlayer factory
 │       ├── routing/                     # deriveRoute, buildRouteUrl, formatPlayRouteTransitions
 │       └── view/                        # deriveCurrentView (meta.view → PlaySpec)
 │
-├── play-router/                # Layer 4: Route extraction, bidirectional mapping, bridge base
+├── play-router/                # Layer 3: Route extraction, bidirectional mapping, bridge base
 │   └── src/
 │       ├── router-bridge-base.ts        # RouterBridgeBase (Template Method for all adapters)
 │       ├── base-route-map.ts            # RouteMap (bidirectional stateId ↔ path)
@@ -439,14 +447,15 @@ With `declarationMap: true` in the base tsconfig (from [`@xmachines/shared/tscon
 
 **Dependency rules:**
 
-The **protocol layer** is `play`, `play-atom` and `play-actor`. The three form a chain — `play-atom` reads `play`, and `play-actor` reads `play-atom` — and none of them reads a package below.
+The **protocol layer** is `play`, `play-atom` and `play-actor`. `play` reads `core` alone, for the base of `PlayError`. `play-atom` reads no workspace package. `play-actor` reads `play-atom`, and no other package of the workspace.
 
 | Layer                                 | May import from                                         | Must not import from             |
 | ------------------------------------- | ------------------------------------------------------- | -------------------------------- |
-| Protocol (`play`)                     | External libs only                                      | Any other `@xmachines/*` package |
-| Protocol (`play-atom`)                | `play`, `@xstate/store`                                 | Any other `@xmachines/*` package |
-| Protocol (`play-actor`)               | `play`, `play-atom`                                     | Any other `@xmachines/*` package |
-| Pattern language (`play-pattern`)     | External libs only                                      | Any other `@xmachines/*` package |
+| Core (`core`)                         | No package                                              | Any `@xmachines/*` package       |
+| Protocol (`play`)                     | `core`                                                  | Any other `@xmachines/*` package |
+| Protocol (`play-atom`)                | `@xstate/store`                                         | Any other `@xmachines/*` package |
+| Protocol (`play-actor`)               | `play-atom`                                             | Any other `@xmachines/*` package |
+| Pattern language (`play-pattern`)     | `core`                                                  | Any other `@xmachines/*` package |
 | URL layer (`play-url`)                | Protocol layer, `play-pattern`, `urlpattern-polyfill`   | Any other `@xmachines/*` package |
 | View half (`play-view`)               | Protocol layer, `@xmachines/json-render-core`           | Router adapters, framework code  |
 | Actor logic (`play-xstate`)           | Protocol layer, `play-pattern`, `xstate`                | View renderers, router adapters  |
@@ -454,20 +463,26 @@ The **protocol layer** is `play`, `play-atom` and `play-actor`. The three form a
 | Router adapters (`play-*-router`)     | `play-router`, protocol layer, framework router lib     | View renderers                   |
 | View renderers (`play-*`)             | Protocol layer, `play-view`, `@xmachines/json-render-*` | Router adapters                  |
 
+Every layer above the protocol layer may also import [`@xmachines/core`](../api/@xmachines/core/README.md), and `play` imports it for `BaseError`. It is a peer, and not a dependency: `err instanceof BaseError` answers `false` for an error of a second copy, so an install must hold one copy. See [the packages that must exist one time](development.md#the-packages-that-must-exist-one-time).
+
 `play-view` and `play-router` are OPTIONAL peer dependencies of `play-xstate`, because the two capability subpaths carry them: [`@xmachines/play-xstate/view`](../api/@xmachines/play-xstate/README.md) names the first and [`@xmachines/play-xstate/routing`](../api/@xmachines/play-xstate/README.md) names the second. The core entry point imports neither.
 
 ## Error Handling
 
-All `@xmachines/*` errors extend [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md) and carry two stable fields:
+All `@xmachines/*` errors extend [`BaseError`](../api/@xmachines/core/errors/classes/BaseError.md) of [`@xmachines/core/errors`](../api/@xmachines/core/README.md), and carry two stable fields:
 
 - `scope` — the class or module that threw (e.g. `"RouterBridgeBase"`)
 - `code` — a stable machine-readable identifier (e.g. `"PLAY_ROUTER_SYNC_FAILED"`)
 
+Every error of a Play package extends [`PlayError`](../api/@xmachines/play/errors/classes/PlayError.md), which extends `BaseError`. A package below the Play protocol extends `BaseError` directly: [`@xmachines/core`](../api/@xmachines/core/README.md) throws `DisposeConflictError` when `asDisposable` receives a named release that the scope would never run.
+
 **Error hierarchy:**
 
 ```mermaid
 flowchart TD
-    PE["PlayError\n@xmachines/play/errors"]
+    BE["BaseError\n@xmachines/core/errors"]
+    BE --> DCE["DisposeConflictError\nCORE_DISPOSE_CONFLICT"]
+    BE --> PE["PlayError\n@xmachines/play/errors"]
     PE --> NNE["NonNullableError\nPLAY_NON_NULLABLE"]
     PE --> RSE["RouterSyncError\nPLAY_ROUTER_SYNC_FAILED"]
     PE --> DBE["DuplicateBridgeError\nPLAY_ROUTER_DUPLICATE_BRIDGE"]

package/contributing/configuration.md

@@ -54,13 +54,15 @@ The root TypeScript config is a **build coordinator only** — it compiles nothi
 	"files": [],
 	"references": [
 		// Layer 0 — no internal deps
+		{ "path": "./packages/core" },
 		{ "path": "./packages/docs" },
-		{ "path": "./packages/play" },
+		{ "path": "./packages/play-atom" },
 		{ "path": "./packages/shared" },
 		// Layer 1 — depends on Layer 0
-		{ "path": "./packages/play-atom" },
-		// Layer 2
+		{ "path": "./packages/play" },
 		{ "path": "./packages/play-actor" },
+		// Layer 2
+		{ "path": "./packages/play-view" },
 		// Layer 3
 		{ "path": "./packages/play-router" }
 		// ...etc.
@@ -425,8 +427,8 @@ 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`
-    - `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
+    - `stage-generated-docs` — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`, so a page that TypeDoc deleted leaves git too
+5. `@semantic-release/git` — commits the changelog, the manifests, the READMEs and the generated docs (`api/`, `examples/@xmachines/` and the demo lists of `examples/README.md`), 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.
 

package/contributing/deployment.md

@@ -88,13 +88,27 @@ That job publishes the JUnit results as `reports/test-results.xml` and the Cober
 
 ### Docs Job
 
-The `docs` job runs `pnpm run docs` — the full build, then TypeDoc, then the formatter. It runs automatically on `main` and it waits for a click on a merge request. It declares `needs: []`, because it compiles what it documents.
+The `docs` job runs `pnpm run docs` — the full build, then TypeDoc, then the formatter. It runs automatically on `main` and on the merge train, and it waits for a click on a merge request. It declares `needs: []`, because it compiles what it documents.
 
 TypeDoc treats a warning as an error. This job is therefore the gate that reports a `@see` or a `{@link}` that names a symbol a rename removed. Before it existed, `node-build` regenerated the reference on every push, which put a second pass over every package on a branch that is pushed to many times.
 
-The click is a gate, not an option. The job is manual with `allow_failure: false`, so a pipeline that nobody starts it from stays BLOCKED, and the merge check "Pipelines must succeed" holds the merge request. The `release-pack-smoke` job below uses the same rules for the same reason.
+The click blocks nothing on a merge request. The merge train starts the job by itself, so the train is the gate. The `release-pack-smoke` job below uses the same rules for the same reason.
 
-The job declares `stage: test`. A blocking manual job holds every later stage until it runs, so `build` would keep the unit suite, the browser suite and `release-pack-smoke` waiting for a click. Jobs in the same stage are not affected.
+The job declares `stage: test`. A manual job that blocks holds every later stage until it runs, so `build` would keep the unit suite, the browser suite and `release-pack-smoke` waiting for a click. Jobs in the same stage are not affected.
+
+The job archives the two trees that TypeDoc writes as `reports/docs-reference.tar.gz`, and it keeps the archive as an artifact.
+
+### Docs Links Job
+
+The `test:docs` job crawls the reference that the `docs` job generated. It declares `needs: [docs]`, so it starts when `docs` passes. On a merge request it shows `skipped` until someone starts `docs`.
+
+The crawl is `packages/docs/test-generated/links.test.mjs`. It follows every relative link of `api/` and `examples/@xmachines/`, and it checks the file and the anchor of each link. TypeDoc cannot hold this rule: the `routeOutput` plugin moves a demo package to the examples tree after the link validator runs. The job publishes the result as a JUnit report.
+
+The job deletes both trees before it unpacks the archive. GitLab unpacks an artifact over the checkout and deletes no file, and the checkout holds the reference of the last release. Without the delete, a page that TypeDoc no longer writes stays in the checkout, and the crawl reads its links.
+
+The job has the rules of `docs` without the click. A job that needs a job which is absent from the pipeline fails the creation of the pipeline, so the two sets of rules must match. `tests/docs-ci-jobs.test.ts` holds the list of trees equal to the list that the release stages.
+
+To run the same check on your machine, run `pnpm run docs` and then `pnpm run test:docs`.
 
 ### Release Job Detail
 
@@ -166,7 +180,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
+git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md
 ```
 
 Step by step:
@@ -175,9 +189,9 @@ Step by step:
 2. **Install** — `pnpm install --frozen-lockfile` installs the exact dependency versions recorded in the lockfile.
 3. **Sync versions** — `scripts/set-workspace-versions.mjs` sets the same release version across every `package.json` in the workspace (root + all packages), including cross-package workspace dependency ranges.
 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.
+5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` and `packages/docs/examples/@xmachines/` at the release git revision. TypeDoc also rewrites the demo lists of `packages/docs/examples/README.md`.
 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.
+7. **Stage the generated docs** — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`. 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
 
@@ -202,6 +216,8 @@ This phase runs on the branch, BEFORE the tag pipeline publishes.
     - `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)
+    - `packages/docs/examples/@xmachines/**` (generated demo documentation)
+    - `packages/docs/examples/README.md` (TypeDoc rewrites its demo lists)
 
     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.
 
@@ -257,7 +273,7 @@ dist/releases/*.tgz
 
 The same tarballs are attached to the GitLab Release entry as permanent downloadable assets. Tarballs are **not committed** to git (the `dist/` directory is gitignored).
 
-The API documentation (`packages/docs/api/`) **is committed** to git by the post-release git commit and is the only generated artifact tracked in version control.
+The post-release git commit **commits** the generated documentation (`packages/docs/api/` and `packages/docs/examples/@xmachines/`) to git. The same commit holds the demo lists that TypeDoc writes into the hand-written `packages/docs/examples/README.md`. It also holds `CHANGELOG.md`, which `@semantic-release/changelog` writes.
 
 ---
 

package/contributing/development.md

@@ -82,6 +82,7 @@ The repository is organized as a **pnpm workspaces** monorepo with all packages
 ```
 packages/
 ├── shared/                      # Shared configs (tsconfig, oxlint, oxfmt, vitest)
+├── core/                        # BaseError, the release protocol, the cache, small helpers
 ├── play/                        # Core protocol (PlayEvent, PlayError)
 ├── play-atom/                   # The atom primitives over @xstate/store
 ├── play-pattern/                # The route pattern language: one parse, and the path it builds back
@@ -145,6 +146,7 @@ All commands are run from the **repository root** unless otherwise noted.
 | `pnpm run format`                          | Format all files with oxfmt                                               |
 | `pnpm run format:check`                    | Check formatting (CI mode — no writes)                                    |
 | `pnpm run docs`                            | Build packages, generate TypeDoc API docs, then format                    |
+| `pnpm run test:docs`                       | Check every link of the generated docs (run `pnpm run docs` first)        |
 
 ---
 
@@ -187,17 +189,17 @@ React 18 and vue-router 4 are supported by intent — nothing known depends on 1
 
 ### The packages that must exist one time
 
-[`@xmachines/play`](../api/@xmachines/play/README.md) and [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) are a peer of every package that reads them, and a dependency of none.
+[`@xmachines/core`](../api/@xmachines/core/README.md), [`@xmachines/play`](../api/@xmachines/play/README.md) and [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) are a peer of every package that reads them, and a dependency of none.
 
 [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) re-exports the atom of `@xstate/store`, and that library holds the active subscriber in a variable of its own module. Two copies build two graphs. A computed atom of the first copy and a subscription of the second copy therefore never meet: the subscriber stays silent, and no error reports the fault. Every propagation of state in this architecture goes through an atom, so the second copy stops the reactivity of a whole application.
 
-[`@xmachines/play`](../api/@xmachines/play/README.md) holds `PlayError`, and the documentation sends a consumer to `err instanceof PlayError`. That check answers `false` for an error of the second copy.
+[`@xmachines/play`](../api/@xmachines/play/README.md) holds `PlayError`, and the documentation sends a consumer to `err instanceof PlayError`. That check answers `false` for an error of the second copy. [`@xmachines/core`](../api/@xmachines/core/README.md) holds `BaseError`, the base of `PlayError`, and `err instanceof BaseError` fails in the same way.
 
 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.
+Each of the three 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`](../api/@xmachines/play-tanstack-router/README.md) is that case.
+`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 three in its TESTS alone needs the dev entry alone — [`@xmachines/play-tanstack-router`](../api/@xmachines/play-tanstack-router/README.md) 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.
 
@@ -220,16 +222,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-atom`, `play-pattern`                                                      | Layer 0            |
-| 2     | `play-actor`, `play-url`                                                         | 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         |
+| 0     | `core`, `docs`, `play-atom`, `shared`                                            | External libs only |
+| 1     | `play`, `play-actor`, `play-pattern`                                             | Layer 0            |
+| 2     | `play-url`, `play-view`                                                          | 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         |
 
 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.
 
@@ -238,26 +239,24 @@ The layer of an entry is its longest path to a package with no workspace depende
 ```mermaid
 flowchart LR
     subgraph L0["Layer 0 — no workspace deps"]
-        play
+        core
+        play-atom
         shared
         docs
     end
 
     subgraph L1["Layer 1"]
-        play-atom
+        play
+        play-actor
         play-pattern
     end
 
     subgraph L2["Layer 2"]
-        play-actor
         play-url
-    end
-
-    subgraph L3["Layer 3"]
         play-view
     end
 
-    subgraph L4["Layer 4 — view renderers, and the router core"]
+    subgraph L3["Layer 3 — view renderers, and the router core"]
         play-dom
         play-react
         play-router
@@ -266,31 +265,31 @@ flowchart LR
         play-vue
     end
 
-    subgraph L5["Layer 5"]
+    subgraph L4["Layer 4"]
         play-tanstack-router
         play-xstate
     end
 
-    subgraph L6["Layer 6"]
+    subgraph L5["Layer 5"]
         actorshared["play-actor/examples/shared"]
     end
 
-    subgraph L7["Layer 7"]
+    subgraph L6["Layer 6"]
         renderdemos["renderer demo apps"]
     end
 
-    subgraph L8["Layer 8 — the eight router adapters"]
+    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 L9["Layer 9"]
+    subgraph L8["Layer 8"]
         routerdemos["router demo apps"]
     end
 
-    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8 --> L9
+    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8
 ```
 
 ### Adding a New Package

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

@@ -32,7 +32,7 @@ node codemod-play-atom.mjs --dry-run .
 node codemod-play-atom.mjs .
 ```
 
-The codemod reads `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.vue`, `.svelte`, `.md` and `.json`, so it covers a manifest and a single-file component too. It skips `node_modules`, `dist`, `coverage` and every generated API directory.
+The codemod reads `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.vue`, `.svelte`, `.md` and `.json`, so it covers a manifest and a single-file component too. It skips `node_modules`, `dist`, `coverage` and every directory of generated documentation.
 
 It exits non-zero when it finds a site that needs a human, and it names each one.
 
@@ -57,6 +57,7 @@ pnpm add @xmachines/play-atom @xstate/store
 | `{ equals }`                               | `{ compare }`                                                   |
 | `SignalOptions<T>` / `ComputedOptions<T>`  | `AtomOptions<T>`                                                |
 | `watchSignal(signal, onValue)`             | `watchAtom(atom, onValue)`                                      |
+| `Cleanup` (type)                           | `() => void` — the codemod reports it, and rewrites it not      |
 | `useSignalEffect(cb, deps)` (`play-react`) | `useAtomEffect(sources, cb, deps)`                              |
 | `Signal.subtle.Watcher`                    | `atom.subscribe(fn)`, or `watchAtom`                            |
 | `Signal.subtle.untrack(fn)`                | — no equivalent. See below                                      |

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

@@ -35,7 +35,7 @@ Then open `http://localhost:3000`.
 
 Use this order to understand the implementation:
 
-1. `src/main.ts` creates the page's inspector with `createDemoInspector()`, calls `definePlayer({ machine: authMachine, options: { inspect: inspector.inspect } })`, and starts the actor.
+1. `src/main.ts` creates the page's inspector with `createDemoInspector()`, calls `definePlayer({ machine: authMachine, options: { inspect: inspector.inspect }, actor: compose(PlayerActor, withRouting, withView) })`, and starts the actor.
 2. `initShell(actor, app, inspector)` from `src/components/Shell.ts` builds the HTML scaffold, mounts a reactive `NavBar`, wires the debug panel, and returns a disconnect function.
 3. `defineRegistry(authCatalog, { components, actions })` builds the typed `registryResult` — real async action handlers dispatching to `actor.send()`.
 4. `createPlayUI(registryResult)` produces a `mount` function; `mount(actor, container)` wires the registry to the actor — view switches happen automatically when `actor.currentView` changes.
@@ -49,6 +49,7 @@ const inspector = createDemoInspector();
 const createPlayer = definePlayer({
 	machine: authMachine,
 	options: { inspect: inspector.inspect },
+	actor: compose(PlayerActor, withRouting, withView),
 });
 const actor = createPlayer();
 actor.start();
@@ -56,6 +57,9 @@ actor.start();
 const app = document.getElementById("app");
 if (!app) throw new Error("Root element not found");
 
+// The shell and the actor live as long as the page, so the demo never tears them down:
+// the browser frees them with the page. `initShell` returns a disconnect function for a
+// host that removes the shell before the page ends, and the browser tests call it.
 initShell(actor, app, inspector);
 ```
 
@@ -103,7 +107,7 @@ This demo follows the canonical watcher lifecycle:
 2. `watchAtom` queues one microtask, and it drops each duplicate notification of that batch
 3. The microtask reads the actor atoms and projects DOM state
 
-One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: `disconnectNavBar()`, `disconnectRenderer()`, and `disconnectDebugPanel()` are all called from the disconnect function returned by `initShell`. In this demo, cleanup is called on `beforeunload` via `actor.stop()`.
+One subscription lives for the whole watch, and no caller arms a watcher again. Cleanup is explicit: the disconnect function that `initShell` returns calls `disconnectNavBar()`, `disconnectRenderer()`, and `disconnectDebugPanel()`. This demo does not call that function at the end of the page, because the browser frees the page. The browser tests call it, and then they call `actor.stop()`. Do not tear down on `beforeunload`: that event also fires when the page goes into the back/forward cache, and Back then shows a page that does not respond.
 
 ## Adapter Boundaries
 

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

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

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

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

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

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

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

@@ -6,7 +6,7 @@
 function initShell(actor, appElement, inspector): () => void;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
+Defined in: [packages/play-dom/examples/demo/src/components/Shell.ts:18](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Shell.ts#L18)
 
 Shell — DOM shell layout factory. Renders demo chrome (header + main +
 debug panel), mounts NavBar, connects DOM renderer, and wires DebugPanel.

package/examples/@xmachines/play-dom-demo/type-aliases/AuthCatalog.md

@@ -6,4 +6,4 @@
 type AuthCatalog = typeof authCatalog;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/catalog.ts#L6)
+Defined in: [packages/play-dom/examples/demo/src/catalog.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/catalog.ts#L6)

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

@@ -6,7 +6,7 @@
 const About: ComponentFn<AuthCatalog, "About">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/About.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/About.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/About.ts#L8)
 
 About — Public information page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'About'>). Renders static content from props.

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

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

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

@@ -6,7 +6,7 @@
 const Contact: ComponentFn<AuthCatalog, "Contact">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
+Defined in: [packages/play-dom/examples/demo/src/components/Contact.ts:8](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Contact.ts#L8)
 
 Contact — Public contact page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Contact'>). Renders static content from props.

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

@@ -6,7 +6,7 @@
 const Dashboard: ComponentFn<AuthCatalog, "Dashboard">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Dashboard.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Dashboard.ts#L9)
 
 Dashboard — Protected authenticated home. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Dashboard'>). Renders welcome message; logout

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

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

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

@@ -6,7 +6,7 @@
 const Home: ComponentFn<AuthCatalog, "Home">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/Home.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Home.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Home.ts#L9)
 
 Home — Public landing page. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Home'>). Renders static welcome content from

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

@@ -6,7 +6,7 @@
 const Login: ComponentFn<AuthCatalog, "Login">;
 ```
 
-Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v5.0.1/packages/play-dom/examples/demo/src/components/Login.ts#L9)
+Defined in: [packages/play-dom/examples/demo/src/components/Login.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v6.0.0/packages/play-dom/examples/demo/src/components/Login.ts#L9)
 
 Login — Authentication form. Catalog-typed DOM component
 (ComponentFn<AuthCatalog, 'Login'>). Binds username input to ctx.store via