@xmachines/docs 6.1.0 → 8.0.0-next.1

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")
@@ -63,10 +63,10 @@ states: {
 Instead of hand-writing `play.route` event handlers for every routable state, wrap your machine config with `formatPlayRouteTransitions`:
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 import { definePlayer } from "@xmachines/play-xstate";
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
-import type { PlayRouteEvent } from "@xmachines/play-router";
+import type { PlayRouteEvent, RouteMetadata } from "@xmachines/play-router";
 
 interface AuthContext {
 	isAuthenticated: boolean;
@@ -76,11 +76,15 @@ interface AuthContext {
 }
 
 const authSetup = setup({
-	types: {
-		context: {} as AuthContext,
-		events: {} as
-			PlayRouteEvent | { type: "auth.login"; username: string } | { type: "auth.logout" },
-		input: {} as Partial<AuthContext> | undefined,
+	schemas: {
+		context: types<AuthContext>(),
+		events: {
+			"play.route": types<Omit<PlayRouteEvent, "type">>(),
+			"auth.login": types<{ username: string }>(),
+			"auth.logout": types<void>(),
+		},
+		input: types<Partial<AuthContext> | undefined>(),
+		meta: types<{ route?: RouteMetadata }>(),
 	},
 });
 
@@ -106,17 +110,19 @@ 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 }) },
-    { target: ".about",   guard: ({ event }) => event.to === "#about",   reenter: false, actions: assign({ params, query }) },
-    { target: ".login",   guard: ({ event }) => event.to === "#login",   reenter: false, actions: assign({ params, query }) },
-    { target: ".profile", guard: ({ event }) => event.to === "#profile", reenter: false, actions: assign({ params, query }) },
+    { target: ".home",    matches: { to: "#home" },    reenter: false, context: ({ context, event }) => ({ params, query }) },
+    { target: ".about",   matches: { to: "#about" },   reenter: false, context: ({ context, event }) => ({ params, query }) },
+    { target: ".login",   matches: { to: "#login" },   reenter: false, context: ({ context, event }) => ({ params, query }) },
+    { target: ".profile", matches: { to: "#profile" }, reenter: false, context: ({ context, event }) => ({ params, query }) },
   ],
 }
 ```
 
+Each generated transition is a config object. `matches` selects the event by its `to` field, and `context` returns the patch that XState merges into the context. A `play.route` transition of your own comes after the generated ones, as the fallback.
+
 `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
@@ -124,6 +130,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" });
 
