@xmachines/docs 3.0.0 → 5.0.0

package/guides/signals.md

@@ -1,209 +0,0 @@
-# Understanding TC39 Signals in XMachines
-
-TC39 Signals are the reactive substrate connecting actors to the outside world in XMachines. This page explains what they are, why XMachines uses them instead of observables or callbacks, and how the three Signal primitives map to distinct roles in the architecture.
-
-After reading this, you will understand why infrastructure never reads state directly from an actor — and what it does instead.
-
----
-
-## What problem Signals solve
-
-When a state machine transitions, several things may need to react: the URL bar might update, a router might navigate, a renderer might swap views. The naive approach is to let each of those consumers call `actor.getSnapshot()` whenever they feel like it — or to have the actor call back into each consumer via callbacks.
-
-Both approaches break down:
-
-- **Polling** (`getSnapshot()` on a timer or event) is racy: consumers can observe inconsistent intermediate states during a transition sequence.
-- **Callbacks** create direct dependencies between the actor and infrastructure, violating the architectural invariant that business logic must not depend on runtime APIs.
-
-TC39 Signals solve this with a **push–pull model**:
-
-- The actor **pushes** state changes into signals synchronously on every transition.
-- Consumers **pull** computed values lazily from signals — only when they actually need the value.
-- Changes propagate **atomically**, so no consumer ever sees a half-updated state.
-
-This model is sometimes called _glitch-free reactivity_: intermediate invalid states never escape to the environment.
-
----
-
-## The three Signal primitives
-
-XMachines uses three primitives from the [TC39 Signals proposal](https://github.com/tc39/proposal-signals), accessed via [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md):
-
-### `Signal.State` — writable values
-
-`Signal.State<T>` holds a single mutable value. Only the actor (or code it explicitly delegates to) writes to it. Everything else reads from it.
-
-```typescript
-import { Signal } from "@xmachines/play-signals";
-
-const count = new Signal.State(0);
-
-count.set(1); // write
-count.get(); // read → 1
-```
-
-In XMachines, `actor.state` is a `Signal.State<Snapshot>`. The actor updates it on every XState transition. Infrastructure reads it — never writes it.
-
-### `Signal.Computed` — derived values
-
-`Signal.Computed<T>` derives a value from one or more other signals. It recomputes only when its dependencies change — and only when something reads it (lazy evaluation).
-
-```typescript
-const route = new Signal.Computed(() => {
-	const snapshot = actor.state.get();
-	return snapshot.getMeta()?.route ?? null;
-});
-```
-
-In XMachines, `actor.currentRoute` is a `Signal.Computed<string | null>`. Router adapters read it to know which URL to push — they do not compute the route themselves. Route derivation stays in the actor where the business logic lives.
-
-### `Signal.subtle.Watcher` — reactive observation
-
-`Signal.subtle.Watcher` is the low-level primitive for reacting to signal changes. When a watched signal's value changes, the watcher's `notify` callback fires synchronously. You then schedule the actual work with `queueMicrotask` to avoid re-entrant signal reads.
-
-```typescript
-const watcher = new Signal.subtle.Watcher(() => {
-	queueMicrotask(() => {
-		const pending = watcher.getPending();
-		for (const signal of pending) {
-			signal.get(); // re-read to flush
-		}
-		watcher.watch(...pending); // re-arm for next change
-	});
-});
-
-watcher.watch(actor.currentRoute);
-actor.currentRoute.get(); // initial read required to arm the watcher
-```
-
-Watcher notifications are **one-shot**: if you do not call `watch()` again after draining pending signals, you will miss subsequent changes.
-
-Router bridges and renderers use `Signal.subtle.Watcher` internally. For most application code, the [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) helper covers the common case.
-
----
-
-## [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) — the safe helper
-
-[`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) exports [`watchSignal(signal, onValue)`](../api/@xmachines/play-signals/functions/watchSignal.md) as a lifecycle-safe wrapper around the raw watcher pattern. It returns a cleanup function:
-
-```typescript
-import { watchSignal } from "@xmachines/play-signals";
-
-const stop = watchSignal(actor.currentRoute, (route) => {
-	console.log("Route is now:", route);
-});
-
-// Later — stops observing and prevents use-after-free
-stop();
-```
-
-[`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) handles three subtle correctness concerns for you:
-
-| Concern                | What happens without it                            | How [`watchSignal`](../api/@xmachines/play-signals/functions/watchSignal.md) handles it |
-| ---------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| **Use-after-free**     | Callback fires after component unmounts            | `disposed` flag checked before invoking callback                                        |
-| **Coalescing**         | Rapid synchronous changes cause multiple callbacks | `needsEnqueue` guard — only one microtask queued per synchronous burst                  |
-| **Idempotent cleanup** | Calling the cleanup twice throws                   | Safe to call multiple times                                                             |
-
-Use [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
-
----
-
-## The release, and `using`
-
-`watchSignal()` returns a `Cleanup` from [`@xmachines/play`](../api/@xmachines/play/README.md): a
-function, and a `Disposable`. One value therefore serves two forms, and the same holds for
-the mount of `@xmachines/play-dom` and for `history.subscribe()` of
-`@xmachines/play-dom-router`.
-
-Keep the explicit call where the release outlives the scope that made it — a field that a
-teardown reads, an entry in a `Set` of releases:
-
-```typescript
-const stop = watchSignal(actor.currentRoute, render);
-onUnmount(() => stop());
-```
-
-Write `using` where the release belongs to one scope. The scope releases it, an exception
-releases it too, and the code carries no teardown:
-
-```typescript
-{
-	using stop = watchSignal(actor.currentRoute, render);
-	render(actor.currentRoute.get());
-	// stop() runs here, and it runs even when render() throws
-}
-```
-
-A scope releases from the last declaration to the first, so a release that depends on an
-earlier one is safe.
-
-Every release here is synchronous, so `Cleanup` is a `Disposable` and not an
-`AsyncDisposable`. That is the permissive choice: a `Disposable` serves `using` AND
-`await using`, while an `AsyncDisposable` raises a TypeError under a plain `using` and
-forces every holder into an async function. `asCleanup` therefore refuses a release that
-returns a value, and a promise above all — a promise handed to it would go on the floor,
-released and unawaitable.
-
-`using` needs Node 24 or a browser with Explicit Resource Management. The publishable
-packages build at `target: "esnext"` and pass the syntax through untouched, so your bundler
-decides how to emit it. The `Cleanup` VALUE needs neither: a runtime without
-`Symbol.dispose` still calls it as a plain function.
-
----
-
-## Why not observables (RxJS) or event emitters?
-
-The XMachines architecture chose TC39 Signals over observable libraries and event emitters for three reasons:
-
-**1. Standardization.** Signals are a Stage 1 TC39 proposal. They are not tied to any library, bundler, or framework. Isolating the polyfill behind [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md) means the entire ecosystem can migrate to native signals when the proposal lands, with a single package update.
-
-**2. Synchronous atomic propagation.** RxJS streams are asynchronous by default. Event emitters fire immediately but serially — a listener registered halfway through a sequence can see inconsistent state. Signals propagate atomically: all computeds update before any watcher fires.
-
-**3. Pull-based evaluation.** Observables push values to every subscriber immediately. Signals are lazy: `Signal.Computed` does not recompute until something reads it. An adapter that is not currently mounted does not pay the cost of computing derived values.
-
----
-
-## The five Signal invariants in XMachines
-
-The Play RFC defines five invariants that govern how signals are used:
-
-| Invariant                          | What it means in practice                                                                                   |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| **INV-01: Actor Authority**        | Only actor code writes to `actor.state`. Never write to it from infrastructure.                             |
-| **INV-04: Passive Infrastructure** | Routers and renderers read signals and forward events. They never decide state transitions.                 |
-| **INV-05: Signal-Only Reactivity** | Cross-boundary communication uses signals. Infrastructure does not poll `getSnapshot()`.                    |
-| **INV-03: No Direct Queries**      | Infrastructure reads from signals, not from snapshot methods, outside of actor code.                        |
-| **INV-02: Strict Separation**      | Business logic (`machine` definition) never imports browser APIs, routing libraries, or framework packages. |
-
----
-
-## Cleanup is mandatory
-
-Signals do not clean themselves up when they go out of scope. Every watcher you create must be explicitly disposed when the consuming component or adapter unmounts.
-
-- Framework lifecycle hooks (`useEffect` cleanup in React, `onUnmounted` in Vue, `onCleanup` in Solid) must call `unwatch()` or the cleanup returned by [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md).
-- Router bridge `disconnect()` methods must unwatch all signal subscriptions.
-- If you use the raw `Signal.subtle.Watcher` API, pair every `watch()` call with `unwatch()` in teardown.
-
-Failing to clean up watchers causes memory leaks and stale callbacks firing after the consumer is gone.
-
----
-
-## Summary
-
-| Primitive                                                                  | Role in XMachines                              | Who uses it                        |
-| -------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |
-| `Signal.State`                                                             | Actor output: writable snapshot and view state | Actor writes; infrastructure reads |
-| `Signal.Computed`                                                          | Lazy derivations: routes, view specs           | Actor defines; adapters read       |
-| `Signal.subtle.Watcher`                                                    | Low-level reactive observation                 | Framework adapters, router bridges |
-| [`watchSignal()`](../api/@xmachines/play-signals/functions/watchSignal.md) | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
-
-## See also
-
-- [Understanding the Actor Model](actor-model.md) — why the actor owns all signal writes
-- [Understanding State Machines](state-machines.md) — how state nodes produce the metadata that signals derive
-- [Getting Started](getting-started.md) — hands-on walkthrough using signals to observe an actor
-- [@xmachines/play-signals](../api/@xmachines/play-signals/README.md) — API reference
-- [Play RFC](../rfc/play.md) — architectural specification
-- [TC39 Signals proposal](https://github.com/tc39/proposal-signals) — upstream proposal