@xmachines/docs 4.0.0 → 5.0.0

package/contributing/testing.md

@@ -6,11 +6,11 @@ This document describes the test framework, conventions, and CI integration for
 
 The monorepo uses **[Vitest](https://vitest.dev/) `^5.0.1`** as its test framework, with **@vitest/coverage-v8** for coverage reporting and **@vitest/browser-playwright** (Playwright/Chromium) for browser-mode tests.
 
-All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from `@xmachines/shared/vitest`) which automatically applies:
+All packages extend the shared Vitest configuration helper `defineXmVitestConfig` (from [`@xmachines/shared/vitest`](../api/@xmachines/shared/README.md)) which automatically applies:
 
 - `@xmachines/*` source aliases so imports resolve to source during test runs
-- `@xmachines/shared/vitest-setup` — extends Vitest matchers with `@testing-library/jest-dom`
-- `@xmachines/shared/vitest-node-setup` — enforces Node.js ≥ 24 on non-browser projects
+- [`@xmachines/shared/vitest-setup`](../api/@xmachines/shared/README.md) — extends Vitest matchers with `@testing-library/jest-dom`
+- [`@xmachines/shared/vitest-node-setup`](../api/@xmachines/shared/README.md) — enforces Node.js ≥ 24 on non-browser projects
 
 **Auto-injected setup files:**
 
@@ -19,7 +19,7 @@ All packages extend the shared Vitest configuration helper `defineXmVitestConfig
 | `packages/shared/config/vitest.node.setup.ts` | All non-browser projects | Validates Node.js ≥ 24 runtime; throws if wrong runtime |
 | `packages/shared/config/vitest.setup.ts`      | All projects             | Imports `@testing-library/jest-dom/vitest` matchers     |
 
-`vitest.setup.ts` is also the one file that `@xmachines/shared/tsconfig-test` names in `files`, so its import puts the matcher TYPES in every test program. Each package overrides `include`, and `files` survives that.
+`vitest.setup.ts` is also the one file that [`@xmachines/shared/tsconfig-test`](../api/@xmachines/shared/README.md) names in `files`, so its import puts the matcher TYPES in every test program. Each package overrides `include`, and `files` survives that.
 
 ### The jest-dom patch
 
@@ -141,21 +141,21 @@ packages/<name>/
 
 ### File naming conventions
 
-| Extension                                | Purpose                                                                                                                                 |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `.spec.ts`                               | Protocol enforcement tests; compile-time type safety tests; used in core packages (`play`, `play-actor`, `play-signals`, `play-xstate`) |
-| `.test.ts`                               | Unit, integration, and behavioral tests; used across all packages                                                                       |
-| `.browser.test.ts` / `.browser.test.tsx` | Playwright browser environment tests; excluded from standard `vitest.config.ts`, only run via `vitest.browser.config.ts`                |
-| `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `pnpm run test:build`                                       |
-| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                     |
+| Extension                                | Purpose                                                                                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `.spec.ts`                               | Protocol enforcement tests; compile-time type safety tests; used in core packages (`play`, `play-actor`, `play-atom`, `play-xstate`) |
+| `.test.ts`                               | Unit, integration, and behavioral tests; used across all packages                                                                    |
+| `.browser.test.ts` / `.browser.test.tsx` | Playwright browser environment tests; excluded from standard `vitest.config.ts`, only run via `vitest.browser.config.ts`             |
+| `.typecheck.ts` (in `src/`)              | Compile-time-only type assertion files; not Vitest test files; validated by `pnpm run test:build`                                    |
+| `router-bridge-contract.ts`              | Shared contract test runner; not a test file itself; imported by adapter test files                                                  |
 
 ### Test environments
 
