@xmachines/docs 1.0.0-beta.33 → 1.0.0-beta.35

package/guides/actor-model.md

@@ -0,0 +1,180 @@
+# Understanding the Actor Model and the Actor/Infrastructure Split
+
+XMachines is built around one central design principle: **business logic must never depend on infrastructure**. This page explains what that means, why the split is enforced the way it is, and what concrete responsibilities belong to each side of the boundary.
+
+After reading this, you will understand why a state machine in XMachines has no import from React, Vue, or any router — and why that constraint is a feature, not a limitation.
+
+---
+
+## Two roles, one boundary
+
+Every XMachines application has exactly two roles:
+
+**The Actor** — owns state, guards, routing intent, and view structure. It has zero knowledge of browsers, routing libraries, or UI frameworks.
+
+**Infrastructure** — the runtime environment. It reflects actor state into the world and forwards world events to the actor. It has no opinion on whether a transition is valid.
+
+The boundary between them is enforced by the signal protocol: the actor exposes `Signal.State` and `Signal.Computed` properties; infrastructure observes them. The actor never calls into infrastructure; infrastructure never mutates actor state directly.
+
+```
+Actor (business logic)
+  │
+  │  emits signals: state, currentRoute, currentView
+  ▼
+Infrastructure (runtime adapters)
+  ├── Router Bridge — reflects currentRoute into the URL bar
+  ├── Renderer — renders currentView into framework components
+  └── ... (any other observer)
+
+Infrastructure → actor: only via actor.send({ type: "..." })
+```
+
+---
+
+## What the actor owns
+
+An actor in XMachines is a `PlayerActor` — a concrete class that extends XState's `Actor` class via `AbstractActor`. It implements three reactive properties:
+
+| Property             | Type                              | What it is                                                              |
+| -------------------- | --------------------------------- | ----------------------------------------------------------------------- |
+| `actor.state`        | `Signal.State<Snapshot>`          | Updated on every XState transition. The full machine snapshot.          |
+| `actor.currentRoute` | `Signal.Computed<string \| null>` | Derived from the active state node's `meta.route`.                      |
+| `actor.currentView`  | `Signal.State<PlaySpec \| null>`  | Updated on each transition. Holds the `PlaySpec` that drives renderers. |
+
+All three are set by the actor, never by infrastructure. Infrastructure reads them via signals.
+
+The actor also owns:
+
+- **Guards** — it decides whether a transition is valid. If a router sends a `play.route` event for a path the actor's guards reject, the actor does not transition. It then emits its current valid route back through `currentRoute`, and the router bridge overwrites the URL to match.
+- **Error states** — structured errors (`PlayError`) are part of the actor's state graph, not thrown into the environment.
+- **Initial route** — `actor.initialRoute` is the route the actor starts in. Router adapters use this for initial navigation, not the browser's current URL.
+
+---
+
+## What infrastructure owns
+
+Infrastructure owns everything that touches the environment:
+
+- **Pushing URLs**: reading `actor.currentRoute` and calling `history.pushState()` or a router's navigation API.
+- **Forwarding navigation events**: listening to `popstate`, `routeChange`, or equivalent, then calling `actor.send({ type: "play.route", to: path })`.
+- **Rendering**: reading `actor.currentView` and projecting the spec through framework components.
+- **Lifecycle**: connecting on mount, disconnecting on unmount, explicitly cleaning up signal subscriptions.
+
+Infrastructure does **not**:
+
+- Decide whether a `play.route` event is valid (that is the actor's job via guards).
+- Override the URL to something the actor did not emit.
+- Read `actor.getSnapshot()` to make routing decisions (use `actor.currentRoute` instead).
+
+---
+
+## The reset invariant
+
+One of the most important behaviors in XMachines falls out directly from this split.
+
+If a user navigates directly to `/admin` in the browser but the actor's guards reject that route (because the user is not authenticated), the actor:
+
+1. Receives `{ type: "play.route", to: "/admin" }` from the router bridge.
+2. Evaluates its guards. The guard fails.
+3. Does not transition. It remains in its current state (e.g., `/login`).
+4. `actor.currentRoute` still signals `"/login"`.
+5. The router bridge, watching `currentRoute`, calls its `navigateRouter("/login")` method.
+6. The URL bar resets to `/login`.
+
+The environment is always made to match actor reality. The router bridge does not need any special "auth guard" logic — the state machine already has it.
+
+This is why the invariant is called **State-Driven Reset** in the Play RFC.
+
+---
+
+## `AbstractActor` — the enforced contract
+
+`AbstractActor` (from `@xmachines/play-actor`) is the abstract base class that all actor implementations must extend. It extends XState's `Actor`, which means:
+
+- XState's inspection API works (`@xstate/inspect`)
+- XState DevTools attach to actors normally
+- The full XState ecosystem (testing utilities, visualization) is compatible
+
+`AbstractActor` adds one abstract requirement: a reactive `state` property of type `Signal.State<unknown>`. This is the single point where XState's pull-based snapshot API is bridged to TC39's push-based signal system.
+
+The two optional capability interfaces — `Routable` and `Viewable` — are deliberately separate:
+
+- Not every actor needs routing (e.g., a background data-sync actor).
+- Not every actor drives a view (e.g., a sub-actor composed inside a parent).
+
+An actor implements only the capabilities it actually uses:
+
+```typescript
+// Minimal actor: just reactive state
+class MinimalActor extends AbstractActor<SomeLogic> {
+	state = new Signal.State(this.getSnapshot());
+}
+
+// Full actor: state + routing + view
+class PlayerActor extends AbstractActor<SomeMachine> implements Routable, Viewable {
+	state = new Signal.State(this.getSnapshot());
+	currentRoute = new Signal.Computed(() => deriveRoute(this.state.get()));
+	currentView = new Signal.State<PlaySpec | null>(null);
+}
+```
+
+In practice you never write `PlayerActor` yourself — `definePlayer` from `@xmachines/play-xstate` creates one from your machine definition.
+
+---
+
+## `definePlayer` — the factory builder
+
+`definePlayer({ machine })` is the primary entry point for creating actors:
+
+```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import { myMachine } from "./machine.js";
+
+const createPlayer = definePlayer({ machine: myMachine });
+
+// Each call creates an independent actor instance
+const actor = createPlayer();
+actor.start();
+```
+
+`definePlayer` returns a **factory function**, not an actor. This is intentional: it lets you create multiple independent instances (e.g., one per test, one per user session) without re-processing the machine definition each time.
+
+The factory accepts optional `input` (initial context overrides) and a `restore` snapshot (for resumable sessions):
+
+```typescript
+const actor = createPlayer({ userId: "abc" }); // with input
+const actor = createPlayer(undefined, { snapshot }); // restored from snapshot
+```
+
+---
+
+## Why the actor has no framework imports
+
+The machine definition — the `setup().createMachine(...)` call — is pure TypeScript with zero runtime dependencies on browsers, routers, or UI frameworks. This is not a convention; it is enforced by the dependency graph.
+
+`@xmachines/play-xstate` depends on `xstate` and `@xmachines/play-signals`. It does not depend on React, Vue, any router library, or any browser API. Your machine file inherits those same boundaries.
+
+This has concrete practical benefits:
+
+- **Portable**: the same machine runs in a browser, a Node.js server, a web worker, and a Vitest test suite — with zero modification.
+- **Testable in isolation**: you test the machine with `actor.send()` and `actor.state.get()`. No DOM, no router, no React to mock.
+- **Replaceable infrastructure**: swap the React renderer for a Vue renderer, or swap TanStack Router for React Router, without touching the machine file.
+
+---
+
+## The lock statement
+
+The Play RFC captures the actor/infrastructure split in a single statement:
+
+> _Logic is sovereign. Infrastructure reflects, never decides. Capabilities compose, never prescribe. Logic owns structure and flow. Adapters project, never decide. This is Universal Player._
+
+---
+
+## See also
+
+- [Understanding TC39 Signals](signals.md) — how the actor communicates with infrastructure
+- [Understanding State Machines](state-machines.md) — how the machine definition drives actor behavior
+- [Getting Started](getting-started.md) — hands-on walkthrough creating and starting an actor
+- [@xmachines/play-actor README](../api/@xmachines/play-actor/README.md) — API reference for `AbstractActor`
+- [@xmachines/play-xstate README](../api/@xmachines/play-xstate/README.md) — API reference for `definePlayer` and `PlayerActor`
+- [Play RFC](../rfc/play.md) — complete architectural specification

package/guides/getting-started.md

@@ -206,10 +206,10 @@ window.addEventListener("beforeunload", () => {
 });
 ```
 
-**React** — use `PlayRenderer` from `@xmachines/play-react`:
+**React** — use `PlayUIProvider` + `PlayRenderer` from `@xmachines/play-react`:
 
 ```tsx
-import { PlayRenderer, defineRegistry } from "@xmachines/play-react";
+import { PlayUIProvider, PlayRenderer, defineRegistry } from "@xmachines/play-react";
 import { authCatalog } from "@xmachines/play-actor-shared";
 import { Home, Login } from "./components/index.js";
 
@@ -222,7 +222,11 @@ const registryResult = defineRegistry(authCatalog, {
 });
 
 function App() {
-	return <PlayRenderer actor={actor} registryResult={registryResult} />;
+	return (
+		<PlayUIProvider actor={actor} registryResult={registryResult}>
+			<PlayRenderer />
+		</PlayUIProvider>
+	);
 }
 ```
 
@@ -288,17 +292,17 @@ actor.stop();
 
 ## Glossary
 
-| Term                         | Description                                                                                            |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `setup({ types })`           | XState v5 entry point — declares TypeScript types for context, events, and input                       |
-| `definePlayer({ machine })`  | Creates a factory that produces `PlayerActor` instances from the machine                               |
-| `actor.start()`              | Activates the machine — always call before sending events                                              |
-| `actor.send({ type })`       | Sends an event to the machine                                                                          |
-| `actor.getSnapshot()`        | Synchronous snapshot of the current state and context                                                  |
-| `actor.state`                | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                                  |
-| `actor.currentRoute`         | `Signal.Computed<string \| null>` — resolved URL from the active state's `meta.route`                  |
-| `actor.currentView`          | `Signal.State<ViewMetadata \| null>` — view spec from the active state's `meta.view`; drives renderers |
-| `formatPlayRouteTransitions` | Utility that generates `play.route` handlers from `id` + `meta.route` state pairs                      |
+| Term                         | Description                                                                                        |
+| ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| `setup({ types })`           | XState v5 entry point — declares TypeScript types for context, events, and input                   |
+| `definePlayer({ machine })`  | Creates a factory that produces `PlayerActor` instances from the machine                           |
+| `actor.start()`              | Activates the machine — always call before sending events                                          |
+| `actor.send({ type })`       | Sends an event to the machine                                                                      |
+| `actor.getSnapshot()`        | Synchronous snapshot of the current state and context                                              |
+| `actor.state`                | `Signal.State<Snapshot>` — TC39 Signal for reactive state observation                              |
+| `actor.currentRoute`         | `Signal.Computed<string \| null>` — resolved URL from the active state's `meta.route`              |
+| `actor.currentView`          | `Signal.State<PlaySpec \| null>` — view spec from the active state's `meta.view`; drives renderers |
+| `formatPlayRouteTransitions` | Utility that generates `play.route` handlers from `id` + `meta.route` state pairs                  |
 
 ## Next Steps
 

package/guides/signals.md

@@ -0,0 +1,166 @@
+# 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`:
+
+### `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()` helper covers the common case.
+
+---
+
+## `watchSignal()` — the safe helper
+
+`@xmachines/play-signals` exports `watchSignal(signal, onValue)` 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()` handles three subtle correctness concerns for you:
+
+| Concern                | What happens without it                            | How `watchSignal` 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()` in framework adapters and application code. Use the raw `Signal.subtle.Watcher` only when building infrastructure that needs to watch multiple signals independently.
+
+---
+
+## 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` 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()`.
+- 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()`         | Lifecycle-safe single-signal subscription      | Application code, adapter code     |
+
+## See also
+
+- [Understanding the Actor Model](concepts-actor-model.md) — why the actor owns all signal writes
+- [Understanding State Machines](concepts-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 README](../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