@xmachines/docs 4.0.0 → 5.0.1

package/contributing/configuration.md

@@ -58,7 +58,7 @@ The root TypeScript config is a **build coordinator only** — it compiles nothi
 		{ "path": "./packages/play" },
 		{ "path": "./packages/shared" },
 		// Layer 1 — depends on Layer 0
-		{ "path": "./packages/play-signals" },
+		{ "path": "./packages/play-atom" },
 		// Layer 2
 		{ "path": "./packages/play-actor" },
 		// Layer 3
@@ -75,7 +75,7 @@ Every package must be listed here and must have `composite: true` in its own `ts
 ### TypeScript — Shared Base Config (`@xmachines/shared/tsconfig`)
 
 **Location:** `packages/shared/config/tsconfig.json`
-**Exported as:** `@xmachines/shared/tsconfig`
+**Exported as:** [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md)
 
 All packages extend this base. Key compiler settings:
 
@@ -139,7 +139,7 @@ declared floor is the floor the bundle runs on.
 
 A package declares no `references`. Its dependencies live in `package.json`, and the root array orders the build.
 
-**Test tsconfig (`@xmachines/shared/tsconfig-test`):**
+**Test tsconfig ([`@xmachines/shared/tsconfig-test`](../api/@xmachines/shared/README.md)):**
 
 **Location:** `packages/shared/config/tsconfig.test.json`
 
@@ -151,7 +151,7 @@ Test builds add `noEmit: true`, `allowImportingTsExtensions: true`, and `vitest/
 **Tool:** [oxlint](https://oxc.rs/docs/guide/usage/linter) `^1.62.0`
 **Run:** `pnpm run lint` / `pnpm run lint:fix`
 
-The root config extends the shared base (`@xmachines/shared/oxlint`) and adds workspace-level ignore patterns:
+The root config extends the shared base ([`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md)) and adds workspace-level ignore patterns:
 
 ```typescript
 // /oxlint.config.ts
@@ -358,7 +358,7 @@ Run with `pnpm run test:browser`. Uses Playwright Chromium via Vitest browser mo
 ### Per-Package Vitest Config — `@xmachines/shared/vitest`
 
 **Location:** `packages/shared/config/vitest.ts`
-**Exported as:** `@xmachines/shared/vitest`
+**Exported as:** [`@xmachines/shared/vitest`](../api/@xmachines/shared/README.md)
 
 Packages use `defineXmVitestConfig(import.meta.url, overrides)` to create their config. It automatically injects:
 
@@ -383,7 +383,7 @@ export default defineXmVitestConfig(import.meta.url, {
 ### Vite Source Aliases — `@xmachines/shared/vite-aliases`
 
 **Location:** `packages/shared/config/vite-aliases.ts`
-**Exported as:** `@xmachines/shared/vite-aliases`
+**Exported as:** [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md)
 
 Provides two helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 
@@ -444,15 +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 — 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       | —                             |
+| 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`](../api/@xmachines/shared/README.md) extends | Yes — all packages must extend it       | —                             |
+| [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md) extends   | Yes — all packages must extend it       | —                             |
+| [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md) extends    | Yes — all packages must extend it       | —                             |
 
 ---
 

package/contributing/deployment.md

@@ -27,7 +27,7 @@ The following packages are published on every release (derived from the workspac
 | [`@xmachines/shared`](../api/@xmachines/shared/README.md)                                         | `packages/shared`                     |
 | [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | `packages/play`                       |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `packages/play-actor`                 |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)                             | `packages/play-signals`               |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)                                   | `packages/play-atom`                  |
 | [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `packages/play-router`                |
 | [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | `packages/play-dom`                   |
 | [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | `packages/play-dom-router`            |
@@ -70,20 +70,31 @@ The pipeline includes two reusable CI components, both pinned in `.gitlab-ci.yml
 - **`to-be-continuous/node/gitlab-ci-node`** — handles install, lint, build, test, and audit
 - **`to-be-continuous/semantic-release/gitlab-ci-semrel`** — runs `semantic-release` on eligible branches
 
-The `node-build` job runs with:
+The `node-build` job runs one command:
 
 ```bash
 pnpm run build           # vite build (JavaScript) && tsc --build (declarations)
-pnpm run test:coverage   # vitest run --coverage (with JUnit + Cobertura reporters)
 ```
 
-Coverage is extracted from the `node-build` job via the regex:
+It runs no test. The `test` job owns the unit suite, so `node-build` skips its own with `NODE_TEST_ARGS`. It also builds no documentation: the `docs` job below does that.
+
+Coverage comes from the `test` job, through the regex:
 
 ```
 /All files[^|]*\|[^|]*\s+([\d\.]+)/
 ```
 
-JUnit results are published as `reports/junit.xml` and Cobertura coverage as `reports/coverage/cobertura-coverage.xml`.
+That job publishes the JUnit results as `reports/test-results.xml` and the Cobertura coverage as `reports/cobertura-coverage.xml`. `vitest.config.ts` names both paths, and `COVERAGE_REPORTS_DIR` points them at `reports/`.
+
+### 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.
+
+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 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.
 
 ### Release Job Detail
 
@@ -274,6 +285,71 @@ There is no automated rollback mechanism. To revert a release:
 
 ---
 
+## Bootstrapping a New Package
+
+A package that this workspace publishes for the FIRST time needs one manual publish before
+the release, and it is the one publish that a human runs.
+
+The release authenticates to npm through OIDC and carries no static token. npm configures
+a trusted publisher on a package that EXISTS already, and a package exists after its first
+version. A name that npm has never seen therefore takes no publisher, and the release fails
+on that package alone: it publishes the rest, it creates the tag, and it leaves the new
+package missing — the state that [Recovering a Failed Release](#recovering-a-failed-release)
+describes.
+
+Run this from the repository root, when the release is NEAR:
+
+```bash
+# Rehearse it first. It writes a tarball and publishes nothing.
+node scripts/bootstrap-npm-package.mjs --dry-run play-pattern play-atom
+
+node scripts/bootstrap-npm-package.mjs play-pattern play-atom
+```
+
+The script reads the real manifest of each package and publishes ONE version,
+`0.0.0-bootstrap.0`, that holds the name, the metadata that npm shows, and a README that
+says why the version carries no code. The version carries a prerelease identifier, so a
+RANGE of a consumer selects it never. npm asks the maintainer for a one-time password, and
+the script gives npm the terminal to ask on. Pass a code without a terminal through the
+environment: `npm_config_otp=<code> node scripts/bootstrap-npm-package.mjs <package>`.
+
+> **The bootstrap version takes the `latest` dist-tag.** A package takes its `latest` from
+> its FIRST version, whatever `--tag` says, because npm keeps no package without one. The
+> script asks for the `bootstrap` tag and npm sets both, so `npm install @xmachines/<name>`
+> gives the empty version until the real release replaces the tag. This is the second
+> reason to bootstrap a name when the release is NEAR.
+
+The registry also answers for the new package about three minutes after the publish, so a
+read that says "Not found" right after a publish that reported success is that delay.
+
+Then, for EACH package:
+
+1. Open `https://www.npmjs.com/package/<name>/access` and add a trusted publisher:
+
+    | Field         | Value            |
+    | ------------- | ---------------- |
+    | Namespace     | `xmachin-es`     |
+    | Project       | `xmachines-js`   |
+    | Pipeline file | `.gitlab-ci.yml` |
+    | Environment   | none             |
+
+    The publish job declares no environment, so leaving that field set refuses the token.
+
+2. Cut the release, which publishes the real version through OIDC.
+
+3. Unpublish the bootstrap version:
+
+    ```bash
+    npm unpublish @xmachines/<name>@0.0.0-bootstrap.0
+    ```
+
+> **npm accepts an unpublish for 72 HOURS after the publish.** Bootstrap a name when the
+> release is near, and not weeks before it, or the empty version stays on the registry for
+> ever. [`@xmachines/play-url`](../api/@xmachines/play-url/README.md) and [`@xmachines/play-view`](../api/@xmachines/play-view/README.md) were bootstrapped this way for
+> 4.0.0, and each one carries the release version alone today.
+
+---
+
 ## Recovering a Failed Release
 
 If the job dies partway (e.g. one package's trusted publisher isn't set up), some packages are published, the git tag is created, and the rest are missing. To finish the release:
@@ -319,7 +395,7 @@ pnpm --filter @xmachines/play run build
 pnpm --filter @xmachines/play pack
 ```
 
-**Do not run `npm publish` manually.** All publishing must go through semantic-release in CI to keep `CHANGELOG.md`, git tags, and npm versions in sync.
+**Do not run `npm publish` manually.** All publishing must go through semantic-release in CI to keep `CHANGELOG.md`, git tags, and npm versions in sync. [Bootstrapping a New Package](#bootstrapping-a-new-package) is the ONE exception, and it publishes a version that holds no code.
 
 ---
 

package/contributing/development.md

@@ -11,6 +11,7 @@ This guide covers everything you need to set up a local development environment,
 - [TypeScript Composite Build System](#typescript-composite-build-system)
 - [Code Style](#code-style)
 - [Writing Style](#writing-style-asd-ste100)
+- [Link a Package That You Name](#link-a-package-that-you-name)
 - [Branch Conventions](#branch-conventions)
 - [PR Process](#pr-process)
 
@@ -82,8 +83,9 @@ The repository is organized as a **pnpm workspaces** monorepo with all packages
 packages/
 ├── shared/                      # Shared configs (tsconfig, oxlint, oxfmt, vitest)
 ├── play/                        # Core protocol (PlayEvent, PlayError)
-├── play-signals/                # TC39 Signals polyfill wrapper
-├── play-url/                    # The URL language: the grammar, a base path, framework params
+├── play-atom/                   # The atom primitives over @xstate/store
+├── play-pattern/                # The route pattern language: one parse, and the path it builds back
+├── play-url/                    # The URL layer: the URLPattern API, a base path, framework params
 ├── play-actor/                  # The actor contract (PlayActor). It names no engine
 ├── play-view/                   # The shared view half (Viewable, PlaySpec, the view store lifecycle)
 ├── play-xstate/                 # XState v5 adapter (definePlayer, PlayerActor)
@@ -185,17 +187,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` and `@xmachines/play-signals` are a peer of every package that reads them, and a dependency of none.
+[`@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-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-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` 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.
 
 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.
+`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.
 
 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.
 
@@ -219,8 +221,8 @@ 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`, `play-url`                                                       | Layer 0            |
-| 2     | `play-actor`                                                                     | Layers 0–1         |
+| 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         |
@@ -242,14 +244,20 @@ flowchart LR
     end
 
     subgraph L1["Layer 1"]
-        play-signals
+        play-atom
+        play-pattern
     end
 
     subgraph L2["Layer 2"]
         play-actor
+        play-url
     end
 
-    subgraph L3["Layer 3 — view renderers, and the router core"]
+    subgraph L3["Layer 3"]
+        play-view
+    end
+
+    subgraph L4["Layer 4 — view renderers, and the router core"]
         play-dom
         play-react
         play-router
@@ -258,31 +266,31 @@ flowchart LR
         play-vue
     end
 
-    subgraph L4["Layer 4"]
+    subgraph L5["Layer 5"]
         play-tanstack-router
         play-xstate
     end
 
-    subgraph L5["Layer 5"]
+    subgraph L6["Layer 6"]
         actorshared["play-actor/examples/shared"]
     end
 
-    subgraph L6["Layer 6"]
+    subgraph L7["Layer 7"]
         renderdemos["renderer demo apps"]
     end
 
-    subgraph L7["Layer 7 — the eight router adapters"]
+    subgraph L8["Layer 8 — 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"]
+    subgraph L9["Layer 9"]
         routerdemos["router demo apps"]
     end
 
-    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8
+    L0 --> L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8 --> L9
 ```
 
 ### Adding a New Package
@@ -313,15 +321,11 @@ flowchart LR
     }
     ```
 
-    If the package depends on other monorepo packages, add `references`:
-
-    ```json
-    {
-    	"extends": "@xmachines/shared/tsconfig",
-    	"compilerOptions": { "skipLibCheck": true },
-    	"references": [{ "path": "../play" }, { "path": "../play-actor" }]
-    }
-    ```
+    Declare no `references` here. TypeScript does not inherit a `references` array
+    through `extends`, so an array in this file orders nothing: `--showConfig` on the
+    package reports `references: None`. A package declares its dependencies in
+    `package.json`, with a `workspace:*` range, and the root `tsconfig.json` holds the
+    one build order. Step 4 below adds the entry.
 
 3. **`tsconfig.json`** — enable composite build:
 
@@ -356,7 +360,7 @@ All style rules are **mandatory** — CI enforces them on every merge request.
 
 ### Formatter — oxfmt
 
-oxfmt (Biome-based) is configured via `oxfmt.config.ts` at the root (extends `@xmachines/shared/oxfmt`).
+oxfmt (Biome-based) is configured via `oxfmt.config.ts` at the root (extends [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md)).
 
 ```bash
 pnpm run format          # Format all files
@@ -376,7 +380,7 @@ Key settings (from `packages/shared/config/oxfmt.config.ts`):
 
 ### Linter — oxlint
 
-oxlint is configured via `oxlint.config.ts` at the root (extends `@xmachines/shared/oxlint`).
+oxlint is configured via `oxlint.config.ts` at the root (extends [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md)).
 
 ```bash
 pnpm run lint        # Lint all packages
@@ -405,7 +409,7 @@ Active plugins: `typescript`, `unicorn`, `import`. Key rules:
 
 ### TypeScript Strict Mode
 
-All packages extend `@xmachines/shared/tsconfig` which enables full strict mode. Mandatory constraints:
+All packages extend [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md) which enables full strict mode. Mandatory constraints:
 
 | Option                       | Value  |
 | ---------------------------- | ------ |
@@ -466,13 +470,37 @@ The root `AGENTS.md` carries the same rules for AI coding agents.
 
 ---
 
+## Link a Package That You Name
+
+A document that names a package of this workspace links to the page of that package. A reader who meets a package name in the middle of a paragraph needs the page of that package, and a code span gives no way to reach it.
+
+Write the link against the place that holds the document:
+
+| Document                                                     | Link                                   |
+| ------------------------------------------------------------ | -------------------------------------- |
+| `packages/<name>/README.md`                                  | `../<target>/README.md`                |
+| `packages/<name>/examples/<demo>/README.md`                  | `../../../<target>/README.md`          |
+| `packages/docs/{guides,contributing,rfc,examples}/<file>.md` | `../api/@xmachines/<target>/README.md` |
+
+A subpath names the package that holds it, so [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) links to the README of [`@xmachines/play-router`](../api/@xmachines/play-router/README.md).
+
+Three places keep a plain code span:
+
+- A code block. The text is code, and an import specifier is not a reference to follow.
+- A heading. The heading names the section, and the body links the package.
+- The README of the package itself. A page does not link to itself.
+
+`tests/package-mentions-are-linked.test.ts` holds the rule true. It reads every README and every hand-written document of `packages/docs/`, and it fails when a mention carries no link, or when the link names a file that is absent.
+
+---
+
 ## Branch Conventions
 
 Use a `<type>/` prefix that matches the conventional commit type for the work being done:
 
 ```
 feat/vue-router-adapter
-fix/signal-watcher-cleanup
+fix/atom-subscription-cleanup
 docs/play-actor-jsdoc
 chore/update-vitest-4
 refactor/route-map-extraction
@@ -546,7 +574,7 @@ wrapped paragraph therefore announces a major that nobody intended.
 Use the package short-name as scope when the change is isolated to one package:
 
 ```
-fix(play-actor): correct signal cleanup on dispose
+fix(play-actor): correct atom cleanup on dispose
 feat(play-react): add PlayRenderer suspense boundary
 ```
 

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

@@ -0,0 +1,209 @@
+# Migrating to `@xmachines/play-atom`
+
+`@xmachines/play-signals` is gone. [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) replaces it.
+
+The old package wrapped the [TC39 Signals](https://github.com/tc39/proposal-signals) polyfill. The new package re-exports the atom of [`@xstate/store`](https://stately.ai/docs/xstate-store), whose reactive core adapts the [Alien Signals](https://github.com/stackblitz/alien-signals) algorithm.
+
+The two APIs agree on the shape: both read with `get()`, and both write with `set()`. A codemod therefore does most of the work. Three behaviours differ, and no codemod can decide those for you — read [What the codemod cannot do](#what-the-codemod-cannot-do).
+
+---
+
+## Why
+
+Every renderer of this workspace already imported `createAtom` from `@xstate/store`, for the state store of the view. Every application therefore shipped TWO reactive graphs: the Signals polyfill for the actor, the route and the view, and the atom for the view store. The move collapses them into one.
+
+It also drops about 3 KB gzip, and it inherits the diamond fix and the `compare` option that merge request [statelyai/xstate#5250](https://github.com/statelyai/xstate/pull/5250) landed.
+
+---
+
+## Run the codemod
+
+The script travels with the repository, and no package publishes it. Download it first:
+
+```bash
+curl -O https://gitlab.com/xmachin-es/xmachines-js/-/raw/main/scripts/codemod-play-atom.mjs
+```
+
+```bash
+# Look first. It writes nothing.
+node codemod-play-atom.mjs --dry-run .
+
+# Then write.
+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.
+
+It exits non-zero when it finds a site that needs a human, and it names each one.
+
+Install the new package afterwards:
+
+```bash
+pnpm remove @xmachines/play-signals
+pnpm add @xmachines/play-atom @xstate/store
+```
+
+---
+
+## The name table
+
+| `@xmachines/play-signals`                  | [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) |
+| ------------------------------------------ | --------------------------------------------------------------- |
+| `new Signal.State(value)`                  | `createAtom(value)`                                             |
+| `new Signal.Computed(fn)`                  | `createAtom(fn)`                                                |
+| `Signal.State<T>` (type)                   | `Atom<T>`                                                       |
+| `Signal.Computed<T>` (type)                | `ReadonlyAtom<T>`                                               |
+| `SignalState<T>` / `SignalComputed<T>`     | `Atom<T>` / `ReadonlyAtom<T>`                                   |
+| `{ equals }`                               | `{ compare }`                                                   |
+| `SignalOptions<T>` / `ComputedOptions<T>`  | `AtomOptions<T>`                                                |
+| `watchSignal(signal, onValue)`             | `watchAtom(atom, onValue)`                                      |
+| `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                                      |
+| `signal.set(value)`                        | `atom.set(value)`, and `atom.set(fn)`                           |
+
+`createAtom` also accepts a function in `set`, which `Signal.State` did not.
+
+---
+
+## What the codemod cannot do
+
+### 1. A computed atom with a subscriber is EAGER
+
+A TC39 `Signal.Computed` stayed lazy. A watcher notified, and the consumer read the value when it chose to.
+
+`@xstate/store` builds a subscription on an effect that READS the atom. A write to a dependency therefore evaluates the derivation at once, inside that write.
+
+What this changes:
+
+- A derivation runs one time for each write of a dependency, and not one time for each microtask. Keep a derivation cheap, and keep it free of a side effect that must not repeat.
+- `useAtomEffect` of [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) runs your callback from `watchAtom`, which coalesces. Three writes in one tick therefore run the callback ONE time, with the last value, exactly as `useSignalEffect` did. The eagerness above applies to the DERIVATION, and not to your callback.
+
+A computed atom that nobody subscribes to still stays lazy.
+
+**Write ONE atom for each change, and derive the rest.** The library exposes no batching, so every `set` flushes by itself: two writes give two propagations, and an observer that reads both atoms is evaluated in between, on a half-updated pair. The actor of this workspace writes `state` alone for that reason, and `currentRoute` and `currentView` derive from it. If your own code writes two atoms that must agree, make one of them a `createAtom(fn)` over the other.
+
+### 2. The propagation is SYNCHRONOUS, inside `set`
+
+An observer of `subscribe` runs inside the `set` of the atom that changed. An observer that THROWS therefore throws inside that `set`, and the failure lands in the code that wrote the atom — a failure of one view would break the actor for every other observer of it.
+
+Contain it. `watchAtom` does this for you, because it defers the callback to a microtask. `useAtomEffect` catches a throw of a later run and throws it again from a microtask, which reaches the global handler of the runtime.
+
+If you call `subscribe` directly, wrap the body.
+
+**A DERIVATION must contain its own failures.** A subscriber makes a computed atom eager, so the derivation itself runs inside the `set`, before any observer. No subscriber can wrap that, so the rule belongs to the derivation: report through your error channel, and return the previous value. `currentRoute` and `currentView` of the actor both do this, and a release before this one let `currentRoute` throw — which was safe only while the TC39 watcher read it from a microtask.
+
+```typescript
+// A derivation that a subscriber may watch.
+const derived = createAtom((previous) => {
+	try {
+		return expensiveDerivation(source.get());
+	} catch (error) {
+		report(error);
+		return previous ?? null;
+	}
+});
+```
+
+### 3. There is no `untrack`
+
+`@xstate/store` exports no equivalent of `Signal.subtle.untrack`, because it keeps the active subscriber in a variable of its own module.
+
+**Derive the value, and read `previous`.** Almost every `untrack` guarded the same shape: a gate that compares the new value with the last one it emitted. A computed atom is handed that last value, so the gate needs no read and therefore tracks nothing. `withView` of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) is the worked example:
+
+```typescript
+// Before: a written atom, plus untrack to read what it held.
+this.currentView = new Signal.State<View | null>(null);
+const last = Signal.subtle.untrack(() => this.currentView.get());
+if (!equivalent(last, next)) this.currentView.set(next);
+
+// After: a computed atom. `previous` IS what the atom holds.
+this.currentView = createAtom((previous): View | null => {
+	const last = previous ?? null;
+	const next = derive(this.state.get());
+	return equivalent(last, next) ? last : next;
+});
+```
+
+The second form is shorter, and it removes more than the `untrack`: the atom stops being written, so the gate keeps no bookkeeping of its own.
+
+A read that already stands outside every computed atom and every effect tracks nothing, so it needs no wrapper at all.
+
+### 4. `useAtomEffect` takes the sources first
+
+`useSignalEffect(callback, deps)` tracked every signal that its callback read. `useAtomEffect(sources, callback, deps)` tracks the atoms of its FIRST argument, and the callback runs OUTSIDE the tracking scope.
+
+The codemod renames the call, and it cannot write the source list. Add that array yourself, and move the callback one place to the right:
+
+```tsx
+// Before
+useSignalEffect(() => {
+	setView(actor.currentView.get());
+}, [actor]);
+
+// After
+useAtomEffect(
+	[actor.currentView],
+	() => {
+		setView(actor.currentView.get());
+	},
+	[actor],
+);
+```
+
+The list is the reason the hook exists in this form: a callback that reads a view store no longer depends on that store, so a write of the store runs the effect never. Name every atom that must run the effect, and read whatever else you need inside the callback.
+
+---
+
+## Install ONE copy of `@xstate/store`
+
+`@xstate/store` holds the active subscriber in a variable of its own module. Two copies build two separate graphs: a computed atom of the first copy and a subscription of the second copy never meet, the subscriber stays silent, and no error reports the fault.
+
+[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) declares `@xstate/store` as a PEER dependency for this reason. A renderer declares it no more: a renderer reads the atom through [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md), and it imports the engine in no source file. Declare it once in your application, and let every `@xmachines` package resolve to that copy.
+
+Check an install:
+
+```bash
+pnpm why @xstate/store
+```
+
+More than one version in the output is the fault above.
+
+## The engine moved to `@xstate/store` 4
+
+XMachines 5.0.0 declares `@xstate/store` `^4.2.3`, where the release before it declared `^3.17.0`. Install the new major with this release.
+
+One signature changed. A computed getter took a `read` helper in its first position in version 3, and it takes the previous value alone now, because `get` records the dependency by itself. The codemod writes the new form, and a derivation that you wrote by hand needs the first parameter deleted:
+
+```diff
+-const derived = createAtom((_read, previous) => …);
++const derived = createAtom((previous) => …);
+```
+
+`createAsyncAtom` gives its getter an `AbortSignal` now. A getter that needs none takes no parameter, so nothing forces a change.
+
+---
+
+## A type error that names a type you never wrote
+
+```
+Property 'set' is missing in type 'ReadonlyAtom<T>' but required in type 'Atom<T>'
+```
+
+`createAtom` carries two signatures, and TypeScript must prove the argument is not a function before it reaches the writable one. For a concrete type it proves that at once. For a type parameter, or a conditional type over one, it cannot, so it picks the computed signature.
+
+Use `createWritableAtom`, which states the one signature:
+
+```typescript
+import { createWritableAtom } from "@xmachines/play-atom";
+
+this.state = createWritableAtom(this.getSnapshot());
+```
+
+---
+
+## See also
+
+- [Understanding Atoms](../guides/atoms.md) — the concepts, and the invariants
+- [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) — the API reference
+- [Play RFC](../rfc/play.md) — section 5.1.1 defines the reactive substrate