@xmachines/docs 6.0.0 → 7.0.0

package/examples/routing-patterns.md

@@ -14,7 +14,7 @@ Every routing interaction starts with a `play.route` event sent to the actor. If
 
 Add a `meta.route` URL template to any state to make it routable:
 
-```typescript
+```typescript fragment
 states: {
   home: {
     id: "home",            // required: used as the play.route target ("#home")
@@ -106,7 +106,7 @@ const authMachine = authSetup.createMachine(
 
 `formatPlayRouteTransitions` generates root-level handlers equivalent to:
 
-```typescript
+```typescript fragment
 on: {
   "play.route": [
     { target: ".home",    guard: ({ event }) => event.to === "#home",    reenter: false, actions: assign({ params, query }) },
@@ -117,13 +117,17 @@ on: {
 }
 ```
 
-`reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/about", reenter: true } }` for a state that must re-enter its own domain.
+`reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/about", reenter: true } }` for a state whose route must also re-enter the domain of the transition. See [Re-entry on a navigation](../guides/routing.md#re-entry-on-a-navigation).
 
 ### `play.route` Events — Navigation
 
 To navigate, send a `play.route` event with `to: "#stateId"`:
 
 ```typescript
+import type { RoutableActor } from "@xmachines/play-router";
+
+declare const actor: RoutableActor; // the started actor of "Complete Actor Usage" below
+
 // Navigate to home
 actor.send({ type: "play.route", to: "#home" });
 
@@ -151,7 +155,7 @@ actor.send({
 
 Use XState `always` transitions to protect states. If the guard fires, the machine redirects _before_ the state is fully entered:
 
-```typescript
+```typescript fragment
 dashboard: {
   id: "dashboard",
   meta: { route: "/dashboard" },
@@ -177,7 +181,7 @@ profile: {
 
 Domain events placed at the root `on:` level are handled from any state:
 
-```typescript
+```typescript fragment
 const authMachine = authSetup.createMachine(
 	formatPlayRouteTransitions({
 		// ...
@@ -207,6 +211,12 @@ const authMachine = authSetup.createMachine(
 ## Complete Actor Usage
 
 ```typescript
+import type { AnyStateMachine } from "xstate";
+import { compose, definePlayer, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+
+declare const authMachine: AnyStateMachine; // the machine of the sections above
+
 const createPlayer = definePlayer({
 	machine: authMachine,
 	actor: compose(PlayerActor, withRouting),
@@ -244,12 +254,18 @@ To sync the browser URL with `actor.currentRoute`, use [`@xmachines/play-dom-rou
 
 ```typescript
 import { createBrowserHistory, createRouter, connectRouter } from "@xmachines/play-dom-router";
-import { createRouteMap } from "@xmachines/play-router/xstate";
+import { createRouteMap, extractMachineRoutes } from "@xmachines/play-router/xstate";
+import type { RoutableActor } from "@xmachines/play-router";
+import type { AnyStateMachine } from "xstate";
+
+declare const authMachine: AnyStateMachine; // the machine of the sections above
+declare const actor: RoutableActor; // the started actor of "Complete Actor Usage"
+
 // createRouteMap extracts meta.route declarations from the machine
 const routeMap = createRouteMap(authMachine);
 
 const history = createBrowserHistory({ window });
-const router = createRouter({ routeTree: authMachine, history });
+const router = createRouter({ routeTree: extractMachineRoutes(authMachine), history });
 
 // connectRouter handles all bidirectional sync:
 // - actor.currentRoute atom → browser URL (history.push)
@@ -271,14 +287,33 @@ function teardown(): void {
 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";
+import type { ReactNode } from "react";
+import {
+	PlayRouterProvider,
+	createRouteMapFromTree,
+	type RoutableActor,
+	type TanStackRouterInstance,
+} from "@xmachines/play-tanstack-react-router";
 import { extractMachineRoutes } from "@xmachines/play-router/xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const authMachine: AnyStateMachine; // the machine of the sections above
+declare const actor: RoutableActor; // the started actor of "Complete Actor Usage"
+declare const router: TanStackRouterInstance; // your TanStack Router instance
+declare function Shell(props: { actor: RoutableActor }): ReactNode; // your layout component
 
 const routeTree = extractMachineRoutes(authMachine);
 const routeMap = createRouteMapFromTree(routeTree);
 
 function App() {
-	return <PlayRouterProvider actor={actor} router={router} routeMap={routeMap} />;
+	return (
+		<PlayRouterProvider
+			actor={actor}
+			router={router}
+			routeMap={routeMap}
+			renderer={(currentActor) => <Shell actor={currentActor} />}
+		/>
+	);
 }
 ```
 

package/examples/traffic-light.md

@@ -36,7 +36,7 @@ const trafficSetup = setup({
 					params?: Record<string, string>;
 					query?: Record<string, string>;
 			  },
-		input: {} as undefined,
+		input: undefined,
 	},
 });
 
@@ -106,7 +106,7 @@ actor.stop();
 
 `formatPlayRouteTransitions` crawls every state that has **both** an `id` and a `meta.route`, then generates root-level `play.route` event handlers of the form:
 
-```typescript
+```typescript fragment
 // Auto-generated by formatPlayRouteTransitions — you don't write this manually:
 on: {
   "play.route": [
@@ -121,7 +121,7 @@ on: {
 
 - Every routable state must have both `id` (the `#id` navigation target) and `meta.route` (the URL template).
 - 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.
+- `reenter` comes from the object form of `meta.route`, and the default is `false`. Declare `meta: { route: { path: "/red", reenter: true } }` for a state whose route must also re-enter the domain of the transition. See [Re-entry on a navigation](../guides/routing.md#re-entry-on-a-navigation).
 
 ## The `actor.currentRoute` atom
 
@@ -129,6 +129,10 @@ on: {
 
 ```typescript
 import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+// The actor of the complete code above.
+declare const actor: Routable;
 
 const unwatch = watchAtom(actor.currentRoute, () => {
 	console.log("URL changed to:", actor.currentRoute.get());

package/guides/README.md

@@ -10,10 +10,11 @@ User-facing guides for the XMachines Play architecture.
 
 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 Atoms](atoms.md)** — The atom primitives (`createAtom`, `createWritableAtom`, `watchAtom`), why XMachines uses them instead of observables, and the architectural invariants they enforce
+- **[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
+- **[The Actor Model](actor-model.md)** — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
+- **[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
+- **[Views](views.md)** — Which state supplies the view, the read-only `/context` projection, the `viewKey` that decides when a renderer keeps the UI, and the four invariants that every renderer follows
+- **[Atoms](atoms.md)** — The atom primitives (`createAtom`, `createWritableAtom`, `watchAtom`), why XMachines uses them instead of observables, and the architectural invariants they enforce
 
 ## Tooling
 

package/guides/actor-model.md

@@ -1,4 +1,4 @@
-# Understanding the Actor Model and the Actor/Infrastructure Split
+# The Actor Model in XMachines
 
 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.
 
@@ -33,7 +33,7 @@ Infrastructure → actor: only via actor.send({ type: "..." })
 
 ## What the actor owns
 
-An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) — a concrete class that extends XState's `Actor` class via [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md). It implements three reactive properties:
+An actor in XMachines is a [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) — a concrete class that extends the `Actor` class of XState and implements the [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) interface. With its capabilities, it holds three reactive properties:
 
 | Property             | Type                             | What it is                                                                                                                                               |
 | -------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -50,7 +50,7 @@ beside an old derivation, and the composition order of the capabilities decides
 
 A derivation that fails reports through the `onError` option of the actor and keeps its
 last good value. It throws never, because it runs inside the write and a throw would break
-the transition for every other observer. See [Understanding Atoms](atoms.md).
+the transition for every other observer. See [Atoms](atoms.md).
 
 The actor also owns:
 
@@ -116,27 +116,30 @@ The two optional capability interfaces — [`Routable`](../api/@xmachines/play-r
 An actor implements only the capabilities it actually uses:
 
 ```typescript
+import type { PlayActor } from "@xmachines/play-actor";
+import { createAtom } from "@xmachines/play-atom";
+import { compose, PlayerActor } from "@xmachines/play-xstate";
+import { withRouting } from "@xmachines/play-xstate/routing";
+import { withView } from "@xmachines/play-xstate/view";
+import type { AnyStateMachine } from "xstate";
+
+type CounterEvent = { type: "increment" };
+
 // Minimal actor: the contract alone, which is reactive state and send
-class MinimalActor implements PlayActor<SomeSnapshot, SomeEvent> {
-	readonly state = createAtom<SomeSnapshot>(initial);
-	send(event: SomeEvent): void {
-		/* dispatch */
+class CounterActor implements PlayActor<{ count: number }, CounterEvent> {
+	readonly state = createAtom({ count: 0 });
+
+	send(event: CounterEvent): void {
+		if (event.type === "increment") this.state.set(({ count }) => ({ count: count + 1 }));
 	}
 }
 
-// Full actor: the contract, the routing and the view. It extends the actor class of
-// its own engine, and `PlayActor` stays out of the inheritance.
-class PlayerActor
-	extends Actor<SomeMachine>
-	implements PlayActor<SomeSnapshot, SomeEvent>, Routable, Viewable
-{
-	readonly state = createAtom(this.getSnapshot());
-	readonly currentRoute = createAtom(() => deriveRoute(this.state.get()));
-	readonly currentView = createAtom((): PlaySpec | null => deriveView(this.state.get()));
-}
+// Full actor: `PlayerActor` extends the `Actor` class of XState, and it implements
+// `PlayActor`. `withRouting` adds `Routable`, and `withView` adds `Viewable`.
+const FullActor = compose(PlayerActor<AnyStateMachine>, withRouting, withView);
 ```
 
-In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) yourself — [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates one from your machine definition.
+In practice you never write the actor class yourself — [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) from [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) creates the actor from your machine definition and from the class that `compose` returns.
 
 ---
 
@@ -146,7 +149,9 @@ In practice you never write [`PlayerActor`](../api/@xmachines/play-xstate/index/
 
 ```typescript
 import { definePlayer } from "@xmachines/play-xstate";
-import { myMachine } from "./machine.js";
+import { setup } from "xstate";
+
+const myMachine = setup({}).createMachine({ id: "app", initial: "idle", states: { idle: {} } });
 
 const createPlayer = definePlayer({ machine: myMachine });
 
@@ -157,11 +162,24 @@ actor.start();
 
 [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) 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):
+The factory accepts an optional `input` (initial context overrides) and an optional second argument `{ snapshot }` (a persisted snapshot, for resumable sessions):
 
 ```typescript
+import { definePlayer } from "@xmachines/play-xstate";
+import { setup } from "xstate";
+
+const machine = setup({
+	types: {
+		input: {} as { userId: string } | undefined,
+		context: {} as { userId: string | null },
+	},
+}).createMachine({ context: ({ input }) => ({ userId: input?.userId ?? null }) });
+
+const createPlayer = definePlayer({ machine });
+
 const actor = createPlayer({ userId: "abc" }); // with input
-const actor = createPlayer(undefined, { snapshot }); // restored from snapshot
+const snapshot = actor.getPersistedSnapshot();
+const restored = createPlayer(undefined, { snapshot }); // restored from snapshot
 ```
 
 ---
@@ -190,8 +208,8 @@ The Play RFC captures the actor/infrastructure split in a single statement:
 
 ## See also
 
-- [Understanding Atoms](atoms.md) — how the actor communicates with infrastructure
-- [Understanding State Machines](state-machines.md) — how the machine definition drives actor behavior
+- [Atoms](atoms.md) — how the actor communicates with infrastructure
+- [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](../api/@xmachines/play-actor/README.md) — API reference for [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md)
 - [@xmachines/play-xstate](../api/@xmachines/play-xstate/README.md) — API reference for [`definePlayer`](../api/@xmachines/play-xstate/index/functions/definePlayer.md) and [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md)

package/guides/atoms.md

@@ -1,4 +1,4 @@
-# Understanding Atoms in XMachines
+# Atoms in XMachines
 
 Atoms 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 atom primitives map to distinct roles in the architecture.
 
@@ -48,6 +48,8 @@ In XMachines, `actor.state` is an `Atom<Snapshot>`. The actor updates it on ever
 An atom notifies nobody when the new value compares equal to the old one. The default comparison is `Object.is`, and the `compare` option replaces it:
 
 ```typescript
+import { createAtom } from "@xmachines/play-atom";
+
 const point = createAtom(
 	{ x: 0, y: 0 },
 	{ compare: (previous, next) => previous.x === next.x && previous.y === next.y },
@@ -59,13 +61,18 @@ const point = createAtom(
 `ReadonlyAtom<T>` derives a value from one or more other atoms. It recomputes only when its dependencies change, and it memoizes the result. The atom tracks each dependency for you: read another atom inside the function, and the edge exists.
 
 ```typescript
-const route = createAtom(() => {
-	const snapshot = actor.state.get();
-	return snapshot.getMeta()?.route ?? null;
-});
+import { createAtom } from "@xmachines/play-atom";
+import type { PlayerActor } from "@xmachines/play-xstate";
+import type { AnyStateMachine } from "xstate";
+
+declare const actor: PlayerActor<AnyStateMachine>;
+
+// Whether the machine is in a state that shows the dashboard. The atom reads actor.state,
+// so it recomputes on each snapshot, and it notifies only when the answer changes.
+const onDashboard = createAtom(() => actor.state.get().matches("dashboard"));
 ```
 
-In XMachines, `actor.currentRoute` is a `ReadonlyAtom<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.
+In XMachines, `actor.currentRoute` is such a derived `ReadonlyAtom<string | null>`. It derives the route template of the active branch from `actor.state`, and it then fills the params from the context. 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.
 
 > **A computed atom with a subscriber is EAGER.** `@xstate/store` builds a subscription on an effect that READS the atom, so a write to a dependency evaluates the derivation at once, inside that write. A computed atom that nobody subscribes to stays lazy, and it computes on a read. Keep a derivation cheap and free of a side effect.
 
@@ -80,11 +87,15 @@ The actor writes exactly one atom for each transition — `state` — and `curre
 A subscriber makes a computed atom eager, so the derivation runs inside the `set` of its dependency — before any observer sees anything. No subscriber can wrap that, so a derivation that something may watch must not throw:
 
 ```typescript
-const derived = createAtom((previous) => {
+import { createAtom } from "@xmachines/play-atom";
+
+const source = createAtom('{ "count": 0 }');
+
+const derived = createAtom((previous?: unknown) => {
 	try {
-		return expensiveDerivation(source.get());
+		return JSON.parse(source.get()) as unknown;
 	} catch (error) {
-		report(error);
+		console.error(error);
 		return previous ?? null; // keep the last good value
 	}
 });
@@ -97,6 +108,8 @@ const derived = createAtom((previous) => {
 `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 and returns a `ReadonlyAtom` that carries no `set`.
 
 ```typescript
+import { createWritableAtom, type Atom } from "@xmachines/play-atom";
+
 class Holder<T extends { value: unknown }> {
 	public readonly state: Atom<T["value"]>;
 
@@ -114,6 +127,10 @@ Use `createAtom` everywhere else.
 Every atom carries `subscribe`. The observer runs **synchronously**, inside the `set` of the atom that changed, and it returns a subscription with `unsubscribe()`.
 
 ```typescript
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+
 const subscription = actor.currentRoute.subscribe((route) => {
 	console.log("Route is now:", route);
 });
@@ -124,6 +141,12 @@ subscription.unsubscribe();
 The subscription is a plain object. To hold it with `using`, publish it with `asDisposable` of [`@xmachines/core/utils`](../api/@xmachines/core/README.md), and name `unsubscribe` as the release:
 
 ```typescript
+import { asDisposable } from "@xmachines/core/utils";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+declare function render(route: string | null): void;
+
 {
 	const plain = actor.currentRoute.subscribe((route) => render(route));
 	using subscription = asDisposable(plain, () => plain.unsubscribe());
@@ -145,6 +168,11 @@ For both reasons, application code should use [`watchAtom()`](../api/@xmachines/
 [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) exports [`watchAtom(atom, onValue)`](../api/@xmachines/play-atom/functions/watchAtom.md) as a lifecycle-safe wrapper around `subscribe`. It returns a cleanup function:
 
 ```typescript
+import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+
 const stop = watchAtom(actor.currentRoute, (route) => {
 	console.log("Route is now:", route);
 });
@@ -175,6 +203,13 @@ Keep the explicit call where the release outlives the scope that made it — a f
 teardown reads, an entry in a `Set` of releases:
 
 ```typescript
+import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+declare function render(route: string | null): void;
+declare function onUnmount(teardown: () => void): void; // the hook of your framework
+
 const stop = watchAtom(actor.currentRoute, render);
 onUnmount(() => stop());
 ```
@@ -185,6 +220,11 @@ it, an exception releases it too, and the code carries no teardown:
 
 ```typescript
 import { asDisposable } from "@xmachines/core/utils";
+import { watchAtom } from "@xmachines/play-atom";
+import type { Routable } from "@xmachines/play-router";
+
+declare const actor: Routable;
+declare function render(route: string | null): void;
 
 {
 	using stop = asDisposable(watchAtom(actor.currentRoute, render));
@@ -214,7 +254,7 @@ decides how to emit it. A caller that does not write `using` needs neither, and
 
 `@xstate/store` holds the active subscriber in a variable of its own module. Two copies in one application 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. Every propagation of state in this architecture goes through an atom, so the second copy stops the whole reactivity of an application.
 
-[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) therefore declares `@xstate/store` as a **peer** dependency. A renderer declares it no more, because it reads the atom through [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) and names the engine in no import. Install one copy, and install it yourself. `tests/singleton-peers.test.ts` holds the rule true inside this workspace.
+[`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) therefore declares `@xstate/store` as a **peer** dependency. A renderer does not declare it, because it reads the atom through [`@xmachines/play-atom`](../api/@xmachines/play-atom/README.md) and names the engine in no import. Install one copy, and install it yourself. `tests/singleton-peers.test.ts` holds the rule true inside this workspace.
 
 ---
 
@@ -268,8 +308,8 @@ Failing to clean up subscriptions causes memory leaks and stale callbacks firing
 
 ## See also
 
-- [Understanding the Actor Model](actor-model.md) — why the actor owns all atom writes
-- [Understanding State Machines](state-machines.md) — how state nodes produce the metadata that atoms derive
+- [The Actor Model](actor-model.md) — why the actor owns all atom writes
+- [State Machines](state-machines.md) — how state nodes produce the metadata that atoms derive
 - [Getting Started](getting-started.md) — hands-on walkthrough using atoms to observe an actor
 - [@xmachines/play-atom](../api/@xmachines/play-atom/README.md) — API reference
 - [Play RFC](../rfc/play.md) — architectural specification