flexdesk 0.17.18 → 0.18.1

package/docs/README.md

@@ -8,7 +8,7 @@ New here? Start with the [quickstart](quickstart.md). The [README](../README.md)
 
 ## Packages
 
-FlexDesk is nine entry points that share their code, so you load only what you use. [Packages and entry points](concepts/packages-and-entry-points.md) has the sizes and the reasoning.
+FlexDesk is ten entry points that share their code, so you load only what you use. [Packages and entry points](concepts/packages-and-entry-points.md) has the sizes and the reasoning.
 
 | Entry | What is in it | Read |
 |---|---|---|
@@ -21,6 +21,7 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 | `@flexdesk/editor` | Monaco loader, editor factory, tab bar, search, split panes | [Editor](components/editor.md) |
 | `@flexdesk/canvas` | The canvas kernel: a pannable, zoomable surface, the edge router, a graph layer | [Flow canvas editor](components/flow-canvas-editor.md) |
 | `@flexdesk/flow` | The flow-editor kit and the canvas, outline and lane editors | [Flow editors and the flow kit](components/flow-editors.md) |
+| `@flexdesk/git` | A source-control panel, a commit graph and a diff viewer, over a written adapter contract | [Git panel, commit graph and diff viewer](components/git.md) |
 
 ## Components
 
@@ -48,8 +49,10 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 - [Forms and dialogs](components/forms-and-dialogs.md): `openForm`, `openConfirm`, and every field type.
 - [Settings page](components/settings-view.md): a settings store's schema drawn as a page.
 - [Wizard](components/wizard.md): a multi-step flow, inline or in a window.
-- [Input fields: slider and tags](components/input-fields.md): `SliderField` and `createTagInput`.
-- [Menus](components/menus.md): `createMenuBar`, `ActionDropdown` and `CategoryPicker`.
+- [Input fields: slider, tags, select and combobox](components/input-fields.md): `SliderField`, `createTagInput`, `createSelect` and `createCombobox`.
+- [Filter builder](components/filter-builder.md): recursive AND/OR/NOT filters: the model, a mountable builder, a dialog, and the condition tree a server compiles.
+- [Menus](components/menus.md): `createMenuBar`, `ActionDropdown`, `CategoryPicker`, `openPopover` and `positionAnchored`.
+- [Workspace picker](components/workspace-picker.md): the top-bar field, its switcher and the recent-items store.
 
 ### Layout, content and feedback
 
@@ -59,6 +62,7 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 - [Slide-out panel](components/slide-out-panel.md): `SlideOutPanel`, an inline panel that slides in over its host.
 - [Markdown and document outline](components/markdown-and-outline.md): `renderMarkdown` and `createDocumentOutline`.
 - [Conversation view](components/conversation.md): a transcript above a composer.
+- [Assistant chat shell](components/chat-shell.md): `mountChatShell`, tabs, a model picker and streaming replies over a thin transport.
 - [Notifications and progress](components/notifications.md): toasts, history, the alert log, progress bars, lists and phases.
 
 ### Charts, editor and dashboards
@@ -66,6 +70,7 @@ FlexDesk is nine entry points that share their code, so you load only what you u
 - [Charts](components/charts.md): `@flexdesk/charts`, on Plotly.
 - [Editor](components/editor.md): `@flexdesk/editor`, on Monaco.
 - [Dashboard tiles](components/tiles.md): `@flexdesk/tiles`, a draggable widget grid.
+- [Git panel, commit graph and diff viewer](components/git.md): `@flexdesk/git`, over a written adapter contract that any backend can implement.
 
 ### Flow editors
 
@@ -82,7 +87,7 @@ These have no page of their own: `ManagedWindow`, modals, `TreeView`, context me
 
 ## Concepts
 
