@xmachines/docs 3.0.0 → 5.0.0

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,14 +83,17 @@ 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-actor/                  # Abstract actor base (AbstractActor, Routable, Viewable)
+├── 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)
 ├── 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 +185,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`](../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.
+
+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`](../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.
+
 ---
 
 ## TypeScript Composite Build System
@@ -201,14 +221,15 @@ Packages are grouped into dependency layers as defined in the root `tsconfig.jso
 | Layer | Packages                                                                         | Depends on         |
 | ----- | -------------------------------------------------------------------------------- | ------------------ |
 | 0     | `docs`, `play`, `shared`                                                         | External libs only |
-| 1     | `play-signals`                                                                   | Layer 0            |
-| 2     | `play-actor`                                                                     | Layers 0–1         |
-| 3     | `play-dom`, `play-react`, `play-router`, `play-solid`, `play-svelte`, `play-vue` | Layers 0–2         |
-| 4     | `play-tanstack-router`, `play-xstate`                                            | Layers 0–3         |
-| 5     | `play-actor/examples/shared`                                                     | Layers 0–4         |
-| 6     | renderer demo apps                                                               | Layers 0–5         |
-| 7     | the eight router adapters                                                        | Layers 0–6         |
-| 8     | router demo apps                                                                 | Layers 0–7         |
+| 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         |
 
 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.
 
@@ -223,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"]
+        play-view
     end
 
-    subgraph L3["Layer 3 — view renderers, and the router core"]
+    subgraph L4["Layer 4 — view renderers, and the router core"]
         play-dom
         play-react
         play-router
@@ -239,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
@@ -294,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:
 
@@ -337,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
@@ -357,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
@@ -386,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  |
 | ---------------------------- | ------ |
@@ -447,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
@@ -500,12 +547,34 @@ 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:
 
 ```
-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