nanoeffects 0.26.0 → 0.28.0

package/docs/README.md

@@ -2,9 +2,9 @@
 
 ## Start here
 
-The [Guide](guide.md) is the ladder: small bus → policies for async UI → effects when you need them → commands and modules for domain logic off the UI.
+The [Guide](guide.md) is the ladder: small bus → policies for async UI → effects when you need them → handlers and modules for domain logic off the UI.
 
-Why the library exists, and when to pick it over Redux, Effector or RxJS (SDKs, shared libraries, Module Federation): [Why nanoeffects exists](motivation.md).
+Why the library exists (logic and side effects outside React, Vue and Svelte components, as plain `async` functions), and when to pick it over redux-saga, RxJS, Redux or Effector (including SDKs and Module Federation): [Why nanoeffects exists](motivation.md).
 
 Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-checked and tested).
 
@@ -15,10 +15,11 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 | Small app / widget (rare races) | [Guide § Create a bus](guide.md#1-create-a-bus) |
 | SPA with async UI | [Policies](policies.md), [Guide § latest](guide.md#3-abort-the-previous-run-with-latest) |
 | Unreliable network / long flows | [Effects](effects.md) — one helper per job, then the rest as reference |
-| Domain logic off the UI | [Actions, commands, modules](actions.md) |
+| Domain logic off the UI | [Actions, handlers, modules](actions.md) |
 | Already on Redux / Zustand / MobX / Pinia | [Stores](stores.md) |
 | A Node server (Fastify) whose work must stop when the client leaves | [Stop work on a server](server.md) |
 | A React form with async checks | [Build a sign-up form in React](react.md) |
+| A site widget that listens only while open | [Build a chat widget](chat-widget.md) |
 | A Vue app | [Use nanoeffects in a Vue app](vue.md) |
 | A Svelte app | [Use nanoeffects in a Svelte app](svelte.md) |
 | Old responses overwrite new ones | [Cancel stale requests](cancel-stale-requests.md) |
@@ -33,7 +34,7 @@ Code for every guide step: [`examples/guide.ts`](../examples/guide.ts) (type-che
 
 - [Policies](policies.md) — `latest`, `leading`, `debounce`, `throttle`, `queue`, `key`
 - [Effects and cancellation](effects.md) — `retry`, `timeout`, `poll`, `take`, `all`, …
-- [Actions, commands, jobs and modules](actions.md)
+- [Actions, jobs and modules](actions.md)
 - [Sign-up form in React](react.md) — one form: races, double submit, retry
 - [nanoeffects in a Vue app](vue.md) — `watchEmitter` and `useEventRef`
 - [nanoeffects in a Svelte app](svelte.md) — `eventStore`

package/docs/actions.md

@@ -1,4 +1,4 @@
-# Actions, commands, jobs and modules
+# 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.
 
@@ -10,7 +10,9 @@ 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 command
+## 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.
 
 The bus lives in one file and its events in another, so any module can import both without a cycle.
 
@@ -24,10 +26,10 @@ export const bus = createBus();
 
 ```js
 // math.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-// createCommand — emit runs the handler and returns its result
-export const double = createCommand("math/double", (value) => value * 2);
+// createAction with a handler — emit runs the handler and returns its result
+export const double = createAction("math/double", (value) => value * 2);
 ```
 
 ```js
@@ -37,27 +39,24 @@ import { double } from "./math";
 bus.emit(double(21)); // 42
 ```
 
-## Describe events, commands, and jobs
+## Describe events, handlers and jobs
 
 `nanoeffects/actions` has the pieces to name what a bus does, apart from the code that does it.
 
 ```js
 // user.js
-import { createAction, createCommand, createJob } from "nanoeffects/actions";
+import { createAction, createJob } from "nanoeffects/actions";
 
-// createAction — event with a payload (like RTK createAction)
+// createAction — an event with a payload (like RTK createAction)
 export const userLoaded = createAction("user/loaded");
 export const loadFailed = createAction("user/failed");
 
-// createCommand with a handler — emit returns what the handler returns
-export const getUser = createCommand("user/get", (id, { signal }) => {
+// createAction with a handler — emit returns what the handler returns
+export const getUser = createAction("user/get", (id, { signal }) => {
   return fetchUser(id, { signal });
 });
 
-// createCommand without a handler — a contract; register the work elsewhere
-export const sendMail = createCommand("mail/send");
-
-// createJob — command that also emits success / fail actions
+// createJob — an action with a handler that also emits success / fail actions
 export const loadUser = createJob("user/load", fetchUser, {
   success: userLoaded,
   fail: "user/failed",
@@ -73,57 +72,99 @@ These are the events of the user domain, in a file of their own (`user.js`). The
 - `userLoaded(user)` → `{ type, payload }`
 - `userLoaded.type` — the type string
 - `userLoaded.match(action)` — narrows an action
-- `createAction(type, prepare)` — build the payload from several arguments
+- `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)
 - Works as the event of its type: `bus.emit(userLoaded(user))`, `bus.on(userLoaded, fn)`
 
-### Commands
+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 })`.
+
+- Wrap the handler in a policy: `createAction("search", latest(fn))`.
 
-Calling a command builds `{ type, payload }` like `createAction`. `bus.emit(command(payload))` (or `bus.emit(command, payload)`) tells the listeners of the command’s type, then runs its handler as a task and returns the result.
+An action with no handler is an event. Emitting it does not throw, and `onUnhandled` hears about it when nobody listens.
 
-- Wrap the handler in a policy: `createCommand("search", latest(fn))`.
-- `command.match(action)` narrows like an action creator’s `match`.
+### Bind a handler later
 
-**Where handlers are registered.** The command may carry a handler. The bus can also take handlers from a registry (`commandsPlugin`). A handler bound there wins over the command’s own. Each bus (each test) has its own registry.
+**Problem.** The work belongs to another layer, or a test must replace it. Putting the handler in `createAction` then ties the event file to the work.
+
+**When.** Use the registry when the handler is not known where the action is made. The action can have no handler at all; a handler bound to its type answers it. Each bus (each test) has its own registry.
+
+```js
+// mail.js
+import { createAction } from "nanoeffects/actions";
+
+// createAction without a handler — an event; the work is bound elsewhere
+export const sendMail = createAction("mail/send");
+```
 
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
-import { bindHandler, commandsPlugin } from "nanoeffects/actions";
-import { sendMail } from "./user";
+import { actionsPlugin, setHandler } from "nanoeffects/actions";
+import { sendMail } from "./mail";
 
 export const bus = createBus();
 
-// commandsPlugin — registry of handlers for this bus
-export const commands = bus.use(
-  commandsPlugin([bindHandler(sendMail, smtpSend)]),
+// actionsPlugin — the registry of handlers of this bus; setHandler pairs an action with its work
+export const actions = bus.use(
+  actionsPlugin([setHandler(sendMail, smtpSend)]),
 );
 ```
 
 ```js
-import { commands } from "./bus";
+import { actions } from "./bus";
 import { getUser } from "./user";
 
-// later, e.g. in a test — latest binding wins
-const unbind = commands.handle(getUser, async () => fakeUser);
+// later, e.g. in a test — the latest binding wins, a handler bound here wins over the one in createAction
+const unbind = actions.handle(getUser, async () => fakeUser);
 unbind();
 ```
 