-| Environment                   | Packages                                                                                                   |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `node`                        | Core logic: `@xmachines/play`, `play-actor`, `play-signals`, `play-xstate`, `play-router`, router adapters |
-| `jsdom`                       | UI renderers: `@xmachines/play-react`, `play-vue`, `play-solid`, `play-svelte`, `play-dom`                 |
-| Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                        |
+| Environment                   | Packages                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node`                        | Core logic: [`@xmachines/play`](../api/@xmachines/play/README.md), `play-actor`, `play-atom`, `play-xstate`, `play-router`, router adapters |
+| `jsdom`                       | UI renderers: [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), `play-vue`, `play-solid`, `play-svelte`, `play-dom`        |
+| Browser (Playwright/Chromium) | Browser-specific and E2E demo tests                                                                                                         |
 
 `defineXmVitestConfig` gives a jsdom project the `vmThreads` pool. The `forks` pool builds one jsdom for each test file, and a jsdom costs about 0.4 s. The `vmThreads` pool gives each file its own VM context in a worker that keeps the environment, so a worker builds one jsdom for all the files that it runs. Each file still gets a fresh module registry and fresh globals. The full `pnpm test` run takes 94 s with `vmThreads` and 160 s with `forks`, and the environment share of the tracked time drops from 42% to 14%.
 
@@ -167,15 +167,15 @@ A project that declares its own `pool` keeps it.
 
 Isolation gives each test FILE its own worker: Vitest spawns a process, builds the environment, and evaluates the module graph one more time. That costs about 110 ms for each file, and the full `pnpm test` run takes 90 s with isolation on every project and 62 s with this rule.
 
-A jsdom project keeps isolation and loses no time by it, because `vmThreads` above already gives one worker to many files. It also needs isolation: `isolate: false` shares the globals between the files of one worker, and three `@xmachines/play-react` tests fail under it.
+A jsdom project keeps isolation and loses no time by it, because `vmThreads` above already gives one worker to many files. It also needs isolation: `isolate: false` shares the globals between the files of one worker, and three [`@xmachines/play-react`](../api/@xmachines/play-react/README.md) tests fail under it.
 
-A worker that runs without isolation keeps ONE module registry for all the files that it runs, so `vi.mock` applies only while the worker has not yet loaded the real module. The order that the pool picks decides the winner, and the suite then fails on some runs and passes on others. `@xmachines/play-router` showed it: one file mocked `machine-to-graph.js` while twenty-five sibling files called the real module, and the package failed three tests on one run of the whole suite and twenty-five on the next. The file now builds a real machine, the package needs no isolation, and it runs in 1.0 s rather than 5.4 s.
+A worker that runs without isolation keeps ONE module registry for all the files that it runs, so `vi.mock` applies only while the worker has not yet loaded the real module. The order that the pool picks decides the winner, and the suite then fails on some runs and passes on others. [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) showed it: one file mocked `machine-to-graph.js` while twenty-five sibling files called the real module, and the package failed three tests on one run of the whole suite and twenty-five on the next. The file now builds a real machine, the package needs no isolation, and it runs in 1.0 s rather than 5.4 s.
 
 **A project whose test files call `vi.mock`, `vi.doMock`, `vi.stubGlobal`, or `vi.stubEnv` declares `isolate: true` in its own `vitest.config.ts`, with the reason.** `tests/isolate-policy.test.ts` holds this rule true: it asks `vitest list` which project collects which file, reads `isolate` from the config module, and names the file and the config when the two disagree. The scan follows the relative imports of each test file and reads the setup files of the project, so a fixture that mocks a module cannot hide, and it reads each `@vitest-environment` docblock, which reaches no config. Two projects declare it today: the `play-sveltekit-router` demo, which mocks `$app/navigation`, and the `play-actor` shared example, which stubs `window`.
 
 Prefer the other answer where you can reach it. A test that builds the real collaborator needs no isolation, and it costs the whole project nothing.
 
-A project that gives SOME of its files another environment isolates for the same reason. Vitest builds and tears down that environment inside a worker that keeps its module registry, so a module evaluated against the jsdom of one file stays cached for the next one and holds a `window` that no longer exists. `@xmachines/play-react-router` runs three React files that way.
+A project that gives SOME of its files another environment isolates for the same reason. Vitest builds and tears down that environment inside a worker that keeps its module registry, so a module evaluated against the jsdom of one file stays cached for the next one and holds a `window` that no longer exists. [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md) runs three React files that way.
 
 A spy needs no isolation, and neither do fake timers. Each patches something that the test itself owns and restores, and neither depends on a fresh module registry.
 
@@ -187,8 +187,8 @@ pnpm exec vitest run --sequence.shuffle.files
 
 ### Test helpers and shared setup
 
-- **`@xmachines/shared/vitest-setup`** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
-- **`@xmachines/shared/vitest-node-setup`** — Enforces Node ≥ 24 at runtime. Auto-injected for non-browser configs.
+- **[`@xmachines/shared/vitest-setup`](../api/@xmachines/shared/README.md)** — Injects `@testing-library/jest-dom` matchers. Applied automatically by `defineXmVitestConfig`.
+- **[`@xmachines/shared/vitest-node-setup`](../api/@xmachines/shared/README.md)** — Enforces Node ≥ 24 at runtime. Auto-injected for non-browser configs.
 - **`packages/play-react/test/test-utils.ts`** — React-specific test utilities for the `play-react` package.
 - **`packages/play-router/examples/shared/`** and **`packages/play-actor/examples/shared/`** — Shared test fixtures for router and actor integration tests.
 
@@ -263,7 +263,6 @@ describe("ClassName or functionName()", () => {
 
 ```typescript
 import { PlayActor } from "../src/abstract-actor.js";
