nanoeffects 0.27.0 → 0.28.0

package/docs/actions.md

@@ -326,7 +326,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).

package/docs/chat-example.md

@@ -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` 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.
 
@@ -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");
 ```
 
@@ -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, 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/guide.md

@@ -31,7 +31,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";

package/docs/oop.md

@@ -310,7 +310,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.

package/docs/package.md

@@ -12,7 +12,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `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/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve`, `Subject` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |

package/docs/starter.md

@@ -46,7 +46,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 |
 
@@ -94,13 +94,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
 

package/docs/tracing.md

@@ -132,9 +132,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";
@@ -202,7 +202,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
 

package/llms-full.txt

@@ -48,7 +48,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";
@@ -563,7 +563,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 +611,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
 
@@ -706,7 +706,7 @@ Imports are split so you only load what you use. `createBus` stays small; the re
 | `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/scope` | `scopePlugin`, `effect`: fields for one action, job, module or `emit` (the types `Scope`, `Effect`) |
 | `nanoeffects/redux` | `createEffectsMiddleware` |
 | `nanoeffects/observable` | `createObserve`, `Subject` |
 | `nanoeffects/react` | `reactPlugin`: adds the `useEmitter` hook to a bus (needs React 18 or newer) |
@@ -2476,7 +2476,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).
@@ -3867,7 +3867,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 +3883,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 +4014,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 +4066,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. |
+
+## 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.
+
 ---
 Source: docs/vue.md
 
@@ -4903,7 +5042,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.
@@ -6055,9 +6194,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";
@@ -6125,7 +6264,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
 

package/llms.txt

@@ -38,6 +38,7 @@ Rules that generated code often gets wrong:
 - [Stop work on a server when the client leaves](docs/server.md): one `AbortController` for each request or socket, `signalPlugin`, a clean shutdown, and a queue worker; Fastify examples
 - [Build a sign-up form in React](docs/react.md): a form with a username check, a submit that cannot fire twice, and retry; `useEventState` shows an event as state, `usePolicy` keeps a debounced handler between renders
 - [Build a chat with entities, features, modules and a small server](docs/chat-example.md): rooms, a history under `latest`, a send under `queue` and `retry`, a search with `allSettled` and `timeout`, new messages polled with `poll`
+- [Build a chat widget that listens only while it is open](docs/chat-widget.md): a bot widget for a site; opening mounts a module (handlers, polling, Escape), closing unmounts it and aborts running requests
 - [Use nanoeffects in a Vue app](docs/vue.md): `vuePlugin` adds `watchEmitter` (a value of a component to the bus) and `useEventRef` (an event as a ref)
 - [Use nanoeffects in a Svelte app](docs/svelte.md): `sveltePlugin` adds `eventStore` (an event as a Svelte store)
 - [Context fields](docs/context.md): put a store or client on every task

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "nanoeffects",
-	"version": "0.27.0",
-	"description": "Cancel stale async work and fix race conditions in event handlers: a typed event bus where every handler is a task with an AbortSignal, plus latest, debounce, throttle, queue, retry, timeout and poll. About 1.4 kB gzip.",
+	"version": "0.28.0",
+	"description": "Business logic and side effects outside UI components, as plain async functions. Tiny, no dependencies.",
 	"keywords": [
 		"event-bus",
 		"event-emitter",
@@ -226,7 +226,7 @@
 		{
 			"name": "actions (all)",
 			"path": "dist/actions.js",
-			"limit": "3.3 kB"
+			"limit": "3.31 kB"
 		},
 		{
 			"name": "match (plugin)",

package/dist/bus-DQDHUN5e.js

@@ -1 +0,0 @@
-import{d as e,n as t,o as n,r}from"./context-UcmrAIhP.js";import{n as i}from"./promise-CSLpzwSR.js";import{n as a,t as o}from"./event-0RIBGYqS.js";const s=()=>{let e={},t={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()};return{get:n=>(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]),add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>{r(e,t)}},remove:r,clear:()=>{e={},t={}}}},c=Symbol(),l=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,c,{value:e,enumerable:!1}),r},u=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&c in e)return e[c]},d=(e,t,n)=>Reflect.apply(e,null,[t,n]),f=(c={})=>{let l=s(),f=(e,t)=>l.add(o(e),t),p=(e,t)=>{let n=f(e,(e,r)=>(n(),t(e,r)));return n},m=(e,t)=>{e===void 0?l.clear():l.remove(o(e),t)},h=(n,a)=>{let{onError:o}=c,{ctx:s}=t({event:a,bus:g,tracer:c.trace,parent:{ref:r()}});if(!o){n(a.payload,s);return}let l=t=>{try{o(t,a)}catch(t){e(`onError failed`,t)}};try{let e=n(a.payload,s);i(e)&&Promise.resolve(e).catch(l)}catch(e){l(e)}},g={on:f,once:p,off:m,emit:(e,i)=>{let s=o(e),f=a(e,i),p={type:s,payload:f},m=u(e);m||=g.actions?.bound?.(s);let _=[...l.get(s),...l.get(`*`)];_.length===0&&!m&&c.onUnhandled?.(p);for(let e of _)h(e,p);if(m){let{ctx:e}=t({event:p,bus:g,tracer:c.trace,parent:{ref:r()}}),i=g.actions?.run??d;return n(e,`command`,()=>i(m,f,e))}},use:e=>e(g),ctx:c.context,trace:c.trace};return g};export{f as n,l as r,u as t};

