nanoeffects 0.28.0 → 0.30.1

package/llms-full.txt

@@ -9,25 +9,44 @@ 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`.
-- `bus.emit(command(payload))` runs the command's handler and returns its result. Plain events return nothing.
+- 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.
 
 ---
 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).
 
+## On this page
+
+- [1. Create a bus](#1-create-a-bus)
+  - [Listen to every event](#listen-to-every-event)
+  - [Pick events with a function](#pick-events-with-a-function)
+- [2. Use the handler context](#2-use-the-handler-context)
+- [3. Abort the previous run with `latest`](#3-abort-the-previous-run-with-latest)
+- [4. Pick another policy when overlap differs](#4-pick-another-policy-when-overlap-differs)
+- [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. 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)
+- [Where next](#where-next)
+
 ## 1. Create a bus
 
 `on` subscribes. `emit` calls the subscribers. `on` returns the unsubscribe function.
@@ -48,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";
@@ -66,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
@@ -88,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 -->
 
@@ -234,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
 
@@ -289,10 +315,11 @@ import { all, delay, race, take } from "nanoeffects/effects";
 const bus = createBus();
 
 // all — run together; one failure cancels the rest
+// 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: ({ signal }) => api.user(id, { signal }),
-    posts: ({ signal }) => api.posts(id, { signal }),
+    user: (child) => api.user(id, child),
+    posts: (child) => api.posts(id, child),
   });
   ctx.emit("loaded", { user, posts });
 });
@@ -363,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
@@ -377,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
 
@@ -513,336 +548,825 @@ More in [Errors](errors.md).
 | Which import | [Package entries](package.md) |
 
 ---
-Source: docs/starter.md
-
-# Start a project from a template
+Source: docs/recipes.md
 
-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`).
+# Common tasks
 
-You need Node 18 or newer.
+> **Levels A to E.** Read first: [README](../README.md).
 
-## Create the project
+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.
 
-Run the command for your package manager. Replace `my-app` with the name of the new directory.
+## On this page
 
-```bash
-npm create nanoeffects@latest my-app
-```
+- [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`.
 
-```bash
-pnpm create nanoeffects my-app
-```
+```js
+import { createBus } from "nanoeffects";
 
-```bash
-yarn create nanoeffects my-app
-```
+// createBus({ context }) — every task gets these fields on ctx
+const bus = createBus({ context: { api, logger } });
 
-```bash
-bun create nanoeffects my-app
+bus.on("save", async (draft, { api, logger }) => {
+  await api.save(draft);
+  logger.info("saved");
+});
 ```
 
-The command asks for the template when you do not give one. The directory must be new or empty: the command stops instead of overwriting files.
+More: [Context fields](context.md).
 
-Then follow the steps it prints:
+### One handler fails, the others must still run
 
-```bash
-cd my-app
-npm install
-npm run dev
-```
+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.
 
-Open the address that Vite prints and type in the box. The fake server answers after 800 ms, so you can see the older request being aborted.
+```js
+import { createBus } from "nanoeffects";
 
-## Choose a template
+const bus = createBus({
+  // onError — isolates the handlers: a thrown error goes here and the next handler still runs
+  onError: (error, { type }) => report(error, type),
+});
 
-Pass `--template` to skip the question. With npm, put `--` before the option.
+const sendAnalytics = (order) => {
+  throw new Error(`analytics is down for ${order.id}`);
+};
+const saveOrder = (order) => console.log("saved", order.id);
 
-| Template | What it shows | Use it when |
-| -------- | ------------- | ----------- |
-| `vanilla` | A bus, one event and a `debounce` plus `latest` handler, with plain DOM code | You use no framework, or want to see the bus alone |
-| `react` | The same handler with `useEmitter` and `useEventState`, and `usePolicy` for a debounced save in a component | You build a React app |
-| `vanilla-ts` | The `vanilla` app in TypeScript | You want the compiler to check events and handlers |
-| `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
-| `domains-ts` | Actions with handlers, a job and modules, with the logic split into domain folders and React as a thin layer | You build an app with more than one feature and want the logic off the UI |
-| `vue-ts` | The `react-ts` app in Vue 3, with `watchEmitter` and `useEventRef` from `nanoeffects/vue` | You build a Vue 3 app |
-| `svelte-ts` | The `react-ts` app in Svelte 5, with `eventStore` from `nanoeffects/svelte` | You build a Svelte app |
+bus.on("order/placed", sendAnalytics); // throws
+bus.on("order/placed", saveOrder); // still runs
 
-```bash
-npm create nanoeffects@latest my-app -- --template react
+bus.emit("order/placed", { id: 1 }); // saved 1
 ```
 
-In the `react` templates, `useEventState` keeps the found items in the component. It is not a global store: another component gets its own copy. To share a value between components, use a state manager and see [Stores](stores.md).
+More: [Errors and unheard events](errors.md#isolate-failing-handlers).
 
-The TypeScript templates are the same apps with the same files, written in `.ts` and `.tsx`. Events are made with `createAction<Payload>`, so handlers and `useEventState` get their types from the events, with no annotation in the component. `npm run build` type-checks the project (`tsc --noEmit`) before bundling it.
+### A typo in an event name
 
-```bash
-npm create nanoeffects@latest my-app -- --template react-ts
-```
+`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.
 
-### Start with Vue
+```js
+import { createBus } from "nanoeffects";
 
-`vue-ts` is the search app of `react-ts` in Vue 3 with `<script setup lang="ts">`. Its bus uses `vuePlugin` from `nanoeffects/vue`: `watchEmitter` sends the query to the bus when it changes, and `useEventRef` keeps the result of the search in a `ref`. Like `useEventState` in React, `useEventRef` is [not a store](vue.md#it-is-not-a-store): a value that several components share belongs in a store such as Pinia.
+const bus = createBus({
+  // onUnhandled — called when an event has no listeners
+  onUnhandled: ({ type }) => console.warn(`Nobody listens to "${type}"`),
+});
 
-```bash
-npm create nanoeffects@latest my-app -- --template vue-ts
+bus.on("search", (query) => console.log(query));
+
+bus.emit("serch", "nano"); // warning: Nobody listens to "serch"
 ```
 
-`npm run build` type-checks the `.vue` files with `vue-tsc`, which needs TypeScript 5: the template depends on it.
+More: [Warn when nobody listens](errors.md#warn-when-nobody-listens).
 
-### Start with Svelte
+## Races and repeated actions in the UI
 
-`svelte-ts` is the search app of `react-ts` in Svelte 5. Its bus uses `sveltePlugin` from `nanoeffects/svelte`: `eventStore` makes a Svelte store from an event. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](svelte.md#it-is-not-a-store-of-the-app): a value that several components share belongs in a store of your own.
+### An old response overwrites a new one
 
-```bash
-npm create nanoeffects@latest my-app -- --template svelte-ts
-```
+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:
 
-`npm run build` type-checks the `.svelte` files with `svelte-check`, which needs TypeScript 5: the template depends on it.
+```jsx
+import { useEffect, useState } from "react";
 
-### Start with domains
+export function Search({ query }) {
+  const [items, setItems] = useState([]);
 
-`domains-ts` is not the search box of the other templates grown in TypeScript: it shows where logic goes when an app has several features. Each domain is a folder under `src/domains/`. It has the events of the domain, the work that handles them, and a module that mounts the work. The React components only emit events and read values.
+  useEffect(() => {
+    // two requests are in flight, and the one that finishes last wins, even the older one
+    api.search(query).then(setItems);
+  }, [query]);
 
-```bash
-npm create nanoeffects@latest my-app -- --template domains-ts
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.title}</li>
+      ))}
+    </ul>
+  );
+}
 ```
 
-| Path | Job |
-| ---- | --- |
-| `src/bus.ts` | Creates the bus. It imports no events and no domain. |
-| `src/app.ts` | Mounts the domains with `modulePlugin`. |
-| `src/domains/catalog/` | Searching products: `catalog.ts` (events and an action with a handler), `catalog-handlers.ts` (`debounce` and `latest`), `catalog-module.ts`. |
-| `src/domains/checkout/` | Placing an order: `checkout.ts` (a job), `checkout-handlers.ts` (`leading` and `retry`), `checkout-store.ts` (state written from the job's outcomes), `checkout-module.ts`. |
-| `src/ui/` | The components. None of them calls the fake server in `src/api.ts`. |
-
-For a bigger example, a chat in which parts react to each other, see [Build a chat with entities, features, modules and a small server](chat-example.md). It has more layers than `domains-ts`: when domains must react to each other, it keeps them from importing each other by splitting them into entities and features.
+Move the request into a handler with `latest`: a new `search` aborts the previous request, and the aborted one delivers no result.
 
-The actions, jobs and modules themselves are explained in [Actions, jobs and modules](actions.md). The template keeps found products in a Context provider with one `useEventState`, and the order state in a store of its own: `useEventState` is [not a store](react.md#show-the-last-value-of-an-event-as-state).
+```js
+import { createBus } from "nanoeffects";
+import { latest } from "nanoeffects/policies";
 
-## Read the files
+const bus = createBus();
 
-Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components, `.svelte` for Svelte components).
+// 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);
+  }),
+);
 
