nanoeffects 0.29.0 → 0.31.0

package/llms-full.txt

@@ -9,7 +9,7 @@ Rules that generated code often gets wrong:
 - A handler gets the payload and a task context: `(payload, ctx)`. The context has `signal`, `emit`, `on`, `run`. Pass `ctx.signal` to `fetch`.
 - Effects take `ctx` as the first argument: `retry(ctx, fn, options)`, `timeout(ctx, ms, fn)`, `take(ctx, "event")`.
 - Policies wrap a handler: `bus.on("search", latest(async (query, ctx) => { ... }))`.
-- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `tracePlugin`), `nanoeffects/dev`.
+- Each part is imported from its own path: `nanoeffects` (`createBus`), `nanoeffects/policies`, `nanoeffects/effects`, `nanoeffects/actions`, `nanoeffects/redux`, `nanoeffects/observable`, `nanoeffects/react` (`reactPlugin`, adds `bus.useEmitter` and `bus.useEventState`; `usePolicy`; needs React), `nanoeffects/svelte` (`sveltePlugin`, adds `bus.eventStore`; needs Svelte), `nanoeffects/vue` (`vuePlugin`, adds `bus.watchEmitter` and `bus.useEventRef`; needs Vue), `nanoeffects/trace` (`createTracer`, loggers, `graphLogger`, `tracePlugin`), `nanoeffects/guard` (`loopGuardPlugin`), `nanoeffects/dev`.
 - `bus.emit(action(payload))` runs the action's handler and returns its result. Plain events return nothing.
 
 ---
@@ -17,14 +17,16 @@ Source: docs/guide.md
 
 # Guide
 
-Climb one step at a time: small bus → policies → effects → handlers and modules. Stop when your project has what it needs.
+> **Levels A to D.** Read first: [README](../README.md) (install and the first example).
 