-A command with no handler anywhere throws `No handler for command "..."` from `emit` (the call itself only builds the action).
+A handler bound in the registry makes `bus.emit(sendMail(mail))` run it and return its result, the same as for an action that carries its handler. The listeners of the type are told first. With no handler bound, `sendMail` is an event again.
+
+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
+
+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.
+
+```ts
+// mail.ts
+import type { Call } from "nanoeffects";
+import { createAction } from "nanoeffects/actions";
+
+// Call — payload Mail, a bound handler answers with a boolean (checker only; nothing runs differently)
+type Mail = { to: string };
+export const sendMail = createAction<Call<Mail, boolean>>("mail/send");
+```
+
+In an event map the same type does the job for string events, and `emit` returns `boolean`:
+
+```ts
+// events.ts
+import type { Call } from "nanoeffects";
+
+// Call in the map — the payload is checked, emit returns the result (checker only)
+export type Events = {
+  "user/getId": Call<void, string>;
+  "user/loaded": { id: string };
+};
+```
 
-The registry lives in `nanoeffects/actions`, so a bus without one carries none of that code. Without a registry, `emit` runs the command’s own handler. `bus.use(commandsPlugin())` sets `bus.commands`. A second `commandsPlugin` binds its list in that registry and returns it. There is no `commands` option in `createBus`; assign a custom runner with `bus.commands = { run }`.
+On a bus without an event map you can say it where you call: `const id = bus.emit<string>("user/getId")`. A bus with a map takes no such hint, so its names and payloads stay checked.
 
 ### Jobs
 