-import { Signal } from "@xmachines/play-signals";
 ```
 
 ### Lifecycle hooks
@@ -306,7 +305,7 @@ afterEach(() => {
 
 **Never mock these:**
 
-- **TC39 Signals** (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`) — always use real implementations from `@xmachines/play-signals`. Signals have precise reactive semantics (synchronous propagation, lazy computation) that mocks cannot replicate accurately.
+- **Atoms** (`createAtom`, `watchAtom`) — always use real implementations from [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md). Atoms have precise reactive semantics (synchronous propagation, memoized derivation) that mocks cannot replicate accurately.
 - **Internal `@xmachines/*` packages** — these are resolved directly to source via the `xmAliases` Vite plugin in the Vitest config. Mocking them would hide integration bugs and defeat the purpose of cross-package testing.
 - **XState** — always use real `setup()` / `createMachine()` / `createActor()`. XState's actor lifecycle (start, stop, snapshot, subscription) is a behavioral contract that mocks cannot reliably emulate.
 
@@ -317,17 +316,16 @@ afterEach(() => {
 ```typescript
 import { PlayActor } from "@xmachines/play-actor";
 import type { Routable } from "@xmachines/play-router";
-import { Signal } from "@xmachines/play-signals";
 
 class MockActor implements PlayActor, Routable {
-	readonly state = new Signal.State({} as unknown);
-	private _routeState: Signal.State<string | null>;
-	readonly currentRoute: Signal.Computed<string | null>;
+	readonly state = createAtom({} as unknown);
+	private _routeState: Atom<string | null>;
+	readonly currentRoute: ReadonlyAtom<string | null>;
 	readonly initialRoute: string | null;
 
 	constructor(startRoute: string | null = "/") {
-		this._routeState = new Signal.State<string | null>(startRoute);
-		this.currentRoute = new Signal.Computed(() => this._routeState.get());
+		this._routeState = createAtom<string | null>(startRoute);
+		this.currentRoute = createAtom(() => this._routeState.get());
 		this.initialRoute = startRoute;
 	}
 
@@ -344,14 +342,14 @@ import { stubOf } from "@xmachines/shared/test-support";
 
 function createMockActor(initialView: PlaySpec | null = null) {
 	return stubOf<ViewActor>({
-		currentView: new Signal.State<PlaySpec | null>(initialView),
+		currentView: createAtom<PlaySpec | null>(initialView),
 		send: vi.fn(),
 		start: vi.fn(),
 		stop: vi.fn(),
 		getSnapshot: vi.fn(),
 		subscribe: vi.fn(),
-		state: new Signal.State<unknown>({}),
-		currentRoute: new Signal.Computed(() => null),
+		state: createAtom<unknown>({}),
+		currentRoute: createAtom(() => null),
 	});
 }
 ```
@@ -363,9 +361,9 @@ sites. `X as unknown as T` is banned in this repo; if `stubOf` cannot express
 the case, `unsafeCast<T>(value)` from the same module is the deliberate,
 greppable escape hatch.
 
-### Async and signal patterns
+### Async and atom patterns
 
-**Flushing the microtask queue (required for Signal propagation):**
+**Flushing the microtask queue (required for `watchAtom` delivery):**
 
 ```typescript
 function waitForMicrotask(): Promise<void> {
@@ -377,23 +375,26 @@ await waitForMicrotask();
 await vi.waitFor(() => expect(result).toBe(expected), { timeout: 100 });
 ```
 
-**Signal watcher pattern:**
+**Atom watch pattern:**
 
 ```typescript
-let notified = false;
-const watcher = new Signal.subtle.Watcher(() => {
-	notified = true;
+import { createAtom, watchAtom } from "@xmachines/play-atom";
+
+let notified: string | null = null;
+const stop = watchAtom(actor.currentRoute, (route) => {
+	notified = route;
 });
-watcher.watch(actor.currentRoute);
-actor.currentRoute.get(); // Initial read required to prime computed signals
 
 actor.state.set({ path: "/dashboard" });
-watcher.getPending(); // Process notifications synchronously
+// `watchAtom` coalesces into a microtask, so flush before the assertion.
+await new Promise((resolve) => setTimeout(resolve, 0));
 
-expect(notified).toBe(true);
-watcher.unwatch(actor.currentRoute); // Always clean up
+expect(notified).toBe("/dashboard");
+stop(); // Always clean up
 ```
 
+`atom.subscribe` delivers SYNCHRONOUSLY, inside the `set`, and it needs no flush. Use it when a test must observe the notification at the moment of the write. Use `watchAtom` everywhere else, because it is what the renderers and the bridges use.
+
 ### Compile-time type tests
 
 For type-only assertions, use `@ts-expect-error` in `.spec.ts` files:
@@ -448,18 +449,18 @@ try {
 
 ### An expected report in the log
 
-A test that makes a component fail gets a report of the framework for free. React writes the error and a component stack to `console.error` when the root declares no `onCaughtError`, and `@xmachines/play-solid` writes a line of its own when the caller gives no `onError`. Both reports are correct, and both reach the log of the pipeline, where 29 of them once filled more than half of the `test` job.
+A test that makes a component fail gets a report of the framework for free. React writes the error and a component stack to `console.error` when the root declares no `onCaughtError`, and [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md) writes a line of its own when the caller gives no `onError`. Both reports are correct, and both reach the log of the pipeline, where 29 of them once filled more than half of the `test` job.
 
 Claim the report in the test that expects it, and assert it:
 
-- **React.** Take `render` from `test/test-utils.js` of `@xmachines/play-react`, and not from `@testing-library/react`. It gives an `onCaughtError` to the root, which stops the print, and the result carries `caughtErrors` for an assertion. Keep the `render` of the library for a test that holds the DEFAULT report: the print of React IS the report of play-react for a caller that gives no `onError`.
+- **React.** Take `render` from `test/test-utils.js` of [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), and not from `@testing-library/react`. It gives an `onCaughtError` to the root, which stops the print, and the result carries `caughtErrors` for an assertion. Keep the `render` of the library for a test that holds the DEFAULT report: the print of React IS the report of play-react for a caller that gives no `onError`.
 - **Any framework.** Call `vi.spyOn(console, "error").mockImplementation(() => {})` before the render, and `expect(spy).toHaveBeenCalled()` after it. An `afterEach` with `vi.restoreAllMocks()` returns the console to the next test.
 
 A report that a spy swallows and no assertion reads is worse than the noise, because it hides the day that the renderer stops to report.
 
 ## Contract Tests
 
-The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in `@xmachines/play-router`) because the suite drives a real actor via `@xmachines/play-xstate` and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps `@xmachines/play-router` free of any dependency on the actor runtime:
+The `@xmachines/play-router-shared` package exports a shared behavioral contract suite that all router bridge adapters must satisfy. It lives here (rather than in [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)) because the suite drives a real actor via [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) and uses the shared `authMachine` fixture from `@xmachines/play-actor-shared`, so it sits one layer above the router package and keeps [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) free of any dependency on the actor runtime:
 
 ```typescript
 // packages/play-router/examples/shared/test/router-bridge-contract.ts
@@ -481,7 +482,7 @@ runBridgeContractTests({
 
 The contract covers: deep-link sync on connect, router→actor navigation sync, actor→router sync, guard redirect flows, duplicate event deduplication, and restore-from-snapshot behavior.
 
-**Used by:** `@xmachines/play-router`, `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-react-router`, and other adapter packages.
+**Used by:** [`@xmachines/play-router`](../api/@xmachines/play-router/README.md), `play-tanstack-react-router`, `play-vue-router`, `play-solid-router`, `play-react-router`, and other adapter packages.
 
 **Compile-time bridge contract verification:**
 
@@ -505,13 +506,13 @@ Coverage is collected using the **v8** provider. The root `vitest.config.ts` def
 
 Individual packages enforce their own (typically stricter) thresholds inside their `vitest.config.ts`:
 
-| Package tier                                                                       | Lines | Functions | Branches | Statements |
-| ---------------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
-| Core packages (`@xmachines/play`, `@xmachines/play-actor`, `@xmachines/play-view`) | 90%   | 90%       | 85%      | 90%        |
-| Complex logic (`@xmachines/play-xstate`, `@xmachines/play-router`)                 | 85%   | 85%       | 80%      | 85%        |
-| Integration packages (e.g. `@xmachines/play-react`, `@xmachines/play-dom`)         | 80%   | 80%       | 80%      | 80%        |
+| Package tier                                                                                                                                                                                              | Lines | Functions | Branches | Statements |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | --------- | -------- | ---------- |
+| Core packages ([`@xmachines/play`](../api/@xmachines/play/README.md), [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md), [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)) | 90%   | 90%       | 85%      | 90%        |
+| Complex logic ([`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md), [`@xmachines/play-router`](../api/@xmachines/play-router/README.md))                                                  | 85%   | 85%       | 80%      | 85%        |
+| Integration packages (e.g. [`@xmachines/play-react`](../api/@xmachines/play-react/README.md), [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md))                                              | 80%   | 80%       | 80%      | 80%        |
 