-| Your project | Stop after |
-| ------------ | ---------- |
-| Widget / prototype | §1–2 |
-| SPA with async UI | §3–4 |
-| Unreliable network / long flows | §5–6 |
-| Domain logic off the UI | §7–9 |
+Climb one step at a time: small bus → policies → effects → handlers and modules. Stop when your project has what it needs. Install the package first: `npm install nanoeffects` (details in the [README](../README.md#install)). The levels A to D are described in the [map of the docs](README.md#the-ladder-from-a-to-f).
+
+| Level | Your project | Stop after |
+| ----- | ------------ | ---------- |
+| A | Widget / prototype | §1–2 |
+| B | SPA with async UI | §3–4 |
+| C | Unreliable network / long flows | §5–6 |
+| D | Domain logic off the UI | §7–9 |
 
 Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
 
@@ -39,7 +41,7 @@ Runnable code for every step: [`examples/guide.ts`](../examples/guide.ts).
 - [5. Add retry and timeout](#5-add-retry-and-timeout)
 - [6. Run work in parallel or wait for an event](#6-run-work-in-parallel-or-wait-for-an-event)
 - [7. Name events three ways](#7-name-events-three-ways)
-- [8. Bind a handler to an action later](#8-bind-a-handler-to-an-action-later)
+- [8. Replace a handler on the fly](#8-replace-a-handler-on-the-fly)
 - [9. Mount a domain as a module](#9-mount-a-domain-as-a-module)
 - [10. Add types when you want checking (optional)](#10-add-types-when-you-want-checking-optional)
 - [11. Isolate errors and warn on typos](#11-isolate-errors-and-warn-on-typos)
@@ -65,7 +67,12 @@ bus.emit("greet", "Bob"); // nobody listens
 
 Handlers run at once, in subscription order.
 
-`bus.once` is like `on`, but the handler runs at most once (it is removed before it is invoked). `bus.off("greet")` clears every listener of that event; `bus.off()` with no arguments clears **every** listener on the bus (including `"*"`). `ctx.off` is the same `off` as the bus’s — so `ctx.off()` also clears the whole bus. `bus.get("greet")` gives the listeners that event has right now; `bus.get("greet").length === 0` tells that nobody listens any more (`"*"` gives the any-event listeners, which a named event does not include; `bus.get()` with no name gives every listener of every event). It takes the event name as a string: for an action creator use `creator.type`.
+Four more calls cover most of what you need from the bus itself:
+
+- `bus.once(event, handler)` is like `on`, but the handler runs at most once (it is removed before it is invoked).
+- `bus.off("greet")` clears every listener of that event.
+- `bus.off()` with no arguments clears **every** listener on the bus, `"*"` included. `ctx.off` is the same `off` as the bus's, so `ctx.off()` also clears the whole bus.
+- `bus.get("greet")` gives the listeners that event has right now, so `bus.get("greet").length === 0` tells that nobody listens any more. `"*"` gives the any-event listeners, which a named event does not include; `bus.get()` with no name gives every listener of every event. It takes the event name as a string: for an action creator use `creator.type`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -83,6 +90,8 @@ bus.off(); // clear every subscription
 
 ### Listen to every event
 
+You can skip this and the next section on a first read.
+
 `bus.on("*", fn)` runs for every event of the bus. It is for logging, debugging, or forwarding events elsewhere. The handler gets the payload and the task context as usual, and `ctx.type` is the name of the event.
 
 ```js
@@ -105,7 +114,7 @@ unbind();
 
 ### Pick events with a function
 
-To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
+This is for level B and later. To listen to a group of events, such as every `user/*` event, `"*"` and a check of `ctx.type` do the job but leave the check to you. `matchPlugin` lets `on` take a function that picks the events. The function gets `{ type, payload }` of each event, and the handler runs when it returns true.
 
 <!-- docs-check: new -->
 
@@ -251,7 +260,7 @@ const searchLatest = latest(async (query, { signal }) => {
 bus.on("search", debounce(300, searchLatest));
 ```
 
-Full options: [Policies](policies.md). No bus? A policy also works as a plain function: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
+Full options: [Policies](policies.md). No bus? A policy also works as a plain function: [`withPolicy`: call a policy outside a bus](policies.md#withpolicy-call-a-policy-outside-a-bus).
 
 ## 5. Add retry and timeout
 
@@ -306,7 +315,7 @@ import { all, delay, race, take } from "nanoeffects/effects";
 const bus = createBus();
 
 // all — run together; one failure cancels the rest
-// child — the context of that starter: it has the `signal`, so the request stops with the group
+// child — the context of that request: it has the `signal`, so the request stops with the group
 bus.on("search", async (id, ctx) => {
   const { user, posts } = await all(ctx, {
     user: (child) => api.user(id, child),
@@ -381,9 +390,11 @@ bus.emit(double(21)); // 42
 
 Use strings for the plain case. Use objects when other code already builds actions. Give `createAction` a handler when you need a result from `emit`.
 
-## 8. Bind a handler to an action later
+## 8. Replace a handler on the fly
 
-An action may carry its handler, as `double` above, or get it later from a registry — another file, or a fake in a test. An action with no handler is an event until one is bound.
+**Problem.** The handler of an action is in the file of the feature, but a test needs a fake, or another layer owns the work. If the handler sits in `createAction`, the event file is tied to the work.
+
+**What to do.** Create the action without a handler: it is an event. Bind the real handler with `setHandler` when the bus is made. Later, `actions.handle` binds a newer handler that wins until you remove it.
 
 ```js
 // user.js
@@ -395,26 +406,32 @@ export const getUser = createAction("user/get"); // no handler yet: an event
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
-import { actionsPlugin } from "nanoeffects/actions";
+import { actionsPlugin, setHandler } from "nanoeffects/actions";
+import { getUser } from "./user";
 
 export const bus = createBus();
-// actionsPlugin — registry of handlers for this bus
-export const actions = bus.use(actionsPlugin());
+
+// setHandler — binds the real handler to the action
+const realUser = setHandler(getUser, (id) => api.user(id));
+
+// actionsPlugin — the registry of bound handlers of this bus
+export const actions = bus.use(actionsPlugin([realUser]));
 ```
 
 ```js
 import { bus, actions } from "./bus";
 import { getUser } from "./user";
 
-bus.emit(getUser("1")); // nothing is bound: only an event
+const user = await bus.emit(getUser("1")); // the real handler answers
 
-const unregister = actions.handle(getUser, (id) => api.user(id));
-const user = await bus.emit(getUser("1"));
+// actions.handle — a newer binding wins, for example a fake in a test
+const restore = actions.handle(getUser, (id) => ({ id, name: "test" }));
+const fake = await bus.emit(getUser("1")); // the fake answers
 
-unregister();
+restore(); // the real handler answers again
 ```
 
-Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can register handlers and remove them on unmount. More in [Actions](actions.md).
+Each bus has its own registry. A [module](#9-mount-a-domain-as-a-module) can bind handlers and remove them on unmount. More in [Actions](actions.md#bind-a-handler-later).
 
 ## 9. Mount a domain as a module
 
@@ -530,11 +547,545 @@ More in [Errors](errors.md).
 | Guarantees | [Semantics](semantics.md) |
 | Which import | [Package entries](package.md) |
 
+---
+Source: docs/recipes.md
+
+# Common tasks
+
+> **Levels A to E.** Read first: [README](../README.md).
+
+Each task below starts with the problem, then a short solution. Where the page has more to say, the last line links to it. The tasks go from the simplest to the most involved.
+
+## On this page
+
+- [Events and handlers](#events-and-handlers)
+  - [A handler needs an API client, a store or a logger](#a-handler-needs-an-api-client-a-store-or-a-logger)
+  - [One handler fails, the others must still run](#one-handler-fails-the-others-must-still-run)
+  - [A typo in an event name](#a-typo-in-an-event-name)
+- [Races and repeated actions in the UI](#races-and-repeated-actions-in-the-ui)
+  - [An old response overwrites a new one](#an-old-response-overwrites-a-new-one)
+  - [A search box sends a request on every key](#a-search-box-sends-a-request-on-every-key)
+  - [A second click sends a second request](#a-second-click-sends-a-second-request)
+  - [Messages must go out in order](#messages-must-go-out-in-order)
+  - [A "Delete" button in a list blocks the other rows](#a-delete-button-in-a-list-blocks-the-other-rows)
+- [An unreliable network and long flows](#an-unreliable-network-and-long-flows)
+  - [A request fails sometimes: retry and backoff](#a-request-fails-sometimes-retry-and-backoff)
+  - [A request hangs: timeout](#a-request-hangs-timeout)
+  - [Refresh data every N seconds: poll](#refresh-data-every-n-seconds-poll)
+  - [Wait for another event inside a handler: take](#wait-for-another-event-inside-a-handler-take)
+  - [Load several things at once: all](#load-several-things-at-once-all)
+  - [Take the fastest answer: race](#take-the-fastest-answer-race)
+- [Features and domain logic](#features-and-domain-logic)
+  - [Get the result of emit](#get-the-result-of-emit)
+  - [Group a feature with its handlers: modules](#group-a-feature-with-its-handlers-modules)
+  - [Do not leave subscriptions after a widget closes](#do-not-leave-subscriptions-after-a-widget-closes)
+- [Stop work on a server](#stop-work-on-a-server)
+- [Debugging: what ran and why](#debugging-what-ran-and-why)
+- [Other libraries in the project](#other-libraries-in-the-project)
+- [Classes and TypeScript](#classes-and-typescript)
+  - [Use the bus in a class](#use-the-bus-in-a-class)
+  - [Keep the types of the bus in many files](#keep-the-types-of-the-bus-in-many-files)
+- [Examples of whole apps](#examples-of-whole-apps)
+
+## Events and handlers
+
+### A handler needs an API client, a store or a logger
+
+Many handlers use the same `api` client or logger. Importing it in every handler file ties the handlers to one client and makes tests harder. Put it on the bus once, and every task gets it on `ctx`.
+
+```js
+import { createBus } from "nanoeffects";
+
+// createBus({ context }) — every task gets these fields on ctx
+const bus = createBus({ context: { api, logger } });
+
+bus.on("save", async (draft, { api, logger }) => {
+  await api.save(draft);
+  logger.info("saved");
+});
+```
+
+More: [Context fields](context.md).
+
+### One handler fails, the others must still run
+
+Two handlers listen to `order/placed`: one sends analytics, the other saves the order. By default the first error stops the loop, so a broken analytics call can keep the order from being saved. With `onError` every handler runs and the errors go to one place.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus({
+  // onError — isolates the handlers: a thrown error goes here and the next handler still runs
+  onError: (error, { type }) => report(error, type),
+});
+
+const sendAnalytics = (order) => {
+  throw new Error(`analytics is down for ${order.id}`);
+};
+const saveOrder = (order) => console.log("saved", order.id);
+
+bus.on("order/placed", sendAnalytics); // throws
+bus.on("order/placed", saveOrder); // still runs
+
+bus.emit("order/placed", { id: 1 }); // saved 1
+```
+
+More: [Errors and unheard events](errors.md#isolate-failing-handlers).
+
+### A typo in an event name
+
+`emit("serch")` does not fail: no one listens to that name, so nothing happens, and you look for the bug in the handler. `onUnhandled` warns about an event that nobody heard. Turn it on in development.
+
+```js
+import { createBus } from "nanoeffects";
+
+const bus = createBus({
+  // onUnhandled — called when an event has no listeners
+  onUnhandled: ({ type }) => console.warn(`Nobody listens to "${type}"`),
+});
+
+bus.on("search", (query) => console.log(query));
+
+bus.emit("serch", "nano"); // warning: Nobody listens to "serch"
+```
+
+More: [Warn when nobody listens](errors.md#warn-when-nobody-listens).
+
+## Races and repeated actions in the UI
+
+### An old response overwrites a new one
+
+A user types `re`, then `react`. Two requests are in flight. The server answers `react` fast and `re` slowly, so the answer for `re` arrives last and replaces the right list with the wrong one. This is what a plain React effect does:
+
+```jsx
+import { useEffect, useState } from "react";
+
+export function Search({ query }) {
+  const [items, setItems] = useState([]);
+
+  useEffect(() => {
+    // two requests are in flight, and the one that finishes last wins, even the older one
+    api.search(query).then(setItems);
+  }, [query]);
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Move the request into a handler with `latest`: a new `search` aborts the previous request, and the aborted one delivers no result.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// latest — a new "search" aborts the previous one and drops its result
+bus.on(
+  "search",
+  latest(async (query, { signal }) => {
+    // signal — lets the browser cancel the request itself
+    const items = await api.search(query, { signal });
+    bus.emit("results", items);
+  }),
+);
+
+bus.on("results", (items) => render(items));
+```
+
+More: [Cancel stale requests](cancel-stale-requests.md), [Policies](policies.md#latest-abort-the-previous-run), and the component side in [Build a sign-up form in React](react.md).
+
+### A search box sends a request on every key
+
+Typing `react` sends five requests, and the list flickers. `debounce` waits for a pause in typing; `latest` aborts the request that is still in flight.
+
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// latest — a new search aborts the request in flight
+const searchLatest = latest(async (query, { signal }) => {
+  const items = await api.search(query, { signal });
+  bus.emit("results", items);
+});
+
+// debounce — start after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+```
+
+More: [Pause between requests](debounce-and-abort.md).
+
+### A second click sends a second request
+
+A user double-clicks "Sign up" on a slow network, and two accounts are created. `leading` drops every call that comes while the first one still runs.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// leading — a call that comes while the previous one runs is dropped
+bus.on(
+  "form/submitted",
+  leading(async (form, { signal }) => {
+    await api.signUp(form, { signal });
+  }),
+);
+```
+
+More: [Prevent a double submit](prevent-double-submit.md).
+
+### Messages must go out in order
+
+In a chat, a user sends `Hello` and then `How are you?` within a second. Two parallel requests can reach the server in the wrong order. `queue` sends the next message only after the previous one is delivered.
+
+```js
+import { createBus } from "nanoeffects";
+import { queue } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// queue — the next message waits until the previous one is delivered
+bus.on(
+  "message/sent",
+  queue(async (message, { signal }) => {
+    await api.sendMessage(message, { signal });
+  }),
+);
+```
+
+More: [Policies, `queue`](policies.md#run-calls-one-after-another-with-queue).
+
+### A "Delete" button in a list blocks the other rows
+
+You protect "Delete" with `leading`. While one row is deleted, clicks on the other rows are dropped too, because the whole handler has one state. `key` gives every row its own state.
+
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// leading with key — every row id has its own state, so other rows are not blocked
+bus.on(
+  "row/deleted",
+  leading(
+    async (row, { signal }) => {
+      await api.deleteRow(row.id, { signal });
+    },
+    { key: (row) => row.id },
+  ),
+);
+```
+
+More: [Policies, `key`](policies.md#key-isolate-state-by-key).
+
+## An unreliable network and long flows
+
+### A request fails sometimes: retry and backoff
+
+A request fails once in a while because of the network. `retry` repeats it. If the server is overloaded, repeating at once makes it worse, so use `backoff` to make the pause longer with each attempt.
+
+```js
+import { createBus } from "nanoeffects";
+import { backoff, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+// retry — repeat the request after an error, up to 4 attempts
+const loadWithRetry = retry((id, { signal }) => api.getUser(id, { signal }), {
+  times: 4,
+  // backoff — the pause grows (200, 400, 800 ms) with a random part, so clients do not retry at the same moment
+  delay: backoff({
+    base: 200,
+    max: 5000,
+    jitter: true,
+  }),
+});
+
+bus.on("user/opened", loadWithRetry);
+```
+
+More: [`backoff`](effects.md#backoff).
+
+### A request hangs: timeout
+
+A request does not fail and does not answer, and the spinner spins forever. `timeout` rejects the call after the time you set and aborts the request.
+
+```js
+import { createBus } from "nanoeffects";
+import { timeout } from "nanoeffects/effects";
+
+const bus = createBus();
+
+// timeout — reject with TimeoutError and abort the request after 5 s
+const loadOnce = timeout(5000, (id, { signal }) => api.getUser(id, { signal }));
+
+bus.on("user/opened", loadOnce);
+```
+
+More: [`timeout`](effects.md#timeout).
+
+### Refresh data every N seconds: poll
+
+A dashboard must refresh its numbers every ten seconds while it is open. `poll` is an effect: it calls your function on a timer and ends when the task is aborted, so a closed dashboard does not keep asking.
+
+```js
+import { createBus } from "nanoeffects";
+import { poll } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("dashboard/opened", async (_, ctx) => {
+  // stop the polling when the user leaves
+  ctx.on("dashboard/closed", () => ctx.abort());
+
+  // poll — call refresh every 10 s until the task is aborted
+  await poll(ctx, () => refresh(), 10_000);
+});
+```
+
+More: [`poll`](effects.md#poll).
+
+### Wait for another event inside a handler: take
+
+After a login the handler must wait for the user to log out before it cleans up. Instead of a flag and a second handler, `take` pauses the handler until the next event with that name.
+
+```js
+import { createBus } from "nanoeffects";
+import { take } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("login", async (user, ctx) => {
+  // take — pause this handler until the next "logout"
+  const reason = await take(ctx, "logout");
+  cleanup(user, reason);
+});
+```
+
+More: [`take`](effects.md#take).
+
+### Load several things at once: all
+
+A profile page needs the user and the posts. Loading them one after another is slow. `all` runs both requests together and aborts the second one if the first fails.
+
+```js
+import { createBus } from "nanoeffects";
+import { all } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("profile/opened", async (id, ctx) => {
+  // all — run both requests together; if one fails, the other is aborted. child carries the signal of its own request
+  const { user, posts } = await all(ctx, {
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
+  });
+
+  ctx.emit("profile/loaded", { user, posts });
+});
+```
+
+### Take the fastest answer: race
+
+The same data lives on two servers, and you want the answer of the faster one. `race` returns the first answer and aborts the other request.
+
+```js
+import { createBus } from "nanoeffects";
+import { race } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("user/opened", async (id, ctx) => {
+  // race — the first answer wins, the slower request is aborted
+  const result = await race(ctx, {
+    primary: (child) => api.getUser(id, child),
+    backup: (child) => api.getUserFromBackup(id, child),
+  });
+
+  const user = "primary" in result ? result.primary : result.backup;
+  ctx.emit("user/loaded", user);
+});
+```
+
+More: [`all`](effects.md#all), [`race`](effects.md#race).
+
+## Features and domain logic
+
+### Get the result of emit
+
+`emit` of a plain event returns nothing, so to get an answer you need a second event. An action with a handler returns the result of its handler right from `emit`.
+
+```js
+import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+
+const bus = createBus();
+
+// createAction with a handler — emit runs it and returns what it returns
+const double = createAction("math/double", (value) => value * 2);
+
+const result = bus.emit(double(21)); // 42
+```
+
+More: [Actions, jobs and modules](actions.md).
+
+### Group a feature with its handlers: modules
+
+A feature has several subscriptions, and you must remember to remove each one. A module registers them together and removes them all with one `unmount`.
+
+```js
+import { createBus } from "nanoeffects";
+import { createModule, modulePlugin } from "nanoeffects/actions";
+
+// createModule — one feature; unmount cancels everything it registered
+const greeting = createModule("greeting", (m) => {
+  m.on("greet", (name) => console.log(`hello ${name}`));
+});
+
+const bus = createBus();
+const app = bus.use(modulePlugin([greeting]));
+
+app.unmount(greeting); // the subscription is gone
+```
+
+More: [Modules](actions.md#modules) and [the guide](guide.md#9-mount-a-domain-as-a-module).
+
+### Do not leave subscriptions after a widget closes
+
+A chat widget subscribes to the bus when it opens. If it closes without unsubscribing, the handlers stay: memory grows with every open, and they still update a widget that is gone. A module that you mount on open and unmount on close leaves nothing behind.
+
+```js
+import { createBus } from "nanoeffects";
+import { createModule, modulePlugin } from "nanoeffects/actions";
+
+// the module owns the listeners of the widget
+const chatModule = createModule("chat", (m) => {
+  m.on("message/received", (message) => render(message));
+});
+
+const bus = createBus();
+const app = bus.use(modulePlugin());
+
+const stop = app.mount(chatModule); // the widget is opened: the listeners are on the bus
+
+stop(); // the widget is closed: no listeners are left
+console.log(bus.get("message/received").length); // 0
+```
+
+More: [Build a chat widget](chat-widget.md).
+
+## Stop work on a server
+
+A client closes the tab, but the server goes on asking other services for it. Create an `AbortController` for the request, abort it when the connection closes, and pass its signal to `emit`: `timeout`, `retry` and the request itself stop.
+
+```js
+import { createBus } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — emit accepts { signal }
+const bus = createBus().use(signalPlugin());
+
+const getUser = createAction("user/get", (id, { signal }) => api.getUser(id, { signal }));
+
+export async function handleRequest(request, reply) {
+  const controller = new AbortController();
+
+  // close — the client left: abort everything started for this request
+  reply.raw.on("close", () => controller.abort());
+
+  // the task, and the requests it made, stop with the controller
+  return bus.emit(getUser(request.params.id), { signal: controller.signal });
+}
+```
+
+More: [Stop work on a server](server.md), including WebSocket and queue workers.
+
+## Debugging: what ran and why
+
+An effect fired and you cannot tell which event caused it. The tracer logs every task with its parent, so you see the chain of events.
+
+```js
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, tracePlugin } from "nanoeffects/trace";
+
+// createTracer — send every task to the console
+const trace = createTracer(consoleLogger());
+
+// tracePlugin — also report every emit
+const bus = createBus({ trace }).use(tracePlugin());
+
+bus.on("search", (query, ctx) => ctx.emit("results", [query]));
+bus.emit("search", "nano"); // the log shows: search · emit, then results · emit with search as the cause
+```
+
+More: [Trace tasks](tracing.md). To reload modules without a page refresh, see [Hot reload](hmr.md).
+
+## Other libraries in the project
+
+- **Redux Toolkit, Zustand, MobX or Pinia.** [Connect a store](stores.md).
+- **React Query, SWR or RTK Query.** [Query libraries](query-libraries.md).
+- **RxJS.** [Use nanoeffects next to RxJS](migrating-from-rxjs.md) and [Observables](observable.md).
+- **Moving from redux-saga.** [Coming from redux-saga](migrating-from-saga.md).
+- **Moving from Effector.** [Coming from Effector](migrating-from-effector.md).
+- **Moving from mitt or nanoevents.** [Coming from mitt](migrating-from-mitt.md).
+
+## Classes and TypeScript
+
+### Use the bus in a class
+
+Your logic lives in classes, and each instance must remove its subscriptions when it is no longer needed. `Emitter` gives every instance its own bus and a `dispose` that removes all of its subscriptions.
+
+```js
+import { Emitter } from "nanoeffects/oop";
+
+// Emitter — every instance gets its own bus with on, once, off, emit and dispose
+class VideoService extends Emitter {
+  constructor() {
+    super();
+    this.on("played", () => console.log("playing"));
+  }
+}
+
+const video = new VideoService();
+video.emit("played");
+
+video.dispose(); // removes every subscription of this instance
+```
+
+More: [Use the bus from a class](oop.md).
+
+### Keep the types of the bus in many files
+
+Handlers and modules are in different files, and TypeScript must know the payloads and the fields of `ctx`. See [TypeScript in many files](typescript.md).
+
+## Examples of whole apps
+
+- **A form with a username check and a submit, in React.** [Build a sign-up form in React](react.md).
+- **A whole app in layers: entities, features, modules, a server.** [Build a chat](chat-example.md).
+- **A widget that listens only while it is open.** [Build a chat widget](chat-widget.md).
+- **Vue.** [Use nanoeffects in a Vue app](vue.md).
+- **Svelte.** [Use nanoeffects in a Svelte app](svelte.md).
+- **A ready project.** [Start a project from a template](starter.md).
+
 ---
 Source: docs/starter.md
 
 # Start a project from a template
 
+> **Level A.** Read first: nothing: this page makes a project for you.
+
 Use this page when you want a running project in one command instead of wiring Vite and the bus by hand. It makes a small app with a search box that waits for you to stop typing (`debounce`) and aborts the older request when a newer one starts (`latest`).
 
 You need Node 18 or newer.
@@ -661,17 +1212,23 @@ Source: docs/motivation.md
 
 # Why nanoeffects exists
 
-Read this page to see why the library exists and when to pick it. The main reason is to take business logic and side effects out of React, Vue or Svelte components and write them as plain `async` functions, with cancellation, retries and a context for dependencies. The second part of the page is for SDKs, core libraries and micro-frontend shells, where a shared dependency is a shared risk. It does not teach the API: start with the [Guide](guide.md).
+> **Level A.** Read first: [README](../README.md).
+
+Read this page to see why the library exists. It moves business logic and side effects out of React, Vue or Svelte components into plain `async` functions, with cancellation, retries and a context for dependencies. It does not teach the API: start with the [Guide](guide.md).
 
-## The main reason: logic outside the UI
+## Moving logic out of the UI
 
 Components that hold requests, timers and races are hard to test and easy to break. The usual cure is services and pure functions outside the UI, and then every service needs the same things: to cancel work that is no longer wanted, to retry, to share dependencies, and to show what ran and why.
 
-The common tools ask a lot: redux-saga writes this logic as generators, and RxJS as streams and operators. nanoeffects keeps ordinary `async` functions and adds one idea, the `AbortSignal`. The event bus is its heart but not its value: any emitter can send events (`nanoevents` is about 100 bytes, and there are [dozens more](https://github.com/gajus/sister#similar-libraries)). What nanoeffects adds is cancellable tasks, policies and effects, a context that works as a small container for dependencies, actions and modules to group a feature, and [tracing](tracing.md) with an adapter for Redux DevTools. It also fits what a project already has: recipes and small adapters for [stores](stores.md) (Redux Toolkit, Zustand, MobX, Pinia), an [RxJS](migrating-from-rxjs.md) bridge, and helpers for [React](react.md), [Vue](vue.md) and [Svelte](svelte.md), so nothing has to be rewritten to start.
+The common tools ask a lot: redux-saga writes this logic as generators, and RxJS as streams and operators. nanoeffects keeps ordinary `async` functions and adds one idea, the `AbortSignal`.
+
+Another way to take logic out of the UI is a dependency injection (DI) container, such as the one in Angular or in any DI library. nanoeffects has no container, but it can do dependency injection at the level of the contract: a handler takes what it needs from `ctx`, and the bus decides what to give. See [Context fields](context.md).
 
-## When the constraint is a shared library
+The event bus is the heart of the library but not its value: any emitter can send events (`nanoevents` is about 100 bytes, and there are [dozens more](https://github.com/gajus/sister#similar-libraries)). What nanoeffects adds is cancellable tasks, policies and effects, a context that works as a small container for dependencies, actions and modules to group a feature, and [tracing](tracing.md) with an adapter for Redux DevTools. It also fits what a project already has: recipes and small adapters for [stores](stores.md) (Redux Toolkit, Zustand, MobX, Pinia), an [RxJS](migrating-from-rxjs.md) bridge, and helpers for [React](react.md), [Vue](vue.md) and [Svelte](svelte.md), so nothing has to be rewritten to start.
 
-A shared library (an SDK, a core package, a platform shell) is loaded by many apps. Whatever it depends on, the apps depend on too. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other.
+## Micro-frontends
+
+In micro-frontends every app can bring its own versions of the same libraries. State and event libraries are the worst case, because they keep **internal state and identity** (a store, a context, a class). Two copies or two versions of them do not merge: they silently stop seeing each other. Different versions and copies also do more than work out of step: they load more code and use more resources than one agreed copy would. So the goal is a project that is as simple as possible, with as few shared dependencies that hold state as possible.
 
 Module Federation makes this visible. Each remote can bring its own copy unless every team agrees on a `singleton` and a version range. The [Nx guide on library versions](https://nx.dev/docs/kb/manage-library-versions-with-module-federation) lists the result: libraries with internal state conflict, and a missing method in one version breaks callers written for another.
 
@@ -684,34 +1241,23 @@ Real cases from the libraries nanoeffects was compared with:
 | Effector | A library that uses `effector-react/scope` and is bundled into another project gets two instances. Its `Provider` is not seen by `useStore` of the app: "no scope found". | [effector#727](https://github.com/effector/effector/issues/727) |
 | RxJS | Two copies give two `Observable` classes. Types of one version do not fit the other, and operators added to one copy are missing on the other. The advice is "one version in `node_modules`". | [RxJS#2984](https://github.com/ReactiveX/rxjs/issues/2984), [neo4j-javascript-driver#978](https://github.com/neo4j/neo4j-javascript-driver/issues/978) |
 
-A library that is **not** a shared singleton cannot break this way. nanoeffects has no dependencies and no module-level state: a bus is an object you create. Two copies, or two versions, of the package in one page are two independent buses. Nothing is registered globally, no `Provider` is needed, and the host app does not have to pick a version for you.
-
-## Why not the alternatives
+nanoeffects has no dependencies and no module-level state: a bus is an object you create. Two copies, or two versions, of the package in one page are two independent buses. Nothing is registered globally, no `Provider` is needed, and the host app does not have to pick a version for you.
 
-| Option | Why it did not fit |
-| ------ | ------------------ |
-| Redux (with sagas) | A store and a provider shared by every consumer, which is the risk above. `redux-saga` also has no cheap way to get an answer back from an event: effects talk through the store. |
-| Effector | A graph with global identity. A version or scope mismatch between the SDK and the app reaches the whole infrastructure. |
-| Zustand | Good state, but it is a store, not a way to run and cancel work. It is the natural place to hold state next to nanoeffects: see [Stores](stores.md). |
-| RxJS | Flexible, but learning its ecosystem (operators, subjects, schedulers) is a high entry cost for every developer who touches the SDK. The package is also not small: [Bundlephobia](https://bundlephobia.com/package/rxjs) reports 17.3 kB minified and gzipped for 7.8.2. |
-
-## What the library does instead
+## What the library does
 
 - **No dependencies, no global state.** It is safe to ship inside an SDK next to whatever the host app runs. It does not need a `singleton` entry in the Module Federation config.
 - **Small enough for a strict budget.** SDKs often get a few kilobytes for all third-party code. `createBus` is about 1.4 kB gzip (1.3 kB brotli); policies, effects and actions are separate entries you import only when you need them. See [Package entries](package.md).
-- **Simple first.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
+- **Easy to start.** `on` and `emit` are the whole model. Cancellation, retry and the rest are plain functions on top. The [Guide](guide.md) and [Coming from redux-saga](migrating-from-saga.md) map the familiar names.
 - **`emit` can return an answer.** An [action with a handler](actions.md) returns a result, so one module can ask another and wait for the reply. Events alone cannot do that, and it was the main thing missing from the Redux-based options.
 - **Easy to debug.** Event-driven code is hard to follow: you see an effect and not the event that caused it. Every task knows its parent, so [tracing](tracing.md) shows the chain of events, with loggers for the console, the Performance panel and Redux DevTools.
 
-## When this is not the right tool
-
-nanoeffects holds no state. If you need a store, keep Redux, Zustand or Effector and let the bus run the async work: [Stores](stores.md). If you already have streams everywhere, keep RxJS: [Use nanoeffects next to RxJS](migrating-from-rxjs.md).
-
 ---
 Source: docs/package.md
 
 # Choose a package entry
 
+> **Levels A to F.** Read first: [README](../README.md).
+
 Imports are split so you only load what you use. `createBus` stays small; the rest is another entry.
 
 ## Start with these three
@@ -740,7 +1286,8 @@ Each row is optional. The "when" column says what need brings you to it.
 | `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) | Svelte components |
 | `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) | Vue components |
 | `nanoeffects/dev` | `devPlugin` (no-op in production) | you look for leaks in development |
-| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) | you want to see what ran and why |
+| `nanoeffects/trace` | `createTracer`, the loggers (`graphLogger` finds event loops) and `tracePlugin` (names for the trace) | you want to see what ran and why |
+| `nanoeffects/guard` | `loopGuardPlugin`: refuses the emit that would pass a limit of a chain | a loop must not take the app down |
 
 The `...Plugin` names above are used with `bus.use`. [Plugins](plugins.md) lists all of them, what each returns, and the order to use them in.
 
@@ -754,105 +1301,13 @@ The package ships plain-text files for assistants that write code with it:
 
 Find them in `node_modules/nanoeffects/`, or load `llms-full.txt` from a CDN such as `https://unpkg.com/nanoeffects/llms-full.txt`. All match the installed version.
 
----
-Source: docs/stability.md
-
-# Know what is stable
-
-Use this page to decide what you can rely on. It says which imports are stable, what counts as a breaking change, which versions are supported, and which call forms stay.
-
-## See which entries are stable
-
-A stable entry follows the rules below. An unstable entry can change in any minor release; every change is written in the [CHANGELOG](../CHANGELOG.md), and nothing promises a deprecation period first.
-
-| Import | Status | Note |
-| ------ | ------ | ---- |
-| `nanoeffects` | Stable | `createBus` and the types of a bus |
-| `nanoeffects/effects` | Stable | `retry`, `timeout`, `poll`, `take`, `delay`, `all`, `allSettled`, `race`, `backoff`, `cancellable`, `effectsPlugin` |
-| `nanoeffects/policies` | Stable | `latest`, `leading`, `debounce`, `throttle`, `queue`, `withPolicy` |
-| `nanoeffects/actions` | Stable | `createAction`, `createJob`, `createModule` and their plugins |
-| `nanoeffects/trace` | Stable: the contract | `Tracer`, `Trace`, `TraceEvent`, `TraceLogger`, `Phase`, `EffectName` and `tracePlugin` |
-| `nanoeffects/trace` | Unstable: the tools | `createTracer`, `consoleLogger`, `performanceLogger`, `createTraceRecorder`, `reduxDevtools` and their option types |
-| `nanoeffects/scope` | Unstable | `scopePlugin`, `effect` |
-| `nanoeffects/match` | Unstable | `matchPlugin` |
-| `nanoeffects/signal` | Unstable | `signalPlugin` |
-| `nanoeffects/context` | Unstable | `contextPlugin` |
-| `nanoeffects/oop` | Unstable | `Emitter`, `extendBus`, `On`, `Once`, `WithBus`, `disposeBus` |
-| `nanoeffects/observable` | Unstable | `createObserve`, `Subject` |
-| `nanoeffects/redux` | Unstable | `createEffectsMiddleware` |
-| `nanoeffects/react` | Unstable | `reactPlugin`, `usePolicy` |
-| `nanoeffects/svelte` | Unstable | `sveltePlugin` |
-| `nanoeffects/vue` | Unstable | `vuePlugin` |
-| `nanoeffects/dev` | Unstable | `devPlugin` |
-
-The adapters (`react`, `vue`, `svelte`, `redux`) are unstable because they follow the APIs of other libraries and have had little use. They can become stable after the library has been in use for a while.
-
-## Know what is a breaking change
-
-For a stable entry, these changes are breaking:
-
-- A change in what a call does at run time.
-- A change in a type that stops code that compiled before from compiling.
-- A removed or renamed export.
-
-A stricter type that only finds mistakes in code that was already wrong is not breaking. It ships in a minor release with a note in the CHANGELOG.
-
-These are not covered by the promise:
-
-- Any unstable entry.
-- The text of the messages of `nanoeffects/dev`.
-- The payload details of trace events. The shape of an event (`id`, `parentId`, `rootId`, `type`, `effect`, `phase`) is covered; the contents of `payload` are not.
-
-Before version 1.0.0, a breaking change ships in a minor release under `### Breaking` in the CHANGELOG. From 1.0.0 it ships only in a major release.
-
-A deprecated export keeps working and is removed only in a major release. `RaceStarter` is deprecated: use `StarterOf` instead.
-
-## Check the supported versions
-
-| What | Supported |
-| ---- | --------- |
-| Node.js, the library | 18, 20, 22 and 24 (a smoke test runs the built package on each) |
-| Node.js, the dev tools and the trace in a browser | 22 and newer |
-| TypeScript | 5.9 and 7. The built declaration files are type-checked with TypeScript 5.9 in CI, and the source with TypeScript 7. Older versions are not tested. |
-| React | 18 or newer (`nanoeffects/react`) |
-| Vue | 3.3 or newer (`nanoeffects/vue`) |
-| Svelte | 5 or newer (`nanoeffects/svelte`) |
-
-The library has no dependencies. React, Vue and Svelte are optional peer dependencies of their own entries only.
-
-## Rely on these call forms
-
-`retry`, `timeout` and `poll` have three call forms, and all three stay:
-
-```js
-import { createBus } from "nanoeffects";
-import { race, retry } from "nanoeffects/effects";
-
-const bus = createBus();
-
-bus.on("open", async (id, ctx) => {
-  // with ctx: you pass the context, and the function takes the signal from it
-  const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 3 });
-
-  // as a starter: a group (race, all, allSettled, timeout) calls it with its child
-  const result = await race(ctx, {
-    user: retry((_, { signal }) => fetchUser(id, { signal }), { times: 3 }),
-  });
-});
-
-// as a Task: a function of (payload, ctx), which bus.on and ctx.run call
-bus.on("reload", retry((id, { signal }) => fetchUser(id, { signal }), { times: 3 }));
-```
-
-The forms are told apart by the arguments: a context first is the form with `ctx`; a function called with a payload and a context is the Task; the same function called by a group with one argument, its child, is the starter. The rule is part of the contract and does not depend on how many parameters your function declares.
-
-`all` and `allSettled` take options only in the form with `ctx`, `all(ctx, effects, { concurrency })`. The form without `ctx` has one argument, so a second one would look like the `ctx` form. `race` takes no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. See [Effects](effects.md#run-several-starters-together).
-
 ---
 Source: docs/plugins.md
 
 # Choose the plugins of a bus
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 and 2.
+
 Optional. A plugin adds one thing to a bus: fields on `ctx`, a method, a registry of handlers, diagnostics. Read this page when you want to know which plugins exist, what each one gives you, and in what order to use them. Skip it for a small bus: `createBus()` alone is enough.
 
 ## On this page
@@ -872,6 +1327,7 @@ Optional. A plugin adds one thing to a bus: fields on `ctx`, a method, a registr
   - [Hand the bus to a state manager: `emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin)
   - [Tell the bus when a React value changes: `reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin)
   - [Find leaks while you develop: `devPlugin`](#find-leaks-while-you-develop-devplugin)
+  - [Cut a loop that runs away: `loopGuardPlugin`](#cut-a-loop-that-runs-away-loopguardplugin)
 - [Put them together](#put-them-together)
 - [Use them in any order](#use-them-in-any-order)
 - [See what is not a plugin](#see-what-is-not-a-plugin)
@@ -900,6 +1356,7 @@ Find your need in the left column. No row fits: you need no plugin.
 | A React component that sends its value to the bus | [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) |
 | Names in the trace | [`tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin) |
 | Warnings about leaks while you develop | [`devPlugin`](#find-leaks-while-you-develop-devplugin) |
+| A loop that must not take the app down | [`loopGuardPlugin`](#cut-a-loop-that-runs-away-loopguardplugin) |
 
 ## Main plugins
 
@@ -909,7 +1366,7 @@ These four cover what most apps need: shared dependencies, effects, handlers and
 | ------ | ----------------- | ------ | ----------------- |
 | [`contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin) | Your own fields (a store, a client, a logger) on `ctx` of every handler. | `nanoeffects` | The same bus, typed with the fields |
 | [`effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin) | `race`, `all`, `delay` and your own effects on `ctx`, called without passing `ctx`. | `nanoeffects/effects` | The same bus, typed with the effects |
-| [`actionsPlugin`](#let-a-test-replace-a-handler-commandsplugin) | The handlers of actions in a registry, so a test can bind or replace one. | `nanoeffects/actions` | The registry `{ run, handle }` |
+| [`actionsPlugin`](#bind-or-replace-a-handler-actionsplugin) | The handlers of actions in a registry, so a test can bind or replace one. | `nanoeffects/actions` | The registry `{ run, handle }` |
 | [`modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin) | A module: the listeners, handlers and tasks of one domain, mounted and unmounted with one call. | `nanoeffects/actions` | The app `{ mount, unmount, isMounted, dispose, actions, createModule }` |
 
 ### Put a store or a client on every handler: `contextPlugin`
@@ -930,7 +1387,7 @@ A client that must stop with the task, such as an `axios` instance, goes in as `
 
 ### Use `race` and `delay` without `ctx`: `effectsPlugin`
 
-Effects such as `race`, `all`, `take` and `delay` are bound to the task, so a handler calls `race({ … })` and not `race(ctx, { … })`. Your own functions that take `{ signal }` first work too. More in [Effects](effects.md#put-selected-effects-on-ctx).
+Effects such as `race`, `all`, `take` and `delay` are bound to the task, so a handler calls `race({ … })` and not `race(ctx, { … })`. Your own functions that take `{ signal }` first work too. More in [Effects](effects.md#effectsplugin).
 
 ```js
 import { createBus } from "nanoeffects";
@@ -969,7 +1426,7 @@ const user = await bus.emit(getUser("1")); // { id: "1" }
 
 ### Mount a domain as one unit: `modulePlugin`
 
-A module groups the listeners, the bound handlers and the background tasks of one domain, and ends all of them when it is unmounted. It also makes [hot reload](hmr.md) work. More in [Modules](actions.md#mount-domains-with-modules).
+A module groups the listeners, the bound handlers and the background tasks of one domain, and ends all of them when it is unmounted. It also makes [hot reload](hmr.md) work. More in [Modules](actions.md#modules).
 
 ```js
 import { createBus } from "nanoeffects";
@@ -996,10 +1453,11 @@ Add one of these when you meet its need. None of them is required.
 | [`tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin) | `traceId` and `traceGroupId` for a trace: the root of an emitter, a flow, a named listener. | `nanoeffects/trace` | The same bus |
 | [`reactPlugin`](#tell-the-bus-when-a-react-value-changes-reactplugin) | A React hook that emits when a value of a component changes. | `nanoeffects/react` | The same bus, with `useEmitter` |
 | [`devPlugin`](#find-leaks-while-you-develop-devplugin) | Warnings about listeners that pile up, and messages about modules, while you develop. | `nanoeffects/dev` | A function that disconnects it |
+| [`loopGuardPlugin`](#cut-a-loop-that-runs-away-loopguardplugin) | Refuses the emit that would pass a limit of a chain, so a loop ends. | `nanoeffects/guard` | The same bus |
 
 ### Give one action its own fields: `scopePlugin`
 
-An action with a handler, an action, a job or a module can carry its own fields and effects, and one `emit` can replace them. A test gives a fake to one call. More in [Scopes](scope.md).
+An action with a handler, an action, a job or a module can carry its own fields and effects, and one `emit` can replace them. A test gives a fake to one call. More in [Scopes](context.md#scope-fields-for-an-action-a-module-and-a-call).
 
 ```js
 import { createBus } from "nanoeffects";
@@ -1027,7 +1485,7 @@ import { createBus } from "nanoeffects";
 import { createAction } from "nanoeffects/actions";
 import { signalPlugin } from "nanoeffects/signal";
 
-// signalPlugin — emit takes { signal } for an action, a job or an action
+// signalPlugin — emit takes { signal } for an action or a job
 const bus = createBus().use(signalPlugin());
 
 const getUser = createAction("user/get", (id, { signal }) => api.getUser(id, { signal }));
@@ -1144,6 +1602,18 @@ const disconnect = bus.use(devPlugin());
 disconnect(); // stops the diagnostics
 ```
 
+### Cut a loop that runs away: `loopGuardPlugin`
+
+Two handlers that emit each other's events never stop, and a loop of microtasks freezes the page. The plugin follows the chain of emits and refuses the emit that would repeat one event too often or make the chain too long. It needs no tracer, so it can stay on in production. More in [Cut a loop](loop-guard.md).
+
+```js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+// loopGuardPlugin — refuses the emit that would put one event in a chain 50 times
+const bus = createBus().use(loopGuardPlugin({ maxRepeats: 50 }));
+```
+
 ## Put them together
 
 One bus with every plugin that does not need React, in a file of its own. The events of the app stay in other files. The plugins work in any order; the next section says what that means for modules.
@@ -1242,11 +1712,13 @@ Source: docs/policies.md
 
 # Policies
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when handlers overlap in a SPA (search-as-you-type, double submit, leave page). A **policy** wraps a handler and decides what happens then.
 
 Start with `latest`. The table and sections below are the rest of the reference.
 
-## Abort the previous run
+## `latest`: abort the previous run
 
 ```js
 import { createBus } from "nanoeffects";
@@ -1268,7 +1740,7 @@ Pass `signal` to `fetch` (and the like) so the request cancels.
 
 ## Choose a policy
 
-Every policy accepts `key` in its options (see [Isolate state by key](#isolate-state-by-key)).
+Every policy accepts `key` in its options (see [`key`: isolate state by key](#key-isolate-state-by-key)).
 
 | Policy | Overlapping calls |
 | ------ | ----------------- |
@@ -1278,54 +1750,79 @@ Every policy accepts `key` in its options (see [Isolate state by key](#isolate-s
 | `throttle(ms, fn, options?)` | at most one run per `ms` |
 | `queue(fn, options?)` | one after another, in order |
 
-## Call a policy without its function
+Each policy has a short entry in [Look up a policy](#look-up-a-policy).
 
-**Problem.** Some code builds the function for you and only asks which policy to use, as [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) does. If you must pass your own function there, it is easy to pass the wrong one.
+## Look up a policy
 
-**When.** You pass a policy to `usePolicy`. With a bus, `withPolicy` or your own code, call the policy with its function as above.
+One entry per policy: what it does, and a link to the full recipe.
 
-Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+### `latest`
 
-```js
-import { debounce } from "nanoeffects/policies";
+A newer call aborts the older one and drops its result.
 
-const runSearch = async (query) => {
-  await api.search(query);
-};
+Signature: `latest(fn, options?)`.
 
-// debounce(300) — no function yet: returns a wrapper
-const wrap = debounce(300);
+More: [`latest`: abort the previous run](#latest-abort-the-previous-run).
 
-// the wrapper takes the function; same as debounce(300, runSearch)
-const search = wrap(runSearch);
-```
+### `leading`
 
-- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
-- Each time you apply a wrapper to a function, you get a new policy with its own state.
-- To combine policies, nest them as before: `throttle(100, latest(fn))`.
-- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
+New calls are dropped while a run is going.
+
+Signature: `leading(fn, options?)`.
+
+More: [Prevent a double submit](prevent-double-submit.md).
+
+### `debounce`
+
+Runs after a period of quiet.
+
+Signature: `debounce(ms, fn, options?)`.
+
+More: [Configure debounce and throttle](#configure-debounce-and-throttle).
+
+### `throttle`
+
+At most one run within `ms`.
+
+Signature: `throttle(ms, fn, options?)`.
+
+More: [Configure debounce and throttle](#configure-debounce-and-throttle).
+
+### `queue`
+
+Builds a queue of calls: they run one after another, in order.
+
+Signature: `queue(fn, options?)`.
+
+More: [Run calls one after another with `queue`](#run-calls-one-after-another-with-queue).
+
+### `key`
+
+An option of every policy. It splits the state of the policy by a property, for example by id: calls with different keys do not affect each other.
+
+Signature: `latest(fn, { key: (payload) => payload.id })`.
+
+More: [`key`: isolate state by key](#key-isolate-state-by-key).
+
+To use a policy for your own function with no bus, see [`withPolicy`: call a policy outside a bus](#withpolicy-call-a-policy-outside-a-bus).
 
 ## Configure debounce and throttle
 
-`debounce` and `throttle` take `leading` and `trailing`. Behavior matches lodash (and patronum); tests compare random call sequences to lodash itself.
+`debounce` and `throttle` take two options, `leading` and `trailing`. They decide which call of a series runs. `leading` runs the first call of the series at once. `trailing` runs the last call at the end of the series. Both functions are built on the same algorithm as in lodash (and patronum) and behave exactly like them.
 
-**Throttle** (`throttle(ms, fn)`):
+**Throttle** (`throttle(ms, fn)`) runs a call at once if it has been idle for at least `ms`, holds the calls that come within `ms`, and runs the last of them when the window closes. Under a steady stream it runs every `ms`.
 
-- Default `leading: true`, `trailing: true`.
-- A call when the throttle is idle (at least `ms` after the previous call and run) runs at once.
-- Calls made while it waits are held; the latest runs when the window closes.
-- Under a steady stream it runs every `ms`.
-- `leading: false` — even the first call waits for the end of its window.
-- `trailing: false` — drop calls made during a window.
+- `leading` — run the first call of a series at once. It is `true` by default. With `false`, even the first call waits for the end of its window.
+- `trailing` — run the last held call when the window closes. It is `true` by default. With `false`, calls made during a window are dropped.
 
-**Debounce** (`debounce(ms, fn)`):
+**Debounce** (`debounce(ms, fn)`) runs the last call of a series after `ms` of quiet.
 
-- Default `trailing: true` — run the last call after `ms` of quiet.
-- `leading: true` — also run the first call of a burst at once; the trailing run happens only if more calls follow.
-- `leading: true, trailing: false` — only the first call of a burst.
+- `trailing` — run the last call after `ms` of quiet. It is `true` by default.
+- `leading` — also run the first call of a series at once. It is `false` by default. The closing run then happens only if more calls follow.
+- `leading: true, trailing: false` — only the first call of a series.
 - Both `false` — nothing runs.
 
-## Isolate state by key
+## `key`: isolate state by key
 
 `key` gives each key its own state. Calls with different keys do not affect each other. Idle keys are dropped, so keys can be unbounded (ids, urls).
 
@@ -1384,44 +1881,46 @@ Every call returns a promise with the result of its own run. An error rejects on
 - When a running call aborts, its slot is freed at once and its result is dropped.
 - Pass `signal` into what `fn` does. A `fn` that ignores it can overlap with the next run.
 
-## Use a policy without a bus
+## `withPolicy`: call a policy outside a bus
 
-**Problem.** You want a debounced input handler or a "latest request wins" fetch, but your code has no bus. A policy needs a context on every call, so `debounce(300, search)("re")` does not work on its own.
+**Problem.** You want a debounced input handler or a "latest request wins" fetch for your own function, but the code has no bus: a DOM handler, a click callback, a function in a service. A policy needs a context on every call, so `debounce(300, search)("re")` does not work on its own.
 
-**When.** One component or module needs a policy and nothing else from the library. If you already have a bus, `bus.on(event, policy)` is simpler.
+**When.** One input, button or function needs a policy and nothing else from the library. If you already have a bus, `bus.on(event, policy)` is simpler. In a React component use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders), which also keeps the function between renders.
 
-`withPolicy` takes the result of any policy and returns a plain function. It needs no bus and no context argument, and it keeps the state of the policy between calls.
+`withPolicy` takes a policy and returns a plain function. The function needs no bus and no context argument, and it keeps the state of the policy between calls.
 
 ```js
 import { debounce, withPolicy } from "nanoeffects/policies";
 
+const input = document.querySelector("#search");
+
 // debounce — waits for 300 ms of quiet, then runs the callback
 const policy = debounce(300, async (query, { signal }) => {
-  await api.search(query, { signal });
+  const items = await api.search(query, { signal });
+  render(items);
 });
 
 // withPolicy — a plain function: no bus, no context argument
-const onChange = withPolicy(policy);
+const onInput = withPolicy(policy);
 
-onChange("re");
-onChange("redux"); // only this call runs, 300 ms after it
+input.addEventListener("input", (event) => onInput(event.target.value));
 
-// cancel — drops a pending call and aborts a running one
-onChange.cancel();
+// cancel — drops a pending call and aborts a running request, for example when the page closes
+window.addEventListener("pagehide", () => onInput.cancel());
 ```
 
 - The callback has the same `(payload, ctx)` shape as for a bus. `ctx.signal`, `ctx.abort` and `ctx.run` work. `ctx.emit` and `ctx.on` do nothing, because there is no bus.
 - Every call returns a promise with the result. A call the policy drops resolves with `undefined`.
 - `cancel()` aborts every call that has not finished. Calls made after it work again.
-- Where `Symbol.dispose` exists, `using onChange = withPolicy(policy)` calls `cancel()` at the end of the scope.
-
-In a React component, use [`usePolicy`](react.md#keep-a-debounced-handler-between-renders) instead: it keeps the function between renders.
+- Where `Symbol.dispose` exists, `using onInput = withPolicy(policy)` calls `cancel()` at the end of the scope.
 
 ---
 Source: docs/cancel-stale-requests.md
 
 # Cancel stale requests and fix race conditions
 
+> **Level B.** Read first: the bus from the [README](../README.md).
+
 Read this page if an older response can overwrite a newer one: a search box that shows the results of the previous query, a filter that flickers, a form that submits twice. It shows the cause, the fix with `latest`, and how to add a pause, a retry and a timeout. It needs only the bus from the [README](../README.md).
 
 ## See the problem
@@ -1539,7 +2038,9 @@ All policies and their options: [Policies](policies.md). The same step by step i
 ---
 Source: docs/debounce-and-abort.md
 
-# Debounce a request and abort the previous one
+# Pause between requests
+
+> **Level B.** Read first: [Policies](policies.md).
 
 Read this page if you debounce user input (a search box, an autosave, a resize handler) and you also want the request in flight to stop when a new one starts. `debounce` alone waits for a pause. It does not cancel a request that already started. This page shows the two policies together, the order to put them in, and when to use `throttle` instead.
 
@@ -1649,6 +2150,8 @@ Source: docs/prevent-double-submit.md
 
 # Prevent a double submit
 
+> **Level B.** Read first: [Policies](policies.md).
+
 Read this page if a second click on "Pay", "Sign up" or "Save" sends the request twice. It shows how to ignore the second click while the first request runs, how to do it per item, and when to queue the calls instead.
 
 ## See the problem
@@ -1743,7 +2246,7 @@ bus.on(
 );
 ```
 
-Backoff between tries: [Back off between retries](effects.md#back-off-between-retries).
+Backoff between tries: [`backoff`](effects.md#backoff).
 
 ## Guard a handler when you have no bus
 
@@ -1781,120 +2284,156 @@ Source: docs/effects.md
 
 # Effects and cancellation
 
-Use this page for retry, timeouts, waiting, or parallel work — not as the first page for a small bus. Pick **one** helper for your job; the rest is reference.
+> **Level C.** Read first: [Policies](policies.md).
+
+Use this page for retry, timeouts, waiting, or parallel work — not as the first page for a small bus. Pick **one** effect for your job; the rest is reference.
 
 An abort only raises a flag. Your code decides to stop. Start with `retry` / `timeout` on a handler (see [Guide §5](guide.md#5-add-retry-and-timeout)).
 
-## On this page
+## Effects
+
+Every effect below has its own section with its forms, options and an example. `ctx` is the context of the task.
+
+- [`retry`](#retry) — repeat a call after an error.
+- [`timeout`](#timeout) — stop a call that takes too long.
+- [`poll`](#poll) — call a function at an interval.
+- [`backoff`](#backoff) — make the pause between retries grow.
+- [`delay`](#delay) — wait for a time; an abort ends the wait.
+- [`cancellable`](#cancellable) — a Promise tied to the task signal, for callbacks and timers.
+- [`onAbort`](#onabort) — run code when the task is aborted.
+- [`ctx.on` and `ctx.off`](#ctxon-and-ctxoff) — subscribe to the bus inside a task.
+- [`take`](#take) — wait for the next event inside a handler.
+- [`all`](#all) — run several calls together; one failure cancels the rest.
+- [`allSettled`](#allsettled) — wait for all of them, whatever the outcome.
+- [`race`](#race) — take the first result and cancel the rest.
+- [`effectsPlugin`](#effectsplugin) — short forms of effects: call them without `ctx`.
+- [Effects outside a task](#effects-outside-a-task) — call effects where there is no handler.
+
+## `retry`
 
-- [Wrap a handler with retry and timeout](#wrap-a-handler-with-retry-and-timeout)
-  - [Options for retry, timeout, and poll](#options-for-retry-timeout-and-poll)
-- [Back off between retries](#back-off-between-retries)
-- [Put selected effects on `ctx`](#put-selected-effects-on-ctx)
-- [Tie a promise to the task signal](#tie-a-promise-to-the-task-signal)
-- [Run cleanup on abort](#run-cleanup-on-abort)
-- [Wait for the next event with `take`](#wait-for-the-next-event-with-take)
-- [Run several starters together](#run-several-starters-together)
-- [Pass `ctx` outside a task](#pass-ctx-outside-a-task)
+Runs a function again after an error. Use it when a call fails now and then, for example because of the network.
 
-## Wrap a handler with retry and timeout
+Forms:
 
-`retry`, `timeout`, and `poll` have two forms:
+- `retry(fn, options?)` — a wrapper of a handler: takes a function `(payload, ctx) => result` and returns one. Pass it to `on` next to policies.
+- `retry(ctx, fn, options?)` — a call inside the body of a handler.
 
-- **Task wrapper** — take a function `(payload, ctx) => result` and return one. Pass them into `on` next to policies (no `ctx` in their arguments).
-- **Call inside a body** — take `ctx` first.
+Options:
 
-The first argument tells them apart: a function (`retry`), a number (`timeout`), or a number/function (`poll`) is a wrapper; an object is `ctx`.
+- `times` — total attempts. It is `3` by default.
+- `delay` — a number or a function `(attempt, error) => ms`. For a growing pause see [`backoff`](#backoff).
+- `shouldRetry(error, attempt)` — return `false` to stop early.
+- `fn` gets the attempt number, starting at `1`.
+- On abort, `retry` rejects with the abort reason.
 
 ```js
 import { createBus } from "nanoeffects";
-import { poll, retry, timeout } from "nanoeffects/effects";
+import { retry } from "nanoeffects/effects";
 import { latest } from "nanoeffects/policies";
 
 const bus = createBus();
 const loadUser = (id, { signal }) => fetchUser(id, { signal });
 
-// timeout — one try must finish within 5 s
-const loadOnce = timeout(5000, loadUser);
-// retry — up to 4 attempts with backoff
-const loadWithRetry = retry(loadOnce, {
+// retry — a wrapper of the handler: up to 4 attempts, but not after a fatal error
+const loadWithRetry = retry(loadUser, {
   times: 4,
-  delay: (attempt) => 2 ** attempt * 100,
   shouldRetry: (error) => !isFatal(error),
 });
-// latest — a newer load aborts the older retry chain
-bus.on("load", latest(loadWithRetry));
 
-// poll — call refresh every 10 s until the task aborts
-bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
+// latest — a newer load aborts the older chain of attempts
+bus.on("load", latest(loadWithRetry));
 
-// ctx.run — run a wrapped Task as a child (aborted with the handler)
+// ctx.run — run the wrapped function as a child task (aborted with the handler)
 bus.on("open", async (id, ctx) => {
-  const load = retry(timeout(5000, loadUser));
-  const user = await ctx.run(load, id);
+  const user = await ctx.run(loadWithRetry, id);
   ctx.emit("opened", user);
 });
+```
+
+Use the wrapper for a whole handler or a whole `ctx.run`. Each attempt gets its own child context: an abort of the caller reaches it, and an abort of one attempt does not reach the caller. For one call in the middle of a body use the form with `ctx`:
+
+```js
+import { createBus } from "nanoeffects";
+import { retry } from "nanoeffects/effects";
+
+const bus = createBus();
 
-// ctx-first form — one call inside a body
 bus.on("load", async (id, ctx) => {
+  // retry with ctx — one call inside the body
   const user = await retry(
     ctx,
     () => fetchUser(id, { signal: ctx.signal }),
     { times: 4 },
   );
-  const data = await timeout(ctx, 5000, (child) => fetchData(id, child));
-  await poll(ctx, () => refresh(), 10_000);
-  ctx.emit("ready", { user, data });
+
+  ctx.emit("loaded", user);
 });
 ```
 
-Use the wrapper for a whole handler or a whole `ctx.run`. Use the `ctx` form for one call in the middle of a body.
+## `timeout`
+
+Rejects when the work takes longer than the time you set, and aborts it. Use it when a request can hang.
+
+Forms:
+
+- `timeout(ms, handler)` — a wrapper of a handler.
+- `timeout(ctx, ms, fn)` — a call inside a body; `fn` gets the context of its own child task.
+
+The error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`). `timeout` rejects even if the function ignores its signal.
 
-Each attempt or call of a wrapper gets its own child context. Abort of the caller reaches it. Abort of one attempt (a timeout) does not reach the caller. The attempt number is passed only in the `ctx` form.
+```js
+import { createBus } from "nanoeffects";
+import { timeout } from "nanoeffects/effects";
+
+const bus = createBus();
+const loadUser = (id, { signal }) => fetchUser(id, { signal });
+
+// timeout — a wrapper of the handler: it must finish within 5 s
+bus.on("load", timeout(5000, loadUser));
 
-### Options for retry, timeout, and poll
+bus.on("open", async (id, ctx) => {
+  // timeout with ctx — one call inside the body; child carries the signal of the request
+  const data = await timeout(ctx, 5000, (child) => fetchData(id, child));
+  ctx.emit("opened", data);
+});
+```
 
-**`retry`**
+## `poll`
 
-- `times` — total attempts (default `3`).
-- `delay` — number or `(attempt, error) => ms`.
-- `shouldRetry(error, attempt)` — stop early.
-- `fn` gets the attempt number starting at `1`.
-- On abort, rejects with the abort reason.
+Calls a function again and again at an interval, until the task is aborted. Use it to refresh data every N seconds. It is like `interval` in patronum.
 
-**`timeout`**
+Forms:
 
-- Error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`).
-- Rejects even if the starter ignores its signal.
+- `poll(ms, fn, options?)` — a wrapper of a handler.
+- `poll(ctx, fn, ms)` — a call inside a body.
 
-**`poll`** (like patronum `interval`)
+Options:
 
-- First call after `ms`. `leading: true` also calls at once.
-- Next ticks keep a steady rate whatever the duration of `fn`, so a slow `fn` can overlap the next call.
-- `waitForFn: true` starts each pause when the call ends — calls never overlap.
-- `fn` gets the call number from `0`.
+- The first call happens after `ms`. `leading: true` also calls at once.
+- The next ticks keep a steady rate whatever the duration of `fn`, so a slow `fn` can overlap the next call. `waitForFn: true` starts each pause when the call ends, so calls never overlap.
+- `fn` gets the call number, starting at `0`.
 - An error from `fn` stops polling and rejects. An abort ends it normally and clears the timer.
 
-A pause can be a function wherever a time is given. For retries with a cap and jitter, see [Back off between retries](#back-off-between-retries):
-
 ```js
 import { createBus } from "nanoeffects";
-import { delay, poll, retry } from "nanoeffects/effects";
+import { poll } from "nanoeffects/effects";
 
 const bus = createBus();
 
+// poll — a wrapper of the handler: call refresh every 10 s until the task aborts
+bus.on("watch", poll(10_000, (_, { signal }) => refresh({ signal })));
+
 bus.on("sync", async (_, ctx) => {
-  retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, …
-  poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows to once a minute
-  await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
+  // poll with ctx — the same inside a body
+  await poll(ctx, () => refresh(), 10_000);
 });
 ```
 
-All three are traced: the effect is a group (`retry`, `timeout`, `poll`) and each attempt or call is a `run` child.
+`retry`, `timeout` and `poll` are traced: the effect is a group, and each attempt or call is a `run` child.
 
-## Back off between retries
+## `backoff`
 
-Use this when a server or network fails under load. Retrying at once, or at the same fixed pause, sends every client back at the same moment and can keep the server down. Make the pause grow with each attempt, and add jitter so clients spread out.
+Makes the pause between retries grow, with a cap and jitter. Use it when a server or network fails under load: retrying at once, or at the same fixed pause, sends every client back at the same moment and can keep the server down. `backoff(options)` returns a function `(attempt) => ms`.
 
 The shortest form is a `delay` function. It needs no import:
 
@@ -1934,49 +2473,41 @@ const loadWithRetry = retry(loadUser, {
 - `retry` counts attempts from 1. `poll` counts calls from 0, so with `poll` the first pause is `base / factor`.
 - The result is a plain function `(attempt) => ms`, so it also fits `delay(ctx, …)`.
 
-## Put selected effects on `ctx`
-
-If handlers call the same helpers often, put them on the task once. A handler then destructures them like `signal`, with no `ctx` argument. Only the effects you pass are imported, so the rest stay out of the bundle ([package entries](package.md)).
+A pause can be a function wherever a time is given:
 
 ```js
 import { createBus } from "nanoeffects";
-import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
-
-// effectsPlugin — add race, all and delay to the context of every task
-const effects = effectsPlugin({ race, all, delay });
-
-// use returns the same bus, typed with the new fields
-const bus = createBus().use(effects);
+import { delay, poll, retry } from "nanoeffects/effects";
 
-bus.on("load", async (id, { race, all, delay }) => {
-  // race — same as race(ctx, …)
-  const result = await race({
-    // child — the context of this starter; it has the `signal`, so the request stops with the race
-    data: (child) => fetchData(id, child),
-    // a starter gets its own child with the same bound effects, so delay(5000) stops with the race
-    timeout: ({ delay }) => delay(5000),
-  });
-  if ("timeout" in result) throw new Error("timed out");
+const bus = createBus();
 
-  // all — same as all(ctx, …)
-  const { user, posts } = await all({
-    user: (child) => fetchUser(id, child),
-    posts: (child) => fetchPosts(id, child),
-  });
+bus.on("sync", async (_, ctx) => {
+  retry(ctx, load, { times: 5, delay: (attempt) => 2 ** attempt * 100 }); // 200, 400, 800, …
+  poll(ctx, refresh, (call) => Math.min(1000 * 2 ** call, 60_000)); // slows to once a minute
+  await delay(ctx, () => 200 + Math.random() * 200); // 200–400 ms
 });
 ```
 
-- The key is the name the effect gets on `ctx`. `race`, `all`, `allSettled`, `take` and `delay` are typed by hand.
-- Your own function works too if its first parameter is `{ signal }` (an *effect*): `effectsPlugin({ fetchJson })` gives `ctx.fetchJson(url)`. TypeScript removes the first parameter from its type; for a generic function see [keep a generic effect generic](scope.md#keep-a-generic-effect-generic).
-- Leave `retry`, `timeout` and `poll` out: bound to the task they would look like their handler wrappers.
-- Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
-- Free forms keep working: `race(ctx, …)`.
+## `delay`
 
-## Tie a promise to the task signal
+Waits for the given time and rejects on abort. A plain `setTimeout` would go on after the task is aborted; `delay` ends the wait at once and clears the timer. `delay(ctx, ms)`, where `ms` can be a function.
 
-`delay(ctx, ms)` waits and rejects on abort (`ms` can be a function).
+```js
+import { createBus } from "nanoeffects";
+import { delay } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("saved", async (_, ctx) => {
+  // delay — wait 3 s; an abort ends the wait at once and clears the timer
+  await delay(ctx, 3000);
+  ctx.emit("toast/hidden");
+});
+```
+
+## `cancellable`
 
-`cancellable(ctx, executor)` is a promise tied to the task signal. It works like `new Promise`, but the executor gets `{ resolve, reject, onCancel }`.
+A Promise tied to the task signal. Use it for APIs that work with callbacks, timers or listeners: the signal cannot stop them by itself, so `cancellable` rejects the Promise on abort and runs your cleanup. `cancellable(ctx, executor)` works like `new Promise`, but the executor gets `{ resolve, reject, onCancel }`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -1985,7 +2516,7 @@ import { latest } from "nanoeffects/policies";
 
 const bus = createBus();
 
-// cancellable — promise tied to the task signal; onCancel for cleanups
+// cancellable — a Promise tied to the task signal; onCancel registers a cleanup
 // latest — a newer wait aborts the older timer
 bus.on(
   "wait",
@@ -1998,13 +2529,13 @@ bus.on(
 );
 ```
 
-- If the task aborts before the promise settles, cleanups run (last registered first) and the promise rejects with the abort reason.
+- If the task aborts before the Promise settles, cleanups run (last registered first) and the Promise rejects with the abort reason.
 - If the task is already aborted, the executor does not run.
-- After the promise settles, the abort listener is removed and cleanups are dropped.
+- After the Promise settles, the abort listener is removed and cleanups are dropped.
 
-## Run cleanup on abort
+## `onAbort`
 
-`onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if already aborted) and returns a function that unsubscribes.
+Runs code when the task is aborted: a hook of the life of the task. A task may be aborted because the user left or a newer call replaced it, and whatever it opened (a socket, a timer, a listener) must be closed then. `onAbort(ctx, fn)` runs `fn(reason)` on abort (at once if the task is already aborted) and returns a function that unsubscribes.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2014,14 +2545,14 @@ const bus = createBus();
 
 bus.on("connect", (url, ctx) => {
   const socket = new WebSocket(url);
-  // onAbort — run cleanup when this task aborts
+  // onAbort — close the socket when this task aborts
   onAbort(ctx, () => socket.close());
 });
 ```
 
-## Wait for the next event with `take`
+## `ctx.on` and `ctx.off`
 
-A task context has `on` and `off`, like the bus. A subscription made with `ctx.on` ends when the task aborts:
+Subscribes to the bus inside a task. A task context has `on` and `off`, like the bus, and a subscription made with `ctx.on` ends when the task aborts.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2029,15 +2560,29 @@ import { createBus } from "nanoeffects";
 const bus = createBus();
 
 bus.on("watch", (_, ctx) => {
-  ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
+  // gone when this task aborts
+  const stop = ctx.on("tick", (n) => console.log(n));
+
+  // or end it sooner yourself: stop() unsubscribes
+  ctx.on("watch/closed", stop);
 });
 ```
 
-- The returned function unsubscribes sooner. After abort, `ctx.on` does nothing.
-- Under `latest`, subscriptions of a superseded run end with that run.
-- `ctx.off(event)` clears every handler of the event on the bus, not only the task’s.
+Be careful with it:
+
+- **A task that finishes by itself is not aborted**, so its `ctx.on` subscription stays. When the work is done, unsubscribe with the function that `ctx.on` returns, or call `ctx.abort()`.
+- To wait for **one** event, use [`take`](#take): it unsubscribes by itself.
+- For listeners that live as long as a feature, use a [module](actions.md#modules): `unmount` removes all of them.
+
+Also:
+
+- After an abort, `ctx.on` does nothing.
+- Under `latest`, the subscriptions of a superseded run end with that run.
+- `ctx.off(event)` clears every handler of the event on the bus, not only the ones of this task.
 
-`take(ctx, event, options?)` waits for the next `event` and resolves with its payload. `event` is the name of an event or an action creator, as for `bus.on`:
+## `take`
+
+Waits for the next event of the bus inside a handler and resolves with its payload. `take(ctx, event, options?)`. The `event` is the name of an event or an action creator, as for `bus.on`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2059,22 +2604,65 @@ bus.on("login", async (user, ctx) => {
   const id = await timeout(
     ctx,
     5000,
-    take("saved", { predicate: (savedId) => savedId === draft.id }), // take without ctx: a starter
+    take("saved", { predicate: (savedId) => savedId === draft.id }), // take without ctx — a ready-made function for the group
   );
 });
 ```
 
-- Sees only events emitted after the call, takes one, and unsubscribes.
+- It sees only events emitted after the call, takes one, and unsubscribes.
 - With an action creator the result has the payload type of the creator. A creator made without a payload type (`createAction("saved")`) takes it from the event map of the bus.
 - `options.predicate` skips payloads it rejects. In TypeScript, a type guard (`(payload): payload is Admin`) narrows the type of the result.
-- `options.signal` stops the wait. Inside `race`, `all` or `timeout` you do not need it: the group already stops the starter, so write `take("saved")` without options.
-- On abort of the task or of `options.signal`, unsubscribes and rejects with the abort reason.
+- `options.signal` stops the wait. Inside `race`, `all` or `timeout` you do not need it: the group already stops the wait, so write `take("saved")` without options.
+- On abort of the task or of `options.signal`, it unsubscribes and rejects with the abort reason.
+
+## `all`
+
+Runs several calls together; one failure cancels the rest. Use it to load several things at once. `all(ctx, effects)` takes an object or an array of functions, and the result keeps that shape.
+
+```js
+import { createBus } from "nanoeffects";
+import { all } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("open", async (id, ctx) => {
+  // all — run both requests together; one failure cancels the other. child is the context of its own request
+  const { user, posts } = await all(ctx, {
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
+  });
+
+  ctx.emit("opened", { user, posts });
+});
+```
+
+Every function of the group gets `child`, the context of its own child task. Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the group ends or fails, `child` is aborted and stops exactly this effect. If your API takes the signal in its options, `child` has a `signal`, so pass it as the options: `(child) => fetchUser(id, child)` (`fetch` reads only `signal` from it). The same holds for `allSettled`, `race` and `timeout`.
+
+**Limit how many run at once.** `all` and `allSettled` start everything together. Over a long list that is a burst of requests. Pass `{ concurrency }` as the third argument and at most that many run at a time; the next one starts when a running one settles:
 
-## Run several starters together
+```js
+import { createBus } from "nanoeffects";
+import { all, retry } from "nanoeffects/effects";
+
+const bus = createBus();
+
+bus.on("sync", async (ids, ctx) => {
+  // all with concurrency — 5 loads at a time, results in the order of ids
+  const users = await all(
+    ctx,
+    ids.map((id) => retry(() => loadUser(id), { times: 2 })),
+    { concurrency: 5 },
+  );
+
+  render(users);
+});
+```
+
+The result has the same order and shape as without the option. If one call of `all` fails, the running ones are cancelled and the waiting ones are never started. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a call that waited for a free slot would never run.
 
-`all(ctx, effects)` runs starters together. One failure cancels the rest. Shape of the input (object or array) is preserved in the result.
+## `allSettled`
 
-`allSettled(ctx, effects)` waits for every starter and never fails because of one. Each result is `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`. Nothing is cancelled when a starter fails. Only an abort of `ctx` rejects it.
+Waits for every call and never fails because of one. Use it when a partial answer is better than none. `allSettled(ctx, effects)`. Each result is `{ status: "fulfilled", value }` or `{ status: "rejected", reason }`. Nothing is cancelled when a call fails; only an abort of `ctx` rejects it.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2083,6 +2671,7 @@ import { allSettled } from "nanoeffects/effects";
 const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
+  // allSettled — wait for both, whatever the outcome
   const { user, posts } = await allSettled(ctx, {
     user: (child) => fetchUser(id, child),
     posts: (child) => fetchPosts(id, child),
@@ -2094,7 +2683,9 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-`race(ctx, effects)` settles with the first starter that finishes and cancels the others.
+## `race`
+
+Settles with the first call that finishes and cancels the others. Use it to take the fastest answer or to cut a wait short. `race(ctx, effects)`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2103,9 +2694,9 @@ import { delay, race, take } from "nanoeffects/effects";
 const bus = createBus();
 
 bus.on("save", async (draft, ctx) => {
-  // race — the first starter to finish wins, the other is cancelled
+  // race — the first to finish wins, the other is cancelled
   const result = await race(ctx, {
-    waited: delay(1000), // delay without ctx — a starter: race gives it its own child
+    waited: delay(1000), // delay without ctx — a ready-made function for the group: race gives it its own child
     cancelled: take("cancel"), // take without ctx — the same, waits for the next "cancel"
   });
 
@@ -2115,9 +2706,9 @@ bus.on("save", async (draft, ctx) => {
 });
 ```
 
-**`delay` and `take` without `ctx` are ready-made starters.** In a group, `delay(1000)` and `take("cancel")` do what `(child) => delay(child, 1000)` and `(child) => take(child, "cancel")` do. The group calls them with the child, so the wait stops with the group. Use this form inside `race`, `all`, `allSettled` and `timeout`; use `delay(ctx, 1000)` in plain handler code. A starter waits only when a group calls it: do not `await delay(1000)` on its own, it is a function, not a promise. Write `take("cancel")` in the group, as above; a starter stored in a variable outside it does not know the events of your bus, and you name them yourself in TypeScript (`const cancelled: StarterOf<Events> = take("cancel")`; `StarterOf` is exported by `nanoeffects/effects`).
+**`delay` and `take` without `ctx` are ready-made functions for a group.** In a group, `delay(1000)` and `take("cancel")` do what `(child) => delay(child, 1000)` and `(child) => take(child, "cancel")` do: the group calls them with the child, so the wait stops with the group. Use this form inside `race`, `all`, `allSettled` and `timeout`; use `delay(ctx, 1000)` in plain handler code. They wait only when a group calls them: `await delay(1000)` on its own does not wait, because it is a function, not a Promise. In TypeScript, one kept in a variable outside a group does not know the events of your bus; name them yourself: `const cancelled: StarterOf<Events> = take("cancel")` (`StarterOf` is exported by `nanoeffects/effects`).
 
-The wrapper form of `retry`, `timeout` and `poll` is a starter too: a group calls it with the child, and the function you wrap gets `undefined` as its payload and the child as its context. Write the data it needs into a closure:
+The wrapper form of `retry`, `timeout` and `poll` works in a group too: the group calls it with the child, and the function you wrap gets `undefined` as its payload and the child as its context. Write the data it needs into a closure:
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2127,7 +2718,7 @@ const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
   const result = await race(ctx, {
-    // retry without ctx — a starter: up to 3 attempts, each with the signal of the child
+    // retry without ctx — up to 3 attempts, each with the signal of the child
     user: retry((_, { signal }) => fetchUser(id, { signal }), { times: 3 }),
     // delay without ctx — the loser is cancelled when the other one finishes
     waited: delay(5000),
@@ -2139,9 +2730,9 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-The same call with a payload and a context, `(payload, ctx)`, is the Task that `bus.on` and `ctx.run` use, and it does not change. `retry`, `timeout` and `poll` therefore have three call forms: with `ctx`, as a Task, and as a starter. All three stay; [Stability](stability.md#rely-on-these-call-forms) says how they are told apart.
+So `retry`, `timeout` and `poll` have three call forms: with `ctx`, as a Task for `bus.on` and `ctx.run`, and inside a group. The arguments tell them apart: a context first is the `ctx` form; a function called with a payload and a context is a Task; the same function called by a group with one argument, its child, is the group form. This does not depend on how many parameters your function declares.
 
-**`all`, `allSettled` and `race` without `ctx` are starters too**, so a group nests in another group with no wrapper. Load two things, but give up after five seconds:
+**`all`, `allSettled` and `race` without `ctx` also work in a group**, so a group nests in another group with no wrapper. Load two things, but give up after five seconds:
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2151,7 +2742,7 @@ const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
   const result = await race(ctx, {
-    // all without ctx — a starter: loads both, each with up to 3 attempts
+    // all without ctx — loads both, each with up to 3 attempts
     loaded: all({
       user: retry((_, { signal }) => fetchUser(id, { signal }), { times: 3 }),
       posts: retry((_, { signal }) => fetchPosts(id, { signal }), { times: 3 }),
@@ -2166,46 +2757,77 @@ bus.on("open", async (id, ctx) => {
 });
 ```
 
-One argument is the short form and two arguments are the form with `ctx`: `all(effects)` returns a starter, `all(ctx, effects)` runs the group. The inner group stops with the outer one and cancels its own starters. Passing only a context, `all(ctx)`, is a mistake and throws a `TypeError` at once. A group starter written in a group needs no type. One kept in a variable outside a group does not know its bus: in TypeScript, annotate it with `StarterOf<Events>`, or `StarterOf<Events, Result>` when you need its value.
+One argument is the short form and two arguments are the form with `ctx`: `all(effects)` returns a function for a group, `all(ctx, effects)` runs the group. The inner group stops with the outer one and cancels its own calls. Passing only a context, `all(ctx)`, is a mistake and throws a `TypeError` at once. The form without `ctx` takes no options, because a second argument would look like the form with `ctx`; write `(child) => all(child, effects, { concurrency: 5 })` there. In TypeScript, a group kept in a variable outside a group needs a type: `StarterOf<Events>`, or `StarterOf<Events, Result>` when you need its value.
+
+## `effectsPlugin`
 
-**Limit how many run at once.** `all` and `allSettled` start every starter together. Over a long list that is a burst of requests. Pass `{ concurrency }` as the third argument and at most that many run at a time; the next one starts when a running one settles:
+Short forms of effects: `effectsPlugin(effects)` puts chosen effects on `ctx`, so a handler calls them without passing `ctx` around. Use it when many handlers call the same helpers, to cut the boilerplate. A handler destructures them like `signal`. Only the effects you pass are imported, so the rest stay out of the bundle ([package entries](package.md)).
 
 ```js
 import { createBus } from "nanoeffects";
-import { all, retry } from "nanoeffects/effects";
+import { all, delay, effectsPlugin, race } from "nanoeffects/effects";
 
-const bus = createBus();
+// effectsPlugin — add race, all and delay to the context of every task
+const effects = effectsPlugin({ race, all, delay });
 
-bus.on("sync", async (ids, ctx) => {
-  // all with concurrency — 5 loads at a time, results in the order of ids
-  const users = await all(
-    ctx,
-    ids.map((id) => retry(() => loadUser(id), { times: 2 })),
-    { concurrency: 5 },
-  );
+// use returns the same bus, typed with the new fields
+const bus = createBus().use(effects);
 
-  render(users);
+bus.on("load", async (id, { race, all, delay }) => {
+  // race — same as race(ctx, …)
+  const result = await race({
+    data: (child) => fetchData(id, child),
+    // a group function gets its own child with the same bound effects, so delay(5000) stops with the race
+    timeout: ({ delay }) => delay(5000),
+  });
+  if ("timeout" in result) throw new Error("timed out");
+
+  // all — same as all(ctx, …)
+  const { user, posts } = await all({
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
+  });
 });
 ```
 
-The result has the same order and shape as without the option. If one starter of `all` fails, the running ones are cancelled and the waiting ones are never called. `allSettled` goes on after a failure. When `ctx` aborts, both stop and start nothing more. A value that is not a positive integer (`0`, `-1`, `NaN`, `1.5`) throws a `RangeError` before anything starts; `Infinity` means no limit. `race` has no `concurrency`: it ends at the first result, so a starter that waited for a free slot would never run. The form without `ctx` takes no options, because a second argument would look like the form with `ctx`, so a group starter inside another group takes none; write `(child) => all(child, effects, { concurrency: 5 })` there.
+- The key is the name the effect gets on `ctx`. `race`, `all`, `allSettled`, `take` and `delay` are typed by hand.
+- Your own function works too if its first parameter is `{ signal }` (an *effect*): `effectsPlugin({ fetchJson })` gives `ctx.fetchJson(url)`. TypeScript removes the first parameter from its type; for a generic function see [keep a generic effect generic](context.md#keep-a-generic-effect-generic).
+- Leave `retry`, `timeout` and `poll` out: bound to the task they would look like their handler wrappers.
+- Fields from `createBus({ context })` stay. TypeScript rejects an effect whose name is already a context field of the bus, including one added by an earlier `effectsPlugin`.
+- The free forms keep working: `race(ctx, …)`.
+
+## Effects outside a task
 
+Effects take `ctx` first. Inside a handler it is the `ctx` you already have. Outside a task (in a plain function, a script or a test) there is no `ctx`: pass an object with a `signal`, or `{}` if you never abort.
 
-**A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options, and `child` has a `signal`, so pass it as the options: `(child) => fetchUser(id, child)` (`fetch` reads only `signal` from it). The same holds for `all`, `allSettled` and `timeout`.
+```js
+import { delay, retry } from "nanoeffects/effects";
+
+const controller = new AbortController();
 
-If `ctx` is `{}` or a bare `{ signal }` (outside a task), `child` has only `signal` and `abort`, so it fits `delay` and `poll` but not `take`, which needs a bus.
+// outside a task there is no ctx: an object with a signal is enough
+const context = { signal: controller.signal };
 
-## Pass `ctx` outside a task
+// the effects take it as ctx; fetchUser gets the same signal, so the request itself stops too
+const user = await retry(
+  context,
+  () => fetchUser("1", { signal: controller.signal }),
+  { times: 3 },
+);
 
-Effects that wait inside a body take `ctx` first: `delay`, `all`, `allSettled`, `race`, `cancellable`, `onAbort`, `take`, and the `ctx` forms of `retry` / `timeout` / `poll`. Outside a task, pass `{}` or any object with a `signal`. The one exception is `delay(ms)` and `take(event)` as starters of a group, which take no `ctx` (see above).
+await delay(context, 500);
 
-For `fetch` and other APIs that take a signal, pass `ctx.signal`. A timeout without `race`: `AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)])`.
+// stops the pending retries and waits
+controller.abort();
+```
 
 ---
 Source: docs/errors.md
 
 # Handle errors and unheard events
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 and 2.
+
 Defaults match a small bus. Set these when you want isolation or typo warnings.
 
 ## Isolate failing handlers
@@ -2227,9 +2849,9 @@ const bus = createBus({
 
 ## Warn when nobody listens
 
-A typo in an event name (`emit("serch")`) does nothing and says nothing. `onUnhandled` runs when an event is emitted and nobody listens (a listener of every event, `"*"`, counts). It is not called for actions, which always have a handler to run.
+A typo in an event name (`emit("serch")`) does nothing and says nothing. `onUnhandled` runs when an event is emitted and nobody listens (a listener of every event, `"*"`, counts). It is not called for an action that has a handler to run. An action without a handler is only an event, so it is called for it.
 
-Use it as a warning in development:
+Use it as a warning in development (`import.meta.env.DEV` is the Vite flag; use your own check in another bundler):
 
 ```js
 import { createBus } from "nanoeffects";
@@ -2246,7 +2868,24 @@ Source: docs/actions.md
 
 # Actions, jobs and modules
 
-Use this page when **domain logic lives on the bus**, off the UI: the UI emits and listens; handlers and modules own the work.
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 6.
+
+When a project has a lot of business logic, you need to split it. One way is to split it by domains, or entities. In a shop, the domains could be products and product categories. Then the code that belongs to the actions of one domain goes into one file (`product.js`), its handlers into another, and the module that mounts them into a third. A domain can then be mounted, replaced or unmounted without touching the others. For the shop the files could look like this:
+
+```text
+src/
+  bus.js
+  product/
+    product.js
+    product-handlers.js
+    product-module.js
+  category/
+    category.js
+    category-handlers.js
+    category-module.js
+```
+
+The examples below show the content of such files.
 
 If you only need `on` / `emit` or policies, stay in the [Guide](guide.md) until you need a result from `emit` or a mountable domain.
 
@@ -2256,37 +2895,37 @@ A chat with two entities and three features, jobs under policies and effects, an
 
 A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
 
-## Pick the word: event, action, job, module
+## Action, job and module
 
-Four names, one idea each. Take the first row that fits.
+Four forms, one idea each. Take the first row that fits.
 
-| Word | What it is | Use it when |
+| Form | What it is | Use it when |
 | ---- | ---------- | ----------- |
-| Event | A name and a payload; `createAction("x")` with no handler. | The UI or a handler tells that something happened. |
-| Action with a handler | The same, plus work: `createAction("x", handler)`. `emit` returns the result. | The caller needs a value back. |
-| Job | An action with a handler that also emits `pending`, `success`, `fail` and `cancel`. | The UI shows a loading state. |
-| Module | A group of listeners, handlers and tasks, mounted and unmounted with one call. | One domain must start and stop as a unit. |
+| `createAction(type)` | An action with no handler: a name and a payload. | The UI or a handler tells that something happened. |
+| `createAction(type, handler)` | An action with a handler: `emit` runs the handler and returns its result. | You want the result of the handler from `emit`. |
+| `createJob(type, handler)` | An action with a handler that returns its result as the actions `success` and `fail`, and also sends `pending` and `cancel`. | You want the result of the work of a handler and, if you need it, to subscribe to the state of that work. |
+| `createModule(name, setup)` | A group of actions and jobs with their handlers, mounted and unmounted with one call. | One domain must start and stop as a unit. |
 
-Start with events. Add a handler when you need a result, a job when you need a status, a module when you need a unit.
+Start with actions. Add a handler when you need a result, a job when you need a status, a module when you need a unit.
 
 ## On this page
 
-- [Pick the word: event, action, job, module](#pick-the-word-event-action-job-module)
-- [Return a value from `emit` with a handler](#return-a-value-from-emit-with-a-handler)
-- [Describe events, handlers and jobs](#describe-events-handlers-and-jobs)
+- [Action, job and module](#action-job-and-module)
+- [Get the result of `emit`](#get-the-result-of-emit)
+- [Actions, handlers and jobs](#actions-handlers-and-jobs)
   - [Actions](#actions)
   - [Bind a handler later](#bind-a-handler-later)
-  - [Say what a bound handler returns](#say-what-a-bound-handler-returns)
+  - [The result type of a bound handler](#the-result-type-of-a-bound-handler)
   - [Jobs](#jobs)
-- [Show a loading state with a job](#show-a-loading-state-with-a-job)
-- [Mount domains with modules](#mount-domains-with-modules)
-- [Give an action or a module its own fields](#give-an-action-or-a-module-its-own-fields)
+- [The state of a job](#the-state-of-a-job)
+- [Modules](#modules)
+- [Extend the context of actions and modules](#extend-the-context-of-actions-and-modules)
 
-## Return a value from `emit` with a handler
+## Get the result of `emit`
 
-Give `createAction` a handler, and `emit` runs it and returns its result. There is one creator for an event and for an action with work behind it; the handler is the only difference.
+When you want an answer from a handler at the `emit` call, give `createAction` the handler. A handler is a function `(payload, ctx) => result` that runs when the action is emitted. `emit` runs it and returns its result. There is one creator for an action with and without a handler; the handler is the only difference.
 
-The bus lives in one file and its events in another, so any module can import both without a cycle.
+The bus lives in one file and its actions in another, so any module can import both without a cycle.
 
 ```js
 // bus.js
@@ -2311,7 +2950,7 @@ import { double } from "./math";
 bus.emit(double(21)); // 42
 ```
 
-## Describe events, handlers and jobs
+## Actions, handlers and jobs
 
 `nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
 
@@ -2346,7 +2985,7 @@ These are the events of the user domain, in a file of their own (`user.js`). The
 - `userLoaded.match(action)` — narrows an action
 - `createAction(type, handler)` — a function as the second argument is the handler; `bus.emit(action(payload))` tells the listeners, runs the handler as a task and returns its result
 - `createAction(type, { prepare })` — build the payload from several arguments
-- `createAction(type, { handle, prepare, ...scope })` — everything in one object: `handle` and `prepare` are taken out, and every other field is the [scope](scope.md)
+- `createAction(type, { handle, prepare, ...scope })` — everything in one object: `handle` and `prepare` are taken out, and every other field is the [scope](context.md#scope-fields-for-an-action-a-module-and-a-call)
 - Works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`
 
 A scope goes after a handler as the last argument, `createAction(type, handler, scope)`; `prepare` with a handler goes in that last object: `createAction(type, handler, { prepare, ...scope })`.
@@ -2396,7 +3035,7 @@ A handler bound in the registry makes `bus.emit(sendMail(mail))` run it and retu
 
 The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the handler that the action carries. `bus.use(actionsPlugin())` sets `bus.actions`. A second `actionsPlugin` binds its list in that registry and returns it. There is no `actions` option in `createBus`; assign a custom runner with `bus.actions = { run }`, and add `bound(type)` to it to answer for actions that have no handler of their own.
 
-### Say what a bound handler returns
+### The result type of a bound handler
 
 TypeScript cannot see which handler the registry has, so the type of `emit` for an action without a handler is `void`. Tell it what the bound handler returns with `Call<Payload, Result>`. This is a promise of yours: nothing checks it against the handler.
 
@@ -2440,7 +3079,7 @@ On a bus without an event map you can say it where you call: `const id = bus.emi
 - Calling the job only builds `{ type, payload }`; the handler runs on `emit`.
 - The outcomes are events like any other: with `onUnhandled` set on the bus, it is called for a `pending` or a `cancel` that nobody listens to.
 
-## Show a loading state with a job
+## The state of a job
 
 **Problem.** A spinner needs a flag that is `true` while a request runs. Setting it by hand in the handler (`loading = true`, then `try` / `finally`) breaks when the task is aborted: `ctx.emit` does nothing after an abort, so a flag that is cleared through the bus stays `true`.
 
@@ -2513,7 +3152,7 @@ bus.emit(loadUser("1"));
 
 A flag is exact when calls do not overlap, or when `latest` replaces them. If several runs can go at once (`queue` with `concurrency` above 1, or a job without a policy called many times), keep a counter: add one on `pending` and take one off on `success`, `fail` and `cancel`. A policy that you write yourself, or that you hide in your own function, does not report to the job; `pending` is then sent at the call, as for a job with no policy.
 
-## Mount domains with modules
+## Modules
 
 **Problem.** A domain needs several subscriptions and handler bindings. With plain `bus.on` / `actions.handle` you must remember every unsubscribe.
 
@@ -2606,9 +3245,9 @@ If the `setup` of one module throws, the modules of that call that were already
   - `spawn` — background task, aborted on unmount.
 - An action that carries a handler keeps answering after unmount (`use` only tracks registration). Use `handle` for a handler that must live only as long as the module.
 
-## Give an action or a module its own fields
+## Extend the context of actions and modules
 
-An action with a handler can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`$effects` binds functions to the task), as the last argument of `createAction`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
+An action with a handler can need its own client, a module its own logger. Pass a scope, a plain object whose keys go on `ctx` (`$effects` binds functions to the task), as the last argument of `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
 
 ```js
 // bus.js
@@ -2640,13 +3279,15 @@ const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
 bus.emit(getUser("1"), { api: fakeApi });
 ```
 
-The handler gets the fields typed. Without `scopePlugin` the scope is ignored. The full picture, with jobs, actions, modules and which value wins, is in [scopes](scope.md).
+The handler gets the fields typed. Without `scopePlugin` the scope is ignored. The full picture, with jobs, actions, modules and which value wins, is in [scopes](context.md#scope-fields-for-an-action-a-module-and-a-call).
 
 ---
 Source: docs/stores.md
 
 # Connect Redux, Zustand, MobX, or Pinia
 
+> **Level E.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when you **already have a store** and want async work with cancellation and policies next to it. It is not a reason to pick Redux (or any store).
 
 If you do not have a store yet, use `createBus` from the [Guide](guide.md).
@@ -3322,6 +3963,8 @@ Source: docs/query-libraries.md
 
 # Use nanoeffects with React Query, SWR and RTK Query
 
+> **Level E.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query), [SWR](https://swr.vercel.app) or [RTK Query](https://redux-toolkit.js.org/rtk-query/overview) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one action that the libraries call, then three recipes for the parts around it: a client that stops with the request, a live stream into the cache, and a refetch on a bus event.
 
 You need a React project, `nanoeffects`, and one of the libraries. `api` below is your own client: replace it with your requests.
@@ -3448,7 +4091,7 @@ import { createAction } from "nanoeffects/actions";
 export const userLoaded = createAction("user/loaded");
 ```
 
-Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the action with `createJob` here: a job handles the error itself and resolves with `undefined`, so React Query would never see the failure. Use a job when nothing waits for the result and the app shows a loading state from the bus, see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job).
+Send it from the handler with `ctx.emit(userLoaded(user))`. Do not replace the action with `createJob` here: a job handles the error itself and resolves with `undefined`, so React Query would never see the failure. Use a job when nothing waits for the result and the app shows a loading state from the bus, see [Show a loading state with a job](actions.md#the-state-of-a-job).
 
 ## Call it from RTK Query
 
@@ -3720,6 +4363,8 @@ Source: docs/server.md
 
 # Stop work on a server when the client leaves
 
+> **Level C.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if you run a Node server (the examples use [Fastify](https://fastify.dev)) and want the work for a request, a socket or a queued job to stop when nobody needs it. It shows one pattern in three places: a request, a WebSocket and a worker.
 
 You need Node 18 or newer, `fastify` and `nanoeffects`. `api` below is your own client for another service: replace it with your requests.
@@ -3926,31 +4571,35 @@ Source: docs/react.md
 
 # Build a sign-up form in React
 
-Use this page when a React screen starts requests on user input and you need them not to race: a username check while typing, a submit button, a flaky network. It builds one registration form. The bus lives outside React; the component only subscribes to it.
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
+The task is a registration form. While the user types a name, the form asks the backend whether it is free, and the "Sign up" button submits the form. That makes the requests race: the answer to an old input can arrive after the answer to a new one and show a wrong result. This page shows how to solve it with nanoeffects. The bus lives outside React; the component only subscribes to it.
+
+Steps 1 and 2 are required, step 3 is not. The last two sections are extra.
 
 You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
 
 ## On this page
 
-- [See what goes wrong without a bus](#see-what-goes-wrong-without-a-bus)
-- [Wire the bus once](#wire-the-bus-once)
-- [Connect the form](#connect-the-form)
-- [Stop running work when the form closes](#stop-running-work-when-the-form-closes)
+- [Problems of the form without a bus](#problems-of-the-form-without-a-bus)
+- [1. The bus and the handlers](#1-the-bus-and-the-handlers)
+- [2. The form component](#2-the-form-component)
+- [3. Stop requests when the form closes](#3-stop-requests-when-the-form-closes)
 - [Show the last value of an event as state](#show-the-last-value-of-an-event-as-state)
 - [Keep a debounced handler between renders](#keep-a-debounced-handler-between-renders)
 - [Where to go next](#where-to-go-next)
 
-## See what goes wrong without a bus
+## Problems of the form without a bus
 
 A registration form has three problems that `useEffect` and `fetch` leave to you:
 
-- **A stale answer.** The user types `ann`, then `anna`. The answer for `ann` arrives last and says the name is free, although `anna` is taken.
+- **A race in the name check.** The user types `ann`, then `anna`, and every input sends a "is the name free" request. The answer for `ann` arrives last and says the name is free, although `anna` is taken.
 - **A double submit.** A second click on "Sign up" sends a second request while the first one is running.
 - **A flaky network.** One failed request should be retried, but a "name is taken" answer should not.
 
 Each has a policy or an effect: `latest`, `leading`, `retry`. They live in one place, outside the component.
 
-## Wire the bus once
+## 1. The bus and the handlers
 
 Keep the bus in a file of its own, and the handlers of the form in another. Create the bus once, outside any component: a bus created in the body of a component would be a new bus, without subscribers, on every render.
 
@@ -4007,7 +4656,7 @@ bus.on(
 
 The handlers know nothing about React. A test can emit `username/typed` and read `username/checked` without rendering anything: the same wiring is tested in [`examples/registration-form.ts`](../examples/registration-form.ts) and `src/tests/registration-form.test.ts`.
 
-## Connect the form
+## 2. The form component
 
 <!-- docs-check: continue -->
 
@@ -4078,11 +4727,11 @@ The `disabled` button is only for the look. The form stays correct without it: `
 
 In development, React StrictMode runs the effect twice (subscribe, unsubscribe, subscribe). That is safe here, because the cleanup removes exactly what the effect added.
 
-## Stop running work when the form closes
+## 3. Stop requests when the form closes
 
 <!-- docs-check: continue -->
 
-Unsubscribing stops the component from hearing results, but a request that has started keeps running. To cancel it, the component emits `form/closed` when it unmounts, and each handler that should stop listens for it with `ctx.on`:
+This step is optional. Unsubscribing stops the component from hearing results, but a request that has started keeps running. To cancel it, the component emits `form/closed` when it unmounts, and each handler that should stop listens for it with `ctx.on`:
 
 ```js
 import { latest } from "nanoeffects/policies";
@@ -4204,12 +4853,37 @@ export const Search = ({ wait }) => {
 - Write the policy without its callback: `debounce(300)`, not `debounce(300, callback)`. `usePolicy` puts the callback in itself, always the one of the latest render.
 - To combine policies, write a function of the task: `(task) => throttle(100, latest(task))`. Here `task` is the callback that `usePolicy` keeps current; pass it, not your own function.
 - `deps` stay your job: `debounce(wait)` is made again on every render, but only the first one (and the one after `deps` change) is used.
-- Without a React component, use [`withPolicy`](policies.md#use-a-policy-without-a-bus).
+- Without a React component, use [`withPolicy`](policies.md#withpolicy-call-a-policy-outside-a-bus).
+
+### Write a policy without its function
+
+**Problem.** `usePolicy` puts the callback of the latest render into the policy itself, so it needs a policy that has no function yet. If you passed your own function there, it would be easy to pass the wrong one.
+
+Leave the function out and the policy returns a wrapper. The wrapper takes a function and gives back the same policy as the direct call:
+
+```js
+import { debounce } from "nanoeffects/policies";
+
+const runSearch = async (query) => {
+  await api.search(query);
+};
+
+// debounce(300) — no function yet: returns a wrapper
+const wrap = debounce(300);
+
+// the wrapper takes the function; same as debounce(300, runSearch)
+const search = wrap(runSearch);
+```
+
+- It works for `latest()`, `leading()`, `debounce(ms)`, `throttle(ms)` and `queue()`, with the options as the last argument: `queue({ concurrency: 2 })`, `debounce(300, { leading: true })`.
+- Each time you apply a wrapper to a function, you get a new policy with its own state.
+- To combine policies, nest them: `throttle(100, latest(fn))`.
+- With `key`, annotate the payload of the key function in TypeScript: `latest({ key: (user: User) => user.id })`. Without the annotation the wrapper cannot know the payload type.
 
 ## Where to go next
 
 - The policies behind this form: [Policies](policies.md).
-- A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-a-bus).
+- A policy as a plain function without a bus: [`withPolicy`: call a policy outside a bus](policies.md#withpolicy-call-a-policy-outside-a-bus).
 - `retry`, `timeout` and the other effects: [Effects](effects.md).
 - A state library instead of `useState`: [Stores](stores.md).
 - React Query or SWR instead of your own state: [Use nanoeffects with React Query, SWR and RTK Query](query-libraries.md).
@@ -4219,6 +4893,8 @@ Source: docs/chat-example.md
 
 # Build a chat with entities, features, modules and a small server
 
+> **Level D.** Read first: [Actions, jobs and modules](actions.md).
+
 Use this page when your app has several features that react to each other and you want to see where each piece of logic goes. The example is a chat with rooms, a history that loads, messages that can fail to send, a search across all rooms, and new messages that arrive on their own. A small Fastify server in the example answers every request, and it misbehaves on a known schedule, so each problem on this page really happens.
 
 It is a level D example. Start with [Actions, jobs and modules](actions.md) for the API, or with the `domains-ts` template in [Start a project from a template](starter.md#start-with-domains) for a smaller project.
@@ -4307,7 +4983,7 @@ import { latest } from "nanoeffects/policies";
 export const fetchHistory = latest((roomId, { signal }) => api.loadHistory(roomId, { signal }));
 ```
 
-The module gives the job its work and keeps the state from the outcomes, so an aborted load clears the flag too (see [Show a loading state with a job](actions.md#show-a-loading-state-with-a-job)):
+The module gives the job its work and keeps the state from the outcomes, so an aborted load clears the flag too (see [Show a loading state with a job](actions.md#the-state-of-a-job)):
 
 ```js
 // message-module.js
@@ -4487,6 +5163,8 @@ Source: docs/chat-widget.md
 
 # Build a chat widget that listens only while it is open
 
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when a site has a chat with a bot behind a launcher button, and the chat must cost nothing while it is closed. Closed means no subscriptions on the bus, no polling, no keyboard listener, and no request still running. Opening turns all of it on, and closing turns all of it off in one call.
 
 The code is in [`examples/chat-widget`](../examples/chat-widget): plain DOM and TypeScript, a fake bot in the browser, no server. Run it on [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat-widget), or on your machine:
@@ -4621,11 +5299,77 @@ While the chat is closed the launcher holds no subscription at all: it only has
 - Replace the polling by a WebSocket in a spawned task: the abort closes it the same way (see [`examples/trades`](../examples/trades) for a socket under `retry` and `latest`).
 - Watch the whole thing in the [trace](tracing.md): the module, the bot task, the retries and the polling are tasks of one tree.
 
+---
+Source: docs/examples.md
+
+# Examples
+
+> **Levels A to F.** Read first: [README](README.md#the-ladder-from-a-to-f).
+
+Examples to run in the browser and to read. Every folder lives in `examples/` of the repository and is type-checked with the project. Two of them are explained step by step: [Build a chat](chat-example.md) and [Build a chat widget](chat-widget.md).
+
+## Try it in the browser
+
+All three are the same search box: type fast and only one request starts (`debounce`); type again while a request runs and the older one is aborted (`latest`). StackBlitz runs them with no install.
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`playground`](../examples/playground) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground) | Plain DOM and one file: the smallest setup. The page lists the requests, so the abort is visible. |
+| [`playground-react`](../examples/playground-react) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground-react) | The same search in a React component, with the bus outside React. |
+| [`playground-devtools`](../examples/playground-devtools) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/playground-devtools) | The same search with its emits and stopped calls sent to Redux DevTools. |
+
+## Bigger projects
+
+React and TypeScript projects that show where logic goes when an app has several features.
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`chat`](../examples/chat) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat) | Rooms, history under `latest`, ordered sends under `queue` and `retry`, search under `allSettled`, polling with `poll`. Explained in [Build a chat](chat-example.md). |
+| [`pokedex`](../examples/pokedex) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/pokedex) | Real requests to PokeAPI: a search with `debounce`, `latest`, `timeout` and `retry`, abilities with `allSettled`. |
+| [`spells`](../examples/spells) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/spells) | The smallest example: a search in one file, one action that carries its handler. |
+| [`chat-widget`](../examples/chat-widget) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat-widget) | A chat behind a launcher button: opening mounts one module, closing unmounts it. Explained in [Build a chat widget](chat-widget.md). |
+| [`counter`](../examples/counter) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/counter) | The counter of the redux-saga tutorial, without a store and with Redux Toolkit. |
+| [`rickandmorty`](../examples/rickandmorty) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/rickandmorty) | Characters with React Query: requests are actions that get its abort signal. |
+| [`trades`](../examples/trades) · [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/trades) | A live stream over a WebSocket: `retry`, `latest` and `throttle`. |
+
+## Backend examples
+
+Small [Fastify](https://fastify.dev) apps with no database. They need Node 18 or newer: run `npm install` and `npm start` in the folder. More in [Stop work on a server](server.md).
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`api-server`](../examples/api-server) | A server over PokeAPI: `timeout`, `retry`, `allSettled`, and an abort when the client leaves. |
+| [`job-worker`](../examples/job-worker) | A queue worker: `queue`, `retry`, `timeout`, counts from the outcomes of a job. |
+| [`ws-server`](../examples/ws-server) | A WebSocket server: one controller per socket, `latest` with a `key`. |
+
+## Recipes
+
+Each file is one job, written as a short program with a comment on every nanoeffects call.
+
+| File | Job | Docs |
+| ---- | --- | ---- |
+| [`search.ts`](../examples/search.ts) | A search box that waits for quiet and aborts the older request. | [Policies](policies.md) |
+| [`backoff.ts`](../examples/backoff.ts) | Retry a flaky request with a growing pause. | [Effects](effects.md#backoff) |
+| [`registration-form.ts`](../examples/registration-form.ts) | A sign-up form: a username check that does not race. | [React form](react.md) |
+| [`scope.ts`](../examples/scope.ts) | An action with its own effects and a test that replaces one. | [Working with context](context.md) |
+| [`modules.ts`](../examples/modules.ts) | Domain logic with no UI, mounted and unmounted as one unit. | [Actions](actions.md) |
+| [`redux.ts`](../examples/redux.ts) | Redux Toolkit actions that also reach the bus. | [State managers](stores.md) |
+| [`guide.ts`](../examples/guide.ts) | The code of every step of the guide. | [Guide](guide.md) |
+
+## TypeScript projects
+
+| Folder | What is in it |
+| ------ | ------------- |
+| [`typescript`](../examples/typescript) | Name the event map once and use it in modules and actions. |
+| [`typescript-context`](../examples/typescript-context) | Give `ctx` the fields of your bus and type them from one place. |
+
 ---
 Source: docs/vue.md
 
 # Use nanoeffects in a Vue app
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when your app is in Vue 3 and a component has to talk to the bus: tell it that a value changed, and show the result of an event. `vuePlugin` gives you two functions for that. To see them in a running project, start from the `vue-ts` template in [Start a project from a template](starter.md#start-with-vue).
 
 You need Vue 3.3 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
@@ -4718,7 +5462,7 @@ In TypeScript the type of the `ref` comes from the event: with `createAction<str
 ## Where to go next
 
 - The same two jobs for React: [Build a sign-up form in React](react.md).
-- A policy in a component (a debounced save): in `<script setup>` make it once with [`withPolicy`](policies.md#use-a-policy-without-a-bus); Vue runs the setup once, so it needs no hook.
+- A policy in a component (a debounced save): in `<script setup>` make it once with [`withPolicy`](policies.md#withpolicy-call-a-policy-outside-a-bus); Vue runs the setup once, so it needs no hook.
 - Keep values in Pinia: [Connect Redux, Zustand, MobX, or Pinia](stores.md).
 
 ---
@@ -4726,6 +5470,8 @@ Source: docs/svelte.md
 
 # Use nanoeffects in a Svelte app
 
+> **Level B.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Use this page when your app is in Svelte 5 and a component has to show the result of an event. `sveltePlugin` gives you one function for that, `eventStore`. To see it in a running project, start from the `svelte-ts` template in [Start a project from a template](starter.md#start-with-svelte).
 
 You need Svelte 5 or newer and `nanoeffects` installed. If you do not know what the bus is, read the [Guide](guide.md) first.
@@ -4804,16 +5550,39 @@ bus.on(searchLoaded, (titles) => foundTitles.set(titles));
 ## Where to go next
 
 - The same job for React: [Build a sign-up form in React](react.md); for Vue: [Use nanoeffects in a Vue app](vue.md).
-- A policy in a component (a debounced save): in the script of a component make it once with [`withPolicy`](policies.md#use-a-policy-without-a-bus); Svelte runs the script once, so it needs no hook.
+- A policy in a component (a debounced save): in the script of a component make it once with [`withPolicy`](policies.md#withpolicy-call-a-policy-outside-a-bus); Svelte runs the script once, so it needs no hook.
 
 ---
 Source: docs/context.md
 
-# Put your own fields on every task
+# Working with context
+
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus).
+
+Optional: put a store, client or logger on every task, or give fields to one action, module or call. Skip until many handlers need the same dependency.
+
+## On this page
 
-Optional: put a store, client, or logger on every task. Skip until many handlers need the same dependency.
+- [Context fields](#context-fields)
+  - [Pass values at runtime](#pass-values-at-runtime)
+  - [Type the fields (optional)](#type-the-fields-optional)
+  - [Build a field from the signal of each task](#build-a-field-from-the-signal-of-each-task)
+- [Scope: fields for an action, a module and a call](#scope-fields-for-an-action-a-module-and-a-call)
+  - [Turn scopes on](#turn-scopes-on)
+  - [Give an action its own fields](#give-an-action-its-own-fields)
+  - [Bind an effect to the task](#bind-an-effect-to-the-task)
+  - [Replace a field for one call](#replace-a-field-for-one-call)
+  - [Give an action, a job or a module its own fields](#give-an-action-a-job-or-a-module-its-own-fields)
+  - [Which value wins](#which-value-wins)
+  - [Keep a generic effect generic](#keep-a-generic-effect-generic)
+  - [Type the fields of a scope](#type-the-fields-of-a-scope)
+  - [Limits](#limits)
+
+## Context fields
+
+### Pass values at runtime
 
-## Pass values at runtime
+<!-- docs-check: new -->
 
 ```js
 import { createBus } from "nanoeffects";
@@ -4826,15 +5595,17 @@ bus.on("save", (draft, { store }) => {
 });
 ```
 
-That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, actions, modules, and child tasks of effects and policies.
+Here `store` is your own object: a store, an API client, a logger, anything. That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, actions, modules, and child tasks of effects and policies.
 
 Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may be a function `(task) => fields` when the value depends on the task.
 
-To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
+To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#effectsplugin).
+
+To give fields to **one** action, job or module, or to replace them for one `emit`, see [scopes](context.md#scope-fields-for-an-action-a-module-and-a-call).
 
-To give fields to **one** action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
+### Type the fields (optional)
 
-## Type the fields (optional)
+<!-- docs-check: new -->
 
 In TypeScript, `contextPlugin` (from `nanoeffects/context`) puts the fields on every task of **this** bus and takes their types from the value you pass. The event map holds only events. It does not wire anything across the app — another bus can have different fields or none.
 
@@ -4856,7 +5627,9 @@ bus.on("save", (draft, { store }) => store.put(draft));
 - A name that the bus already has is a type error. The fields of the library (`signal`, `emit`, `run`, …) win at runtime, and a field that the context already has is not replaced.
 - The plugin returns the same bus, so keep the result of the chain: `const bus = createBus().use(contextPlugin({ store }))`.
 
-## Build a field from the signal of each task
+### Build a field from the signal of each task
+
+<!-- docs-check: new -->
 
 Problem: an HTTP client or a database handle should stop when the task is aborted. Without help, every handler passes `ctx.signal` to it by hand, and one forgotten call leaves a request running.
 
@@ -4883,12 +5656,13 @@ bus.on("user/open", async (id, ctx) => {
 });
 ```
 
+- `signalFetch` from the same entry is a `fetch` bound to a signal, so `fetch: fromSignal(signalFetch)` gives every handler a `ctx.fetch` that stops with the task. [Bind the signal once](pass-the-signal.md#bind-the-signal-once)
 - `make` runs at the first read, so a handler that never uses `ctx.http` pays nothing for it.
 - A task that `ctx.run` starts builds its own value from its own signal, so aborting the child stops only the child's requests.
 - The field is not copied by `{ ...ctx }` and `Object.keys(ctx)` does not list it. Read `ctx.http` first if you copy a context.
 - Without `contextPlugin` a `fromSignal` marker is only an object.
 
-### Name the fields in the event map instead
+#### Name the fields in the event map instead
 
 `createBus<Events>({ context: { store } })` also types the fields, but through the event map: `WithContext` is checker-only and says which fields the handlers of this bus have. Use it when you cannot call `use`, for example for the bus that `createEffectsMiddleware` makes.
 
@@ -4901,10 +5675,7 @@ type Events = { save: Draft } & WithContext<{ store: Store }>;
 const bus = createBus<Events>({ context: { store } });
 ```
 
----
-Source: docs/scope.md
-
-# Pin context fields to an action, a module or a call
+## Scope: fields for an action, a module and a call
 
 Optional, for domain logic. Use it when one action needs its own client, one module its own logger, or one test its own fake, and a field on the whole bus ([context fields](context.md)) is too wide.
 
@@ -4912,19 +5683,9 @@ A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`,
 
 You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
 
-## On this page
-
-- [Turn scopes on](#turn-scopes-on)
-- [Give an action its own fields](#give-an-action-its-own-fields)
-- [Bind an effect to the task](#bind-an-effect-to-the-task)
-- [Replace a field for one call](#replace-a-field-for-one-call)
-- [Give an action, a job or a module its own fields](#give-an-action-a-job-or-a-module-its-own-fields)
-- [Which value wins](#which-value-wins)
-- [Keep a generic effect generic](#keep-a-generic-effect-generic)
-- [Type the fields (optional)](#type-the-fields-optional)
-- [Limits](#limits)
+### Turn scopes on
 
-## Turn scopes on
+<!-- docs-check: new -->
 
 Scopes are a plugin, so a bus that does not use them pays nothing.
 
@@ -4942,7 +5703,9 @@ The bus is in one file and the actions in files named after their domain, so the
 - Without `scopePlugin` a scope is **ignored**: no error and no warning. If a field is missing from `ctx`, check this first.
 - Use it in any order with the other plugins: a scope wins over `effectsPlugin`, `contextPlugin` and `createBus({ context })`.
 
-## Give an action its own fields
+### Give an action its own fields
+
+<!-- docs-check: new -->
 
 <!-- docs-check: continue -->
 
@@ -4970,7 +5733,9 @@ const user = await bus.emit(getUser("1")); // the handler has api and cache
 
 The listeners of `"user/get"` get the same fields when the action is emitted, because the fields belong to the call.
 
-## Bind an effect to the task
+### Bind an effect to the task
+
+<!-- docs-check: new -->
 
 An effect is a function with `{ signal }` as its first parameter. In `$effects` it is bound to the task, so it stops with the task.
 
@@ -5015,7 +5780,9 @@ const result = await bus.emit(loadFeed("/feed"));
 - A function under any other key is copied as it is; a function in `$effects` is bound.
 - `$effects` is the one name with a meaning. A field called `effects` is an ordinary field: `{ effects: { retries: 3 } }` puts that object on `ctx`, and nothing in it is bound.
 
-## Replace a field for one call
+### Replace a field for one call
+
+<!-- docs-check: new -->
 
 The second argument of `emit` is a scope for the tasks of **that** call. It is the usual way to give a test a fake.
 
@@ -5057,7 +5824,9 @@ Rules for the second argument:
 - It can replace `$effects` too: `{ $effects: { delay: instantDelay } }`.
 - Fields of the library (`signal`, `emit`, …) in it are ignored.
 
-## Give an action, a job or a module its own fields
+### Give an action, a job or a module its own fields
+
+<!-- docs-check: new -->
 
 ```js
 // user.js
@@ -5096,7 +5865,9 @@ If the outcome action (`success` or `fail`) has a scope of its own, its listener
 
 A module scope does not leak: a listener registered outside the module does not see it.
 
-## Which value wins
+### Which value wins
+
+<!-- docs-check: new -->
 
 When several places set the same field, the strongest one wins:
 
@@ -5109,7 +5880,9 @@ When several places set the same field, the strongest one wins:
 
 The fields of the library (`signal`, `abort`, `emit`, `on`, `off`, `run`, `type`, `payload`) are never replaced. The name `traceGroupId` is reserved: the tracer reads it, and it is not put on `ctx` ([Follow one flow](tracing.md#follow-one-flow-with-a-tracegroupid)). A child task (`ctx.run`, an attempt of `retry`) has the fields of its parent.
 
-## Keep a generic effect generic
+### Keep a generic effect generic
+
+<!-- docs-check: new -->
 
 In `$effects` a function loses its first parameter, and TypeScript cannot keep a generic through that step: `<T>(items: T[]) => T` becomes `(items: unknown[]) => unknown`. JavaScript code is not affected. If you want the exact type, use one of two ways.
 
@@ -5151,7 +5924,9 @@ const pick = createAction(
 
 `Effect<F>` and `effect` change what the checker sees. At run time the function is the same.
 
-## Type the fields (optional)
+### Type the fields of a scope
+
+<!-- docs-check: new -->
 
 A handler of an action, job or module with a scope sees the fields of the scope in `ctx`, typed from the values you gave. You write no `WithContext`.
 
@@ -5175,7 +5950,9 @@ const getUser = createAction(
 - A field that no scope and no bus declares has no type to check against, so `emit(call, { unknown: 1 })` is an error in TypeScript.
 - `bus.on(creator, fn)` for an action with a scope types `ctx` with its fields.
 
-## Limits
+### Limits
+
+<!-- docs-check: new -->
 
 - No plugin, no scope: see [Turn scopes on](#turn-scopes-on).
 - The fields of the bus are not in the handler of an action made with `createAction(…, scope)` unless you type `ctx` yourself; the fields of the scope are.
@@ -5188,6 +5965,8 @@ Source: docs/oop.md
 
 # Use the bus from a class
 
+> **Level D.** Read first: [Guide](guide.md#1-create-a-bus) step 1.
+
 Use this page when **your domain logic lives in classes**: a service, a store or a controller that needs the bus inside its methods. There are two ways to give a class the methods of a bus, and both remember what each instance subscribed to, so `dispose()` ends it all:
 
 | You want | Use |
@@ -5195,7 +5974,7 @@ Use this page when **your domain logic lives in classes**: a service, a store or
 | every `new Service()` to be an independent emitter | `extends Emitter` |
 | the instances to share a bus, or to use plugins | `extends extendBus(bus)` |
 
-If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-modules): a module is the same idea without a class.
+If your logic is plain functions, stay with [modules](actions.md#modules): a module is the same idea without a class.
 
 ## On this page
 
@@ -5621,6 +6400,8 @@ Source: docs/typescript.md
 
 # Use nanoeffects in a TypeScript app with many files
 
+> **Level D.** Read first: [Guide](guide.md#10-add-types-when-you-want-checking-optional).
+
 Read this page if your app is in TypeScript and the handlers and modules live in different files. It shows how to write an action with a handler so that TypeScript infers its payload and result, and what to add when the handlers need the fields of your bus (`ctx.store`, the effects of `effectsPlugin`). For one file or for JavaScript you do not need it.
 
 ## Write an action with its handler
@@ -5793,6 +6574,8 @@ Source: docs/migrating-from-saga.md
 
 # Coming from redux-saga
 
+> **Level E, for readers who know redux-saga.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if you know redux-saga and want to find the same job in nanoeffects. It maps the names, shows one saga rewritten, and lists what has no equivalent. It does not teach the library: start with the [Guide](guide.md).
 
 ## Find the equivalent
@@ -5892,6 +6675,8 @@ Source: docs/migrating-from-effector.md
 
 # Coming from Effector
 
+> **Level E, for readers who know Effector.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if your project uses Effector and you want to know where nanoeffects fits. They overlap in one place: events that start effects. Effector also holds state; nanoeffects does not. It maps the names, shows one effect both ways, and lists what has no equivalent.
 
 ## On this page
@@ -5923,7 +6708,7 @@ nanoeffects has no store. `createStore` can be replaced by any store you like, f
 | event call `loaded(user)` | `bus.emit("loaded", user)` |
 | `createEffect(handler)` | a handler: `bus.on(event, handler)` |
 | effect with `done` and `fail` | [`createJob`](actions.md): emits the success and fail actions |
-| `effect.pending` | `job.pending`, `job.success`, `job.fail` and `job.cancel`: set and clear the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)) |
+| `effect.pending` | `job.pending`, `job.success`, `job.fail` and `job.cancel`: set and clear the flag in your store ([Show a loading state](actions.md#the-state-of-a-job)) |
 | `sample({ clock, fn, target })` | `bus.on(clock, handler)` and `ctx.emit(target, …)` |
 | `sample({ source: $store, clock })` | read the store from a [context field](context.md) in the handler |
 | `sample({ filter })` | an `if` in the handler |
@@ -6221,7 +7006,7 @@ bus.on(
 ## What is different
 
 - **No state.** There is no `createStore`, `combine`, `restore`, `$store.map`. The bus holds listeners only. Take a store such as Zustand for state ([Stores](stores.md)).
-- **`pending` is an action, not a store.** `createJob` sends `pending` when the handler starts, and `success`, `fail` or `cancel` when it ends; you keep the flag in your store ([Show a loading state](actions.md#show-a-loading-state-with-a-job)). Policies report to the job, so the flag also follows `latest`, `leading`, `debounce`, `throttle` and `queue`; that section says when to count instead. A running task is also visible through [Tracing](tracing.md).
+- **`pending` is an action, not a store.** `createJob` sends `pending` when the handler starts, and `success`, `fail` or `cancel` when it ends; you keep the flag in your store ([Show a loading state](actions.md#the-state-of-a-job)). Policies report to the job, so the flag also follows `latest`, `leading`, `debounce`, `throttle` and `queue`; that section says when to count instead. A running task is also visible through [Tracing](tracing.md).
 - **Cancellation is the default tool.** An Effector effect runs every call to the end. Here `latest` and `ctx.signal` stop what is no longer needed.
 - **Events are matched by name, not by identity.** An event is a string or a `createAction` creator, not a unit that you import and call. Two modules agree on the name.
 - **No graph.** `sample` and `forward` build a static graph. A bus subscribes handlers at runtime and the call order is the order of `on`.
@@ -6231,9 +7016,11 @@ bus.on(
 ---
 Source: docs/migrating-from-mitt.md
 
-# Coming from mitt, nanoevents or EventEmitter
+# Coming from mitt and nanoevents
 
-Read this page if your app uses a small event emitter (`mitt`, `nanoevents`, Node's `EventEmitter`, `tiny-emitter`) and its handlers start to do async work: requests, timers, retries. It maps the calls, shows what you gain, and shows what to check before you switch.
+> **Level A, for readers who know mitt or nanoevents.** Read first: nothing: the bus is the same idea.
+
+Read this page if your app uses a small event emitter (`mitt`, `nanoevents`, `tiny-emitter`) and its handlers start to do async work: requests, timers, retries. It maps the calls, shows what you gain, and shows what to check before you switch.
 
 ## When to switch
 
@@ -6248,8 +7035,8 @@ If handlers stay synchronous, keep your emitter. nanoeffects costs about 1.4 kB
 
 ## Find the equivalent
 
-| mitt / EventEmitter | nanoeffects |
-| ------------------- | ----------- |
+| mitt / nanoevents | nanoeffects |
+| ----------------- | ----------- |
 | `emitter.on("a", handler)` | `bus.on("a", handler)` |
 | `emitter.off("a", handler)` | call the function that `bus.on` returned, or `bus.off("a")` for all handlers of `a` |
 | `emitter.emit("a", payload)` | `bus.emit("a", payload)` |
@@ -6334,6 +7121,8 @@ Source: docs/migrating-from-rxjs.md
 
 # Use nanoeffects next to RxJS
 
+> **Level E, for readers who know RxJS.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 3.
+
 Read this page if your project uses RxJS and you wonder what nanoeffects takes over. It does not replace RxJS. The two split the work: RxJS shapes streams of values, nanoeffects runs the side effects that events start. It maps the operators, shows a search box and a polling loop both ways, and lists what stays in RxJS.
 
 ## Split the work
@@ -6533,6 +7322,8 @@ Source: docs/semantics.md
 
 # Semantics
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 to 6.
+
 Guarantees and sharp edges. Read when something surprises you; not required to start.
 
 ## Five rules to know first
@@ -6551,11 +7342,363 @@ Details of each rule and the rest:
 - **`leading` releases its lock when the task aborts**, not only when `fn` settles. A `fn` that ignores the abort signal can then overlap with the next run — pass `ctx.signal` to what `fn` does.
 - **Effects start their function synchronously**, so an event emitted right after the call reaches a `take` inside it.
 
+---
+Source: docs/pass-the-signal.md
+
+# Keep the signal through a handler
+
+> **Level B.** Read first: [Policies](policies.md#latest).
+
+A policy such as `latest` cancels an older call by aborting its `ctx.signal`. The handler stops only if every step that waits gets that signal. One request without it keeps running, and its result arrives after the newer one. This page lists the ways the signal gets lost, what catches each one before the code runs (a linter) and while it runs (`devPlugin`), and how to fix it.
+
+## On this page
+
+- [Know what the signal does](#know-what-the-signal-does)
+- [Bind the signal once](#bind-the-signal-once)
+- [Fix a handler that loses the signal](#fix-a-handler-that-loses-the-signal)
+- [Pass the signal when it is hard](#pass-the-signal-when-it-is-hard)
+- [Turn on the checks](#turn-on-the-checks)
+- [Choose which calls are checked](#choose-which-calls-are-checked)
+- [Count lost signals in a test](#count-lost-signals-in-a-test)
+- [Prove it with a test](#prove-it-with-a-test)
+- [Know what the checks cannot see](#know-what-the-checks-cannot-see)
+
+## Know what the signal does
+
+`ctx.signal` is an `AbortSignal`. The policy aborts it when the call is cancelled (a newer call of `latest`, a `debounce` that was replaced, an unmounted module). A step stops when you give it the signal: `fetch(url, { signal: ctx.signal })`, `api.search(query, { signal: ctx.signal })`, or the whole `ctx` for an effect, `retry(ctx, ...)`. Everything else keeps running. The bus drops what a cancelled handler emits with `ctx.emit`, so the loss shows up late and quietly.
+
+## Bind the signal once
+
+The surest fix is a handler with no signal in it. Make the client from the signal of the task, once, and the handler calls `ctx.fetch` and cannot forget anything. `signalFetch` is a `fetch` bound to a signal; `fromSignal` builds it for each task.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal, signalFetch } from "nanoeffects/signal";
+import axios from "axios";
+
+// fromSignal — ctx.fetch is made from the signal of the task that reads it
+export const bus = createBus().use(
+  contextPlugin({
+    fetch: fromSignal(signalFetch),
+    // your own client too: it is made from the signal of each task
+    http: fromSignal((signal) => axios.create({ signal })),
+  }),
+);
+```
+
+```js
+// search-handlers.js
+import { latest } from "nanoeffects/policies";
+import { bus } from "./bus";
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // no signal here: ctx.fetch stops when the policy cancels the handler
+    const response = await ctx.fetch(`/api?q=${query}`);
+    ctx.emit("results", await response.json());
+  }),
+);
+```
+
+A call with a `signal` of its own stops with whichever aborts first. Then make the linter hold the line: with `requireContext: true`, every call that a handler waits for must go through `ctx` or be given `ctx`, so a global `fetch` or `api.search(...)` is an error even when the signal is passed by hand ([turn on the checks](#turn-on-the-checks)).
+
+## Fix a handler that loses the signal
+
+The two shapes you meet first, and the fix:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+// 1. ctx is taken and the signal is lost: the request cannot stop
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    const items = await api.search(query);
+    ctx.emit("results", items);
+  }),
+);
+
+// 2. one step passes it and another does not: the first one cannot stop
+bus.on(
+  "feed",
+  latest(async (query, ctx) => {
+    const news = await api.news(query);
+    const posts = await api.posts(query, { signal: ctx.signal });
+    ctx.emit("results", { news, posts });
+  }),
+);
+
+// the fix: every step that waits gets the signal
+bus.on(
+  "feed/fixed",
+  latest(async (query, ctx) => {
+    const news = await api.news(query, { signal: ctx.signal });
+    const posts = await api.posts(query, { signal: ctx.signal });
+    ctx.emit("results", { news, posts });
+  }),
+);
+```
+
+## Pass the signal when it is hard
+
+Each row is a situation where the signal is easy to lose. The right column says how to keep it. "Lint" is the rule from [`examples/lint`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/lint) that flags it, and "devPlugin" is the warning at run time ([details](hmr.md#find-a-handler-that-ignores-the-signal)).
+
+| Situation | What to do | Lint | devPlugin |
+| --------- | ---------- | :--: | :-------: |
+| The handler has no `ctx`: `latest(async (query) => ...)` | Take `(query, ctx)` and pass `ctx.signal` | yes | |
+| `ctx` is taken and never used for the request | Pass `{ signal: ctx.signal }` to each request, or bind it once: `ctx.fetch` ([above](#bind-the-signal-once)) | yes | yes |
+| One step passes the signal, another does not | Pass it to every step | yes | yes |
+| The signal is in a variable: `const options = { signal: ctx.signal }` | Nothing, a variable that holds it counts | accepted | |
+| Calls run together: `Promise.all([a(), b()])` | Pass it to each call, not only one | yes | |
+| `Promise.all(ids.map((id) => load(id)))` | Pass it inside the callback | yes | |
+| The step is inside an effect: `retry(ctx, () => api.search(q))` | The callback is not given the signal. Pass `{ signal: ctx.signal }` in it, or use the child context it gets | yes | |
+| `timeout(ctx, 1000, (child) => api.search(q))` | Pass `child`, or `child.signal`, to the request | yes | |
+| `ctx.run((child) => api.search(q))` | Pass `child` | yes | |
+| A pause: `await new Promise((r) => setTimeout(r, 1000))` | Use `delay(ctx, 1000)` | yes | |
+| A stream: `for await (const x of api.stream(q))` | Pass the signal to `api.stream` | yes | |
+| A chain: `api.news(q).then(...)` | Pass the signal to the first call | yes | |
+| Another signal: `AbortSignal.timeout(5000)`, or the signal of your own `AbortController` | Join it with the handler's: `AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)])` | yes | |
+| Reading a response body: `await response.json()` | Nothing, the signal of the request stops it | accepted | |
+| A library that takes no signal (a cache, a local database) | List it in `ignore`, or check only the calls on your list with `only`. With type information the rule skips a function that takes no signal on its own | `ignore`, `only`, types | |
+| A function takes the signal and never uses it: `search(query, options) { return fetch(url); }` | Pass the signal on inside it. Only type information finds this in the linter; a test finds it for sure | types | |
+| The signal is wired by hand: `signal.addEventListener("abort", ...)` | Nothing, the handler is not checked step by step | accepted | |
+| `bus.emit` in a handler | Use `ctx.emit`: only it is dropped after the handler was cancelled | yes | |
+| A request that keeps running after the cancel, on Node | Pass the signal, or use `ctx.fetch` | | yes |
+| Results emitted after the cancel | The handler ignored the signal. Pass it, or check `ctx.signal.aborted` | | yes |
+| `ctx.on` after the cancel | The same | | yes |
+
+The pause and the effect rows in code:
+
+```js
+import { createBus } from "nanoeffects";
+import { delay, retry, timeout } from "nanoeffects/effects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // delay — a pause that stops with ctx, not new Promise(setTimeout)
+    await delay(ctx, 300);
+
+    // retry — the attempts stop with ctx, but the request needs the signal too
+    const items = await retry(ctx, () => api.search(query, { signal: ctx.signal }));
+
+    // timeout — the callback gets a child context: give it to the request
+    const details = await timeout(ctx, 5000, (child) => api.details(query, child));
+
+    ctx.emit("results", { items, details });
+  }),
+);
+```
+
+Calls that run together, and a signal that joins another:
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+bus.on(
+  "feed",
+  latest(async (query, ctx) => {
+    // each call of the group gets the signal, not only the first
+    const [news, posts] = await Promise.all([
+      api.news(query, { signal: ctx.signal }),
+      api.posts(query, { signal: ctx.signal }),
+    ]);
+
+    // AbortSignal.any — stops with the handler or after 5 seconds, whichever comes first
+    const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(5000)]);
+    const details = await api.details(query, { signal });
+
+    ctx.emit("results", { news, posts, details });
+  }),
+);
+```
+
+## Turn on the checks
+
+**While you write.** [`examples/lint`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/lint) has a rule for ESLint and oxlint (one file, no dependency) and two GritQL plugins for Biome. Copy the file, turn the rule on, and give it the names of calls that cannot be cancelled:
+
+<!-- docs-check: skip - a config file of the reader's project -->
+```js
+// eslint.config.mjs
+import nanoeffects from "./nanoeffects-lint.mjs";
+
+export default [
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,ts,tsx}"],
+    plugins: { nanoeffects },
+    rules: {
+      "nanoeffects/policy-handler-uses-signal": [
+        "warn",
+        // calls that take no signal and are fine to wait for
+        { ignore: ["cache.get", "storage.*"], requireContext: false },
+      ],
+    },
+  },
+];
+```
+
+For oxlint list the file in `jsPlugins` of `.oxlintrc.json` and use the same rule name. For Biome list the two `.grit` files in `plugins`. The Biome plugins read text, so they flag the direct steps (the first rows above) and miss the deeper ones: the calls of `Promise.all`, the callbacks of effects, `for await`, a pause, and the key of an options object.
+
+**While you run.** `devPlugin` warns once when a handler emits, or subscribes with `ctx.on`, after its task was cancelled:
+
+```js
+import { createBus } from "nanoeffects";
+import { devPlugin } from "nanoeffects/dev";
+
+const bus = createBus();
+
+// devPlugin — warns about a handler that kept running after it was cancelled; nothing in production
+bus.use(devPlugin());
+```
+
+## Choose which calls are checked
+
+The rule cannot tell, from the call alone, whether the function takes a signal. Ways to tell it:
+
+- **`requireContext`** needs no list: set it to `true` when handlers make requests through `ctx` (see [Bind the signal once](#bind-the-signal-once)), and any call that does not go through `ctx` is reported. `ignore` still skips a call.
+- **`ignore`** lists the calls to skip, by name: `ignore: ["cache.get", "storage.*"]`. Use it when most calls take a signal and a few cannot.
+- **`only`** lists the calls to check, by name: `only: ["api.*", "fetch"]`. Anything else is left alone, so a call that is not on the list is never reported. Use it when you know which clients take a signal. A call on both lists is skipped, and a pause that nothing can cancel (`await new Promise(...)`) is reported whatever `only` says.
+- **Type information** needs no list. With `@typescript-eslint/parser` and a `project`, the rule reads the function it calls. A call that does not get the signal is reported only when the function takes one (a parameter typed `AbortSignal`, or an options object with `signal`), so `cache.get(key)` is left alone. A call that passes the signal is reported when the function is in your sources and never uses it: the parameter is unused, or only other options are read from it. A signal forwarded to another function of yours is followed up to three calls deep, and a function from a library is trusted. A callee typed `any` is reported as before.
+
+<!-- docs-check: skip - a config file of the reader's project -->
+```js
+// eslint.config.mjs
+import parser from "@typescript-eslint/parser";
+import nanoeffects from "./nanoeffects-lint.mjs";
+
+export default [
+  {
+    files: ["**/*.{ts,tsx}"],
+    // the parser gives the rule the type checker of your project
+    languageOptions: { parser, parserOptions: { project: "./tsconfig.json" } },
+    plugins: { nanoeffects },
+    rules: { "nanoeffects/policy-handler-uses-signal": "warn" },
+  },
+];
+```
+
+oxlint and Biome do not give a rule type information, so they use the syntax and the lists. The type-aware mode needs the `typescript` package with the compiler API (version 5 today; the native version 7 has none), as `@typescript-eslint/parser` does.
+
+## Count lost signals in a test
+
+`getLostSignalsCount(bus)` from `nanoeffects/dev` returns how many signals the handlers of a bus lost: each emit or `ctx.on` that a handler made after its task was cancelled. The bus needs `devPlugin`. Run the flow the way a user would, cancel it, and check that the count is 0:
+
+```js
+import { createBus } from "nanoeffects";
+import { devPlugin, getLostSignalsCount, getLostSignals } from "nanoeffects/dev";
+import { latest } from "nanoeffects/policies";
+import { expect, test } from "vitest";
+
+test("a newer search leaves no lost signals", async () => {
+  const bus = createBus();
+  // devPlugin — records every emit that a cancelled handler made; log hides its warnings in the test
+  bus.use(devPlugin({ log: () => {} }));
+  bus.on(
+    "search",
+    latest(async (query, ctx) => {
+      const items = await api.search(query, { signal: ctx.signal });
+      ctx.emit("results", items);
+    }),
+  );
+
+  bus.emit("search", "a");
+  bus.emit("search", "ab"); // cancels the first call
+
+  // wait — how long to let the handlers finish before counting, in ms
+  const count = await getLostSignalsCount(bus, { wait: 50 });
+
+  expect(count).toBe(0);
+});
+```
+
+`getLostSignals(bus)` gives the list instead of the count: `{ kind: "emit" | "on", handler, event }` for each, so a failing test says which handler and which event. Without `devPlugin` (or with `abandoned: false`) it throws and says so. In a production build both functions are empty: the count is 0.
+
+On Node (tests, servers) it counts requests too. `devPlugin` follows the `fetch` calls that a handler makes, also after `await`, and counts one with `kind: "request"` when its task was cancelled while the request was still running and the request did not stop: it got no signal, or a signal that is not the task's. You add nothing to the test. In a browser there is no way to tell which task made a request, so only the emits and subscriptions are counted. `requests: false` turns the tracking off.
+
+```js
+import { createBus } from "nanoeffects";
+import { devPlugin, getLostSignals } from "nanoeffects/dev";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+bus.use(devPlugin({ log: () => {} }));
+
+bus.on(
+  "search",
+  latest(async (query) => {
+    await fetch(`/api?q=${query}`); // no signal
+  }),
+);
+
+bus.emit("search", "a");
+bus.emit("search", "ab");
+
+// [{ kind: "request", handler: "search", event: "/api?q=a" }]
+console.log(await getLostSignals(bus, { wait: 50 }));
+```
+
+A request that finished before the cancel is not counted. For another client (axios, a driver) bind it with `fromSignal`, or stub it in a test as the next section does for `fetch`.
+
+## Prove it with a test
+
+A linter reads code; it cannot know what a function does with the signal. A test can. The idea: replace `fetch` with a server that answers when the test lets it and stops when the request's signal aborts, run the handler, cancel it in the middle of each step, and list the requests that did not stop. No timers are involved, so the result does not depend on how fast the machine is.
+
+<!-- docs-check: skip - a test file of the reader's project -->
+```js
+// search.cancel.test.js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+import { expect, test } from "vitest";
+// copy prove-cancel.js from examples/lint; it needs no package
+import { requestsThatKeptRunning } from "./prove-cancel.js";
+
+test("a newer search stops the older one at every step", async () => {
+  const bus = createBus();
+  bus.on(
+    "search",
+    latest(async (query, ctx) => {
+      const news = await api.news(query, { signal: ctx.signal });
+      const posts = await api.posts(query, { signal: ctx.signal });
+      ctx.emit("results", { news, posts });
+    }),
+  );
+
+  // for each step: start a call, cancel it with a newer one, and collect the requests that did not stop
+  const kept = await requestsThatKeptRunning((value) => bus.emit("search", value));
+
+  // empty when every request got a signal that aborted with the handler
+  expect(kept).toEqual([]);
+});
+```
+
+`kept` has the url of each request that went on, the step where the handler was cancelled, and whether the request got a signal at all (`hadSignal: false`) or one that is not the handler's (`hadSignal: true`). This finds what the linter cannot: `api.posts` that takes `{ signal }` and ignores it, an `AbortSignal.timeout` in place of the handler's signal, a request in a branch you did not think of. It checks the boundary, `fetch`; for another client (axios, a database driver) stub that client in the same way. The repository tests the helper on handlers that forward the signal, ignore it, drop it at the third step, and use a signal of their own.
+
+## Know what the checks cannot see
+
+- **A handler that is not written in place.** `latest(searchHandler)` and `latest(withLogging(async (query, ctx) => ...))` are not read by the linter.
+- **A callee that ignores the signal you pass.** Without type information the rule sees that you passed it, not what the callee does with it. With it, the rule reads callees in your sources; a library is trusted. The test above checks the real requests.
+- **A handler that never emits.** `devPlugin` sees a lost signal by an emit after the cancel; a handler that only writes elsewhere is seen by the linter alone.
+- **Shadowed names.** The rule uses no scope analysis, so an inner variable named `signal` can hide a lost signal.
+
 ---
 Source: docs/tracing.md
 
 # Trace tasks
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) steps 1 and 2.
+
 Find out what your app did and why: which events were emitted, which calls a policy cancelled or dropped, which request failed. You see it in the browser console, in Redux DevTools, or in the Performance panel.
 
 Tracing is optional. A bus works the same without it, and it costs almost nothing until you turn it on. If you only want to see what happens while you develop, jump to [Show every emit](#show-every-emit) and [Configure Redux DevTools](#configure-redux-devtools); the rest of the page is for apps that need to follow a flow or turn tracing off in a build.
@@ -6573,6 +7716,8 @@ Tracing is optional. A bus works the same without it, and it costs almost nothin
   - [Cut volume in production](#cut-volume-in-production)
   - [Keep the last events for an incident](#keep-the-last-events-for-an-incident)
   - [Configure Redux DevTools](#configure-redux-devtools)
+  - [Find loops with `graphLogger`](#find-loops-with-graphlogger)
+  - [Send safe data to a tool](#send-safe-data-to-a-tool)
   - [Write your own logger](#write-your-own-logger)
 - [Drop tracing from a build](#drop-tracing-from-a-build)
 
@@ -6611,7 +7756,7 @@ Phases:
 - `cancel` — aborted after it started (superseded by `latest`, parent aborted, lost a `race`).
 - `drop` — never started (`leading` while busy, a `throttle` call replaced by a newer one, a `debounce` call replaced before its delay ended).
 
-`all` and `race` are traced when you pass them the handler `ctx`: the group is one task; every starter is a child `run` task.
+`all` and `race` are traced when you pass them the handler `ctx`: the group is one task; every function of the group is a child `run` task.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -6803,6 +7948,7 @@ const bus = createBus({
 | `consoleLogger()` | Prints one line per phase, indented by task depth |
 | `performanceLogger()` | User Timing measures for the browser Performance panel |
 | `createTraceRecorder()` | Keeps events in `recorder.events`: all of them for tests, or with `{ capacity }` the last N ([see below](#keep-the-last-events-for-an-incident)) |
+| `graphLogger()` | Builds the map of which event leads to which, finds loops while the app runs, and writes the map as Mermaid, Graphviz or JSON ([see below](#find-loops-with-graphlogger)) |
 
 ### Cut volume in production
 
@@ -6935,6 +8081,58 @@ reduxDevtools({
 
 With two quick `search` emits and a `latest` handler, the default list is `search`, `search`. With `policies: true` it adds the `latest` stages of each call, for example `search/latest/cancel` for the first one.
 
+### Find loops with `graphLogger`
+
+Two handlers that emit each other's events never stop. `graphLogger` is a logger that finds such a loop while the app runs, writes a report once for it, and keeps the map of the events so you can draw it.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// graphLogger — the map of events and the loop finder, in one logger
+export const graph = graphLogger({ name: "app" });
+
+// createTracer — sends every task of the bus to the logger
+const trace = createTracer(graph);
+
+// tracePlugin — also reports each emit; the logger works without it, with a coarser map
+export const bus = createBus({ trace }).use(tracePlugin());
+
+// graph.cycles() lists the loops found; graph.toMermaid() draws the map
+```
+
+It reports a node that is in one chain three times, a storm of emits from outside any handler, and a chain that starts too many tasks. It writes to `console.warn`, or to `onCycle`, or to Redux DevTools with `devtools: true`. Nothing is stopped: to cut a loop use [`loopGuardPlugin`](loop-guard.md). The full walk-through, with scenarios you can run, is [Find and cut event loops](debugging-loops.md).
+
+### Send safe data to a tool
+
+A payload or an error can be anything: a class instance, a `Map`, a circular object, a function, an `Error` with a `cause`. A tool that gets such a value as it is can fail or show nothing. The built-in loggers make sure that what leaves your process is plain data:
+
+| Logger | What it does with a payload and an error |
+| ------ | ---------------------------------------- |
+| `reduxDevtools()` | Makes both plain data with `safeSerialize` before the extension gets them. An `Error` is sent as its message. `serialize` changes this. |
+| `performanceLogger()` | Sends ids and the phase; an error is text. A payload is not sent. |
+| `consoleLogger()` | Passes the value to `console`, which prints any value and keeps it open for you to inspect. |
+| `createTraceRecorder()` | Keeps the events as they are. `recorder.toJSON()` and `JSON.stringify(recorder)` give plain data. |
+| `graphLogger()` | Exports no payload unless you ask, and then makes it plain. |
+
+`safeSerialize(value)` is exported for your own logger. It never throws and never loops: an `Error` keeps its name, message, stack and cause, a cycle becomes `"[Circular]"`, a `Map` becomes `{ $map }`, a `Set` becomes `{ $set }`, an instance of a class keeps its own fields and its name as `$class`, and a getter is never called. A value that is too deep or too big is cut.
+
+```js
+import { createTracer, reduxDevtools, safeSerialize } from "nanoeffects/trace";
+
+const trace = createTracer(
+  reduxDevtools({
+    name: "app",
+    // serialize — runs on every payload and error before the extension gets it;
+    // hide a secret first, then make the rest plain
+    serialize: (value) => safeSerialize(value, { maxDepth: 4 }),
+  }),
+);
+```
+
+`serialize: false` sends values as they are, which is faster and can fail on a circular one.
+
 ### Write your own logger
 
 ```ts
@@ -6964,11 +8162,448 @@ conditions: ["notrace"]
 
 In a build from the sources, `define: { __NANOEFFECTS_TRACE__: "false" }` does the same. With the condition set, that build’s types have no `trace` option: `createBus({ trace })` is a type error. `nanoeffects/trace` has no `notrace` build. The saving is about 0.4 kB gzip of the whole library.
 
+---
+Source: docs/debugging-loops.md
+
+# Find and cut event loops
+
+> **Level F.** Read first: [Trace tasks](tracing.md#attach-a-tracer). To only cut a loop, go to [`loopGuardPlugin`](loop-guard.md).
+
+A loop is two handlers that emit each other's events, or one handler that emits its own. This page finds a loop, shows it, and stops it. Every scenario below is a runnable file in [`examples/debug`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/debug), and a page with buttons and Redux DevTools is in [`examples/debug-playground`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/debug-playground).
+
+## On this page
+
+- [Start from the symptom](#start-from-the-symptom)
+- [Find a loop](#find-a-loop)
+- [Read a report](#read-a-report)
+- [Draw the graph](#draw-the-graph)
+- [See the loop in Redux DevTools](#see-the-loop-in-redux-devtools)
+- [Find a loop that no chain shows](#find-a-loop-that-no-chain-shows)
+- [Break the loop](#break-the-loop)
+- [Cut a loop at run time](#cut-a-loop-at-run-time)
+- [Fail a test on a loop](#fail-a-test-on-a-loop)
+- [Export the graph and the payloads](#export-the-graph-and-the-payloads)
+- [Know the limits](#know-the-limits)
+
+## Start from the symptom
+
+| What you see | Likely cause | Go to |
+| ------------ | ------------ | ----- |
+| The page freezes | A loop of microtasks or a synchronous loop | [Find a loop](#find-a-loop), then [Cut a loop at run time](#cut-a-loop-at-run-time) |
+| A request repeats on its own | A handler emits the event that starts it | [Read a report](#read-a-report) |
+| `RangeError: Maximum call stack size exceeded` | A synchronous loop through `emit` | [Find a loop](#find-a-loop) |
+| A component renders again and again | A value is sent to the bus on every render | [Find a loop that no chain shows](#find-a-loop-that-no-chain-shows) |
+| You do not know which event leads to which | No map of the events | [Draw the graph](#draw-the-graph) |
+
+## Find a loop
+
+`graphLogger` is a trace logger. Pass it to `createTracer` like any other logger. It builds the map of which event leads to which, and writes a report once when a chain passes the same event three times. Add `tracePlugin` so that it also sees every emit and the names of your listeners. It works without the plugin, with a coarser map.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// graphLogger — the map of events and the loop finder, in one logger
+export const graph = graphLogger({ name: "cart" });
+
+// createTracer — sends every task of the bus to the logger
+const trace = createTracer(graph);
+
+// tracePlugin — reports every emit, so the graph also shows events that nothing listens to
+export const bus = createBus({ trace }).use(tracePlugin());
+```
+
+The handlers are the part of your app that has the loop. Here a cart and a total update each other:
+
+```js
+// cart-handlers.js
+import { bus } from "./bus";
+
+// traceId — the name of the listener in the graph and in the report
+bus.on(
+  "cart/changed",
+  (cart, ctx) => {
+    ctx.emit("total/changed", cart);
+  },
+  { traceId: "recalcTotal" },
+);
+
+bus.on(
+  "total/changed",
+  (total, ctx) => {
+    ctx.emit("cart/changed", total);
+  },
+  { traceId: "syncCart" },
+);
+```
+
+`graphLogger` costs a lookup for each task. Use it while you develop, or with `createTracer(graph, { sample })` in production.
+
+## Read a report
+
+<!-- docs-check: continue -->
+
+The report is one `console.warn` for each loop:
+
+```text
+[nanoeffects cart] cycle: recalcTotal → total/changed → syncCart → cart/changed → recalcTotal (repeated 3 times, started at cart/changed)
+  recalcTotal at src/cart-handlers.js:6; syncCart at src/cart-handlers.js:14   (only with devPlugin)
+  handlers feed each other: break the loop with a condition, or emit a different event for the result
+```
+
+- **The path** goes from the first turn of the loop back to it. A named listener shows its event before it.
+- **`started at`** is the first event of the chain.
+- **`at file:line`** appears when you also use [`devPlugin`](hmr.md#report-leaks-with-devplugin).
+- **The last line** is advice for this shape of loop.
+
+To receive the finding in code, pass `onCycle`. It replaces the console report:
+
+```js
+// report.js
+import { graphLogger } from "nanoeffects/trace";
+
+export const graph = graphLogger({
+  // onCycle — called once for each loop; the finding has a path, the repeats and the root
+  onCycle: (finding) => {
+    console.error(finding.kind, finding.path.join(" → "));
+  },
+});
+```
+
+`graph.cycles()` lists the loops found so far, with `turns`: how many times a loop went round after it was found. It also lists cycles that no single chain showed, when the edges of different runs close a loop (`source: "graph"`).
+
+## Draw the graph
+
+<!-- docs-check: continue -->
+
+The graph has a count on each edge, and the edges of a cycle are marked. Write it in the format your tool reads:
+
+```js
+// draw.js
+import { graph } from "./bus";
+
+// Mermaid: paste it into a README, a pull request or https://mermaid.live
+const mermaid = graph.toMermaid({ group: "prefix" }); // group the events by the part before "/"
+
+// Graphviz: dot -Tsvg graph.dot > graph.svg
+const dot = graph.toDot();
+
+// plain data for your own tools
+const data = graph.toJSON();
+
+console.log(mermaid, dot, data);
+```
+
+```mermaid
+flowchart LR
+  n0["cart/changed"]
+  n1["recalcTotal"]
+  n2["total/changed"]
+  n3["syncCart"]
+  n0 -->|x21| n1
+  n1 -->|x20| n2
+  n2 -->|x20| n3
+  n3 -->|x20| n0
+  linkStyle 0,1,2,3 stroke:red,stroke-width:2px
+```
+
+The counts (`x21`) are how many times each edge was seen; they depend on how long the loop ran.
+
+## See the loop in Redux DevTools
+
+`devtools: true` sends each finding to the extension as a `cycle/detected` action. Put `reduxDevtools` next to it to also see the emits:
+
+```js
+// devtools-bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, reduxDevtools, tracePlugin } from "nanoeffects/trace";
+
+// devtools: true — one cycle/detected action for each loop, with the path
+const graph = graphLogger({ name: "app", devtools: true });
+
+// reduxDevtools — the emits of the bus as actions
+const trace = createTracer([reduxDevtools({ name: "app" }), graph]);
+
+export const bus = createBus({ trace }).use(tracePlugin());
+```
+
+Redux DevTools is a browser extension, so open the page in its own tab and pick the instance in its list. Without the extension nothing is sent and nothing throws. You can try it with the buttons of [`examples/debug-playground`](https://github.com/nanoeffects/nanoeffects/tree/main/examples/debug-playground).
+
+## Find a loop that no chain shows
+
+Some loops have no chain of emits:
+
+- **A component that emits on every render.** `useEmitter` and a `bus.emit` in an effect run outside any handler, so each emit is a root. `graphLogger` counts such emits for each event, and reports a **storm** when one event comes 100 times in a second. Change the limit with `storm: { count, perMs }`, or turn it off with `storm: false`.
+- **A `bus.emit` inside a handler.** It starts a new chain, so the handler that calls it again does not look like a loop. Use `ctx.emit` inside handlers to keep the chain.
+- **A chain of generated names** (`step/${n}`) never repeats a name. `graphLogger` reports a **runaway** chain when one root starts more than `maxSteps` tasks (5000 by default).
+
+```js
+// storm.js
+import { graphLogger } from "nanoeffects/trace";
+
+export const graph = graphLogger({
+  storm: { count: 50, perMs: 1000 }, // 50 emits of one event in a second from outside
+  maxSteps: 2000, // 2000 tasks started by one root
+  ignore: ["tree/visit"], // a recursion on purpose is not counted
+});
+```
+
+## Break the loop
+
+| Shape | Fix |
+| ----- | --- |
+| A handler emits its own event | Emit a different event for the result (`user/loaded`, not `user/load`). |
+| Two handlers feed each other | Add the condition that ends it, or send the result to a third event that nothing in the loop listens to. |
+| A job whose outcome has the type of its trigger | Give the outcomes their own types. |
+| A component emits on every render | Pass `equals` to `useEmitter`, so the same value is not an emit, or `debounce` the handler. |
+| A failure re-emits the event that failed | Stop after a number of tries with `retry`, not with an event. |
+
+## Cut a loop at run time
+
+The report does not stop a loop. For a loop that must not take the page down, add [`loopGuardPlugin`](loop-guard.md). It refuses the emit that would pass 50 repeats, or a chain of 1000 emits, and reports it:
+
+```js
+// guarded-bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+const graph = graphLogger({ name: "app" });
+const trace = createTracer(graph);
+
+// loopGuardPlugin — cuts the loop that the graph reports
+export const bus = createBus({ trace })
+  .use(tracePlugin())
+  .use(loopGuardPlugin({ maxRepeats: 50 }));
+```
+
+The guard is independent of the logger: use either one alone.
+
+## Fail a test on a loop
+
+Run a flow of the app and check that the graph has no cycle. A loop that someone adds later fails the build.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// the bus.js of "Find a loop": the graph logger on the tracer of the bus
+export const graph = graphLogger({ name: "cart" });
+export const bus = createBus({ trace: createTracer(graph) }).use(tracePlugin());
+```
+
+```js
+// cart-handlers.js
+import { bus } from "./bus";
+
+bus.on("checkout/started", (_order, ctx) => {
+  ctx.emit("checkout/paid");
+});
+```
+
+```js
+// cycles.test.js
+import { expect, test } from "vitest";
+import { bus, graph } from "./bus";
+import "./cart-handlers";
+
+test("the checkout flow has no event cycles", () => {
+  // run the flow the way a user would
+  bus.emit("checkout/started");
+
+  // cycles() — empty when the graph has no loop
+  expect(graph.cycles()).toEqual([]);
+});
+```
+
+## Export the graph and the payloads
+
+The exports leave payloads out, because a payload can hold private data. Ask for them when you need them:
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTracer, graphLogger, tracePlugin } from "nanoeffects/trace";
+
+// the bus.js of "Find a loop": the graph logger on the tracer of the bus
+export const graph = graphLogger({ name: "cart" });
+export const bus = createBus({ trace: createTracer(graph) }).use(tracePlugin());
+```
+
+```js
+// payloads.js
+import { graph } from "./bus";
+
+// payload: true — adds the last payload and error of each node, made safe
+const data = graph.toJSON({ payload: true });
+
+console.log(JSON.stringify(data));
+```
+
+A payload can be a class instance, a `Map`, a circular object or an `Error`, which a plain `JSON.stringify` cannot take. The exports make them plain JSON: an `Error` keeps its name, message, stack and cause, a cycle becomes `"[Circular]"`, a `Map` becomes `{ "$map": [...] }`, and an instance of a class keeps its own fields and its name as `$class`. Getters are never called, and a value that is too deep or too big is cut.
+
+## Know the limits
+
+### Code that repeats on purpose looks like a loop
+
+`graphLogger` calls it a loop when one event stands in a chain three times. Some code does that by design. A handler that walks a tree emits `tree/visit` for every child, so the same event is in the chain once for each level. The logger cannot tell this from a mistake, so it reports it.
+
+Tell it with `ignore`. The event stays in the graph and in the exports, but it is not counted as a repeat, a step, or a storm:
+
+```js
+// graph.js
+import { graphLogger } from "nanoeffects/trace";
+
+export const graph = graphLogger({
+  // tree/visit repeats once for each level of the tree, on purpose
+  ignore: ["tree/visit"],
+});
+```
+
+Do not list an event only to silence a real loop: the report is the point. `ignore` also takes a function of the name, `ignore: (name) => name.startsWith("tree/")`.
+
+### A loop is reported once, and keeps being counted
+
+A loop that runs 500 turns writes one warning, not 500. After the warning, the logger counts the turns quietly. Read the count from `graph.cycles()` to see whether the loop is still going:
+
+```js
+// turns.js
+import { graph } from "./graph";
+
+const [loop] = graph.cycles();
+
+// turns — how many times the loop has gone round since it was found, the first time included
+console.log(loop.path.join(" → "), loop.turns);
+```
+
+Read it twice a moment apart. A number that grew means the loop is still running. The same number means it stopped. To act on the first report in code, use `onCycle`; it is called once too.
+
+### Without tracePlugin the graph is coarser
+
+Without `tracePlugin` the logger sees handlers but not the emits that nobody listens to, and it cannot give a name to a listener. A loop is still found, by event type.
+
+---
+Source: docs/loop-guard.md
+
+# Cut a loop with `loopGuardPlugin`
+
+> **Level F.** Read first: [Plugins](plugins.md#use-a-plugin). To find a loop before you cut it, see [Find and cut event loops](debugging-loops.md).
+
+Two handlers that emit each other's events never stop. A loop made of `await` and timers burns CPU and network. A loop made of microtasks freezes the page, because the browser never gets a turn to draw. A report cannot stop any of them. `loopGuardPlugin` can: it follows the chain of emits and refuses the emit that would pass a limit.
+
+Use it as a safety net, also in production. It needs no tracer and changes nothing while a chain stays under the limits. It is opt-in: a bus that does not use it behaves as before.
+
+## On this page
+
+- [Cut a loop](#cut-a-loop)
+- [Choose what happens at the limit](#choose-what-happens-at-the-limit)
+- [Limit the emits that come from outside](#limit-the-emits-that-come-from-outside)
+- [Leave a recursion out](#leave-a-recursion-out)
+- [Know what it does not do](#know-what-it-does-not-do)
+
+## Cut a loop
+
+The plugin counts how many times the same event is in the chain of emits that led to an emit. The chain follows `ctx.emit`, also across `await`, timers and microtasks. An emit that would pass a limit is refused, and the loop ends there. Other chains go on, and the next emit from outside starts a chain at zero.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+// loopGuardPlugin — refuses the emit that would pass a limit of a chain
+export const bus = createBus().use(
+  loopGuardPlugin({
+    maxRepeats: 50, // one event may be in a chain 50 times
+    maxDepth: 1000, // a chain may be 1000 emits long, whatever the names are
+  }),
+);
+```
+
+| Option | Default | Cuts |
+| ------ | ------- | ---- |
+| `maxRepeats` | 50 | The same event in one chain too often: a loop. |
+| `maxDepth` | 1000 | A chain that is too long, also when every event has a new name (`step/${n}`). |
+| `maxPerSecond` | none | Emits of one event from outside any handler that come too fast ([below](#limit-the-emits-that-come-from-outside)). |
+| `ignore` | none | Event names that the repeat count skips ([below](#leave-a-recursion-out)). |
+
+## Choose what happens at the limit
+
+`onLimit` says what the refused emit does. Either way the plugin reports the finding once for each path. The report has the path of the loop and never the payload.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { LoopError, loopGuardPlugin } from "nanoeffects/guard";
+
+export const bus = createBus().use(
+  loopGuardPlugin({
+    onLimit: "drop", // "drop" (default): the emit is not sent; "throw": it throws a LoopError
+    // report — replaces the default console.error
+    report: (finding) => console.error(finding.limit, finding.path.join(" → ")),
+  }),
+);
+
+// with onLimit: "throw", the emit that was refused throws, and the error names the path
+try {
+  bus.emit("cart/changed");
+} catch (error) {
+  if (error instanceof LoopError) {
+    console.log(error.limit, error.path);
+  }
+}
+```
+
+- **`"drop"`** is the default. The emit returns as if nobody listened, so no new error appears in an async handler.
+- **`"throw"`** shows the loop with a stack. In an async handler the error becomes a rejection: handle it with `onError`.
+
+A loop that is cut can leave the state of the app half done: the handlers that ran have done their part, the ones after the cut have not. Fix the loop, and keep the guard as a net.
+
+## Limit the emits that come from outside
+
+A component that emits on every render has no chain: each emit comes from outside any handler. `maxPerSecond` counts them for each event.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+// maxPerSecond — over 100 emits of one event in a second from outside are refused
+export const bus = createBus().use(loopGuardPlugin({ maxPerSecond: 100 }));
+```
+
+It is off by default, because a burst of many emits can be right (a stream of messages).
+
+## Leave a recursion out
+
+A chain that repeats on purpose is cut too. A handler that emits `tree/visit` for each level of a tree, or one that emits `tick` again after a timer for hours, passes `maxRepeats`. List its event in `ignore`. `maxDepth` still applies to it.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { loopGuardPlugin } from "nanoeffects/guard";
+
+export const bus = createBus().use(
+  loopGuardPlugin({
+    ignore: ["tree/visit"], // names, or a function of the name
+  }),
+);
+```
+
+## Know what it does not do
+
+- **It does not abort the chain.** It refuses one emit, at the edge where the limit is passed. The handlers that already run, run to the end.
+- **It follows `ctx.emit`.** A `bus.emit` called from inside a handler is not part of the chain: it starts a new one with the counts at zero. Use `ctx.emit` inside handlers.
+- **It does not find a loop.** To see the path of a loop, and loops that go through components, use `graphLogger` ([Find and cut event loops](debugging-loops.md)).
+
 ---
 Source: docs/observable.md
 
 # Turn events into Observables
 
+> **Level F.** Read first: [Guide](guide.md#1-create-a-bus) step 1.
+
 Use this page when your app already works with Observables or RxJS and you want a bus event as a stream. If you start from scratch, prefer `bus.on` with policies: they cancel work and show up in traces.
 
 The same entry has `events`, which needs no stream library: it gives an event to a `for await` loop. See [Read an event with a `for await` loop](#read-an-event-with-a-for-await-loop).
@@ -7204,6 +8839,8 @@ Source: docs/hmr.md
 
 # Hot reload and development diagnostics
 
+> **Level F.** Read first: [Actions, jobs and modules](actions.md).
+
 Use this page in development with modules and hot reload. Skip until you mount domains with `modulePlugin`.
 
 When a file is edited, the bundler loads its new version and runs it again, while the page and the rest of the code stay alive. For a bus that can go wrong in three ways:
@@ -7241,11 +8878,43 @@ bus.use(devPlugin());
 
 - **Listeners that pile up.** When more than `maxListeners` (default `10`) listeners of one event were added and not unsubscribed, one warning names the event and the count. The count follows the function that `on` returns; `bus.off(event, fn)` is not seen.
 - **Modules.** For the app of `modulePlugin` (or the `app` option) it logs `module "user" mounted`, `replaced` when a module of the same name was mounted, and `unmounted`. Only what goes through `app.mount` and `app.unmount` is reported, not sub-modules.
-- **Options.** `leaks: false` and `modules: false` switch a diagnostic off; `maxListeners` sets the limit; `log` receives the messages instead of the console.
+- **Where a named listener was made.** For a listener with a `traceId`, it notes the file and the line of the `bus.on` call, while the listener is subscribed. [`graphLogger`](debugging-loops.md#read-a-report) shows it in a loop report, so you can open the handler that closes the loop.
+- **Handlers that ignore the signal.** When a handler emits after its task was aborted (a newer call of `latest`, an unmounted module), the bus drops that emit. One warning then names the handler and the event: the handler did not stop when it was cancelled, usually because `ctx.signal` never reached the request. [Details](#find-a-handler-that-ignores-the-signal)
+- **Options.** `abandoned: false`, `leaks: false` and `modules: false` switch a diagnostic off; `maxListeners` sets the limit; `log` receives the messages instead of the console.
 - **Disconnect.** `bus.use(devPlugin(...))` returns the function that stops the diagnostics and puts `bus.on` and `app.mount` back.
 
 It changes no behavior: it wraps `bus.on`, `app.mount`, and `app.unmount` and adds messages.
 
+### Find a handler that ignores the signal
+
+A policy such as `latest` cancels the older call by aborting its `ctx.signal`. A handler that does not pass the signal to its request keeps running, and its result arrives after the newer one. The policy drops that result, so nothing looks wrong until the handler does something else with it.
+
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
+
+const bus = createBus();
+
+bus.on(
+  "search",
+  latest(async (query, ctx) => {
+    // the signal is not passed, so an older request is not cancelled
+    const items = await fetch(`/api?q=${query}`).then((response) => response.json());
+    ctx.emit("results", items);
+  }),
+);
+```
+
+With `devPlugin`, the second `search` aborts the first call. When the first call then emits `results`, the bus drops the emit and the plugin warns once:
+
+```text
+[nanoeffects] the handler of "search" emitted "results" after its task was aborted, so the emit was dropped. The handler kept running after it was cancelled: pass ctx.signal to the request (fetch(url, { signal: ctx.signal })) or give ctx to an effect (retry(ctx, ...)).
+```
+
+The check lives in the plugin only: the policies and the bus carry no code for it, and in production `nanoeffects/dev` is empty. It sees the handlers that emit or subscribe with `ctx.on` after the cancel; a handler that never does is not seen.
+
+A linter finds the same mistake before the code runs, and much more of it: a handler with no `ctx`, a step that does not get the signal while another does, the calls of `Promise.all`, the callbacks of `retry` and `timeout`, a pause, a stream, `bus.emit` in a handler. [Keep the signal through a handler](pass-the-signal.md) lists every situation, what catches it and how to fix it, and shows the setup for ESLint, oxlint and Biome.
+
 ### Keep the import in production
 
 `nanoeffects/dev` is a no-op in a production build. `package.json` maps it to an empty build under the `production` export condition (Vite and webpack set that in production mode), so `bus.use(devPlugin())` can stay without a guard: it touches nothing and costs a few bytes.