-`createJob(type, handler, { pending, success, fail, cancel })` makes a command that also sends its outcome as actions, when nobody waits for the result. It returns the command with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
+`createJob(type, handler, { pending, success, fail, cancel })` makes an action with a handler that also sends its outcome as actions, when nobody waits for the result. It returns the action with `loadUser.pending`, `loadUser.success`, `loadUser.fail` and `loadUser.cancel` on it.
 
 - When the handler starts, emits `loadUser.pending(payload)`.
 - On success, emits `loadUser.success(result)`.
 - On failure, emits `loadUser.fail(error)`.
 - When the task is aborted before the handler settles, emits `loadUser.cancel(reason)` instead of `success` or `fail`. After `pending`, exactly one of the three follows.
 - `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, use a command.
-- Outcome actions are emitted as the task that ran the job (also for a handler bound with `commands.handle`). `success` and `fail` are not sent after abort; `cancel` is, at the moment of the abort.
-- A missing handler is not an outcome: `emit` throws `No handler for command "..."` and nothing is sent.
+- `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.
 - 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.
 
@@ -147,7 +188,7 @@ export const bus = createBus();
 // user.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 loadUser = createJob("user/load", fetchUser);
 ```
 
@@ -202,18 +243,18 @@ A flag is exact when calls do not overlap, or when `latest` replaces them. If se
 
 ## Mount domains with modules
 
-**Problem.** A domain needs several subscriptions and command bindings. With plain `bus.on` / `commands.handle` you must remember every unsubscribe.
+**Problem.** A domain needs several subscriptions and handler bindings. With plain `bus.on` / `actions.handle` you must remember every unsubscribe.
 
 **When.** You want one mount / one unmount for that domain. Skip modules while a few top-level `bus.on` calls are enough.
 
-`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `commands`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
+`bus.use(modulePlugin(modules))` assembles an app from modules and returns `mount`, `unmount`, `isMounted`, `dispose`, `actions`, and `createModule`: the same as `createModule` below, with the context fields of the bus typed (see [TypeScript](typescript.md)).
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-export const getUser = createCommand("user/get");
-export const saveUser = createCommand("user/save", persistUser);
+export const getUser = createAction("user/get");
+export const saveUser = createAction("user/save", persistUser);
 ```
 
 ```js
@@ -250,7 +291,7 @@ import { app } from "./bus";
 import { getUser } from "./user";
 
 const unmount = app.mount(orderModule); // later, e.g. after a lazy import