-`@xmachines/play-router` carries the lower numbers for a reason that its `vitest.config.ts` states: the bridge and the provider lifecycle are the mass of that package, and neither is measured by its own project. `@xmachines/play-router-shared` drives them through 3032 lines of contract suite, and each of the nine router adapters drives them again from its own project. The root `pnpm run test:coverage` is what measures the package whole.
+[`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries the lower numbers for a reason that its `vitest.config.ts` states: the bridge and the provider lifecycle are the mass of that package, and neither is measured by its own project. `@xmachines/play-router-shared` drives them through 3032 lines of contract suite, and each of the nine router adapters drives them again from its own project. The root `pnpm run test:coverage` is what measures the package whole.
 
 Coverage includes: `src/**/*.ts`, `src/**/*.tsx`, `src/**/*.vue`, `src/**/*.svelte`
 
@@ -530,23 +531,19 @@ Tests run in GitLab CI using the `to-be-continuous/node` pipeline component (ver
 **CI test command** (from `.gitlab-ci.yml`):
 
 ```bash
-pnpm run test:coverage -- \
-  --coverage.reporter=text \
-  --coverage.reporter=cobertura \
-  --coverage.reportsDirectory=reports/coverage \
-  --reporter=default \
-  --reporter=junit \
-  --outputFile.junit=reports/junit.xml
+pnpm run test:coverage
 ```
 
-**Artifacts:** The CI job (`node-build`) publishes:
+The job passes no reporter flag. `vitest.config.ts` owns the reporters, the JUnit file and the coverage directory, and it reads `COVERAGE_REPORTS_DIR` — which the `test` job sets to `reports/`. A new package therefore needs no CI change.
+
+**Artifacts:** The `test` job publishes:
 
-- JUnit XML report at `reports/junit.xml` (surfaced in GitLab's test results panel)
-- Cobertura coverage XML at `reports/coverage/cobertura-coverage.xml` (used for GitLab's coverage percentage badge — extracted from the `All files` line)
+- JUnit XML report at `reports/test-results.xml` (surfaced in GitLab's test results panel)
+- Cobertura coverage XML at `reports/cobertura-coverage.xml` (used for GitLab's coverage percentage badge — extracted from the `All files` line)
 
 Coverage and test results are always uploaded (`when: always`) so failures are visible even when the job itself fails.
 
-The `pnpm run format:check` and `pnpm run lint` commands enforce code style and are run separately from tests (via the `lint-enabled: true` input to the pipeline component).
+The `pnpm run format:check` and `pnpm run lint` commands enforce code style. They run as the separate `format` and `lint` jobs: the component's own lint job is turned off with `lint-enabled: "false"`, because it runs ESLint.
 
 ## Test Types Reference
 

package/examples/README.md

@@ -8,7 +8,7 @@ Practical code examples demonstrating current XMachines Play patterns and use ca
 
 Start with the fundamental machine + actor pattern:
 
-- **[Basic State Machine](basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + TC39 Signals
+- **[Basic State Machine](basic-state-machine.md)** — `setup().createMachine()` + `definePlayer()` + atoms
 - **[Traffic Light](traffic-light.md)** — Multi-state machine with `meta.route` and `formatPlayRouteTransitions`
 - **[Form Validation](form-validation.md)** — Typed context mutations with `setup.assign`, guards, and `$bindState`
 
@@ -60,7 +60,7 @@ The conceptual examples in this directory are TypeScript snippets. To run them:
 
 ```bash
 # Install dependencies (from the monorepo root)
-pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-signals xstate
+pnpm add @xmachines/play-xstate @xmachines/play-actor @xmachines/play-atom xstate
 
 # Run with tsx
 pnpm dlx tsx my-example.ts
@@ -81,7 +81,7 @@ pnpm --filter @xmachines/play-dom-router-demo run dev
 | [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)        | `definePlayer`, `formatPlayRouteTransitions`, `PlayerActor` |
 | [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)          | `PlayActor`                                                 |
 | [`@xmachines/play-view`](../api/@xmachines/play-view/README.md)            | `Viewable`, `PlaySpec`, `typedSpec`                         |
-| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)      | TC39 Signals polyfill, `watchSignal`                        |
+| [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md)            | The atom primitives, `watchAtom`                            |
 | [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)        | `RouterBridgeBase`, `RouteMap`, `Routable`                  |
 | [`@xmachines/play-router/xstate`](../api/@xmachines/play-router/README.md) | `extractMachineRoutes`, `getRoutableRoutes`                 |
 