@@ -149,25 +159,19 @@ actor.send({
 
 ### `always` Guards — Protected Routes
 
-Use XState `always` transitions to protect states. If the guard fires, the machine redirects _before_ the state is fully entered:
+Use XState `always` transitions to protect states. If the function returns a target, the machine redirects _before_ the state is fully entered:
 
-```typescript
+```typescript fragment
 dashboard: {
   id: "dashboard",
   meta: { route: "/dashboard" },
-  always: {
-    // If not authenticated, redirect to login immediately
-    guard: ({ context }) => !context.isAuthenticated,
-    target: "login",
-  },
+  // If not authenticated, redirect to login immediately
+  always: ({ context }) => (context.isAuthenticated ? undefined : { target: "login" }),
 },
 profile: {
   id: "profile",
   meta: { route: "/profile/:username" },
-  always: {
-    guard: ({ context }) => !context.isAuthenticated,
-    target: "login",
-  },
+  always: ({ context }) => (context.isAuthenticated ? undefined : { target: "login" }),
 },
 ```
 
@@ -177,26 +181,21 @@ profile: {
 
 Domain events placed at the root `on:` level are handled from any state:
 
-```typescript
+```typescript fragment
 const authMachine = authSetup.createMachine(
 	formatPlayRouteTransitions({
 		// ...
 		on: {
-			"auth.login": {
-				target: ".dashboard",
-				guard: ({ context }) => !context.isAuthenticated,
-				actions: authSetup.assign({
-					isAuthenticated: true,
-					username: ({ event }) => (event.type === "auth.login" ? event.username : null),
-				}),
+			"auth.login": ({ context, event }) => {
+				if (context.isAuthenticated) return;
+				return {
+					target: ".dashboard",
+					context: { isAuthenticated: true, username: event.username },
+				};
 			},
-			"auth.logout": {
-				target: ".home",
-				guard: ({ context }) => context.isAuthenticated,
-				actions: authSetup.assign({
-					isAuthenticated: false,
-					username: null,
-				}),
+			"auth.logout": ({ context }) => {
+				if (!context.isAuthenticated) return;
+				return { target: ".home", context: { isAuthenticated: false, username: null } };
 			},
 		},
 		states: {/* ... */},
@@ -207,6 +206,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 +249,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 +282,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

@@ -16,27 +16,24 @@ Applicable patterns:
 ## Complete Code
 
 ```typescript
-import { setup } from "xstate";
+import { setup, types } from "xstate";
 import { definePlayer, compose, PlayerActor } from "@xmachines/play-xstate";
 import { formatPlayRouteTransitions } from "@xmachines/play-xstate/routing";
 import { withRouting } from "@xmachines/play-xstate/routing";
+import type { PlayRouteEvent } from "@xmachines/play-router";
 
-// 1. Typed setup
+// 1. Typed setup. The events are a map from the type of each event to its payload.
 const trafficSetup = setup({
-	types: {
-		context: {} as {
+	schemas: {
+		context: types<{
 			params: Record<string, string>;
 			query: Record<string, string>;
+		}>(),
+		events: {
+			timer: types<void>(),
+			"play.route": types<Omit<PlayRouteEvent, "type">>(),
 		},
-		events: {} as
-			| { type: "timer" }
-			| {
-					type: "play.route";
-					to: string;
-					params?: Record<string, string>;
-					query?: Record<string, string>;
-			  },
-		input: {} as undefined,
+		meta: types<{ route?: string }>(),
 	},
 });
 
@@ -55,17 +52,17 @@ const trafficMachine = trafficSetup.createMachine(
 			red: {
 				id: "red",
 				meta: { route: "/red" },
-				on: { timer: "green" },
+				on: { timer: { target: "green" } },
 			},
 			green: {
 				id: "green",
 				meta: { route: "/green" },
-				on: { timer: "yellow" },
+				on: { timer: { target: "yellow" } },
 			},
 			yellow: {
 				id: "yellow",
 				meta: { route: "/yellow" },
-				on: { timer: "red" },
+				on: { timer: { target: "red" } },
 			},
 		},
 	}),
@@ -106,13 +103,13 @@ 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": [
-    { target: ".red",    guard: ({ event }) => event.to === "#red",    reenter: false, actions: assign({ params, query }) },
-    { target: ".green",  guard: ({ event }) => event.to === "#green",  reenter: false, actions: assign({ params, query }) },
-    { target: ".yellow", guard: ({ event }) => event.to === "#yellow", reenter: false, actions: assign({ params, query }) },
+    { target: ".red",    matches: { to: "#red" },    reenter: false, context: ({ context, event }) => ({ params, query }) },
+    { target: ".green",  matches: { to: "#green" },  reenter: false, context: ({ context, event }) => ({ params, query }) },
+    { target: ".yellow", matches: { to: "#yellow" }, reenter: false, context: ({ context, event }) => ({ params, query }) },
   ],
 }
 ```
@@ -120,7 +117,8 @@ on: {
 **Requirements:**
 
 - 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.
+- The machine's context must include `params` and `query` fields (both `Record<string, string>`), because `formatPlayRouteTransitions` writes them on every `play.route` transition.
+- Each generated transition is a config object: `matches` selects the event by its `to` field, and `context` returns the patch that XState merges into the context. The list holds the generated transitions first, and a `play.route` transition of your own last, as the fallback. The config types of XState 6 declare one transition for each event, and its runtime reads a list in its order.
 - `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 +127,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());
@@ -147,6 +149,6 @@ unwatch();
 
 ## Next Steps
 
-- **[Form Validation Example](form-validation.md)** — Context mutations with `setup.assign` and guards
+- **[Form Validation Example](form-validation.md)** — Context patches and guards in transition functions
 - **[Routing Patterns](routing-patterns.md)** — Parameter routes, relative routes, and `always` auth guards
 - **[Play RFC](../rfc/play.md)** — Complete architectural specification

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                                                                                                                                               |
 | -------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -102,8 +102,7 @@ This is why the invariant is called **State-Driven Reset** in the Play RFC.
 
 An adapter extends the actor class of its own engine. [`PlayerActor`](../api/@xmachines/play-xstate/index/classes/PlayerActor.md) of [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md) extends `Actor` of XState, which means:
 
-- XState's inspection API works ([`@statelyai/inspect`](https://stately.ai/docs/inspector) — see [Inspecting a Running Actor](inspector.md))
-- XState DevTools attach to actors normally
+- The inspection API of XState works: the `inspect` option receives the `@xstate.actor` and `@xstate.transition` events of the actor — see [Inspecting a Running Actor](inspector.md)
 - The full XState ecosystem (testing utilities, visualization) is compatible
 
 [`PlayActor`](../api/@xmachines/play-actor/interfaces/PlayActor.md) asks for two members: a reactive `state` property of type `Atom<TSnapshot>`, and a typed `send`. `state` is the single point where the pull-based snapshot API of an engine is bridged to the push-based atom system.
@@ -116,27 +115,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 +148,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 +161,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, types } from "xstate";
+
+const machine = setup({
+	schemas: {
+		input: types<{ userId: string } | undefined>(),
+		context: types<{ 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));