-app.commands.handle(getUser, fakeUser); // in a test
+app.actions.handle(getUser, fakeUser); // in a test
 app.dispose(); // unmounts every module
 ```
 
@@ -281,37 +322,37 @@ app.unmount(...modules); // also in reverse order
 
 If the `setup` of one module throws, the modules of that call that were already mounted are unmounted again and the error is thrown, so a call mounts all of its modules or none. A module that is mounted already is skipped.
 
-- **Unmounting undoes everything** the module did: subscriptions, bound commands, sub-modules, and background tasks (aborted).
+- **Unmounting undoes everything** the module did: subscriptions, bound handlers, sub-modules, and background tasks (aborted).
 - **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(commandsPlugin())` ran first, that registry is used; otherwise the module plugin attaches its own. Either way it is `bus.commands` and `app.commands`.
+- **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 a command a handler (contract, or override).
-  - `use` — bring sub-modules and commands that carry a handler; the returned function undoes that call.
+  - `handle` — give an action a handler (one that has none, or an override).
+  - `use` — bring sub-modules and actions that carry a handler; the returned function undoes that call.
   - `spawn` — background task, aborted on unmount.
-- A command 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.
+- 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 a command, an action or a module its own fields
+## Give an action or a module its own fields
 
-A command 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 `createCommand`, `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`, `createAction`, `createModule` and `createJob`, and turn it on with `scopePlugin`:
 
 ```js
 // bus.js
 import { createBus } from "nanoeffects";
 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
 export const bus = createBus().use(scopePlugin());
 ```
 
 ```js
 // user.js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 
-// the third argument — fields of this command only
-export const getUser = createCommand(
+// the third argument — fields of this action only
+export const getUser = createAction(
   "user/get",
   (id, { api }) => api.getUser(id),
   { api },

package/docs/chat-example.md

@@ -2,7 +2,7 @@
 
 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, commands, 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.
+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.
 
 The code is in [`examples/chat`](../examples/chat). Run it on [StackBlitz](https://stackblitz.com/github/nanoeffects/nanoeffects/tree/main/examples/chat), or on your machine:
 
@@ -48,7 +48,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`) says that something happened, and any feature may listen: `rooms/selected` is heard by two. A command (`createCommand`) is an order with exactly one handler, as `search/openResult` and `messages/mark` are. The handler is given to `createCommand`, 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.
 
@@ -64,7 +64,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");
 ```
 
@@ -179,11 +179,11 @@ export const runSearch = debounce(
 `take` waits for the next event of a name. Start it before the emit that causes the event, so nothing is missed:
 
 ```js
-import { createCommand } from "nanoeffects/actions";
+import { createAction } from "nanoeffects/actions";
 import { take } from "nanoeffects/effects";
 
-// createCommand — an order for the message entity, with the handler that does it
-const markMessage = createCommand("messages/mark", (messageId) => console.log("mark", messageId));
+// createAction with a handler — an order for the message entity, with the handler that does it
+const markMessage = createAction("messages/mark", (messageId) => console.log("mark", messageId));
 
 // the room that is open, kept from the rooms/selected event
 let selectedRoom = "general";
@@ -195,7 +195,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));
 };
 ```
@@ -247,6 +247,6 @@ 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, commands, 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.

package/docs/chat-widget.md

@@ -0,0 +1,135 @@
+# 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. |
+
+## 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. The launcher puts it together with the one that removes the panel.
+
+<!-- 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);
+  close = () => {
+    stopPanel();
+    stopModule(); // everything the module started ends, a running request included
+    close = null;
+  };
+};
+
+button.addEventListener("click", () => {
+  if (close) {
+    close();
+  } else {
+    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`.
+
+## 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.
+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.

package/docs/context.md

@@ -15,7 +15,7 @@ bus.on("save", (draft, { store }) => {
 });
 ```
 
-That is enough in JavaScript. The fields appear on handlers, `ctx.run`, `ctx.on`, commands, modules, and child tasks of effects and policies.
+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.
 

package/docs/errors.md

@@ -21,7 +21,7 @@ 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 commands, 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 actions, which always have a handler to run.
 
 Use it as a warning in development: