@xmachines/docs 6.1.0 → 7.1.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")
@@ -79,7 +79,9 @@ const authSetup = setup({
 	types: {
 		context: {} as AuthContext,
 		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
+			| PlayRouteEvent
+			| { type: "auth.login"; username: string }
+			| { type: "auth.logout" },
 		input: {} as Partial<AuthContext> | undefined,
 	},
 });
@@ -106,7 +108,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 }) },
@@ -124,6 +126,10 @@ on: {
 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 +157,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 +183,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 +213,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 +256,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 +289,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": [
@@ -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/examples/xstate-example-ports.md

@@ -0,0 +1,106 @@
+[Examples](README.md) / XState Example Ports
+
+# XState Example Ports
+
+The official XState examples ported into XMachines Play demos, and how they are packaged. Every pick exists on the `statelyai/xstate` `next` branch already migrated to XState v6 syntax, so each pick is verified to survive v6. The ports themselves are implemented against the repository's current XState v5 adapter; moving them to v6 later is the same mechanical migration upstream already performed (transition functions returning `{ target, context }`, `createAsyncLogic` / `createCallbackLogic` instead of `fromPromise` / `fromCallback`).
+
+Source catalog: [`statelyai/xstate` `examples/`](https://github.com/statelyai/xstate/tree/next/examples) (`next` branch).
+
+## How The Ports Are Packaged
+
+The eight machines live in [`@xmachines/play-actor-shared`](../../play-actor/examples/shared/README.md), one directory each, with a catalog, action handlers, behavioral tests, view-spec invariant tests, and a reusable browser suite. Every machine declares its views against one five-component vocabulary — `Page`, `Panel`, `Field`, `Button`, `Text` — defined once in `src/components-schema.ts`.
+
+That vocabulary is what makes the packaging cheap:
+
+- **One renderer gallery per framework** (`packages/play-<framework>/examples/gallery`) hosts all eight machines behind a picker. Choosing a machine stops the previous actor and starts a fresh one, so the inspector always shows a single live machine. Each framework implements the five components exactly once, and every machine's views render through them unmodified.
+- **One router demo per adapter and routable machine** (`packages/play-<router>/examples/<machine>`), 32 in total. Each imports its framework's gallery for the catalog, the component kit, and the shell, so the demo itself contains only the router wiring.
+
+The shared browser suites are framework-agnostic: they interact through the DOM contract (`data-page`, `data-demo-id`, `data-demo-shell`) and nothing else, so the same suite drives all five frameworks. That they pass unmodified everywhere is the evidence the machines carry no framework assumptions.
+
+## Selection Criteria
+
+An example qualifies when it:
+
+1. **Survives v6** — present and migrated on the `next` branch, no APIs removed in v6.
+2. **Demonstrates an invariant** — shows Actor Authority, Passive Infrastructure, State-Driven Reset, or Atom-Only Reactivity in a way the shared auth demo does not.
+3. **Maps onto the Play surface** — states become `meta.route` / `meta.view` declarations; UI becomes a JSON-Render catalog; framework code stays out of the machine.
+
+## Common Requirements
+
+Every ported example, routing or not:
+
+- **Wires the Stately inspector.** The actor is created with `options.inspect` from the shared demo controller (`createDemoInspector()`, `packages/play-actor/examples/shared/src/inspector.ts`), and the debug panel exposes the **Show Inspector** button — identical to the existing demos. The shared controller also carries the `@statelyai/inspect` 0.7 → v6 event translation described in the [inspector guide](../guides/inspector.md), so ports get animated transitions for free.
+- Uses the same `setup()` style as the shared auth machine and avoids every API the v6 migration removes, so the later v6 move stays mechanical.
+- Keeps business logic framework-free: views are JSON-Render specs selected via `meta.view`, events are the only input.
+- Ships the standard invariant tests plus browser renderer coverage, mirroring the existing demo test layout.
+
+## Ports With Routing
+
+### 1. TodoMVC — `todomvc-react`
+
+The upstream example already routes its all/active/completed filters, but imperatively through a `useHashChange` hook. The port deletes that hook and makes the filter states routable (`/`, `/active`, `/completed`) via `meta.route` + `formatPlayRouteTransitions` — a direct before/after argument for actor-authoritative routing. The todo list exercises JSON-Render `repeat` / `$item` and per-row actions.
+
+- Demonstrates: INV-01, INV-04 — the router observes, the machine owns the filter.
+- Inspector: high event volume (per-keystroke edits) makes the live machine view genuinely useful.
+
+### 2. Trivia Game — `trivia-game-example`
+
+Home → Trivia → win/lose pages with lives, points, and clues in context. Upstream deliberately keeps navigation out of the machine via `machine.provide(...)`; the port replaces that seam with `meta.route` and guards. Navigating to `/trivia` mid-game or after losing is overwritten by actor-derived state — the clearest INV-05 (State-Driven Reset) showcase in the set.
+
+- Demonstrates: INV-01, INV-05 — guards decide route validity; invalid URLs bounce.
+- Inspector: guard rejections are visible as unhandled `play.route` events.
+
+### 3. Persisted Donut Maker — `persisted-donut-maker`
+
+Multi-step recipe machine, one route per step, combined with `getPersistedSnapshot()` and the factory resume options. Refreshing the browser mid-flow restores machine state and URL together — persistence plus actor-authoritative deep links, which no current demo covers.
+
+- Demonstrates: snapshot persistence, `PlayerFactoryResumeOptions`, deep-link resume.
+- Inspector: attach-after-restore exercises the "turning the inspector on later" flow from the guide.
+
+### 4. Flight Booker — `7guis-flight-booker-react`
+
+Upstream is a single screen; the port stretches it into a wizard (trip type → dates → submitting → booked) with a route per step and query params for the selection. The same date guards that block invalid submissions block `play.route` jumps to `/booked`.
+
+- Demonstrates: wizard routing, param/query routes, guard-gated forward navigation.
+
+## Ports Without Routing
+
+### 5. Fetch — `fetch`
+
+idle/loading/success/failure around an invoked promise actor (`fromPromise`; `createAsyncLogic` in v6). Each state maps to a `meta.view` spec — view selection driven purely by machine state, zero component-level loading logic.
+
+### 6. Stopwatch — `stopwatch`
+
+Callback actor (`fromCallback`; `createCallbackLogic` in v6) ticking every 10 ms while in `running`; cleanup rides on state exit. Stress-tests atom propagation through passive renderers at high frequency.
+
+### 7. Tic-Tac-Toe — `tic-tac-toe-react`
+
+Turn-taking guards and win detection with the whole board in context. The board renders as a JSON-Render `repeat` grid; every move is an inspectable event.
+
+### 8. Temperature Converter — `7guis-temperature-react` / `7guis-2-temperature-vue`
+
+Bidirectional field binding via `$bindState`; complements the [form validation example](form-validation.md) on a tiny, well-known benchmark.
+
+## Stretch Candidates
+
+- **Friends List — `friends-list-react`.** Parent machine spawning a child actor per friend (`spawn` / `stopChild`, refs in context). Exercises the adapter's child-actor behaviour and the [actor model guide](../guides/actor-model.md); scheduled after the core eight because it may surface adapter work.
+- **Express Workflow — `express-workflow`.** Headless: restore snapshot per request, send event, re-persist. A server-side `definePlayer` demo pairing with the WebSocket inspector transport from the guide.
+
+## Not Ported
+
+| Example                             | Reason                                                                      |
+| ----------------------------------- | --------------------------------------------------------------------------- |
+| `store-*` (3 examples)              | `@xstate/store`, not state machines — outside the Play adapter surface      |
+| `snake-react`, `tiles`              | Game-loop and renderer-heavy; little architectural signal                   |
+| `mongodb-*` (2 examples)            | Infrastructure-heavy; persistence is covered by the donut maker             |
+| `workflow-*` (25 examples)          | Headless single-file Serverless Workflow ports; no UI or navigation to show |
+| `counter`, `toggle`, 7GUIs counters | Already covered by [basic state machine](basic-state-machine.md) and guides |
+
+## What The Matrix Caught
+
+Running one machine set across five renderers and eight routers found two defects that a single-framework demo could not:
+
+- **Vue Router lost its history bookkeeping.** The shared suites simulated a manual URL entry with `history.pushState({}, …)`, which nulls `history.state` — where Vue Router keeps its `{ back, current, forward, position }` record. The actor bounced correctly every time, but the router could no longer write the corrected URL back. The suites now carry the existing `history.state` across the synthetic jump, which is also what a real navigation does.
+- **The TanStack bridge dropped a corrective navigation under `<RouterProvider>`.** The provider installs a `Transitioner` that defers `router.latestLocation`, so `commitLocation` saw the pre-change href, decided the URL was unchanged, and skipped the history write. The bridge then synchronized the actor before `router.load()` settled, so the correction landed inside that stale window. [`watchRouterChanges`](../../play-tanstack-router/src/tanstack-router-bridge-base.ts) now waits for the `router.load()` of each event before it synchronizes the actor. Both TanStack demo families still mount a bare navigation-service router, because the actor and not the route tree decides the view.
+
+Neither surfaced while only path-based routers were under test, and the pre-existing auth demo suites had no invalid-URL case at all.

package/guides/actor-model.md

@@ -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                                                                                                                                               |
 | -------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -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
 ```
 
 ---

package/guides/atoms.md

@@ -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));