-| File | Job |
-| ---- | --- |
-| `src/bus.js` | Creates the bus. It imports no events. |
-| `src/search.js` | Names the events with `createAction`. It imports no bus. |
-| `src/search-handlers.js` | Handles the events with `debounce` and `latest`. It knows the bus and the events. |
-| `src/api.js` | A fake server. Replace it with your own requests. |
+bus.on("results", (items) => render(items));
+```
 
-Every call of nanoeffects in these files has a comment that says what it does. To make it your own, replace `src/api.js`, then rename the events and the handler.
+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).
 
-## Next steps
+### A search box sends a request on every key
 
-- [Policies](policies.md): `leading`, `throttle` and `queue` next to `latest`.
-- [Build a sign-up form in React](react.md): the same ideas in a bigger React example.
-- [Package entries](package.md): which import holds what.
+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.
 
----
-Source: docs/motivation.md
+```js
+import { createBus } from "nanoeffects";
+import { debounce, latest } from "nanoeffects/policies";
 
-# Why nanoeffects exists
+const bus = createBus();
 
-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).
+// 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);
+});
 
-## The main reason: logic outside the UI
+// debounce — start after 300 ms without a new "typed"
+bus.on("typed", debounce(300, searchLatest));
+```
 
-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.
+More: [Pause between requests](debounce-and-abort.md).
 
-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.
+### A second click sends a second request
 
-## When the constraint is a shared library
+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.
 
-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.
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
 
-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.
+const bus = createBus();
 
-Real cases from the libraries nanoeffects was compared with:
+// 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 });
+  }),
+);
+```
 
-| Library | What goes wrong | Source |
-| ------- | --------------- | ------ |
-| Redux, React Redux | A shared component library uses `react-redux`. Every micro-frontend must use the same version of that library, or `react-redux` "breaks weirdly". | [react-redux#1949](https://github.com/reduxjs/react-redux/issues/1949) |
-| Redux | A store is reachable only under a `Provider`. Each sub-app needs its own provider, and a second one must not be created when a module is injected. Reducers duplicated between the host and a module add to it. | [Redux on Module Federation](https://dev.to/manomano-tech-team/how-to-work-with-redux-on-module-federation-13gm) |
-| 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) |
+More: [Prevent a double submit](prevent-double-submit.md).
 
-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.
+### Messages must go out in order
 
-## Why not the alternatives
+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.
 
-| 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. |
+```js
+import { createBus } from "nanoeffects";
+import { queue } from "nanoeffects/policies";
 
-## What the library does instead
+const bus = createBus();
 
-- **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.
-- **`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.
+// queue — the next message waits until the previous one is delivered
+bus.on(
+  "message/sent",
+  queue(async (message, { signal }) => {
+    await api.sendMessage(message, { signal });
+  }),
+);
+```
 
-## When this is not the right tool
+More: [Policies, `queue`](policies.md#run-calls-one-after-another-with-queue).
 
-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).
+### A "Delete" button in a list blocks the other rows
 
----
-Source: docs/package.md
+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.
 
-# Choose a package entry
+```js
+import { createBus } from "nanoeffects";
+import { leading } from "nanoeffects/policies";
 
-Imports are split so you only load what you use. `createBus` stays small; the rest is another entry.
+const bus = createBus();
 
-| Import | What is in it |
-| ------ | ------------- |
-| `nanoeffects` | `createBus`, the types |
-| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
-| `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
-| `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` |
-| `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events |
-| `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value |
-| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` |
-| `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` |
-| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) |
-| `nanoeffects/redux` | `createEffectsMiddleware` |
-| `nanoeffects/observable` | `createObserve`, `Subject` |
-| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
-| `nanoeffects/svelte` | `sveltePlugin`: adds `eventStore` to a bus (needs Svelte 5 or newer) |
-| `nanoeffects/vue` | `vuePlugin`: adds `watchEmitter` and `useEventRef` to a bus (needs Vue 3.3 or newer) |
-| `nanoeffects/dev` | `devPlugin` (no-op in production) |
-| `nanoeffects/trace` | `createTracer`, the loggers and `tracePlugin` (names for the trace) |
+// 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 },
+  ),
+);
+```
 
-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.
+More: [Policies, `key`](policies.md#key-isolate-state-by-key).
 
-## Give the docs to an AI assistant
+## An unreliable network and long flows
 
-The package ships plain-text files for assistants that write code with it:
+### A request fails sometimes: retry and backoff
 
-- `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
-- `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
-- `skills/nanoeffects/SKILL.md`: a skill for assistants that support skills (for example Claude Code). It says when to suggest nanoeffects, when not to, and the same rules. Copy the folder to `.claude/skills/` in your project or to `~/.claude/skills/`.
+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.
 
-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.
+```js
+import { createBus } from "nanoeffects";
+import { backoff, retry } from "nanoeffects/effects";
 
----
-Source: docs/stability.md
+const bus = createBus();
 
-# Know what is stable
+// 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,
+  }),
+});
 
-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.
+bus.on("user/opened", loadWithRetry);
+```
 
-## See which entries are stable
+More: [`backoff`](effects.md#backoff).
 
-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.
+### A request hangs: timeout
 
-| 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` |
+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.
 
-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.
+```js
+import { createBus } from "nanoeffects";
+import { timeout } from "nanoeffects/effects";
 
-## Know what is a breaking change
+const bus = createBus();
 
-For a stable entry, these changes are breaking:
+// timeout — reject with TimeoutError and abort the request after 5 s
+const loadOnce = timeout(5000, (id, { signal }) => api.getUser(id, { signal }));
 
-- 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.
+bus.on("user/opened", loadOnce);
+```
 
-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.
+More: [`timeout`](effects.md#timeout).
 
-These are not covered by the promise:
+### Refresh data every N seconds: poll
 
-- 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.
+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.
 
-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.
+```js
+import { createBus } from "nanoeffects";
+import { poll } from "nanoeffects/effects";
 
-A deprecated export keeps working and is removed only in a major release. `RaceStarter` is deprecated: use `StarterOf` instead.
+const bus = createBus();
 
-## Check the supported versions
+bus.on("dashboard/opened", async (_, ctx) => {
+  // stop the polling when the user leaves
+  ctx.on("dashboard/closed", () => ctx.abort());
 
-| 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`) |
+  // poll — call refresh every 10 s until the task is aborted
+  await poll(ctx, () => refresh(), 10_000);
+});
+```
 
-The library has no dependencies. React, Vue and Svelte are optional peer dependencies of their own entries only.
+More: [`poll`](effects.md#poll).
 
-## Rely on these call forms
+### Wait for another event inside a handler: take
 
-`retry`, `timeout` and `poll` have three call forms, and all three stay:
+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 { race, retry } from "nanoeffects/effects";
+import { take } from "nanoeffects/effects";
 
 const bus = createBus();
 
-bus.on("open", async (id, ctx) => {
-  // with ctx: you pass the context, the function gets the signal
-  const user = await retry(ctx, ({ signal }) => fetchUser(id, { 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 }),
-  });
+bus.on("login", async (user, ctx) => {
+  // take — pause this handler until the next "logout"
+  const reason = await take(ctx, "logout");
+  cleanup(user, reason);
 });
-
-// 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.
+More: [`take`](effects.md#take).
 
-`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
+### Load several things at once: all
 
-# Choose the plugins of a bus
+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.
 
-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.
+```js
+import { createBus } from "nanoeffects";
+import { all } from "nanoeffects/effects";
 
-## Use a plugin
+const bus = createBus();
 
-A plugin is a function of the bus. `bus.use(plugin)` calls it with the bus and returns whatever the plugin returns. Most plugins return the same bus, so you can chain them: `createBus().use(a).use(b)`. A few return something of their own (a registry, an app, a `disconnect` function): keep it.
+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),
+  });
 
-In TypeScript keep the result of `contextPlugin` and `effectsPlugin`: the type of the bus with its new fields is the type they return (`const bus = createBus().use(contextPlugin({ store }))`).
+  ctx.emit("profile/loaded", { user, posts });
+});
+```
 
-## Main plugins
+### Take the fastest answer: race
 
