nanoeffects 0.27.0 → 0.29.0

package/llms-full.txt

@@ -10,7 +10,7 @@ Rules that generated code often gets wrong:
 - 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.
+- `bus.emit(action(payload))` runs the action's handler and returns its result. Plain events return nothing.
 
 ---
 Source: docs/guide.md
@@ -28,6 +28,23 @@ Climb one step at a time: small bus → policies → effects → handlers and mo
 
 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. Bind a handler to an action later](#8-bind-a-handler-to-an-action-later)
+- [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 +65,7 @@ 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.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`.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -289,10 +306,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 starter: 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 });
 });
@@ -563,7 +581,7 @@ Pass `--template` to skip the question. With npm, put `--` before the option.
 | `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` | Commands, 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 |
+| `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 |
 
@@ -611,13 +629,13 @@ npm create nanoeffects@latest my-app -- --template domains-ts
 | ---- | --- |
 | `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 a command), `catalog-handlers.ts` (`debounce` and `latest`), `catalog-module.ts`. |
+| `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 commands, 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).
+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
 
@@ -696,24 +714,33 @@ Source: docs/package.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` |
-| `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 command, 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) |
+
+## 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 and `tracePlugin` (names for the trace) | you want to see what ran and why |
 
 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.
 
@@ -804,8 +831,8 @@ import { race, retry } 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 });
+  // with ctx: you pass the context, and the function takes the signal from it
+  const user = await retry(ctx, () => fetchUser(id, { signal: ctx.signal }), { times: 3 });
 
   // as a starter: a group (race, all, allSettled, timeout) calls it with its child
   const result = await race(ctx, {
@@ -828,12 +855,52 @@ Source: docs/plugins.md
 
 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)
+- [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) |
+
 ## Main plugins
 
 These four cover what most apps need: shared dependencies, effects, handlers and modules. Start here.
@@ -859,6 +926,8 @@ 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).
@@ -874,7 +943,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),
   });
 });
@@ -911,7 +980,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,7 +990,7 @@ 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 |
@@ -937,10 +1006,10 @@ 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 +1018,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, a job or an action
 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).
@@ -1080,7 +1165,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 +1206,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
 