package/examples/basic-state-machine.md

@@ -63,7 +63,7 @@ actor.start();
 console.log(actor.getSnapshot().value); // "off"
 console.log(actor.getSnapshot().context.toggleCount); // 0
 
-// 6. Read state via TC39 Signal
+// 6. Read state from the atom
 console.log(actor.state.get().value); // "off"
 
 // 7. Send events
@@ -87,13 +87,13 @@ actor.stop();
 
 3. **`toggleSetup.assign(...)`** — Assigns context mutations using the typed setup's `assign` helper. This provides full inference from the declared context type — no manual type assertions needed.
 
-4. **`definePlayer({ machine })`** — Wraps the machine in a factory. Calling `createPlayer()` returns a `PlayerActor` — XMachines' actor type that extends XState's actor with TC39 Signal reactivity and Play Architecture hooks.
+4. **`definePlayer({ machine })`** — Wraps the machine in a factory. Calling `createPlayer()` returns a `PlayerActor` — XMachines' actor type that extends XState's actor with atom reactivity and Play Architecture hooks.
 
 5. **`actor.start()`** — Activates the machine. Always call `start()` before sending events.
 
 6. **`actor.getSnapshot()`** — Returns the current XState snapshot synchronously. `.value` is the state name; `.context` is the typed context object.
 