package/dist/event-0RIBGYqS.js

@@ -1 +0,0 @@
-const e=e=>typeof e==`string`?e:e.type,t=(e,t)=>typeof e==`object`?e.payload:t;export{t as n,e as t};

package/dist/notrace/bus-CGi2lrd5.js

@@ -1 +0,0 @@
-import{a as e,l as t,n,r}from"./context-_HWcdjZf.js";import{n as i}from"./promise-CSLpzwSR.js";const a=e=>typeof e==`string`?e:e.type,o=(e,t)=>typeof e==`object`?e.payload:t,s=()=>{let e={},t={},n=n=>(t[n]=void 0,e[n]??=/* @__PURE__ */ new Map,e[n]),r=(e,t)=>{let r=n(e),i=r.get(t)??0;i>1?r.set(t,i-1):t?r.delete(t):r.clear()};return{get:n=>(t[n]??=[...e[n]??[]].flatMap(([e,t])=>Array(t).fill(e)),t[n]),add:(e,t)=>{let i=n(e);return i.set(t,(i.get(t)??0)+1),()=>{r(e,t)}},remove:r,clear:()=>{e={},t={}}}},c=Symbol(),l=(e,t,n)=>{let r={type:t,payload:n};return Object.defineProperty(r,c,{value:e,enumerable:!1}),r},u=e=>{if(typeof e==`function`)return e;if(typeof e==`object`&&e&&c in e)return e[c]},d=(e,t,n)=>Reflect.apply(e,null,[t,n]),f=(c={})=>{let l=s(),f=(e,t)=>l.add(a(e),t),p=(e,t)=>{let n=f(e,(e,r)=>(n(),t(e,r)));return n},m=(e,t)=>{e===void 0?l.clear():l.remove(a(e),t)},h=(e,a)=>{let{onError:o}=c,{ctx:s}=n({event:a,bus:g,tracer:c.trace,parent:{ref:r()}});if(!o){e(a.payload,s);return}let l=e=>{try{o(e,a)}catch(e){t(`onError failed`,e)}};try{let t=e(a.payload,s);i(t)&&Promise.resolve(t).catch(l)}catch(e){l(e)}},g={on:f,once:p,off:m,emit:(t,i)=>{let s=a(t),f=o(t,i),p={type:s,payload:f},m=u(t);m||=g.actions?.bound?.(s);let _=[...l.get(s),...l.get(`*`)];_.length===0&&!m&&c.onUnhandled?.(p);for(let e of _)h(e,p);if(m){let{ctx:t}=n({event:p,bus:g,tracer:c.trace,parent:{ref:r()}}),i=g.actions?.run??d;return e(t,`command`,()=>i(m,f,t))}},use:e=>e(g),ctx:c.context,trace:c.trace};return g};export{l as n,a as r,f as t};

package/dist/notrace/promise-CSLpzwSR.js

@@ -1 +0,0 @@
-const e=e=>typeof e!=`object`||!e?!1:`then`in e&&typeof e.then==`function`,t=(t,n)=>e(t)?Promise.resolve(t).finally(n):(n(),t);export{e as n,t};