-- [Packages and entry points](concepts/packages-and-entry-points.md): the nine entries, what they weigh, and why they are separate.
+- [Packages and entry points](concepts/packages-and-entry-points.md): the ten entries, what they weigh, and why they are separate.
 - [Host port](concepts/host-port.md): how FlexDesk reaches storage, dialogs and native windows without touching them.
 - [Domain neutrality](concepts/domain-neutrality.md): storage keys, theme names and MIME types are yours; no application globals.
 - [State guard](concepts/state-guard.md): who wrote that `data-*` attribute.

package/docs/best-practices.md

@@ -8,7 +8,7 @@ The rules the reference pages state, gathered in one place. Each item says what
 
 **2. Start with the smallest host.** Pass `createHost` only the capabilities you have. A capability you leave out is absent and the library degrades instead of throwing: no native window buttons without `window`, a Blob download for CSV without `dialogs`. An in-memory `Map` is a perfectly good `state`, and `NULL_HOST` is a valid host with nothing behind it. See [the host port](concepts/host-port.md#the-host-port).
 
-**3. Load every entry from one copy.** The entries share code through chunks, so importing several does not give you several event buses or several copies of a module-level singleton. Keep it that way: map all entries to the same install or the same import map, rather than mixing a vendored `dist/` with a second bundled copy. See [packages and entry points](concepts/packages-and-entry-points.md#nine-entry-points).
+**3. Load every entry from one copy.** The entries share code through chunks, so importing several does not give you several event buses or several copies of a module-level singleton. Keep it that way: map all entries to the same install or the same import map, rather than mixing a vendored `dist/` with a second bundled copy. See [packages and entry points](concepts/packages-and-entry-points.md#ten-entry-points).
 
 **4. Name your storage before anything reads it.** Every key FlexDesk writes is an option, with a generic default. Set them at boot, before the first read. Tile layouts are the sharp edge: the store is a singleton, and one built before you supply your key uses the default, so every layout your users saved becomes silently invisible, with no error. If users already have data under older keys, pass those keys explicitly and nothing is lost. See [storage keys and names](concepts/domain-neutrality.md#storage-keys-and-names-are-yours-0170) and [layouts are keyed by whatever you key them by](components/tiles.md#layouts-are-keyed-by-whatever-you-key-them-by).
 
@@ -36,7 +36,7 @@ The rules the reference pages state, gathered in one place. Each item says what
 
 **14. Restyle through the tokens.** Every rule reads its values from `tokens.css`, so swapping that one file restyles the shell. Library classes are `twm-` prefixed, and that prefix is stable; the editor components and the help modal keep the class names they were extracted with. Supply the icon font, or accept that icons show their text names. See [theming and CSS](concepts/styling.md#styling).
 
-**15. Run the state guard strictly in your own code.** `StateGuardService` defaults to `mode: 'warn'`. FlexDesk's own widgets run clean under `'strict'`, so choose strict for your code and add your application's keys on top of `DEFAULT_STATE_GUARD_CONFIG`: a key you write that no FlexDesk widget does is yours to list. The defaults also still allow some keys that no widget writes, which a strict guard lets through unless you filter them out ([what 0.18.0 removed and what stayed](concepts/state-guard.md#thirteen-application-keys-leave-the-defaults-0180)). See [state guard](concepts/state-guard.md#the-state-guard-who-wrote-that-attribute-0170) and [the default allow-list](concepts/state-guard.md#the-defaults-cover-flexdesks-own-keys-0170).
+**15. Run the state guard strictly in your own code.** `StateGuardService` defaults to `mode: 'warn'`. FlexDesk's own widgets run clean under `'strict'`, so choose strict for your code and add your application's keys on top of `DEFAULT_STATE_GUARD_CONFIG`: a key you write that no FlexDesk widget does is yours to list. The defaults also still allow some keys that no widget writes, which a strict guard lets through unless you filter them out ([what 0.17.14 removed and what stayed](concepts/state-guard.md#thirteen-application-keys-leave-the-defaults-01714)). See [state guard](concepts/state-guard.md#the-state-guard-who-wrote-that-attribute-0170) and [the default allow-list](concepts/state-guard.md#the-defaults-cover-flexdesks-own-keys-0170).
 
 **16. Dispose what you create.** `shell.dispose()` removes the `?` shortcut and the desktop bar along with the rest of the shell. A `NotificationCenter`'s `dispose()` hands the toast helpers back. Menu bars, tables and lists have `dispose()` too.
 

package/docs/components/charts.md

@@ -414,6 +414,10 @@ config it was given and then calls `onChange(config)`.
   is disposed. A `dispose()` that throws is reported to `logger.warn` and does
   not stop the rest of the editor being disposed.
 
+- [`hide`](#hiding-parts-of-the-editor-hide-0181) takes parts of the editor away,
+  and [`constantsProvider`](#a-reference-line-that-names-a-constant-constantsprovider-resolveconstant-0181)
+  lets a reference line name a constant.
+
 It returns `{ dispose, refresh, selectSubplot, activeSubplot }`: `dispose()`
 disposes every field it created (every `AutocompleteField` among them) and
 removes the editor; `refresh()` redraws it after the config was changed from
@@ -431,3 +435,39 @@ const win = await openPlotPopoutWindow({ id, title, plotConfig, getResults, serv
 
 Its classes are under `.twm-plot-config` in `flexdesk.css`.
 `tests/plot_config_editor.test.mjs` pins all of it.
+
+## Hiding parts of the editor: `hide` (0.18.1)
+
+An embedder whose plots are always 2D time series has no use for some of the editor:
+
+```js
+renderPlotConfigEditor(el, plotConfig, { hide: ['3d', 'stackGroup', 'xAxis'] });
+```
+
+| Name | What goes |
+|---|---|
+| `'3d'` | The 3D chart types and the z axis section. A subplot saved as 3D keeps its chart type, marked as one the list does not offer, until someone picks a 2D one. |
+| `'stackGroup'` | Each series' stack group box. A saved stack group stays in the config and is drawn. |
+| `'xAxis'` | The x axis section. The subplot then plots against time: `xAxis.useTime` is set to true when it opens, and `xAxis.variable` is left as it was. |
+
+Any other name throws. Without `hide` the editor draws what it always did.
+
+## A reference line that names a constant: `constantsProvider`, `resolveConstant` (0.18.1)
+
+A reference line's value is a number, so it cannot follow a parameter whose value changes between runs. With `constantsProvider` it may also name one:
+
+```js
+renderPlotConfigEditor(el, plotConfig, {
+    constantsProvider: () => [{ name: 'bank.rate', value: 0.25, label: 'Bank rate', group: 'bank' }],
+});
+renderPlotGrid(host, plotConfig, results, {
+    resolveConstant: (name) => constants.get(name),   // a number, or undefined
+});
+```
+
+The value box then offers the names, with their values and under their groups, as `attachInputOptions` does. It is asked each time the list is drawn. What is stored is a number when what was typed is one, even when it is part of a name on the list, and the name as a string otherwise; beside a name it knows, the box shows `= 0.25`. An empty box stores `null`, as the number box does. A click shows every name.
+
+`renderPlotGrid` asks `resolveConstant(name)` each time it draws a subplot, so a redraw follows a new value, and `grid.update({ results })` is enough. A name it does not know draws no line and no label, and so does any name without `resolveConstant`. The config keeps the name.
+
+Without `constantsProvider` the box is the number box it always was.
+

package/docs/components/chat-shell.md

@@ -0,0 +1,204 @@
+# Assistant chat shell
+
+> **Package:** `@flexdesk/widgets` · [All docs](../README.md)
+
+A whole assistant chat over the [conversation view](conversation.md): conversation tabs, an optional mode toggle, a model picker, a reply that streams, Markdown bodies, time and copy on every message, and a slot for your own controls. It knows no provider and nothing of what a reply is about.
+
+## An assistant chat: `mountChatShell` (0.18.0)
+
+```js
+import { mountChatShell } from '@flexdesk/widgets';
+
+const chat = mountChatShell(el, {
+    transport: {
+        send(request, emit) { backend.ask(request, (e) => emit(toChatEvent(e))); },
+        cancel(request)     { backend.stop(); },
+    },
+    modes: [{ id: 'ask', label: 'Ask' }, { id: 'act', label: 'Act' }],
+    models: { items: [{ id: 'large', label: 'Large' }, { id: 'small', label: 'Small' }], activeId: 'large' },
+    onModelSelect: (item) => chat.setModels({ activeId: item.id }),
+    renderControls: (el, message) => drawMyControls(el, message.meta),
+    conversations: JSON.parse(localStorage.getItem('chat') ?? 'null'),
+    onChange: (snapshot) => localStorage.setItem('chat', JSON.stringify(snapshot)),
+    placeholder: 'Ask anything',
+    welcome: { icon: 'smart_toy', text: 'What can I help you with?' },
+});
+```
+
+The chat fills its host. It needs `flexdesk.css`, and the Material Symbols font for its icons.
+
+| Option | Is |
+|---|---|
+| `transport` | **Required.** `{ send(request, emit), cancel?(request) }`; `cancel` may answer a promise, see [below](#a-backend-with-no-run-id) |
+| `renderControls(el, message, chat)` | Fills the slot on an assistant message |
+| `markdown` | Options for [`renderMarkdown`](markdown-and-outline.md) (`highlight`, `math`, `inlineRules`, ...) |
+| `onChange(snapshot)` | Something worth keeping changed: a message arrived or finished, a conversation or its meta changed. Not called per text delta |
+| `onConversationChange(conversation, reason)` | Another conversation is in front; `reason` is `new`, `switch`, `close` or `reset`. `conversation` is `{ id, title, conversationId, messages }` |
+| `modes`, `mode`, `onModeChange(id)` | `[{ id, label, title? }]`. The labels are yours. No modes, no toggle |
+| `models`, `onModelSelect(item)`, `onModelAction(action, item)` | See [The model picker](#the-model-picker) |
+| `conversations` | A `snapshot()` to restore |
+| `titleFrom(text)` | A new conversation's title, from its first message. Default: the first 30 characters |
+| `formatTime(at, message)` | A message's time; `''` shows none. Default: the locale's hours and minutes |
+| `placeholder`, `welcome: { icon?, text }` | The composer's placeholder; what an empty transcript shows |
+| `labels` | Over `CHAT_SHELL_LABELS`, every text the chat shows |
+| `eventBus`, `logger` | `eventBus` gets `CHAT_BUS_EVENTS` |
+
+### The transport
+
+`send(request, emit)` starts a turn. A request is `{ text, tabId, conversationId, mode, model }`: `tabId` is the conversation's tab, `conversationId` is your backend's id (`null` until you give one), `model` is the picker's `activeId`.
+
+`emit` takes normalised events, one at a time (`CHAT_TRANSPORT_EVENTS`):
+
+| Event | Does |
+|---|---|
+| `{ type: 'text-delta', text }` | Adds to the reply, which re-renders |
+| `{ type: 'tool-use', id?, name, label?, status? }` | Lists a tool call under the reply, or updates the one with that `id`. `status` is `running` (the default), `done` or `error`; `label` is shown instead of `name` |
+| `{ type: 'message-end', text?, conversationId?, meta? }` | Ends the turn. `text` fills the reply only if nothing was streamed; `conversationId` is kept; `meta` is merged into the message's |
+| `{ type: 'error', message }` | Ends the turn with an error message in the transcript |
+
+Every `emit` belongs to its turn, and what it is handed after that turn ended or was cancelled is dropped. A `send` that throws, or answers a promise that rejects, is an `error` event. To tell the chat a backend id before the turn ends, call `setConversationId(request.tabId, id)`.
+
+So a transport that gives each run its own callback, and calls that run's `emit`, needs no filtering of its own.
+
+#### A backend with no run id
+
+A backend that pushes to a global has one place to send a frame, and the frame does not say which run it is from. The adapter holds the latest `emit`, so the chat cannot tell an old run's chunk from the new reply's. Runs must therefore not overlap, and `cancel` is how: it answers a promise that settles when the cancelled run is over and the backend takes a new request. The next turn shows at once, with its typing dots, and its `send` is called when the promise settles. A promise that rejects is logged and counts as settled. One that never settles, or a run-over that is lost, holds the next turn only until the user stops it: [Stop releases a turn that is waiting](#stop-releases-a-turn-that-is-waiting-0181).
+
+```js
+let emit = null;
+let runEnded = null;
+const ended = () => { runEnded?.(); runEnded = null; };
+window.myBridge = {
+    onChunk: ({ chunk }) => emit?.({ type: 'text-delta', text: chunk }),
+    onDone: ({ text, id, changes }) => {
+        emit?.({ type: 'message-end', text, conversationId: id, meta: { changes } });
+        ended();
+    },
+    onError: ({ error }) => {
+        emit?.({ type: 'error', message: error });
+        ended();
+    },
+};
+const transport = {
+    async send(request, e) {
+        emit = e;
+        try {
+            const result = await api.ask(request);
+            if (!result.ok) throw new Error(result.error);
+        } catch (error) {
+            ended();
+            throw error;
+        }
+    },
+    cancel: () => new Promise((resolve) => {
+        runEnded = resolve;
+        api.stop();
+    }),
+};
+```
+
+While the run winds down, `emit` is still the cancelled turn's, so its late chunks and its report that it was cancelled are dropped, with no check of yours. The promise must not settle before the backend would accept a request: if the backend sends its last frame and only then frees itself, have it send the end of the run after that, and settle on that instead. A `cancel` that answers no promise says there is nothing to wait for, and `send` is called at once.
+
+#### Stop releases a turn that is waiting (0.18.1)
+
+A send made after a Stop waits for `cancel`'s promise. If that promise never settles, because the backend stalled or its run-over was lost, the turn shows its typing dots with nothing behind them. Stop on that turn releases the wait: it was never sent, so `transport.cancel` is not called for it, and the next send goes out at once.
+
+The person has then said twice that they will not wait, and the chat does what they ask. So a backend whose old run may still be alive can see a request while it runs. One that takes one run at a time should refuse the overlapping request: the refusal shows as an error with Retry. One that accepts it will mix the old run's frames into the new reply, because they arrive through the one `emit` the adapter holds.
+
+### A turn
+
+The user's message goes in, then a streamed assistant message that shows the typing dots while it is empty. While the turn runs, Send is Cancel and Esc cancels, as in the conversation view, and the New and Clear buttons are disabled. A turn ends in one of three ways:
+
+- **`message-end`.** Running tools become `done`. The message gets its controls, its time and its copy button.
+- **Stop.** Cancel, Esc or `chat.cancel()`. What arrived stays, running tools become `stopped`, and `transport.cancel(request)` is called once, unless the turn's `send` was still [waiting](#a-backend-with-no-run-id) and so never called. The chat can send again at once.
+- **`error`.** As Stop without `transport.cancel`, and an error message follows. While it is the last message it carries *Retry*, which sends the user message before it again.
+
+In all three, a reply left with no text, no tool call and no `meta` is taken out. `chat.isBusy()` answers at once.
+
+### Conversations
+
+The chat owns the tabs: one per conversation, with a close mark while there is more than one, double-click or F2 to rename, a New button and a Clear button (which asks first when there is something to clear). A new conversation takes its title from its first message unless you renamed it. While a turn runs, the conversation in front cannot be left, closed or cleared; a switch is refused and the strip stays where it was.
+
+`chat.snapshot()` is plain data to keep, and `conversations` takes it back:
+
+```js
+{ activeId, tabs: [{ id, title, conversationId, messages: [{ id, role, text, at?, tools?, meta? }] }] }
+```
+
+A reply still empty is not in a snapshot, and a tool that was `running` when a snapshot was taken comes back `stopped`.
+
+| Method | Does |
+|---|---|
+| `send(text)`, `cancel()` → bool | As the user would; false when refused |
+| `isBusy()`, `messages()`, `snapshot()` | A turn is running; the messages in front; everything to keep |
+| `activeConversation()` → id, `newConversation()` → id, `switchTo(id)`, `close(id)`, `rename(id, title)`, `reset()` | The tabs. `activeConversation` answers the id of the one in front, not the conversation; `snapshot()` holds its messages. `reset` empties the one in front. Refused ones answer false (`newConversation`: null) |
+| `setConversationId(tabId, id)` | Your backend's id for a conversation |
+| `setMessages(tabId, messages)` | Replaces a conversation's messages, when your backend knows better. The one a turn is writing to refuses |
+| `updateMeta(id, patch)`, `refreshControls(id)`, `controlsSlot(id)` | A message's controls, below |
+| `mode()`, `setMode(id)`, `setModels(patch)` | The bar |
+| `getText()`, `setText(text)`, `focus()`, `destroy()` | The composer, and teardown. `destroy` cancels a running turn |
+| `root`, `stateMachine` | The element, and the machine below |
+
+### Your controls on a message
+
+Each assistant message has a slot between its tool calls and its footer. `renderControls(el, message, chat)` fills an emptied `el` when the reply has finished, and again when the message comes back on a tab switch or a restore, after `updateMeta(id, patch)`, and on `refreshControls(id)`. It is not called while a reply streams. Whatever it needs to survive goes in `message.meta`, which is kept in snapshots and handed back untouched:
+
+```js
+renderControls(el, message, chat) {
+    if (!message.meta?.changes) return;
+    const button = document.createElement('button');
+    button.textContent = message.meta.undone ? 'Redo' : 'Undo';
+    button.onclick = () => chat.updateMeta(message.id, { undone: !message.meta.undone });
+    el.append(button);
+}
+```
+
+A `renderControls` that throws is logged and the chat carries on.
+
+### The model picker
+
+An [`ActionDropdown`](menus.md) on a button in the bar. It is controlled: choosing an entry calls your callback, and the picker changes when you call `setModels`. `setModels` takes any of these; what you leave out stays.
+
+| Key | Is |
+|---|---|
+| `items` | Entries: `{ id, label, description?, icon? }` (a model), `{ action, label, description?, icon? }` (a command), `{ separator: true }`. Labels and descriptions are text, never markup |
+| `activeId` | The model marked, and `request.model` |
+| `label` | The button's text. Default: the active item's label, then `labels.selectModel` |
+| `status` | `{ state?: 'ready' \| 'pending', label? }`: a dot on the button, its tooltip the label. None without `status` |
+
+A model calls `onModelSelect(item)`; a command calls `onModelAction(action, item)`. You get your own item back, with whatever else you put on it. With no items and no label there is no button; with no modes either there is no bar.
+
+### The state machine
+
+`ChatStateMachine` is the conversation lifecycle with no view in it, exported for a chat of your own. `chat.stateMachine` is the shell's.
+
+| State | Goes to |
+|---|---|
+| `idle` | `waiting` (`sendMessage`) |
+| `waiting` | `streaming` (`streamStart`), `idle` (`streamComplete`, `cancel`, `reset`), `error` (`error`) |
+| `streaming` | `idle` (`streamComplete`, `cancel`, `reset`), `error` (`error`) |
+| `error` | `waiting` (`sendMessage`), `idle` (`reset`) |
+
+`newConversation()` and `loadConversation(id)` go back to `idle` from anywhere. `canSend()`, `isProcessing()`, `mode`, `setMode(mode)`, `conversationId` and `lastError` read and set the rest; a mode is any string of yours.
+
+Calls are queued in order, because text can arrive in the same tick as the request that asked for it, and each answers a promise of `{ transitioned, reason? }`. A transition the state does not have is refused, not thrown. So `getState()` lags a call by some microtasks, and is `null` until the machine has entered `idle`; `settled()` resolves when everything called so far has taken effect.
+
+`new ChatStateMachine({ eventBus, logger, mode, onChange })`: `onChange({ state, conversationId, mode })` hears every state entered. `eventBus` gets `CHAT_BUS_EVENTS`:
+
+| Constant | Event | Payload |
+|---|---|---|
+| `STATE_CHANGED` | `chat:state:changed` | `{ state, conversationId, mode }` |
+| `MESSAGE_SENT` | `chat:message:sent` | `{ conversationId, text, mode }` |
+| `STREAM_COMPLETE` | `chat:stream:completed` | `{ conversationId, text, meta }` from the shell |
+| `MODE_CHANGED` | `chat:mode:changed` | `{ mode }` |
+| `CONVERSATION_NEW` | `chat:conversation:new` | `{}` |
+| `CONVERSATION_LOADED` | `chat:conversation:loaded` | `{ conversationId }` |
+| `ERROR` | `chat:error:raised` | `{ conversationId, message, detail }` |
+
+### Classes
+
+The block is `twm-chat-shell`, around the conversation view's `twm-chat`: `__tab-bar`, `__tabs`, `__tab-btn` (`--clear`), `__rename`, `__conversation`, `__welcome`, `__welcome-icon`, `__welcome-text`, `__typing`, `__tools`, `__tool` (`--running`, `--done`, `--error`, `--stopped`), `__tool-icon`, `__tool-label`, `__controls`, `__footer`, `__time`, `__copy` (`--done`), `__retry`, `__bar`, `__bar-spacer`, `__modes`, `__mode` (`--on`), `__model-btn`, `__model-label`, `__model-chevron`, `__model-menu`, `__status` (`--ready`, `--pending`).
+
+A message's role is the view's modifier, `twm-chat__msg--<role>`; the shell uses `user`, `assistant` and `error`. Every rule reads FlexDesk's tokens. Nothing is stored in a `data-` attribute beyond the tab strip's `data-tab-id` and the dropdown's own keys.
+
+`tests/chat_shell.test.mjs` and `tests/chat_state_machine.test.mjs` cover all of this in jsdom.

package/docs/components/conversation.md

@@ -26,6 +26,7 @@ view.setBusy(false);
 | Method | Does |
 |---|---|
 | `append({ id?, role, text, meta? })` → id | Adds a message; `role` becomes `twm-chat__msg--<role>` |
+| `remove(id)` → bool | Takes one message out ([below](#taking-one-message-out-remove-0180)) |
 | `replaceAll(messages)`, `clear()` | Restores a transcript (and scrolls to its end), or empties it |
 | `beginStream(message?)` → id, `appendChunk(text)`, `endStream()` | A message that grows; each chunk re-renders that message's body and nothing else |
 | `slot(id)` | The element below a message's body, yours to fill (tool output, buttons); a re-render leaves it alone |
@@ -70,3 +71,12 @@ view.setBusy(false);
 
 `tests/conversation_view.test.mjs` drives all of it in jsdom with a fake
 scroll geometry.
+
+## Taking one message out: `remove` (0.18.0)
+
+`view.remove(id)` takes one message out and answers `true`, or `false` for an
+unknown id. Every other message keeps its row and its slot, so it costs no
+re-render and moves no reader, where `replaceAll` of the rest redrew all of them
+and scrolled to the end. An open stream on that message is over: `streamingId()`
+is `null` and later chunks go nowhere. It is how the
+[assistant chat shell](chat-shell.md) takes out a reply that ended empty.