-7. **`actor.state.get()`** — TC39 Signal access to the current snapshot. Useful when wiring infrastructure that observes signals (renderers, router bridges). Equivalent to `actor.getSnapshot()` for one-time reads.
+7. **`actor.state.get()`** — atom access to the current snapshot. Useful when wiring infrastructure that observes atoms (renderers, router bridges). Equivalent to `actor.getSnapshot()` for one-time reads.
 
 8. **Event types use dot-separated lowercase** — `"toggle"` not `"TOGGLE"`. This matches the XMachines convention used throughout the codebase (e.g. `"auth.login"`, `"auth.logout"`, `"play.route"`).
 
@@ -101,7 +101,7 @@ actor.stop();
 
 - **`setup({ types })`**: The XState v5 typed entry point. Declares context, event, and input shapes before machine creation.
 - **`definePlayer({ machine })`**: Creates a factory function that returns `PlayerActor` instances.
-- **`actor.state`**: A `Signal.State<Snapshot>` — TC39 Signals-based reactive handle on the machine snapshot.
+- **`actor.state`**: An `Atom<Snapshot>` — an atom-based reactive handle on the machine snapshot.
 - **`actor.getSnapshot()`**: Synchronous snapshot access — use for one-time reads and TypeScript-typed context inspection.
 - **Typed `assign`**: Always call `setup.assign(...)` (not the bare `assign` from xstate) for context mutations.
 

package/examples/form-validation.md