-These four cover what most apps need: shared dependencies, effects, handlers and modules. Start here.
+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.
+
+## Create the project
+
+Run the command for your package manager. Replace `my-app` with the name of the new directory.
+
+```bash
+npm create nanoeffects@latest my-app
+```
+
+```bash
+pnpm create nanoeffects my-app
+```
+
+```bash
+yarn create nanoeffects my-app
+```
+
+```bash
+bun create nanoeffects my-app
+```
+
+The command asks for the template when you do not give one. The directory must be new or empty: the command stops instead of overwriting files.
+
+Then follow the steps it prints:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+Open the address that Vite prints and type in the box. The fake server answers after 800 ms, so you can see the older request being aborted.
+
+## Choose a template
+
+Pass `--template` to skip the question. With npm, put `--` before the option.
+
+| Template | What it shows | Use it when |
+| -------- | ------------- | ----------- |
+| `vanilla` | A bus, one event and a `debounce` plus `latest` handler, with plain DOM code | You use no framework, or want to see the bus alone |
+| `react` | The same handler with `useEmitter` and `useEventState`, and `usePolicy` for a debounced save in a component | You build a React app |
+| `vanilla-ts` | The `vanilla` app in TypeScript | You want the compiler to check events and handlers |
+| `react-ts` | The `react` app in TypeScript | You build a React app in TypeScript |
+| `domains-ts` | Actions with handlers, a job and modules, with the logic split into domain folders and React as a thin layer | You build an app with more than one feature and want the logic off the UI |
+| `vue-ts` | The `react-ts` app in Vue 3, with `watchEmitter` and `useEventRef` from `nanoeffects/vue` | You build a Vue 3 app |
+| `svelte-ts` | The `react-ts` app in Svelte 5, with `eventStore` from `nanoeffects/svelte` | You build a Svelte app |
+
+```bash
+npm create nanoeffects@latest my-app -- --template react
+```
+
+In the `react` templates, `useEventState` keeps the found items in the component. It is not a global store: another component gets its own copy. To share a value between components, use a state manager and see [Stores](stores.md).
+
+The TypeScript templates are the same apps with the same files, written in `.ts` and `.tsx`. Events are made with `createAction<Payload>`, so handlers and `useEventState` get their types from the events, with no annotation in the component. `npm run build` type-checks the project (`tsc --noEmit`) before bundling it.
+
+```bash
+npm create nanoeffects@latest my-app -- --template react-ts
+```
+
+### Start with Vue
+
+`vue-ts` is the search app of `react-ts` in Vue 3 with `<script setup lang="ts">`. Its bus uses `vuePlugin` from `nanoeffects/vue`: `watchEmitter` sends the query to the bus when it changes, and `useEventRef` keeps the result of the search in a `ref`. Like `useEventState` in React, `useEventRef` is [not a store](vue.md#it-is-not-a-store): a value that several components share belongs in a store such as Pinia.
+
+```bash
+npm create nanoeffects@latest my-app -- --template vue-ts
+```
+
+`npm run build` type-checks the `.vue` files with `vue-tsc`, which needs TypeScript 5: the template depends on it.
+
+### Start with Svelte
+
+`svelte-ts` is the search app of `react-ts` in Svelte 5. Its bus uses `sveltePlugin` from `nanoeffects/svelte`: `eventStore` makes a Svelte store from an event. In a component, `$found` reads it, and Svelte subscribes and unsubscribes for you. The query goes to the bus from the `oninput` handler, so nothing is emitted when the component mounts. The store listens only while something reads it, and is [not a store of the app](svelte.md#it-is-not-a-store-of-the-app): a value that several components share belongs in a store of your own.
+
+```bash
+npm create nanoeffects@latest my-app -- --template svelte-ts
+```
+
+`npm run build` type-checks the `.svelte` files with `svelte-check`, which needs TypeScript 5: the template depends on it.
+
+### Start with domains
+
+`domains-ts` is not the search box of the other templates grown in TypeScript: it shows where logic goes when an app has several features. Each domain is a folder under `src/domains/`. It has the events of the domain, the work that handles them, and a module that mounts the work. The React components only emit events and read values.
+
+```bash
+npm create nanoeffects@latest my-app -- --template domains-ts
+```
+
+| Path | Job |
+| ---- | --- |
+| `src/bus.ts` | Creates the bus. It imports no events and no domain. |
+| `src/app.ts` | Mounts the domains with `modulePlugin`. |
+| `src/domains/catalog/` | Searching products: `catalog.ts` (events and an action with a handler), `catalog-handlers.ts` (`debounce` and `latest`), `catalog-module.ts`. |
+| `src/domains/checkout/` | Placing an order: `checkout.ts` (a job), `checkout-handlers.ts` (`leading` and `retry`), `checkout-store.ts` (state written from the job's outcomes), `checkout-module.ts`. |
+| `src/ui/` | The components. None of them calls the fake server in `src/api.ts`. |
+
+For a bigger example, a chat in which parts react to each other, see [Build a chat with entities, features, modules and a small server](chat-example.md). It has more layers than `domains-ts`: when domains must react to each other, it keeps them from importing each other by splitting them into entities and features.
+
+The actions, jobs and modules themselves are explained in [Actions, jobs and modules](actions.md). The template keeps found products in a Context provider with one `useEventState`, and the order state in a store of its own: `useEventState` is [not a store](react.md#show-the-last-value-of-an-event-as-state).
+
+## Read the files
+
+Every template except `domains-ts` splits the code the way [the guide](guide.md) does: one job per file. In the TypeScript templates the files end in `.ts` (and `.tsx` for React components, `.vue` for Vue components, `.svelte` for Svelte components).
+
+| File | Job |
+| ---- | --- |
+| `src/bus.js` | Creates the bus. It imports no events. |
+| `src/search.js` | Names the events with `createAction`. It imports no bus. |
+| `src/search-handlers.js` | Handles the events with `debounce` and `latest`. It knows the bus and the events. |
+| `src/api.js` | A fake server. Replace it with your own requests. |
+
+Every call of nanoeffects in these files has a comment that says what it does. To make it your own, replace `src/api.js`, then rename the events and the handler.
+
+## Next steps
+
+- [Policies](policies.md): `leading`, `throttle` and `queue` next to `latest`.
+- [Build a sign-up form in React](react.md): the same ideas in a bigger React example.
+- [Package entries](package.md): which import holds what.
+
+---
+Source: docs/motivation.md
+
+# Why nanoeffects exists
+
+> **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).
+
+## 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`.
+
+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).
+
+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.
+
+## 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.
+
+Real cases from the libraries nanoeffects was compared with:
+
+| Library | What goes wrong | Source |
+| ------- | --------------- | ------ |
+| Redux, React Redux | A shared component library uses `react-redux`. Every micro-frontend must use the same version of that library, or `react-redux` "breaks weirdly". | [react-redux#1949](https://github.com/reduxjs/react-redux/issues/1949) |
+| Redux | A store is reachable only under a `Provider`. Each sub-app needs its own provider, and a second one must not be created when a module is injected. Reducers duplicated between the host and a module add to it. | [Redux on Module Federation](https://dev.to/manomano-tech-team/how-to-work-with-redux-on-module-federation-13gm) |
+| 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) |
+
+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.
+
+## 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).
+- **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.
+
+---
+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
+
+| Import | What is in it |
+| ------ | ------------- |
+| `nanoeffects` | `createBus`, the types |
+| `nanoeffects/policies` | `latest`, `leading`, `debounce`, `throttle`, `queue` |
+| `nanoeffects/effects` | `retry`, `timeout`, `poll`, `delay`, `take`, `all`, `allSettled`, `race`, `effectsPlugin` |
+
+## Add the rest when you need it
+
+Each row is optional. The "when" column says what need brings you to it.
+
+| Import | What is in it | When |
+| ------ | ------------- | ---- |
+| `nanoeffects/actions` | `createAction`, `createJob`, `createModule`, `modulePlugin`, `actionsPlugin` | `emit` must return a result, or domain logic leaves the UI |
+| `nanoeffects/match` | `matchPlugin`: `on`, `once` and `off` that take a function which picks the events | `on` must take a function that picks events |
+| `nanoeffects/context` | `contextPlugin`: your own fields (a store, a client) on `ctx` of every task, typed from the value | a store or client must be on every task |
+| `nanoeffects/signal` | `signalPlugin`: `emit(call, { signal })` ties the tasks of an emit to an outside `AbortSignal` | an outside `AbortSignal` (request, React Query) must stop tasks |
+| `nanoeffects/oop` | `Emitter`, `extendBus`, `WithBus`, `On`, `Once`, `disposeBus`: the methods of a bus on a class, with the subscriptions of each instance ended by `dispose()` | you write classes, not functions |
+| `nanoeffects/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) | one action or module needs its own fields |
+| `nanoeffects/redux` | `createEffectsMiddleware` | you already use Redux |
+| `nanoeffects/observable` | `createObserve`, `Subject` | you need an Observable (RxJS) |
+| `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) | React components |
+| `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 (`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.
+
+## Give the docs to an AI assistant
+
+The package ships plain-text files for assistants that write code with it:
+
+- `llms.txt`: a short index. It states the rules that generated code often gets wrong and links to every page of these docs.
+- `llms-full.txt`: the same summary followed by the text of every linked page, in one file.
+- `skills/nanoeffects/SKILL.md`: a skill for assistants that support skills (for example Claude Code). It says when to suggest nanoeffects, when not to, and the same rules. Copy the folder to `.claude/skills/` in your project or to `~/.claude/skills/`.
+
+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/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
+
+- [Use a plugin](#use-a-plugin)
+- [Pick a plugin by task](#pick-a-plugin-by-task)
+- [Main plugins](#main-plugins)
+  - [Put a store or a client on every handler: `contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin)
+  - [Use `race` and `delay` without `ctx`: `effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin)
+  - [Bind or replace a handler: `actionsPlugin`](#bind-or-replace-a-handler-actionsplugin)
+  - [Mount a domain as one unit: `modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin)
+- [Extra plugins](#extra-plugins)
+  - [Give one action its own fields: `scopePlugin`](#give-one-action-its-own-fields-scopeplugin)
+  - [Tie an emit or a listener to an outside signal: `signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin)
+  - [Name the origin and the flow of a trace: `tracePlugin`](#name-the-origin-and-the-flow-of-a-trace-traceplugin)
+  - [Listen to a group of events: `matchPlugin`](#listen-to-a-group-of-events-matchplugin)
+  - [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)
+- [Write your own plugin](#write-your-own-plugin)
+
+## Use a plugin
+
+A plugin is a function of the bus. `bus.use(plugin)` calls it with the bus and returns whatever the plugin returns. Most plugins return the same bus, so you can chain them: `createBus().use(a).use(b)`. A few return something of their own (a registry, an app, a `disconnect` function): keep it.
+
+In TypeScript keep the result of `contextPlugin` and `effectsPlugin`: the type of the bus with its new fields is the type they return (`const bus = createBus().use(contextPlugin({ store }))`).
+
+## Pick a plugin by task
+
+Find your need in the left column. No row fits: you need no plugin.
+
+| I need | Use |
+| ------ | --- |
+| A store, client or logger on every handler | [`contextPlugin`](#put-a-store-or-a-client-on-every-handler-contextplugin) |
+| `race`, `all` or `delay` without passing `ctx` | [`effectsPlugin`](#use-race-and-delay-without-ctx-effectsplugin) |
+| A test that replaces a handler | [`actionsPlugin`](#bind-or-replace-a-handler-actionsplugin) |
+| One domain mounted and unmounted as a unit | [`modulePlugin`](#mount-a-domain-as-one-unit-moduleplugin) |
+| Fields for one action or module only | [`scopePlugin`](#give-one-action-its-own-fields-scopeplugin) |
+| Tasks that stop when a request, socket or query is cancelled | [`signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin) |
+| One listener for a group of events | [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) |
+| A callback for a state manager that emits | [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) |
+| 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
+
+These four cover what most apps need: shared dependencies, effects, handlers and modules. Start here.
 
 | Plugin | What it gives you | Import | `bus.use` returns |
 | ------ | ----------------- | ------ | ----------------- |
 | [`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`
@@ -859,9 +1383,11 @@ const bus = createBus().use(contextPlugin({ store }));
 bus.on("save", (draft, { store }) => store.put(draft));
 ```
 
+A client that must stop with the task, such as an `axios` instance, goes in as `fromSignal((signal) => axios.create({ signal }))` from `nanoeffects/signal`: it is built from the signal of each task, when the task reads it. More in [Build a field from the signal of each task](context.md#build-a-field-from-the-signal-of-each-task).
+
 ### 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";
@@ -874,7 +1400,7 @@ const bus = createBus().use(effects);
 
 bus.on("load", async (id, { race, delay }) => {
   const result = await race({
-    data: ({ signal }) => api.get(id, { signal }),
+    data: (child) => api.get(id, child),
     timeout: () => delay(5000),
   });
 });
@@ -900,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";
@@ -911,7 +1437,7 @@ const bus = createBus();
 // modulePlugin — mounts userModule at the end of this block, or at the first use if that is earlier, and returns the app
 const app = bus.use(modulePlugin([userModule]));
 
-app.unmount(userModule); // its listeners, bound commands and tasks are gone
+app.unmount(userModule); // its listeners, bound actions and tasks are gone
 ```
 
 ## Extra plugins
@@ -921,26 +1447,27 @@ Add one of these when you meet its need. None of them is required.
 | Plugin | What it gives you | Import | `bus.use` returns |
 | ------ | ----------------- | ------ | ----------------- |
 | [`scopePlugin`](#give-one-action-its-own-fields-scopeplugin) | Its own fields for one action, job or module, and a way to replace them in one `emit`. | `nanoeffects/scope` | The same bus |
-| [`signalPlugin`](#tie-an-emit-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks when an outside signal aborts. | `nanoeffects/signal` | The same bus, typed with the new `emit` |
+| [`signalPlugin`](#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin) | `emit(call, { signal })` that aborts its tasks, and `on(event, handler, { signal })` that removes the listener, when an outside signal aborts. | `nanoeffects/signal` | The same bus, typed with the new `emit` |
 | [`matchPlugin`](#listen-to-a-group-of-events-matchplugin) | `on` that listens to a group of events which a function picks. | `nanoeffects/match` | The same bus, typed with the new overloads |
 | [`emitterPlugin`](#hand-the-bus-to-a-state-manager-emitterplugin) | A callback that emits an action, to give to a state manager. | `nanoeffects/actions` | The same bus, with `emitter` |
 | [`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";
 import { createAction } from "nanoeffects/actions";
 import { scopePlugin } from "nanoeffects/scope";
 
-// scopePlugin — makes the scope of a command work on this bus
+// scopePlugin — makes the scope of an action work on this bus
 const bus = createBus().use(scopePlugin());
 
-// the last argument: fields of this command only
+// the last argument: fields of this action only
 const getUser = createAction("user/get", (id, { api }) => api.getUser(id), {
   api,
 });
@@ -949,25 +1476,41 @@ const fakeApi = { getUser: async (id) => ({ id, name: "test" }) };
 bus.emit(getUser("1"), { api: fakeApi }); // a fake api for this call only
 ```
 
-### Tie an emit to an outside signal: `signalPlugin`
+### Tie an emit or a listener to an outside signal: `signalPlugin`
 
-A library such as React Query owns the request and gives you an `AbortSignal`. `emit` takes it as `{ signal }` and aborts the tasks it starts when the signal aborts, so `timeout`, `retry` and the request stop too. More in [Use nanoeffects with React Query and SWR](query-libraries.md).
+A library such as React Query owns the request and gives you an `AbortSignal`. `emit` takes it as `{ signal }` and aborts the tasks it starts when the signal aborts, so `timeout`, `retry` and the request stop too. More in [Use nanoeffects with React Query, SWR and RTK Query](query-libraries.md).
 
 ```js
 import { createBus } from "nanoeffects";
 import { createAction } from "nanoeffects/actions";
 import { signalPlugin } from "nanoeffects/signal";
 
-// signalPlugin — emit takes { signal } for a command, 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 }));
 
 const controller = new AbortController();
-bus.emit(getUser("1"), { signal: controller.signal }); // runs the command
+bus.emit(getUser("1"), { signal: controller.signal }); // runs the action
 controller.abort(); // ctx.signal of the handler aborts with it
 ```
 
+The same signal can end a listener. `on` and `once` take `{ signal }` as their options, as `addEventListener` does, so code that has a signal keeps no `unbind` function. The listener is removed when the signal aborts; a handler that already runs is not aborted. A signal that is aborted already adds no listener.
+
+```js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — on and once take { signal } in their options
+const bus = createBus().use(signalPlugin());
+
+const controller = new AbortController();
+bus.on("saved", (draft) => console.log(draft), { signal: controller.signal }); // listens until the abort
+controller.abort(); // the listener is gone: bus.get("saved") is empty
+```
+
+Without the plugin the `signal` option is ignored and the listener stays. `off(event, handler)` removes a listener but does not end its link to the signal; call the function that `on` returned for that.
+
 ### Name the origin and the flow of a trace: `tracePlugin`
 
 With a tracer on the bus, the plugin lets a trace say which subscription began a chain (`traceId` of `useEmitter` and `bus.emitter`), follow one flow by a `traceGroupId`, and show which listener ran (`bus.on(event, handler, { traceId })`). Without the plugin the options are ignored. More in [Tracing](tracing.md#show-which-subscription-began-a-chain).
@@ -1059,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.
@@ -1080,7 +1635,7 @@ import { scopePlugin } from "nanoeffects/scope";
 export const bus = createBus()
   .use(contextPlugin({ store })) // ctx.store on every task
   .use(effectsPlugin({ race, all })) // ctx.race and ctx.all, bound to the task
-  .use(scopePlugin()) // scopes for commands, actions, jobs, modules and emit
+  .use(scopePlugin()) // scopes for actions, jobs, modules and emit
   .use(matchPlugin()) // bus.on takes a function that picks the events
   .use(emitterPlugin()); // bus.emitter(creator)
 
@@ -1121,7 +1676,7 @@ These connect the bus to something, but are not used with `bus.use`:
 - `createEffectsMiddleware(bus, { filter })` from `nanoeffects/redux` is a Redux middleware for a bus that exists. See [Stores](stores.md#wire-redux-toolkit-to-a-bus).
 - `createBus({ trace })` takes a tracer from `nanoeffects/trace`. See [Tracing](tracing.md).
 - `extendBus(bus, Base)` from `nanoeffects/oop` gives a class the methods of a bus, with the subscriptions of each instance ended by `dispose()`. It reads the bus as it is, so use the plugins first. See [Use the bus from a class](oop.md).
-- `createObserve(bus)` from `nanoeffects/observable` turns an event into an Observable. See [Observable](observable.md).
+- `createObserve(bus)` from `nanoeffects/observable` turns an event into an Observable, and `events(bus, event)` into a `for await` loop. See [Observable](observable.md).
 
 ## Write your own plugin
 
@@ -1157,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";
@@ -1183,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 |
 | ------ | ----------------- |
@@ -1193,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).
 
@@ -1299,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
@@ -1454,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.
 
@@ -1564,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
@@ -1658,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
 
@@ -1696,110 +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)).
 
-## Wrap a handler with retry and timeout
+## Effects
 
-`retry`, `timeout`, and `poll` have two forms:
+Every effect below has its own section with its forms, options and an example. `ctx` is the context of the task.
 
-- **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.
+- [`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.
 
-The first argument tells them apart: a function (`retry`), a number (`timeout`), or a number/function (`poll`) is a wrapper; an object is `ctx`.
+## `retry`
+
+Runs a function again after an error. Use it when a call fails now and then, for example because of the network.
+
+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.
+
+Options:
+
+- `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, ({ signal }) => {
-    return fetchData(id, { signal });
-  });
-  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.
 
-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.
+The error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`). `timeout` rejects even if the function ignores its signal.
 
-### Options for retry, timeout, and poll
+```js
+import { createBus } from "nanoeffects";
+import { timeout } from "nanoeffects/effects";
 
-**`retry`**
+const bus = createBus();
+const loadUser = (id, { signal }) => fetchUser(id, { signal });
 
-- `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.
+// timeout — a wrapper of the handler: it must finish within 5 s
+bus.on("load", timeout(5000, loadUser));
 
-**`timeout`**
+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);
+});
+```
 
-- Error is a `DOMException` named `TimeoutError` (like `AbortSignal.timeout`).
-- Rejects even if the starter ignores its signal.
+## `poll`
 
-**`poll`** (like patronum `interval`)
+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.
 
-- 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`.
-- An error from `fn` stops polling and rejects. An abort ends it normally and clears the timer.
+Forms:
 
-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):
+- `poll(ms, fn, options?)` — a wrapper of a handler.
+- `poll(ctx, fn, ms)` — a call inside a body.
+
+Options:
+
+- 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.
 
 ```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:
 
@@ -1839,48 +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({
-    data: ({ signal }) => fetchData(id, { signal }),
-    // 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: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { 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
 });
 ```
 
-- 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`
+
+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.
+
+```js
+import { createBus } from "nanoeffects";
+import { delay } from "nanoeffects/effects";
+
+const bus = createBus();
 
-## Tie a promise to the task signal
+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");
+});
+```
 
-`delay(ctx, ms)` waits and rejects on abort (`ms` can be a function).
+## `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";
@@ -1889,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",
@@ -1902,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";
@@ -1918,67 +2545,124 @@ 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`
+
+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";
+
+const bus = createBus();
+
+bus.on("watch", (_, ctx) => {
+  // 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);
+});
+```
+
+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`
+
+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";
+import { createAction } from "nanoeffects/actions";
+import { take, timeout } from "nanoeffects/effects";
+
+const bus = createBus();
+const stopRequested = createAction("stop"); // an event with a name; calling it builds the action
+
+bus.on("login", async (user, ctx) => {
+  const reason = await take(ctx, "logout"); // resolves on the next logout
+  cleanup(user, reason);
+
+  // an action creator works the same, and its payload type is the type of the result
+  const stopped = await take(ctx, stopRequested);
+  console.log(stopped);
+
+  // wait for a matching event, but not longer than 5 s
+  const id = await timeout(
+    ctx,
+    5000,
+    take("saved", { predicate: (savedId) => savedId === draft.id }), // take without ctx — a ready-made function for the group
+  );
+});
+```
+
+- 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 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`
 
-A task context has `on` and `off`, like the bus. A subscription made with `ctx.on` ends when the task aborts:
+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("watch", (_, ctx) => {
-  ctx.on("tick", (n) => console.log(n)); // gone when this task aborts
+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 });
 });
 ```
 
-- 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.
+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`.
 
-`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`:
+**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:
 
 ```js
 import { createBus } from "nanoeffects";
-import { createAction } from "nanoeffects/actions";
-import { take, timeout } from "nanoeffects/effects";
+import { all, retry } from "nanoeffects/effects";
 
 const bus = createBus();
-const stopRequested = createAction("stop"); // an event with a name; calling it builds the action
-
-bus.on("login", async (user, ctx) => {
-  const reason = await take(ctx, "logout"); // resolves on the next logout
-  cleanup(user, reason);
-
-  // an action creator works the same, and its payload type is the type of the result
-  const stopped = await take(ctx, stopRequested);
-  console.log(stopped);
 
-  // wait for a matching event, but not longer than 5 s
-  const id = await timeout(
+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,
-    5000,
-    take("saved", { predicate: (savedId) => savedId === draft.id }), // take without ctx: a starter
+    ids.map((id) => retry(() => loadUser(id), { times: 2 })),
+    { concurrency: 5 },
   );
+
+  render(users);
 });
 ```
 
-- 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.
-
-## Run several starters together
+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";
@@ -1987,9 +2671,10 @@ 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: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { signal }),
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
   });
 
   if (user.status === "fulfilled") {
@@ -1998,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";
@@ -2007,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"
   });
 
@@ -2019,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";
@@ -2031,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),
@@ -2043,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";
@@ -2055,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 }),
@@ -2070,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.
 
+```js
+import { delay, retry } from "nanoeffects/effects";
 
-**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: `({ signal }) => fetchUser(id, { signal })`. The same holds for `all`, `allSettled` and `timeout`.
+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
@@ -2131,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";
@@ -2150,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.
 
@@ -2160,11 +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)).
 
-## Return a value from `emit` with a handler
+## Action, job and module
+
+Four forms, one idea each. Take the first row that fits.
+
+| Form | What it is | Use it when |
+| ---- | ---------- | ----------- |
+| `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 actions. Add a handler when you need a result, a job when you need a status, a module when you need a unit.
 
-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.
+## On this page
+
+- [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)
+  - [The result type of a bound handler](#the-result-type-of-a-bound-handler)
+  - [Jobs](#jobs)
+- [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)
+
+## Get the result of `emit`
+
+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
@@ -2189,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.
 
@@ -2224,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 })`.
@@ -2274,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.
 
@@ -2314,11 +3075,11 @@ On a bus without an event map you can say it where you call: `const id = bus.emi
 - `pending` / `success` / `fail` / `cancel` are a string (job makes an action creator) or an existing action creator. Missing ones become `<type>/pending`, `<type>/success`, `<type>/fail` or `<type>/cancel`.
 - `bus.emit(loadUser(id))` returns a promise of the result. Handler errors are always handled: they go to `fail` and the promise resolves with `undefined`. For a result that must reject, give `createAction` the handler.
 - Outcome actions are emitted as the task that ran the job (also for a handler bound with `actions.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
-- A job without a handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent. An action without a handler is an event and does not throw.
+- A job without a handler is not an outcome: `emit` throws `No handler for action "..."` and nothing is sent. An action without a handler is an event and does not throw.
 - 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`.
 
@@ -2391,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.
 
@@ -2484,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
@@ -2518,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).
@@ -3198,11 +3961,26 @@ A handler gets the store from `ctx.store` and calls a mutation, whatever it hand
 ---
 Source: docs/query-libraries.md
 
-# Use nanoeffects with React Query and SWR
+# 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.
 
-Read this page if you fetch data with [React Query](https://tanstack.com/query) (TanStack Query) or [SWR](https://swr.vercel.app) and want `retry`, `timeout` and the abort of nanoeffects inside the request. It shows one action that both libraries call.
+## On this page
 
-You need a React project, `nanoeffects`, and one of the two libraries. `api` below is your own client: replace it with your requests.
+- [Decide who owns what](#decide-who-owns-what)
+- [Make the action](#make-the-action)
+- [Call it from React Query](#call-it-from-react-query)
+- [Call it from SWR](#call-it-from-swr)
+- [Let the bus know the result](#let-the-bus-know-the-result)
+- [Call it from RTK Query](#call-it-from-rtk-query)
+- [Give the client its signal once](#give-the-client-its-signal-once)
+- [Push a live stream into the cache](#push-a-live-stream-into-the-cache)
+- [Refetch queries when the bus says so](#refetch-queries-when-the-bus-says-so)
+- [Know the limits](#know-the-limits)
 
 ## Decide who owns what
 
@@ -3263,7 +4041,7 @@ import { getUser } from "./user";
 export function Profile({ id }) {
   const { isLoading, data, error } = useQuery({
     queryKey: ["user", id],
-    // emit — runs the command; { signal } ties its task to the signal of React Query
+    // emit — runs the action; { signal } ties its task to the signal of React Query
     queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
   });
 
@@ -3313,11 +4091,266 @@ 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
+
+<!-- docs-check: new -->
+
+RTK Query gives the `queryFn` of an endpoint a `signal` in its second argument, so the call is the same as with React Query: pass it to `emit`. This page does not set up the store; see [Stores](stores.md) for that.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — lets emit take { signal }
+export const bus = createBus().use(signalPlugin());
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction with a handler — emit returns what the handler returns
+export const getUser = createAction("user/get", (id, { signal }) =>
+  api.getUser(id, { signal }),
+);
+```
+
+```js
+// api-slice.js
+import { createApi, fakeBaseQuery } from "@reduxjs/toolkit/query/react";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export const userApi = createApi({
+  reducerPath: "userApi",
+  baseQuery: fakeBaseQuery(), // RTK Query — every endpoint brings its own queryFn
+  endpoints: (build) => ({
+    getUser: build.query({
+      // emit — runs the action; { signal } ties its task to the request of RTK Query
+      queryFn: async (id, { signal }) => {
+        const user = await bus.emit(getUser(id), { signal });
+        return { data: user };
+      },
+    }),
+  }),
+});
+```
+
+## Give the client its signal once
+
+<!-- docs-check: new -->
+
+Problem: the action passes `signal` to every call of `api`, and one forgotten `{ signal }` leaves a request running after the query is gone. `fromSignal` builds the client from the signal of each task, so the handler cannot forget it. Use it when many actions share one client. A single action is simpler as it is in [Make the action](#make-the-action).
+
+`fromSignal` marks a field of `contextPlugin`. The client is made when a handler first reads `ctx.http`, from the `ctx.signal` of that task. More in [Context fields](context.md#build-a-field-from-the-signal-of-each-task).
+
+```js
+// bus.js
+import axios from "axios";
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal, signalPlugin } from "nanoeffects/signal";
+
+// fromSignal — http is a new axios client for each task, bound to the signal of that task
+const http = fromSignal((signal) => axios.create({ baseURL: "/api", signal }));
+
+// contextPlugin — every handler gets ctx.http
+const context = contextPlugin({ http });
+
+// signalPlugin — emit takes { signal }, so the signal of the query reaches the task
+export const bus = createBus().use(signalPlugin()).use(context);
+```
+
+```js
+// user.js
+import { createAction } from "nanoeffects/actions";
+
+// the handler never sees a signal: ctx.http stops when the task aborts
+export const getUser = createAction("user/get", async (id, { http }) => {
+  const response = await http.get(`/users/${id}`);
+  return response.data;
+});
+```
+
+```jsx
+// Profile.jsx
+import { useQuery } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { getUser } from "./user";
+
+export function Profile({ id }) {
+  const { data } = useQuery({
+    queryKey: ["user", id],
+    // emit — the signal of React Query aborts the task, and with it the request of ctx.http
+    queryFn: ({ signal }) => bus.emit(getUser(id), { signal }),
+  });
+
+  return <p>{data?.name}</p>;
+}
+```
+
+## Push a live stream into the cache
+
+<!-- docs-check: new -->
+
+Problem: prices arrive from a socket, and the component should show the newest one without a refetch. The socket code emits an event on the bus; the component reads those events with `events` and writes each into the cache. Both libraries have an entry point for pushed data: `setQueryData` in React Query and `useSWRSubscription` in SWR.
+
+`events` gives the payloads to a `for await` loop. `buffer: 1` keeps only the newest price while a write is running. The abort in the cleanup ends the loop and removes the listener. More in [Read an event with a `for await` loop](observable.md#read-an-event-with-a-for-await-loop).
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+
+// createBus — the bus the socket code and the components share
+export const bus = createBus();
+```
+
+```js
+// prices.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — the event the socket code emits for every new price
+export const priceChanged = createAction("price/changed");
+```
+
+```jsx
+// Price.jsx
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { events } from "nanoeffects/observable";
+import { bus } from "./bus";
+import { priceChanged } from "./prices";
+
+export function Price({ symbol }) {
+  const queryClient = useQueryClient();
+  const { data } = useQuery({
+    queryKey: ["price", symbol],
+    queryFn: () => api.getPrice(symbol), // the first value; the stream keeps it fresh
+  });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    // events — the newest price event, one at a time
+    const prices = events(bus, priceChanged, {
+      signal: controller.signal,
+      buffer: 1,
+    });
+
+    async function follow() {
+      for await (const price of prices) {
+        if (price.symbol === symbol) {
+          queryClient.setQueryData(["price", symbol], price.value); // write into the cache
+        }
+      }
+    }
+
+    follow().catch((error) => {
+      if (!controller.signal.aborted) throw error; // the abort ends the loop; anything else is a bug
+    });
+
+    return () => controller.abort(); // the component left: the loop ends, the listener goes
+  }, [queryClient, symbol]);
+
+  return <p>{data}</p>;
+}
+```
+
+SWR does the same with `useSWRSubscription` from `swr/subscription`. Its subscribe function gets `next` to push a value and returns the cleanup:
+
+```jsx
+// Price.jsx
+import useSWRSubscription from "swr/subscription";
+import { events } from "nanoeffects/observable";
+import { bus } from "./bus";
+import { priceChanged } from "./prices";
+
+export function Price({ symbol }) {
+  const { data } = useSWRSubscription(["price", symbol], (_key, { next }) => {
+    const controller = new AbortController();
+    // events — the newest price event, one at a time
+    const prices = events(bus, priceChanged, {
+      signal: controller.signal,
+      buffer: 1,
+    });
+
+    async function follow() {
+      for await (const price of prices) {
+        if (price.symbol === symbol) {
+          next(null, price.value); // SWR — push the value to the hook
+        }
+      }
+    }
+
+    follow().catch((error) => {
+      if (!controller.signal.aborted) next(error);
+    });
+
+    return () => controller.abort(); // SWR calls this when the last component of the key leaves
+  });
+
+  return <p>{data}</p>;
+}
+```
+
+## Refetch queries when the bus says so
+
+<!-- docs-check: new -->
+
+Problem: a save in one part of the app should refresh the lists in another. The save emits an event, and the component that owns the queries listens for it. One `AbortController` ends every listener of the component, instead of one `unbind` for each. For a single listener, `return bus.on(…)` from the effect is shorter.
+
+This needs `signalPlugin`, because `{ signal }` in the options of `on` is read by the plugin. Without it the listeners stay after the component leaves.
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { signalPlugin } from "nanoeffects/signal";
+
+// signalPlugin — on takes { signal } and removes the listener when it aborts
+export const bus = createBus().use(signalPlugin());
+```
+
+```js
+// user-events.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction — events the save code emits
+export const userSaved = createAction("user/saved");
+export const userDeleted = createAction("user/deleted");
+```
+
+```jsx
+// UserList.jsx
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { bus } from "./bus";
+import { userDeleted, userSaved } from "./user-events";
+
+export function UserList() {
+  const queryClient = useQueryClient();
+  const { data } = useQuery({ queryKey: ["users"], queryFn: () => api.listUsers() });
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const { signal } = controller;
+    const refresh = () => queryClient.invalidateQueries({ queryKey: ["users"] });
+
+    // on with { signal } — both listeners go when the component leaves
+    bus.on(userSaved, refresh, { signal });
+    bus.on(userDeleted, refresh, { signal });
+
+    return () => controller.abort();
+  }, [queryClient]);
+
+  return <ul>{data?.map((user) => <li key={user.id}>{user.name}</li>)}</ul>;
+}
+```
 
 ## Know the limits
 
-- **Without the plugin, `{ signal }` is ignored.** The action runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
+- **Without the plugin, `{ signal }` is ignored,** in `emit` and in the options of `on`. The action runs, but the abort does not reach it. Call `bus.use(signalPlugin())` once, where the bus is made.
 - **Only the call forms take it.** `bus.emit(getUser(id), { signal })` works; `bus.emit("user/get", id, { signal })` does not.
 - **A handler that returns without a promise is finished with the call**, so a signal that aborts later does not reach it. Actions that fetch are async, so this only matters for a sync handler that sets up a callback.
 - **Give each request its own signal for an event.** For an action with a handler or a job the link ends when it settles. For `bus.emit(action, { signal })` it stays until the signal aborts.
@@ -3330,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.
@@ -3367,7 +4402,7 @@ The action loads a user. It tries the request up to three times, and gives up on
 import { createAction } from "nanoeffects/actions";
 import { retry, timeout } from "nanoeffects/effects";
 
-// createAction — a command with a handler: emit returns what the handler returns
+// createAction — an action with a handler: emit returns what the handler returns
 export const getUser = createAction("user/get", async (id, ctx) => {
   // one try: the request, with the signal of timeout so it can stop it
   const load = ({ signal }) => api.getUser(id, { signal });
@@ -3408,7 +4443,7 @@ app.get("/users/:id", async (request, reply) => {
   });
 
   try {
-    // emit with { signal } — aborting the controller aborts the command: timeout, retry and the request
+    // emit with { signal } — aborting the controller aborts the action: timeout, retry and the request
     const call = getUser(request.params.id);
     return await bus.emit(call, { signal: controller.signal });
   } catch (error) {
@@ -3461,7 +4496,7 @@ import { createAction } from "nanoeffects/actions";
 import { poll } from "nanoeffects/effects";
 import { latest } from "nanoeffects/policies";
 
-// createAction — a command with a handler
+// createAction — an action with a handler
 // latest — a new subscription stops the old one; key — but only the old one of the same socket
 export const watchPrices = createAction(
   "prices/watch",
@@ -3536,21 +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.
 
-## See what goes wrong without a bus
+## On this page
+
+- [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)
+
+## 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.
 
@@ -3607,11 +4656,11 @@ 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 -->
 
-The component keeps what it shows in `useState`. It subscribes in `useEffect` and emits events from its handlers. `bus.on` returns the function that unsubscribes; returning it from the effect removes the listener on unmount.
+The component keeps what it shows in `useState`. It subscribes in `useEffect` and emits events from its handlers. `bus.on` returns the function that unsubscribes; returning it from the effect removes the listener on unmount. If the component already holds an `AbortSignal`, `bus.on(event, handler, { signal })` ends the listener with it; see [`signalPlugin`](plugins.md#tie-an-emit-or-a-listener-to-an-outside-signal-signalplugin).
 
 ```jsx
 // SignUpForm.jsx
@@ -3678,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";
@@ -3799,26 +4848,53 @@ export const Search = ({ wait }) => {
 };
 ```
 
-- `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
-- A pending call is cancelled on unmount and when `deps` change.
-- 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).
+- `onChange` keeps its identity while `wait` stays the same, so it is safe in `useEffect` and in props.
+- A pending call is cancelled on unmount and when `deps` change.
+- 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#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 and SWR](query-libraries.md).
+- React Query or SWR instead of your own state: [Use nanoeffects with React Query, SWR and RTK Query](query-libraries.md).
 
 ---
 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.
@@ -3833,6 +4909,18 @@ npm run dev
 
 `npm run dev` starts the server and Vite together. Start it with `CHAOS=off npm run dev` to turn the failures off.
 
+## On this page
+
+- [Read how the server fails](#read-how-the-server-fails)
+- [See how the files are split](#see-how-the-files-are-split)
+- [Load a history that must not race](#load-a-history-that-must-not-race)
+- [Send a message that can fail](#send-a-message-that-can-fail)
+- [Search where one room is slow](#search-where-one-room-is-slow)
+- [Wait for a room before marking a result](#wait-for-a-room-before-marking-a-result)
+- [Poll for new messages](#poll-for-new-messages)
+- [Know where each value lives](#know-where-each-value-lives)
+- [Where to go next](#where-to-go-next)
+
 ## Read how the server fails
 
 The server keeps its data in memory. These rules are on purpose, and they are the same every run, so you can follow each section below by doing what the table says:
@@ -3895,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
@@ -4075,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:
@@ -4105,7 +5195,7 @@ It is a level D example: the logic lives in one module, and the page only mounts
 | `src/chat-handlers.ts` | `askBot` (`timeout` and `retry` inside) and `watchOperator` (`poll`): plain `async` functions that know nothing about the page. |
 | `src/chat-module.ts` | The list of what is alive while the chat is open. |
 | `src/panel.ts` | The view: shows the lines, sends the texts, returns one function that removes it. |
-| `src/main.ts` | The launcher: the only file that knows both the module and the panel. |
+| `src/main.ts` | The launcher: the only file that knows both the module and the panel; it listens for `closeRequested` only while the chat is open. |
 
 ## Bind everything in one module
 
@@ -4155,7 +5245,7 @@ Three details that make the cleanup complete:
 
 ## Open and close from the launcher
 
-`app.mount` returns the function that unmounts the module. The launcher puts it together with the one that removes the panel.
+`app.mount` returns the function that unmounts the module. `bus.on` returns the one that unsubscribes. The launcher puts them together with the one that removes the panel into a single `close`.
 
 <!-- docs-check: skip - the other files of the example are in examples/chat-widget -->
 ```js
@@ -4171,7 +5261,10 @@ let close = null; // set while the chat is open
 const open = () => {
   const stopModule = app.mount(chatModule); // subscriptions, polling and Escape start
   const stopPanel = renderPanel(document.body);
+  // the module emits closeRequested on Escape; nothing does while the chat is closed
+  const stopEscape = bus.on(closeRequested, () => close?.());
   close = () => {
+    stopEscape();
     stopPanel();
     stopModule(); // everything the module started ends, a running request included
     close = null;
@@ -4185,18 +5278,15 @@ button.addEventListener("click", () => {
     open();
   }
 });
-
-// the launcher stays subscribed: it must hear Escape to close the chat
-bus.on(closeRequested, () => close?.());
 ```
 
-The launcher's own `bus.on` is the only subscription that lives while the chat is closed, and it does nothing then: `close` is `null`.
+While the chat is closed the launcher holds no subscription at all: it only has the click listener of the button, which is a DOM listener, not a listener of the bus.
 
 ## Check that closing cleans up
 
 1. Open the chat and send a text. The bot answers after about a second. Every third question fails, and the retry asks again.
 2. Send a text and close the chat before the answer arrives. No line appears, also when you open the chat again.
-3. Look at the box "Listeners on the bus": it shows `bus.get(event).length` for four events and updates when the chat opens or closes. Closed: only `chat/closeRequested` has a listener (the launcher). Open: `chat/sent`, `chat/messageAdded` and `chat/typing` have one each as well. That is the proof that nothing is left subscribed.
+3. Look at the box "Listeners on the bus": it shows `bus.get(event).length` for four events and updates when the chat opens or closes. Closed: every event shows `0`, and so does "all events". Open: each of the four has one listener, and "all events" is `4`. That is the proof that nothing is left subscribed.
 4. Wait 10 s with the chat closed. The operator is not polled: no line from the operator appears.
 5. Press `Escape` with the chat closed. Nothing happens. Open the chat and press it again: it closes.
 6. Open the chat again. The old lines are back, and the polling runs.
@@ -4209,11 +5299,77 @@ The launcher's own `bus.on` is the only subscription that lives while the chat i
 - 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.
@@ -4306,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).
 
 ---
@@ -4314,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.
@@ -4392,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. Skip until many handlers need the same dependency.
+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.
 
-## Pass values at runtime
+## On this page
+
+- [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
+
+<!-- docs-check: new -->
 
 ```js
 import { createBus } from "nanoeffects";
@@ -4414,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** command, action, job or module, or to replace them for one `emit`, see [scopes](scope.md).
+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).
 
-## 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.
 
@@ -4444,7 +5627,41 @@ 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 }))`.
 
-### Name the fields in the event map instead
+### 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.
+
+`fromSignal(make)` from `nanoeffects/signal` marks a field of `contextPlugin` as a value that is built from the signal of the task. It does not run `make` for the bus: it runs it for each task that reads the field, once, with the `ctx.signal` of that task.
+
+```js
+import { createBus } from "nanoeffects";
+import { contextPlugin } from "nanoeffects/context";
+import { fromSignal } from "nanoeffects/signal";
+import axios from "axios";
+
+// contextPlugin — every task gets these fields
+// fromSignal — http is made from the signal of the task that reads ctx.http
+const bus = createBus().use(
+  contextPlugin({
+    logger: console, // a plain field: the same object for every task
+    http: fromSignal((signal) => axios.create({ signal })),
+  }),
+);
+
+bus.on("user/open", async (id, ctx) => {
+  const response = await ctx.http.get(`/users/${id}`); // aborts with the task
+  ctx.logger.log(response.data);
+});
+```
+
+- `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
 
 `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.
 
@@ -4457,10 +5674,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.
 
@@ -4468,7 +5682,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)`.
 
-## Turn scopes on
+### Turn scopes on
+
+<!-- docs-check: new -->
 
 Scopes are a plugin, so a bus that does not use them pays nothing.
 
@@ -4486,7 +5702,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 -->
 
@@ -4498,7 +5716,7 @@ import { createAction } from "nanoeffects/actions";
 export const getUser = createAction(
   "user/get",
   (id, { api, cache }) => {
-    // api and cache are on ctx for this command only
+    // api and cache are on ctx for this action only
     return cache.get(id) ?? api.getUser(id);
   },
   { api, cache: new Map() },
@@ -4514,7 +5732,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.
 
@@ -4559,7 +5779,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.
 
@@ -4601,7 +5823,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
@@ -4640,20 +5864,24 @@ 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:
 
 | Strength | Where it is set |
 | -------- | --------------- |
 | 1 (strongest) | the second argument of `emit` |
-| 2 | the scope of the action, command or job |
+| 2 | the scope of the action or job |
 | 3 | the scope of the module that owns the handler |
 | 4 (weakest) | the bus: `createBus({ context })`, `contextPlugin`, `effectsPlugin` |
 
 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.
 
@@ -4695,7 +5923,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`.
 
@@ -4719,7 +5949,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.
@@ -4732,6 +5964,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 |
@@ -4739,7 +5973,24 @@ 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
+
+- [The problem without it](#the-problem-without-it)
+- [Make an independent emitter with `Emitter`](#make-an-independent-emitter-with-emitter)
+  - [Type the events (optional)](#type-the-events-optional)
+- [Give a class the methods of a shared bus](#give-a-class-the-methods-of-a-shared-bus)
+  - [Extend the result with no class of your own](#extend-the-result-with-no-class-of-your-own)
+- [Let the class make its bus](#let-the-class-make-its-bus)
+- [End the subscriptions with `dispose`](#end-the-subscriptions-with-dispose)
+- [Stream an event with a `Subject`](#stream-an-event-with-a-subject)
+- [Keep a method of your own](#keep-a-method-of-your-own)
+- [Subscribe a method with `@On` and `@Once`](#subscribe-a-method-with-on-and-once)
+- [Decorate the class with `@WithBus`](#decorate-the-class-with-withbus)
+- [Pass a method by hand](#pass-a-method-by-hand)
+- [Type the instances (optional)](#type-the-instances-optional)
+- [What is not done](#what-is-not-done)
 
 ## The problem without it
 
@@ -5148,6 +6399,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
@@ -5171,7 +6424,7 @@ export const getUser = createAction(
   },
 );
 
-// createModule: m.use binds the handler the command carries, while the module is mounted
+// createModule: m.use binds the handler the action carries, while the module is mounted
 export const userModule = createModule("user", (m) => {
   m.use(getUser);
 });
@@ -5320,6 +6573,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
@@ -5419,8 +6674,21 @@ 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
+
+- [Split the work](#split-the-work)
+- [Find the equivalent](#find-the-equivalent)
+- [Rewrite an effect](#rewrite-an-effect)
+  - [Keep the state in Zustand](#keep-the-state-in-zustand)
+- [Rewrite a form](#rewrite-a-form)
+  - [Replace the log with a request](#replace-the-log-with-a-request)
+- [Use both in one app](#use-both-in-one-app)
+- [What is different](#what-is-different)
+
 ## Split the work
 
 | Job | Use |
@@ -5439,7 +6707,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 |
@@ -5737,7 +7005,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`.
@@ -5747,9 +7015,11 @@ bus.on(
 ---
 Source: docs/migrating-from-mitt.md
 
-# Coming from mitt, nanoevents or EventEmitter
+# Coming from mitt and nanoevents
+
+> **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`, 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.
+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
 
@@ -5764,8 +7034,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)` |
@@ -5850,6 +7120,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
@@ -6049,23 +7321,340 @@ 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
+
+1. A handler is `(payload, ctx)`. Use `ctx.signal`, `ctx.emit` and `ctx.on`; the rest of `ctx` is optional.
+2. Pass `ctx.signal` to what the handler calls (`fetch`, a client), so an abort stops the work.
+3. An aborted task delivers no result and emits nothing.
+4. `emit` is synchronous: the first handler error is thrown, unless `onError` is set.
+5. Rejections of async handlers are not handled without `onError`.
+
+Details of each rule and the rest:
+
 - **An aborted task delivers no result.** If the task aborts before a promise settles, the promise rejects with the abort reason, even if the value was just produced in the same tick. `latest`, `debounce`, `all`, `race`, `take`, and the rest follow this rule.
 - **`emit` is a plain, synchronous loop** (see [Errors](errors.md)). A `ctx.emit` inside a handler is the same call: without `onError`, an error of a nested handler is thrown into the handler that emitted; with `onError` it goes there and `ctx.emit` does not throw.
 - **Rejections of async handlers** are not handled for you. Without `onError` they are unhandled rejections, which end a Node process by default. Use `onError` for async handlers.
 - **`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)
+- [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.
+
+## 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 | 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 | |
+| 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.*"] },
+      ],
+    },
+  },
+];
+```
+
+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. Three ways to tell it:
+
+- **`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.
+
+It counts what a handler does after the cancel. A request that a handler started and that the cancel did not stop is not counted unless the handler then emits; the next section finds those.
+
+## 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.
 
+## On this page
+
+- [Attach a tracer](#attach-a-tracer)
+- [Show every emit](#show-every-emit)
+- [Show which subscription began a chain](#show-which-subscription-began-a-chain)
+- [Follow one flow with a traceGroupId](#follow-one-flow-with-a-tracegroupid)
+- [Name a listener](#name-a-listener)
+- [Keep the chain: `ctx.emit`, not `bus.emit`](#keep-the-chain-ctxemit-not-busemit)
+- [Turn the names off](#turn-the-names-off)
+- [Use built-in loggers](#use-built-in-loggers)
+  - [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)
+
 ## Attach a tracer
 
 Pass `trace` to `createBus`. Make it with `createTracer` from `nanoeffects/trace`, which takes a logger (a function) or an array of them. The tracing code lives in that entry, so a bus without `trace` does not carry it.
@@ -6101,7 +7690,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";
@@ -6148,7 +7737,7 @@ The event changes nothing else: the other tasks keep their `parentId`, `rootId`
 
 ## Show which subscription began a chain
 
-**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of commands and retries.
+**Problem.** `useEmitter` and `bus.emitter` put an event on the bus from outside any task, such as a render or the callback of a store. In the trace that event has no sign of where it came from. With many such subscriptions it is hard to tell which one started a chain of actions and retries.
 
 **When.** The bus has a tracer and the project has several `useEmitter` or `bus.emitter` calls. The names come from `tracePlugin`: use it on the bus, or the `traceId` is ignored.
 
@@ -6176,8 +7765,8 @@ In a component, the same option goes in the options of the hook: `useEmitter(nam
 
 ```
 [nanoeffects] Profile · run start
-[nanoeffects]   user/save · command start
-[nanoeffects]   user/save · command done
+[nanoeffects]   user/save · action start
+[nanoeffects]   user/save · action done
 [nanoeffects] Profile · run done
 ```
 
@@ -6217,7 +7806,7 @@ const pay = createAction("checkout/pay", async () => {}, {
 ```
 
 ```
-[nanoeffects] [checkout] checkout/pay · command start
+[nanoeffects] [checkout] checkout/pay · action start
 ```
 
 The emitters take it too: `useEmitter(cartChanged, cart, { traceId: "Cart", traceGroupId: "checkout" })`. `traceGroupId` works without `scopePlugin`, and needs `tracePlugin`.
@@ -6247,7 +7836,7 @@ bus.once("name/changed", (name) => console.log(name), { traceId: "auditLog" });
 
 ```
 [nanoeffects] saveNotifier · run start
-[nanoeffects]   user/save · command start
+[nanoeffects]   user/save · action start
 [nanoeffects] saveNotifier · run done
 ```
 
@@ -6292,7 +7881,8 @@ const bus = createBus({
 | `reduxDevtools()` | Sends the emits to Redux DevTools, and with `policies` the stages of the handlers as `type/effect/phase`; state is `{ running }` |
 | `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`, for tests |
+| `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
 
@@ -6305,11 +7895,63 @@ createTracer(logger, {
 });
 ```
 
-- `sample` is decided once per root task; every task below it follows, so a trace is never cut in the middle. Unsampled tasks cost almost nothing.
-- `filter` runs on each event before any logger sees it.
+- `sample` is decided once per root task; every task below it follows, so a trace is never cut in the middle. Unsampled tasks cost almost nothing.
+- `filter` runs on each event before any logger sees it.
+
+### Keep the last events for an incident
+
+`createTraceRecorder()` with no option keeps every event, so a long session fills memory. That is fine in a test and wrong in a running app. Give it a `capacity` and it keeps only the last N events (a ring buffer): when something goes wrong, you still have what led up to it.
+
+<!-- docs-check: new -->
+
+```js
+// bus.js
+import { createBus } from "nanoeffects";
+import { createTraceRecorder, createTracer } from "nanoeffects/trace";
+
+// A logger that keeps the last 500 events and drops the older ones.
+export const recorder = createTraceRecorder({ capacity: 500 });
+
+// Feed the recorder from the tracer.
+const trace = createTracer(recorder);
+
+export const bus = createBus({ trace });
+```
+
+```js
+// incident.js
+import { recorder } from "./bus";
+
+// Keep what is safe to send. An event also has `payload` and `error`.
+const withoutPayload = ({ id, parentId, type, effect, phase }) => ({
+  id,
+  parentId,
+  type,
+  effect,
+  phase,
+});
+
+window.addEventListener("error", () => {
+  const events = recorder.events; // a snapshot, oldest event first
+  const safe = events.map(withoutPayload);
+  const body = JSON.stringify(safe);
+  navigator.sendBeacon("/api/incident", body);
+});
+```
+
+What to know before you send the events:
+
+- **`payload` and `error` can hold private data**: what a user typed, tokens, personal text. The recorder keeps them as they are and does not redact. Choose what to send, as `withoutPayload` does.
+- **There is no time on an event.** You get the order, not the duration. To add a time, wrap the recorder in a logger that stamps `performance.now()` on a copy of the event.
+- **An old `parentId` can point at an event that was pushed out.** When you build a tree from the events, treat an unknown `parentId` as a root.
+- **`recorder.events` is a snapshot with a `capacity`.** Each read builds a new array, so read it once at the moment you need it. Without a `capacity` it is one live array.
+- **A low `sample` thins the buffer.** `createTracer(recorder, { sample: 0.05 })` records 5% of root tasks, so the buffer may hold little when the incident comes. See [Cut volume in production](#cut-volume-in-production).
+- **A `capacity` that is not a positive integer** (`0`, a negative number, `NaN`) means no limit.
 
 ### Configure Redux DevTools
 
+<!-- docs-check: new -->
+
 Read-only (the bus owns no state, so there is no time travel). Does nothing when the extension is not installed. Has its own instance in the DevTools picker, apart from your store.
 
 Quiet by default, so you see what happened before you see how:
@@ -6373,6 +8015,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
@@ -6402,13 +8096,417 @@ 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
+
+- A chain that repeats on purpose is reported. List its event in `ignore`.
+- The report is made once for each loop. `turns` in `graph.cycles()` keeps counting.
+
+---
+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).
+
 `createObserve(bus)` from `nanoeffects/observable` turns a bus event into an Observable that follows the TC39 proposal (`subscribe`, `unsubscribe`, `Symbol.observable`). RxJS and other stream libraries take it as it is. Nothing here depends on them.
 
 ## Turn an event into a stream
@@ -6552,6 +8650,47 @@ bus.on(
 
 `switchMap` drops the old inner stream. `latest` aborts the old task through `signal`, so a `fetch` that got the signal really stops.
 
+## Read an event with a `for await` loop
+
+Problem: a task wants to handle the payloads of one event one after another, in order, and stop when the screen closes. `take` waits for one payload, and a listener has no place for a loop.
+
+`events(source, event, options)` from `nanoeffects/observable` returns an async iterator of the payloads. It listens from the call, so a payload that comes before the first read is kept. `source` is a bus or a task context; with a context the loop also ends when the task aborts.
+
+```js
+import { createBus } from "nanoeffects";
+import { events } from "nanoeffects/observable";
+
+const bus = createBus();
+const controller = new AbortController();
+
+// events — the "query/changed" payloads one by one; keeps the last 3 while the loop is busy
+const queries = events(bus, "query/changed", {
+  signal: controller.signal,
+  buffer: 3,
+});
+
+async function watchQueries() {
+  for await (const query of queries) {
+    console.log("search for", query); // runs once per payload, in order
+  }
+}
+
+watchQueries().catch((reason) => console.log("stopped:", reason)); // the abort rejects the loop
+bus.emit("query/changed", "cat");
+controller.abort("screen closed"); // the loop ends with this reason
+```
+
+| Option | What it does | Default |
+| ------ | ------------ | ------- |
+| `signal` | Ends the loop. The waiting read rejects with the abort reason. | none |
+| `buffer` | The most payloads kept while the loop is busy. | `Infinity` |
+| `overflow` | Which payload goes when the buffer is full: `"drop-oldest"` or `"drop-newest"`. | `"drop-oldest"` |
+
+- `break`, `return` and a throw inside the loop remove the listener.
+- With no `buffer`, a loop that never reads keeps every payload. Set `buffer` for a slow loop.
+- An event of a bus does not end, so the loop ends only by `break`, the `signal` or the task.
+- Inside a task, `events(ctx, "query/changed")` needs no `signal`: the task ending is the end.
+
 ## Convert back to a stream or a promise
 
 | You need | Write |
@@ -6599,6 +8738,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:
@@ -6636,11 +8777,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.