@@ -1700,6 +1785,18 @@ Use this page for retry, timeouts, waiting, or parallel work — not as the firs
 
 An abort only raises a flag. Your code decides to stop. Start with `retry` / `timeout` on a handler (see [Guide §5](guide.md#5-add-retry-and-timeout)).
 
+## On this page
+
+- [Wrap a handler with retry and timeout](#wrap-a-handler-with-retry-and-timeout)
+  - [Options for retry, timeout, and poll](#options-for-retry-timeout-and-poll)
+- [Back off between retries](#back-off-between-retries)
+- [Put selected effects on `ctx`](#put-selected-effects-on-ctx)
+- [Tie a promise to the task signal](#tie-a-promise-to-the-task-signal)
+- [Run cleanup on abort](#run-cleanup-on-abort)
+- [Wait for the next event with `take`](#wait-for-the-next-event-with-take)
+- [Run several starters together](#run-several-starters-together)
+- [Pass `ctx` outside a task](#pass-ctx-outside-a-task)
+
 ## Wrap a handler with retry and timeout
 
 `retry`, `timeout`, and `poll` have two forms:
@@ -1745,9 +1842,7 @@ bus.on("load", async (id, ctx) => {
     () => fetchUser(id, { signal: ctx.signal }),
     { times: 4 },
   );
-  const data = await timeout(ctx, 5000, ({ signal }) => {
-    return fetchData(id, { signal });
-  });
+  const data = await timeout(ctx, 5000, (child) => fetchData(id, child));
   await poll(ctx, () => refresh(), 10_000);
   ctx.emit("ready", { user, data });
 });
@@ -1856,7 +1951,8 @@ const bus = createBus().use(effects);
 bus.on("load", async (id, { race, all, delay }) => {
   // race — same as race(ctx, …)
   const result = await race({
-    data: ({ signal }) => fetchData(id, { signal }),
+    // child — the context of this starter; it has the `signal`, so the request stops with the race
+    data: (child) => fetchData(id, child),
     // a starter gets its own child with the same bound effects, so delay(5000) stops with the race
     timeout: ({ delay }) => delay(5000),
   });
@@ -1864,8 +1960,8 @@ bus.on("load", async (id, { race, all, delay }) => {
 
   // all — same as all(ctx, …)
   const { user, posts } = await all({
-    user: ({ signal }) => fetchUser(id, { signal }),
-    posts: ({ signal }) => fetchPosts(id, { signal }),
+    user: (child) => fetchUser(id, child),
+    posts: (child) => fetchPosts(id, child),
   });
 });
 ```
@@ -1988,8 +2084,8 @@ const bus = createBus();
 
 bus.on("open", async (id, ctx) => {
   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") {
@@ -2095,7 +2191,7 @@ bus.on("sync", async (ids, ctx) => {
 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.
 
 
-**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`.
+**A starter gets the context of its own child task.** Pass `child` as the first argument to any effect, as a handler passes `ctx`: when the race ends, `child` is aborted and stops exactly this effect. The outer `ctx` is only for `race` itself. Your own API takes the signal in its options, and `child` has a `signal`, so pass it as the options: `(child) => fetchUser(id, child)` (`fetch` reads only `signal` from it). The same holds for `all`, `allSettled` and `timeout`.
 
 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.
 
@@ -2160,6 +2256,32 @@ A chat with two entities and three features, jobs under policies and effects, an
 
 A whole project with two domains, a job and React as a thin layer: `npm create nanoeffects@latest my-app -- --template domains-ts` (see [Start a project from a template](starter.md#start-with-domains)).
 
+## Pick the word: event, action, job, module
+
+Four names, one idea each. Take the first row that fits.
+
+| Word | What it is | Use it when |
+| ---- | ---------- | ----------- |
+| Event | A name and a payload; `createAction("x")` with no handler. | The UI or a handler tells that something happened. |
+| Action with a handler | The same, plus work: `createAction("x", handler)`. `emit` returns the result. | The caller needs a value back. |
+| Job | An action with a handler that also emits `pending`, `success`, `fail` and `cancel`. | The UI shows a loading state. |
+| Module | A group of listeners, handlers and tasks, mounted and unmounted with one call. | One domain must start and stop as a unit. |
+
+Start with events. Add a handler when you need a result, a job when you need a status, a module when you need a unit.
+
+## On this page
+
+- [Pick the word: event, action, job, module](#pick-the-word-event-action-job-module)
+- [Return a value from `emit` with a handler](#return-a-value-from-emit-with-a-handler)
+- [Describe events, handlers and jobs](#describe-events-handlers-and-jobs)
+  - [Actions](#actions)
+  - [Bind a handler later](#bind-a-handler-later)
+  - [Say what a bound handler returns](#say-what-a-bound-handler-returns)
+  - [Jobs](#jobs)
+- [Show a loading state with a job](#show-a-loading-state-with-a-job)
+- [Mount domains with modules](#mount-domains-with-modules)
+- [Give an action or a module its own fields](#give-an-action-or-a-module-its-own-fields)
+
 ## Return a value from `emit` with a handler
 
 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.
@@ -2314,7 +2436,7 @@ 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.
 
@@ -2476,7 +2598,7 @@ If the `setup` of one module throws, the modules of that call that were already
 - **A module is known by its name.** Mounting a module whose name is taken replaces the mounted one (see [Hot reload](hmr.md)).
 - **Registry.** If `bus.use(actionsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.actions` and `app.actions`.
 - A disposed app cannot mount modules.
-- **The given modules are mounted at the end of the block that made the app**, or at the first use of the app or the bus if that comes first (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `commands`). Nothing needs to use the app: `bus.use(modulePlugin([a, b]))` is enough to start them. The plugins that you use after `modulePlugin` in the same block still reach them, because the modules wait until that block has finished. A plugin used after an `await` can come too late: use every plugin before the first `await`. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
+- **The given modules are mounted at the end of the block that made the app**, or at the first use of the app or the bus if that comes first (the first `bus.emit`, or a call of `mount`, `unmount`, `isMounted`, `dispose`, or the read of `actions`). Nothing needs to use the app: `bus.use(modulePlugin([a, b]))` is enough to start them. The plugins that you use after `modulePlugin` in the same block still reach them, because the modules wait until that block has finished. A plugin used after an `await` can come too late: use every plugin before the first `await`. The `bus.on` calls made in between are held and made right after, so the listeners of a module stay ahead of them. See [using plugins in any order](plugins.md#use-them-in-any-order).
 - **To mount by hand instead**, pass no modules: `modulePlugin()` starts nothing, and `app.mount(...)` starts the modules when you want.
 - Module context = task context plus `handle`, `use`, and `spawn`:
   - `handle` — give an action a handler (one that has none, or an override).
@@ -3198,11 +3320,24 @@ 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
 
-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.
+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 two libraries. `api` below is your own client: replace it with your requests.
+You need a React project, `nanoeffects`, and one of the libraries. `api` below is your own client: replace it with your requests.
+
+## On this page
+
+- [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 +3398,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 }),
   });
 
@@ -3315,9 +3450,264 @@ 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).
 
+## 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.
@@ -3367,7 +3757,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 +3798,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 +3851,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",
@@ -3540,6 +3930,16 @@ Use this page when a React screen starts requests on user input and you need the
 
 You need a React project and `nanoeffects` installed. The form talks to your own client, `api` below: replace it with your requests.
 
+## On this page
+
+- [See what goes wrong without a bus](#see-what-goes-wrong-without-a-bus)
+- [Wire the bus once](#wire-the-bus-once)
+- [Connect the form](#connect-the-form)
+- [Stop running work when the form closes](#stop-running-work-when-the-form-closes)
+- [Show the last value of an event as state](#show-the-last-value-of-an-event-as-state)
+- [Keep a debounced handler between renders](#keep-a-debounced-handler-between-renders)
+- [Where to go next](#where-to-go-next)
+
 ## See what goes wrong without a bus
 
 A registration form has three problems that `useEffect` and `fetch` leave to you:
@@ -3611,7 +4011,7 @@ The handlers know nothing about React. A test can emit `username/typed` and read
 
 <!-- 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
@@ -3812,7 +4212,7 @@ export const Search = ({ wait }) => {
 - A policy as a plain function without a bus: [Use a policy without a bus](policies.md#use-a-policy-without-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
@@ -3833,6 +4233,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:
@@ -3867,7 +4279,7 @@ The code is in layers, and a file imports only from the layers below it. The com
 
 That rule is why `show-history` exists. Selecting a room must load its history, but `room` does not know `message` and `message` does not know `room`. The feature `show-history` is the one place that knows both: it listens to `rooms/selected` and starts the job `messages/loadHistory`. The same goes for a message that arrives: `receive-messages` emits `incoming/received`, an event that the `message` entity owns and listens to.
 
-A folder has its events (`room.ts`, which imports no bus), its work (`room-handlers.ts`), the state it keeps (`room-store.ts`) and a module (`room-module.ts`) that wires them. Another layer reaches an entity through its events and commands, never through its handlers or its store. Events and commands both live in the events file. An event (`createAction` with no handler) says that something happened, and any feature may listen: `rooms/selected` is heard by two. A command (`createAction` with a handler) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createAction`, so the command works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is a command that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
+A folder has its events (`room.ts`, which imports no bus), its work (`room-handlers.ts`), the state it keeps (`room-store.ts`) and a module (`room-module.ts`) that wires them. Another layer reaches an entity through its actions, never through its handlers or its store. All actions live in the events file. An action with no handler says that something happened, and any feature may listen: `rooms/selected` is heard by two. An action with a handler is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createAction`, so the action works wherever it is called and can return a result, and the module binds it with `module.use` for as long as it is mounted. A job is an action with a handler that also sends its outcomes, but its handler is bound in the module (`module.handle`): a job usually runs under a policy, and the type of its outcomes is exact only when the handler is not part of the type.
 
 The layers come from [Feature-Sliced Design](https://feature-sliced.design/), reduced to the three that an app of this size needs.
 
@@ -3883,7 +4295,7 @@ A job sends `pending` when its handler starts and exactly one of `success`, `fai
 // message.js
 import { createJob } from "nanoeffects/actions";
 
-// createJob — a command that also sends pending, success, fail and cancel
+// createJob — an action with a handler that also sends pending, success, fail and cancel
 export const loadHistory = createJob("messages/loadHistory");
 ```
 
@@ -4014,7 +4426,7 @@ export const goToResult = async (hit, ctx) => {
     ctx.emit("rooms/selected", hit.roomId);
     await loaded;
   }
-  // ctx.emit with a command — the message entity marks the message
+  // ctx.emit with an action that has a handler — the message entity marks the message
   ctx.emit(markMessage(hit.id));
 };
 ```
@@ -4066,10 +4478,149 @@ Each entity and each feature that has state keeps it in a [Zustand](https://zust
 
 ## Where to go next
 
-- The API of commands, jobs and modules: [Actions, jobs and modules](actions.md).
+- The API of actions, jobs and modules: [Actions, jobs and modules](actions.md).
 - Policies such as `latest` and `queue`: [Policies](policies.md). Effects such as `allSettled`, `take` and `poll`: [Effects](effects.md).
 - A smaller project with two domains: [Start with domains](starter.md#start-with-domains). Its two domains do not talk to each other, so it needs no layers.
 
+---
+Source: docs/chat-widget.md
+
+# Build a chat widget that listens only while it is open
+
+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:
+
+```bash
+cd examples/chat-widget
+npm install
+npm run dev
+```
+
+It is a level D example: the logic lives in one module, and the page only mounts and unmounts it. For an app with several features see [Build a chat with entities, features, modules and a small server](chat-example.md).
+
+## Know what happens on open and on close
+
+| Moment | What happens |
+| ------ | ------------ |
+| Open | The module is mounted: the bot handler is subscribed, the operator messages are polled, the `Escape` listener is added. The panel is drawn and listens to the bus. |
+| The user sends a text | The bot is asked, one text after another, with a time limit and a retry. |
+| `Escape` | The module emits `chat/closeRequested`; the launcher closes the chat. |
+| Close | The panel is removed and unsubscribed, the module is unmounted. A request in flight is aborted, the polling stops, the `Escape` listener goes away. |
+
+## Find the parts in the files
+
+| File | Job |
+| ---- | --- |
+| `src/bus.ts` | The bus, and `modulePlugin()` with no module: the launcher mounts the module itself. |
+| `src/chat.ts` | The events only: `messageSent`, `messageAdded`, `typingChanged`, `closeRequested`. |
+| `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; it listens for `closeRequested` only while the chat is open. |
+
+## Bind everything in one module
+
+A module is the list of what is alive while the chat is open. When it unmounts, the bus undoes every line of it.
+
+<!-- docs-check: skip - the other files of the example are in examples/chat-widget -->
+```js
+// chat-module.js
+import { createModule } from "nanoeffects/actions";
+import { queue } from "nanoeffects/policies";
+import { closeRequested, messageSent } from "./chat";
+import { askBot, watchOperator } from "./chat-handlers";
+
+// a task that stays pending until the module unmounts; its signal then aborts
+const untilAborted = (ctx) =>
+  new Promise((resolve) => {
+    ctx.signal.addEventListener("abort", resolve, { once: true });
+  });
+
+// a DOM listener that lives as long as the module: `signal` removes it when it aborts
+const listenToEscape = async (_, ctx) => {
+  const onKey = (event) => {
+    if (event.key === "Escape") {
+      ctx.emit(closeRequested());
+    }
+  };
+  document.addEventListener("keydown", onKey, { signal: ctx.signal });
+  await untilAborted(ctx);
+};
+
+export const chatModule = createModule("chat", (module) => {
+  // module.run — runs askBot as a child task of the module, so an unmount aborts it
+  const answer = (text) => module.run(askBot, text);
+  // on + queue — answer the texts one after another, in the order they were sent
+  module.on(messageSent, queue(answer));
+  // spawn — a background task that lives as long as the module
+  module.spawn(watchOperator);
+  module.spawn(listenToEscape);
+});
+```
+
+Three details that make the cleanup complete:
+
+- **`module.run`, not `askBot` directly.** A handler given to `module.on` runs as a child of whoever emitted the event (here the panel), so unmounting stops listening but does not abort a request that is already running. Running it with `module.run` makes it a child of the module.
+- **`queue`, not `latest`.** `queue` keeps the order when the user sends two texts fast. [`latest`](policies.md) would abort the first answer, which is wrong for a conversation.
+- **A DOM listener with `signal`.** `addEventListener` takes a `signal` option and removes the listener when it aborts. The task stays pending until then, because a task that has finished is not aborted again.
+
+## Open and close from the launcher
+
+`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
+// main.js
+import { app, bus } from "./bus";
+import { closeRequested } from "./chat";
+import { chatModule } from "./chat-module";
+import { renderPanel } from "./panel";
+
+const button = document.querySelector("#chat-launcher");
+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;
+  };
+};
+
+button.addEventListener("click", () => {
+  if (close) {
+    close();
+  } else {
+    open();
+  }
+});
+```
+
+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: 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.
+
+`src/tests/chat-widget-example.test.ts` checks the same points without a browser.
+
+## Where to go next
+
+- Show an unread count on the launcher while the chat is closed: a second module that stays mounted and listens only to `chat/messageAdded`.
+- 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/vue.md
 
@@ -4281,7 +4832,7 @@ Library fields (`signal`, `emit`, `run`, …) win on name clashes. `context` may
 
 To get `race`, `all`, `take` and the like on every task without passing `ctx`, see [`effectsPlugin`](effects.md#put-selected-effects-on-ctx).
 
-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](scope.md).
 
 ## Type the fields (optional)
 
@@ -4305,6 +4856,38 @@ bus.on("save", (draft, { store }) => store.put(draft));
 - A name that the bus already has is a type error. The fields of the library (`signal`, `emit`, `run`, …) win at runtime, and a field that the context already has is not replaced.
 - The plugin returns the same bus, so keep the result of the chain: `const bus = createBus().use(contextPlugin({ store }))`.
 
+## Build a field from the signal of each task
+
+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.
@@ -4329,6 +4912,18 @@ A **scope** is a plain object. Every key goes on `ctx` as it is (`cache`, `api`,
 
 You give a scope to the thing that uses it. A call can replace it. Nothing else changes: handlers still get `(payload, ctx)`.
 
+## On this page
+
+- [Turn scopes on](#turn-scopes-on)
+- [Give an action its own fields](#give-an-action-its-own-fields)
+- [Bind an effect to the task](#bind-an-effect-to-the-task)
+- [Replace a field for one call](#replace-a-field-for-one-call)
+- [Give an action, a job or a module its own fields](#give-an-action-a-job-or-a-module-its-own-fields)
+- [Which value wins](#which-value-wins)
+- [Keep a generic effect generic](#keep-a-generic-effect-generic)
+- [Type the fields (optional)](#type-the-fields-optional)
+- [Limits](#limits)
+
 ## Turn scopes on
 
 Scopes are a plugin, so a bus that does not use them pays nothing.
@@ -4359,7 +4954,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() },
@@ -4508,7 +5103,7 @@ 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` |
 
@@ -4602,6 +5197,23 @@ Use this page when **your domain logic lives in classes**: a service, a store or
 
 If your logic is plain functions, stay with [modules](actions.md#mount-domains-with-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
 
 A class that listens to the bus keeps a reference to it, and keeps every unsubscribe function in a list to call when the object goes away. Forget one and the old object keeps handling events. `extendBus` does both for you.
@@ -4903,7 +5515,7 @@ export const SearchService = extendBus(bus, SearchServiceBase);
 
 Things to know:
 
-- The event is a name, an action creator or a command, as for `bus.on`. For a creator or a command the payload of the method is checked against it.
+- The event is a name or an action creator, as for `bus.on`. For a creator the payload of the method is checked against it.
 - The second argument, `wrap`, takes the bound handler and returns the one to subscribe: `latest`, or `(handler) => debounce(300, handler)`. A policy needs it: `latest(this.search)` wraps the function without `this`, and the bound handler is what `wrap` gets.
 - The subscriptions are made right after the constructor of `Base`. An event that is emitted inside that constructor does not reach them.
 - A subclass inherits them. A method that a subclass overrides is subscribed only if the override is decorated.
@@ -5032,7 +5644,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);
 });
@@ -5282,6 +5894,17 @@ Source: docs/migrating-from-effector.md
 
 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 |
@@ -5912,6 +6535,16 @@ Source: docs/semantics.md
 
 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.
@@ -5927,6 +6560,22 @@ Find out what your app did and why: which events were emitted, which calls a pol
 
 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)
+  - [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.
@@ -6009,7 +6658,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.
 
@@ -6037,8 +6686,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
 ```
 
@@ -6055,9 +6704,9 @@ Every event of a task below another one has `rootId`, the id of the root of the
 
 **Problem.** A flow such as a checkout has several roots (a click, a timer, a store) and many branches. Parent ids give a tree, but you want to filter the log by the flow.
 
-**When.** One business flow runs through several commands, and you read the log by flow.
+**When.** One business flow runs through several actions, and you read the log by flow.
 
-Give the flow a `traceGroupId` in the scope of the command, the job or the action that starts it. Every task that it starts through `ctx.emit` or `ctx.run` has the same `traceGroupId`, and so does every trace event of those tasks. A task that declares its own `traceGroupId` uses it for itself and for what it starts.
+Give the flow a `traceGroupId` in the scope of the action or the job that starts it. Every task that it starts through `ctx.emit` or `ctx.run` has the same `traceGroupId`, and so does every trace event of those tasks. A task that declares its own `traceGroupId` uses it for itself and for what it starts.
 
 ```js
 import { createBus } from "nanoeffects";
@@ -6078,7 +6727,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`.
@@ -6108,7 +6757,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
 ```
 
@@ -6125,7 +6774,7 @@ The names work wherever an event or a listener is made:
 | A listener, `bus.on` and `bus.once` | `{ traceId }` as the third argument |
 | A listener of a module or of an instance of `extendBus` | the same third argument of its `on` and `once` |
 | A method with `@On` or `@Once` | `{ traceId }` in the decorator |
-| A command, a job or an action | `traceGroupId` in its scope |
+| An action or a job | `traceGroupId` in its scope |
 
 ## Turn the names off
 
@@ -6153,7 +6802,7 @@ 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)) |
 
 ### Cut volume in production
 
@@ -6169,8 +6818,60 @@ 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.
 
+### 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:
@@ -6270,6 +6971,8 @@ Source: docs/observable.md
 
 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
@@ -6413,6 +7116,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 |