@@ -224,7 +224,7 @@ view: {
 
 ## Connecting the Renderer
 
-The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from `@xmachines/play-dom`:
+The machine spec above defines view structure — but nothing renders until you wire a renderer. Use `createRenderer` from [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md):
 
 ```typescript
 import { createRenderer, schema } from "@xmachines/play-dom";

package/examples/multi-router-integration.md

@@ -416,8 +416,8 @@ const disconnect = connectRouter({
 ```
 
 The Svelte adapters take the same two prefix options. They need no `router`:
-`@xmachines/play-svelte-spa-router` reads an optional `window`, and
-`@xmachines/play-sveltekit-router` reads an optional `location`.
+[`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md) reads an optional `window`, and
+[`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md) reads an optional `location`.
 
 ### What the Prefix Changes
 
@@ -480,7 +480,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 // [{ stateId: "home", path: "/:machineId/play" }, ...]
 ```
 
-> **Param note.** Under a mount, `@xmachines/play-vue-router` and `@xmachines/play-solid-router` resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. With no prefix, both keep the parse of their framework whenever it reports at least one
+> **Param note.** Under a mount, [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md) and [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md) resolve each param from the stripped path with `URLPattern`, and not from the pre-parsed params of their framework: under a prefix the framework matched a route of the **host**, so those params describe the route of the machine never — and a collision of names carries the value of the host. With no prefix, both keep the parse of their framework whenever it reports at least one
 > param the pattern declares, and every required one. A pattern whose params are ALL
 > optional and a framework that reports none — `/settings/:section?` under a catch-all of
 > the host — is settled by the PATH: `/settings` is the bare form of that pattern, so
@@ -489,7 +489,7 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 > extraction reads that value.
 >
 > These branches decide the CALLS of a navigation, and never the availability of the API.
-> `@xmachines/play-router` carries `urlpattern-polyfill` as an ordinary dependency and it
+> [`@xmachines/play-router`](../api/@xmachines/play-router/README.md) carries `urlpattern-polyfill` as an ordinary dependency and it
 > uses the native `URLPattern` when the runtime has one, so you install no polyfill and
 > you load none. A BAD pattern is a question of the route map: `RouteMap` compiles each
 > parameterized route in its constructor and throws an `InvalidRoutePatternError` there.
@@ -497,28 +497,28 @@ getRouteMappings(tree, { basePath: "/:machineId/play" });
 
 ## Adapter Summary
 
-| Package                                 | Framework             | Pattern         | Key Import                                                                |
-| --------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
-| `@xmachines/play-dom-router`            | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
-| `@xmachines/play-react-router`          | React Router 7/8      | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
-| `@xmachines/play-tanstack-react-router` | TanStack React Router | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
-| `@xmachines/play-solid-router`          | SolidJS Router        | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
-| `@xmachines/play-tanstack-solid-router` | TanStack Solid Router | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
-| `@xmachines/play-vue-router`            | Vue Router            | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
-| `@xmachines/play-sveltekit-router`      | SvelteKit             | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
-| `@xmachines/play-svelte-spa-router`     | Svelte SPA Router     | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
+| Package                                                                                           | Framework             | Pattern         | Key Import                                                                |
+| ------------------------------------------------------------------------------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------- |
+| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | Vanilla DOM           | `connectRouter` | `connectRouter`, `createRouteMap`, `createBrowserHistory`, `createRouter` |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | React Router 7/8      | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | TanStack React Router | Provider        | `PlayRouterProvider`, `createRouteMapFromTree`                            |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | SolidJS Router        | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | TanStack Solid Router | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | Vue Router            | Provider        | `PlayRouterProvider`, `createRouteMap`                                    |
+| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | SvelteKit             | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | Svelte SPA Router     | `connectRouter` | `connectRouter`, `createRouteMap`                                         |
 
 ## Renderer Packages
 
 Each framework also has a companion renderer package for the view layer:
 
-| Package                  | Framework   | Key API                                            |
-| ------------------------ | ----------- | -------------------------------------------------- |
-| `@xmachines/play-dom`    | Vanilla DOM | `createPlayUI`, `createRenderer`, `defineRegistry` |
-| `@xmachines/play-react`  | React       | `PlayRenderer`, `defineRegistry`                   |
-| `@xmachines/play-solid`  | SolidJS     | `PlayRenderer`, `defineRegistry`                   |
-| `@xmachines/play-vue`    | Vue 3       | `PlayRenderer`, `defineRegistry`                   |
-| `@xmachines/play-svelte` | Svelte 5    | `PlayRenderer`, `defineRegistry`                   |
+| Package                                                             | Framework   | Key API                                            |
+| ------------------------------------------------------------------- | ----------- | -------------------------------------------------- |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)       | Vanilla DOM | `createPlayUI`, `createRenderer`, `defineRegistry` |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)   | React       | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)   | SolidJS     | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)       | Vue 3       | `PlayRenderer`, `defineRegistry`                   |
+| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md) | Svelte 5    | `PlayRenderer`, `defineRegistry`                   |
 
 ## Architectural Invariants
 
@@ -526,9 +526,9 @@ All adapters preserve the 5 architectural invariants:
 
 1. **Actor Authority (INV-01):** Machine guards validate all navigation
 2. **Strict Separation (INV-02):** Business logic (machine) has zero framework imports
-3. **State-Driven Reset (INV-03):** Browser back/forward sends `play.route` events to actor
+3. **Atom-Only Reactivity (INV-03):** atoms work identically in all adapters
 4. **Passive Infrastructure (INV-04):** Router observes actor, never decides
-5. **Signal-Only Reactivity (INV-05):** TC39 Signals work identically in all adapters
+5. **State-Driven Reset (INV-05):** Browser back/forward sends `play.route` events to actor
 
 ## Next Steps
 

package/examples/routing-patterns.md

@@ -6,7 +6,7 @@ How the `authMachine` uses `meta.route`, `play.route` events, `formatPlayRouteTr
 
 XMachines inverts the usual routing model. The **actor** owns navigation — its guards decide which states are valid. The **router** is passive infrastructure that observes `actor.currentRoute` and keeps the browser URL in sync. This is **Actor Authority (INV-01)**.
 
-Every routing interaction starts with a `play.route` event sent to the actor. If the machine's guards allow the transition, the state changes and `actor.currentRoute` updates. The router bridge sees the new signal value and pushes a history entry. The URL never changes unless the actor approves.
+Every routing interaction starts with a `play.route` event sent to the actor. If the machine's guards allow the transition, the state changes and `actor.currentRoute` updates. The router bridge sees the new atom value and pushes a history entry. The URL never changes unless the actor approves.
 
 ## Key Concepts
 
@@ -240,7 +240,7 @@ actor.stop();
 
 ## Vanilla Router Setup
 
-To sync the browser URL with `actor.currentRoute`, use `@xmachines/play-dom-router`:
+To sync the browser URL with `actor.currentRoute`, use [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md):
 
 ```typescript
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
@@ -252,7 +252,7 @@ const history = createBrowserHistory({ window });
 const router = createRouter({ routeTree: authMachine, history });
 
 // connectRouter handles all bidirectional sync:
-// - actor.currentRoute signal → browser URL (history.push)
+// - actor.currentRoute atom → browser URL (history.push)
 // - browser URL changes → play.route event sent to actor
 const disconnect = connectRouter({ actor, router, routeMap });
 
@@ -265,7 +265,7 @@ window.addEventListener("beforeunload", () => {
 
 ## React Router Setup
 
-For React, use `@xmachines/play-react-router` or `@xmachines/play-tanstack-react-router`:
+For React, use [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md) or [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md):
 
 ```tsx
 import { PlayRouterProvider, createRouteMapFromTree } from "@xmachines/play-tanstack-react-router";
@@ -285,7 +285,7 @@ function App() {
 | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
 | **Actor Authority (INV-01)**        | Guards on the machine validate every navigation. The router cannot change state directly.      |
 | **Passive Infrastructure (INV-04)** | The router observes `actor.currentRoute` — it never decides where to go.                       |
-| **State-Driven Reset (INV-03)**     | Browser back/forward sends `play.route` events to the actor. History is driven by actor state. |
+| **State-Driven Reset (INV-05)**     | Browser back/forward sends `play.route` events to the actor. History is driven by actor state. |
 | **Strict Separation (INV-02)**      | The machine has zero framework imports. Guards, actions, and context are pure TypeScript.      |
 
 ## Next Steps

package/examples/traffic-light.md

@@ -81,7 +81,7 @@ const createPlayer = definePlayer({
 const actor = createPlayer();
 actor.start();
 
-// 5. Read current route via signal
+// 5. Read current route from the atom
 console.log(actor.currentRoute.get()); // "/red"
 
 // 6. Advance with domain events
@@ -123,14 +123,14 @@ on: {
 - The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` assigns them on every `play.route` transition.
 - `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state that must re-enter its own domain.
 
-## `actor.currentRoute` Signal
+## The `actor.currentRoute` atom
 
-`actor.currentRoute` is a `Signal.Computed<string | null>` derived from the active state's `meta.route` template and `context.params`. Route signals let router bridges observe URL changes reactively without polling.
+`actor.currentRoute` is a `ReadonlyAtom<string | null>` derived from the active state's `meta.route` template and `context.params`. A route atom lets a router bridge observe URL changes reactively without polling.
 
 ```typescript
-import { watchSignal } from "@xmachines/play-signals";
+import { watchAtom } from "@xmachines/play-atom";
 
-const unwatch = watchSignal(actor.currentRoute, () => {
+const unwatch = watchAtom(actor.currentRoute, () => {
 	console.log("URL changed to:", actor.currentRoute.get());
 });
 
@@ -142,7 +142,7 @@ unwatch();
 
 - **`meta.route`**: Marks a state as routable. The value is a URL template (e.g. `"/profile/:username"`).
 - **`formatPlayRouteTransitions`**: Utility that auto-generates `play.route` handlers from `id` + `meta.route` pairs. Wrap your machine config before passing to `createMachine`.
-- **`actor.currentRoute`**: TC39 `Signal.Computed` containing the resolved URL for the active state.
+- **`actor.currentRoute`**: a computed atom containing the resolved URL for the active state.
 - **`play.route` events**: Navigation events with a `to: "#stateId"` target. Use `to: "#red"` (state ID), not `to: "/red"` (URL path).
 
 ## Next Steps

package/guides/README.md

@@ -13,7 +13,7 @@ Background reading that explains the _why_ behind XMachines design decisions.
 - **[Understanding State Machines](state-machines.md)** — What finite state machines are, how `meta.route` and `meta.view` extend them, and why they replace boolean flags and component-level routing logic
 - **[Understanding the Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
 - **[Understanding Routing](routing.md)** — The URLPattern grammar that a `meta.route` path declares, the prefix rule that decides every optional route, and the three invariants that every router adapter follows
-- **[Understanding TC39 Signals](signals.md)** — The three signal primitives (`Signal.State`, `Signal.Computed`, `Signal.subtle.Watcher`), why XMachines uses them instead of observables, and the architectural invariants they enforce
+- **[Understanding Atoms](atoms.md)** — The atom primitives (`createAtom`, `createWritableAtom`, `watchAtom`), why XMachines uses them instead of observables, and the architectural invariants they enforce
 
 ## Tooling