flexdesk 0.16.0 → 0.17.0

package/README.md

@@ -43,9 +43,9 @@ manager, and neither of them should drag in a plotting engine or a code editor.
 | `@flexdesk/core` | 30 kB | Event bus, settings store, logging, state machine, state guard |
 | `@flexdesk/host` | 5 kB | The host port (below) |
 | `@flexdesk/wm` | 166 kB | Tiling window manager: tabs, splits, desktops, command palette, taxonomy, `createShell()` |
-| `@flexdesk/widgets` | 192 kB | DataTable, modals, managed windows, toasts, trees, panels, context menus |
-| `@flexdesk/charts` | 26 kB | Plotly wrapper, chart types, subplot layouts, downsampling, plot windows |
-| `@flexdesk/tiles` | 67 kB | Draggable/resizable widget grid, tile base class, widget registry, layout persistence, chart and KPI tiles |
+| `@flexdesk/widgets` | 192 kB | DataTable, modals, managed windows, toasts, trees, panels, context menus, menu bars, a document outline, progress, a conversation view |
+| `@flexdesk/charts` | 26 kB | Plotly wrapper, chart types, subplot layouts, downsampling, a plot grid, a plot-config editor, plot windows, injected series transforms |
+| `@flexdesk/tiles` | 67 kB | Draggable/resizable widget grid, tile base class, widget registry, layout persistence, figure, chart and KPI tiles |
 | `@flexdesk/editor` | 62 kB | Monaco loader + factory, multi-file tab bar, search, split panes, undo manager |
 | `@flexdesk/canvas` | 14 kB | The canvas kernel: a pannable, zoomable surface, the edge router, a generic graph layer ([Flow editors](#flow-editors)) |
 | `@flexdesk/flow` | 381 kB | The flow-editor kit and the canvas, outline and lane editors ([Flow editors](#flow-editors)) |
@@ -130,6 +130,113 @@ await createShell({
 });
 ```
 
+### A menu bar: `createMenuBar` (0.17.0)
+
+File / Edit / View menus from one declarative model, instead of hand-built
+buttons and `showContextMenu` calls. A menu is `{ id, label, items }`; an item
+is `{ id, label, shortcut?, disabled?, checked?, radio?, submenu? }` or
+`{ separator: true }`:
+
+```js
+import { createMenuBar, MenuBar } from '@flexdesk/widgets';
+
+const bar = createMenuBar(document.getElementById('menus'), {
+    menus: [
+        { id: 'file', label: 'File', items: [
+            { id: 'open',   label: 'Open…',       shortcut: 'Ctrl+O' },
+            { id: 'recent', label: 'Open recent', submenu: () => recentItems() },  // rebuilt on every open
+            { separator: true },
+            { id: 'save',   label: 'Save',        shortcut: 'Ctrl+S', disabled: true },
+        ] },
+        { id: 'view', label: 'View', items: [
+            { id: 'grid',  label: 'Show grid', checked: true },                // a check item
+            { id: 'light', label: 'Light', radio: 'theme', checked: true },    // a radio group
+            { id: 'dark',  label: 'Dark',  radio: 'theme', checked: false },
+        ] },
+    ],
+    onAction: (id, { checked }) => run(id, checked),
+});
+bar.setEnabled('save', true);     // patches an open menu in place
+bar.setChecked('dark', true);     // …and unchecks the rest of the radio group
+```
+
+`createMenuBar(el, opts)` returns a `MenuBar` (also exported, for
+`instanceof`). Its methods: `open(menuId, { focusItem })`, `close()`,
+`focus()`, `isOpen()`, `isEnabled(id)`, `isChecked(id)`, `setEnabled(id, on)`,
+`setChecked(id, on)`, `commands()` and `dispose()`.
+
+- **Pointer.** Clicking a title opens its menu; while one is open, hovering
+  another title switches to it. Hovering an item with a submenu opens it.
+- **Keyboard.** Alt (on its own) or F10 focuses the bar. Left/Right move across
+  menus, Up/Down/Home/End within one, Right opens a submenu and Left closes it,
+  Enter/Space activate. Esc closes one level; the last Esc gives focus back to
+  what had it. Disabled items and separators are skipped, and never reach
+  `onAction`.
+- **Roles.** The WAI-ARIA menubar pattern: `menubar`, `menu`, `menuitem`,
+  `menuitemcheckbox`, `menuitemradio`, with `aria-checked`, `aria-disabled`
+  and `aria-expanded`.
+- `shortcut` is a label: the bar binds no key for it.
+- `bar.commands()` returns the model as palette rows (`{ id, label, shortcut,
+  context: 'File › Open recent', action }`), so the palette and the bar list the
+  same verbs.
+
+In a shell, pass the model as `menuBar` and the element as `chrome.menuBar`
+(each needs the other; either alone throws at boot);
+`shell.chrome.menuBar` is that `MenuBar`, and its enabled items follow the palette's
+own `commands` unless `menuBar.palette` is `false`:
+
+```js
+const shell = await createShell({
+    // …
+    menuBar: { menus, onAction },
+    chrome:  { menuBar: document.getElementById('menus') },
+});
+shell.chrome.menuBar.setEnabled('save', dirty);
+```
+
+The bar is `.twm-menubar` (not the older `.twm-menu-bar` icon strip).
+`tests/menu_bar.test.mjs` drives it in jsdom; `tests/menu_bar_css.test.mjs`
+holds its stylesheet.
+
+### A kind that exists once: `single` (0.17.0)
+
+Some content holds heavy app-wide state and must not be mounted twice. Mark its
+kind `single` in the taxonomy:
+
+```js
+createTaxonomy({
+    root: 'cosmos',
+    kinds: {
+        cosmos:      { label: 'Cosmos', isTopNav: true },
+        observatory: { label: 'Observatory', isTopNav: true, single: true },  // one, ever
+        planet:      { label: 'Planet', single: 'id' },                       // one per props.id
+    },
+});
+```
+
+- **Every open path reveals the instance that exists** — `navigate`, the top
+  nav, `openInPrimary`, `openInTab*`, `splitLeafWith`, Back. It switches to the
+  desktop it is on, activates its tab (bringing back a top-nav page the tile
+  had switched away from) and focuses its tile, or raises its window. Nothing
+  is mounted twice, and a reveal is one `onChange` / `wm:changed`
+  (`'single-reveal'`), however many steps it took.
+- **A page restore never brings back a copy.** A tile's archived top-nav page
+  can still list an instance that has since moved to another tile or a window;
+  switching back to that page (top nav, `openInPrimary`, Back) leaves it out.
+- **The copy verbs refuse.** Alt+T, Alt+N, Alt+Shift+H/V do nothing; the tile
+  menu's *Open in new tab* and *Open a copy in a window* are greyed with the
+  reason as their tooltip (`taxonomy.singleReason(kind)`); the palette draws its
+  split and window hints greyed, and Ctrl/Shift+Enter on such a row does nothing.
+- **The move verbs still work**: float, dock, drag a tab, move to a desktop.
+- **A restored layout keeps the first** of any duplicates (desktop order, then
+  tile order): the other leaf shows its next tab, or closes if it held nothing
+  else.
+
+The root kind cannot be `single` — every new pane, tab and desktop is seeded
+with it. The taxonomy answers `isSingle(kind)`, `instanceKey(kind, props)` and
+`singleReason(kind)`; the window manager answers `isSingleKind(kind)`,
+`findInstance(kind, props)` and `revealInstance(kind, props)`.
+
 ### A pane that names what it shows: `ctx.setTitle` (0.12.1)
 
 A content factory receives `(hostEl, props, ctx)`, and `ctx` carries, per pane,
@@ -152,6 +259,125 @@ content: {
 chrome shows only — the tree, the tab labels and the saved layout are left
 alone — and a call from content whose pane has since been rebuilt does nothing.
 
+### Panels a page does not offer (0.17.0)
+
+A kind says which panels it offers while it is the primary tile. Each side is
+`true`, `false` or `{ reason }`; a side it does not name is offered, and a kind
+that does not name a side takes it from its top-nav kind, so one declaration on
+a page covers every record opened under it:
+
+```js
+kinds: {
+    paper: { label: 'Paper', isTopNav: true, panels: { bottom: { reason: 'No console here' } } },
+    sheet: { label: 'Sheet', topNav: 'paper' },                        // withholds it too
+    slide: { label: 'Slide', topNav: 'paper', panels: { bottom: true } }, // offers it
+},
+```
+
+While a panel is withheld it is not in the layout, `wm.togglePanel(side)`
+answers `false` and changes nothing (nor what is saved), `wm.isPanelOpen(side)`
+is `false`, and the shell's toggle button and the palette chip carry
+`aria-disabled="true"` with the reason as their tooltip (`data-tooltip` on a
+`twm-has-tooltip` button, `title` otherwise; the button's own comes back after).
+The desktop still remembers the panel was open, and it comes back open when the
+user returns to a page that offers it. With no declarations every panel is
+offered, exactly as before.
+
+Content overrides its kind at runtime, until it clears the override with `null`:
+
+```js
+ctx.wm.setPanelAvailability('bottom', { reason: 'Run the model first' });
+ctx.wm.setPanelAvailability('bottom', null);           // e.g. in destroy()
+```
+
+`wm.isPanelAvailable(side)` and `wm.getPanelAvailability(side)` (`{ available,
+reason }`) read it, and a change is announced once — whatever caused it and
+however many sides it moved — to `wm.onPanelAvailabilityChange(fn)` (which
+returns the unsubscribe) and on the bus as `wm:panels:availability`, both with
+`{ panels, changed }`. `togglePanel` now answers `true` when it flipped a panel.
+
+`PanelStateMachine`, `PANEL_STATES` and `PANEL_TRANSITIONS` are gone from
+`@flexdesk/widgets`: nothing in the library used them, and which panels a page
+offers is now said once, in the taxonomy.
+
+`tests/panel_availability.test.mjs` drives all of it against a real shell.
+
+### Panels keep the size you dragged them to (0.17.0)
+
+Each desktop remembers every panel's share of the window-manager area along
+its axis (width for left and right, height for bottom), taken when a splitter
+drag ends, and saves it with the layout as `panelShares`. A reload, a switch to
+another desktop and back, and toggling one panel all rebuild the panels at
+those shares, and a closed panel comes back at the size it had. Only a panel
+that has never been sized on that desktop opens at the default 1:4. No split is
+built tighter than a drag allows (`TileRenderer.MIN_SLOT_FRACTION` of it per
+slot). A `TileRenderer` built by hand takes `onSplitResized(splitId)`, called
+once when a drag that changed a split's sizes ends.
+
+`tests/panel_sizes_kept.test.mjs` covers each of these.
+
+### A navigation panel you drive yourself: `mountNavPanel` (0.17.0)
+
+`mountNavPanel(hostEl, { modes })` (from `@flexdesk/wm`) builds a mode strip, a
+shared filter box and one lazily-mounted pane per mode. A strip click is no
+longer the only way to switch: the handle's `select(modeId)` takes the same
+path — it mounts the mode on first use, runs its `activate()`, restores that
+mode's filter text — and its promise resolves once `activate()` has run. An
+unknown id is ignored. `active()` names the mode shown.
+
+```js
+const nav = mountNavPanel(hostEl, {
+    modes: [
+        { id: 'files',  icon: 'folder',   label: 'Files',  mount: mountFiles },
+        { id: 'runs',   icon: 'history',  label: 'Runs',   mount: mountRuns,
+          filter: false },                // a pane with controls of its own
+    ],
+    showModeStrip: false,   // no strip: the app switches with select()
+    initialMode: 'runs',    // the mode shown at mount (default: the first)
+});
+await nav.select('files');  // mounted and activated
+nav.active();               // 'files'
+```
+
+A mode with `filter: false` hides the filter box while it is active, and its
+pane is never handed a query; the next mode with a filter shows its own saved
+text again. `showFilter: false` renders no filter box at all. All three options
+default to the old behaviour, so a panel built without them renders exactly as
+before.
+
+### Buttons that change with the pane: `ctx.setChromeActions` (0.17.0)
+
+A factory may return `chromeActions` — `[{icon, title, onClick}]`, drawn in the
+pane's chrome left of the split/float/close buttons — but those are read once.
+`ctx.setChromeActions(specs)` replaces them at any time, the way `setTitle`
+replaces the title: called during the mount it wins over the returned list, the
+later call wins, the list survives repaints, `null` or `[]` clears it, and a
+call from content whose pane has since been rebuilt does nothing. The content is
+never re-mounted.
+
+```js
+content: {
+    page: (hostEl, props, ctx) => {
+        let wide = false;
+        const paint = () => ctx.setChromeActions([
+            { icon: wide ? 'width_normal' : 'width_wide', title: 'Page width',
+              pressed: wide, onClick: () => { wide = !wide; paint(); } },
+            { separator: true },
+            { icon: 'add', label: 'New', title: 'Add a page', onClick: addPage },
+            { icon: 'publish', title: 'Nothing to publish yet', disabled: true },
+        ]);
+        paint();
+        return { destroy() {} };
+    },
+},
+```
+
+A spec may add **`label`** (text beside the glyph, or instead of it),
+**`pressed`** (`aria-pressed`, plus a pressed style; leave it out for a button
+that is not a toggle), **`disabled`** (greyed and inert, with its tooltip kept —
+it is `aria-disabled`, not the `disabled` attribute) and **`{separator: true}`**
+(a divider). A spec with none of them renders exactly as before.
+
 ### Your desktops beside the app's (0.10.0)
 
 Pass `chrome.desktops` and the shell paints a desktop bar: a chip per desktop
@@ -215,6 +441,81 @@ at most half the query (`cstmr` finds *customer*; `cour` does not find *Scroll u
 to*). A drill's `search` is debounced, and a stale answer is aborted and
 never drawn. `palette.invalidate()` drops the cache.
 
+**The built-in *Keyboard shortcuts* command** opens the help topic
+`keyboard-shortcuts`. If your `HelpProvider` defines that id, your topic is
+shown. If it does not, or you register no help at all, the modal shows the window
+manager's own bindings, `KEYMAP_SHORTCUTS` from `@flexdesk/wm`, as a table
+(`keyboardShortcutsTopic()`). Before this the modal showed *Failed to load help
+topic.* The fallback comes from `HelpModal.open(id, { fallback })`
+(`@flexdesk/widgets`), and you can pass one yourself. A topic id that nobody
+provides now shows *Help topic not found.* where it used to raise a load error.
+
+### Your keys, not the window manager's: `keymap` (0.17.0)
+
+The window manager binds F1..F12, Backspace, Ctrl+K, Ctrl+Tab, Ctrl/Shift+Arrows,
+the Alt chords, `?` and Esc, and swallows any other bare Alt+letter. Each of
+those chords can be taken back or rebound:
+
+```js
+await createShell({
+    // …everything above…
+    keymap: {
+        bindings: {
+            'F1': false,               // F1 is the page's: not prevented, nothing clicked
+            'F2': 'nav:0',             // F2 opens the first top-nav kind
+            'Backspace': false,        // Backspace never calls navigateBack
+            'Alt+W': (e, { wm }) => { /* yours; return false to leave e unprevented */ },
+        },
+    },
+});
+```
+
+A value is `false`, an action name, or a function. The actions are `palette`,
+`palette:close`, `help`, `back`, `nav:N`, `desktop:N`, `toDesktop:N` (all
+counted from 0), `desktop:next|prev`, `tab:next|prev`, `panelTab:next|prev`,
+`split:h|v`, `splitWith:h|v`, `openInTab`, `openInWindow`, `close`, `float`,
+`focus:left|right|up|down`, `move:left|right|up|down` and `suppress`. The chord
+ids are the defaults in `src/tiling/keymap.js`: `Ctrl+K`, `Meta+K`, `?`,
+`Escape`, `F1`..`F12`, `Backspace`, `Alt+H`, `Alt+Shift+H`, `Alt+ArrowLeft`,
+`Alt+Shift+1`, `Ctrl+Tab`, `Shift+ArrowRight` and so on, with `Alt+Letter` for
+the Alt+letter suppression. Modifiers may come in any order and case. A chord id
+or action the keymap does not know is warned about once, through `logger` (else
+`console`), when the shell is built, and is then ignored. Only the window
+manager's own chords can be rebound. To add a new key, put your own listener on
+the page. `keymap` itself must be an object whose only key is `bindings`:
+anything else (a string, a typo such as `{ binding: … }`) makes `createShell`
+throw a `TypeError`, so a binding you meant to change never stays in force
+unnoticed.
+
+**A key press is read as loosely as before.** With no bindings every key does
+what it did in 0.16, and a binding takes over every key press its chord was
+read as. Backspace ignores Shift and Alt, so `{ Backspace: false }` also hands
+Shift+Backspace and Alt+Backspace to the page. Alt+T/N/W/F ignore Shift. With
+Alt held, Ctrl and Meta are ignored, so Alt+Ctrl+H is `Alt+H`. Ctrl+K and
+Ctrl+Tab also match with Meta held, and Ctrl wins when both are held:
+Ctrl+Meta+K is `Ctrl+K`, and Meta+K is `Meta+K` only without Ctrl. Esc and `?`
+ignore every modifier. F1..F12, Shift+Left/Right and Ctrl+Left/Right match only
+with exactly those modifiers.
+
+**A key a component handled is the component's.** The keymap skips every
+keydown that is already `defaultPrevented`. A list that deletes a row on
+Backspace calls `preventDefault()`, and the window manager does not navigate
+back as well.
+
+**`?` is installed by the shell.** Importing `HelpModal` no longer adds a
+`document` listener as a side effect. A shell binds `?` as one of its chords,
+and `shell.dispose()` removes it with the rest. A page that uses the help modal
+without a shell calls `installHelpShortcut()` from `@flexdesk/widgets`, which
+returns its disposer. `HelpModal.toggle()` is what `?` does.
+
+**The *Keyboard shortcuts* command shows the bindings in effect.** It lists
+`keymapShortcuts(bindings)` from `@flexdesk/wm`. That is `KEYMAP_SHORTCUTS`
+with each changed row replaced by one line per chord still bound, and no line
+for a chord you disabled. `createCommandPalette({ shortcuts })` takes that table.
+The command's hint names the keys that open help in it: `?` by default, `F9`
+after `{ '?': false, F9: 'help' }`, and none when no key opens help (for
+example after `{ '?': 'palette' }`).
+
 **`chrome.zoom`** paints a − / track / + / readout control into the element you
 pass, restores the saved zoom through the host's `state` capability, and scales
 the content of tiles and floating windows. It deliberately scales *content only*
@@ -903,12 +1204,46 @@ list.setColumnVisible(3, true);
 | `columnChooser: true` | A right-click on the header opens a menu that lists every column, with a check mark on those shown. Choosing one shows or hides it. The last column shown is greyed out and says why. Without the option the header keeps the browser's menu. |
 | `setColumnVisible(colIdx, on)` | Shows or hides a column from code. Returns whether anything changed. The widths of the other columns, dragged or fitted, stay with their columns; a column shown again is measured. |
 | `getHiddenColumns()` | The hidden columns' indices, ascending. |
-| `onColumnsChange(hidden)` | Called after every change of the set: the chooser, `setColumnVisible` and `setData({ hiddenColumns })`. |
+| `onColumnsChange(hidden, { hidden, order })` | Called after every change of the set: the chooser, `setColumnVisible` and `setData({ hiddenColumns })`, and after every change of the column order (see below). `order` is `getColumnOrder()`. |
 | With `persistKey` | The set is saved with the sort and the filters and restored on mount. A saved set wins over `hiddenColumns`, so a column somebody chose stays chosen. A table without these options saves exactly what 0.9.1 saves. |
 
 A column sorted on and then hidden keeps the order; its arrow comes back with
 the column.
 
+### DataTable: columns in the order somebody puts them (0.17.0)
+
+Columns can be dragged into a new order by their headers, or ordered from
+code, and the order is remembered. The order is kept by data index, so
+`hiddenColumns`, the sort, the filters, `renderCell`'s `colIdx` and cell
+mode's `col` stay on their columns. A table that sets none of these options
+draws its columns in their natural order and saves what 0.16 saves.
+
+```js
+const list = DataTable.mount(host, {
+    headers: ['Id', 'Summary', 'Status', 'Owner'],
+    rows,
+    reorderable: true,
+    columnOrder: [0, 3, 1, 2],              // optional starting order
+    stateStore, persistKey: 'bugs:queue',
+    onColumnsChange: (hidden, { order }) => console.log('order now', order),
+});
+list.moveColumn(3, 1);                       // positions in getColumnOrder()
+```
+
+| Option | What it does |
+|---|---|
+| `reorderable: true` | Every data column's header can be dragged onto another; dropped, it takes that column's place (to its left when moved left, to its right when moved right). A press that starts on a column's resize grip resizes it and never starts a drag. The row-number and select columns stay first: they cannot be dragged, and nothing can be dropped on or in front of them. The header's right-click menu offers Move left and Move right, after any `headerMenu` items and before the `columnChooser` items; they pass over hidden columns. |
+| `columnOrder: [colIdx, ...]` | The order to draw the columns in: every data index once, hidden ones included. A list that is not a permutation of the columns is ignored with a console warning, and the natural order is drawn; a table mounted with no headers yet checks it, and warns once, when `setData` brings the first ones. Works without `reorderable`, in which case only code moves columns. `setData({ columnOrder })` applies a new order; `null` goes back to the natural one. |
+| `moveColumn(from, to)` | Moves the column at position `from` of `getColumnOrder()` to position `to`, the others closing up: from the natural order, `moveColumn(3, 1)` draws 0, 3, 1, 2. Returns whether the order changed. Dragged widths stay with their columns. |
+| `getColumnOrder()` | Every data index, hidden ones included, in the order drawn (a copy). |
+| With `persistKey` | The order is saved with the sort, the filters and the widths, and restored on mount. A saved order wins over `columnOrder`. A saved order for a different number of columns than the table has today is ignored: `columnOrder` is drawn, or the natural order when there is none. That holds whether the headers are known when the blob is read or come later with `setData`; likewise, a dragged order that new headers no longer fit gives way to `columnOrder`, or the natural order. A blob saved before 0.17 (no order) loads as it did. |
+| Copies and the CSV | Ctrl+C, the copy menu and `downloadCSV()` write the columns in the order shown. |
+
+The drag is HTML5 drag-and-drop on the header cells. The cell being dragged is
+`twm-dt-col--dragging`, the one under the pointer `twm-dt-col--drop` (plus
+`twm-dt-col--drop-after` when the column would land to its right). The logic
+lives in `column_order.js`, which is internal to the table.
+
 ### DataTable: the CSV button on every table (0.14.1)
 
 `showExportButton: true` draws "Download visible rows as CSV" in the pagination
@@ -956,6 +1291,235 @@ The select column is not a data column: it is not in a copy, a CSV,
 table's whole life, so remembered widths stay on their columns when the mode
 flips, and widths saved by a table without it land on the same columns.
 
+### DataTable: a grid of cells you can edit (0.17.0)
+
+`selectionMode: 'cells'` turns a table into a grid: a click selects a cell, the
+keyboard moves a cursor over cells, and with `editable` a cell opens an editor
+in place. A table that sets none of these options selects rows and behaves as
+in 0.16.
+
+```js
+const grid = DataTable.mount(host, {
+    headers: ['Item', 'Qty', 'Note'],
+    rows,
+    pagination: false,
+    virtualize: true,
+    selectionMode: 'cells',
+    editable: [1, 2],                       // or true, or (colIdx, row, rowIdx) => boolean
+    editors: { num: myNumberEditor },       // by column index or by type
+    onCellCommit: async ({ rowIdx, colIdx, value, previous }) => {
+        const r = await api.save(rowIdx, colIdx, value);
+        return r.ok ? { ok: true } : { ok: false, error: r.message };
+    },
+    headerMenu: (colIdx, ctx) => [{ label: `Sort by ${ctx.header}`, action: 'sort', icon: 'sort' }],
+    onHeaderMenuAction: (action, colIdx) => { if (action === 'sort') grid.sortBy(colIdx); },
+    columnChooser: true,
+});
+grid.getCellSelection();   // { anchor, focus, range }
+```
+
+| Option | What it does |
+|---|---|
+| `selectionMode: 'cells'` | Cell mode. A click selects one cell and puts the cursor on it; Shift+click selects the range from the anchor to it. Every cell of the range is drawn `twm-dt-cell--selected`, the cursor `twm-dt-cell--cursor`; rows are not lit. Combined with `selectToggle`, `selectMode` or `keyboardNav` those are ignored, with a console warning. |
+| The keys (focused table) | Arrows move the cursor (Shift extends the range). Ctrl+arrow jumps to the edge of the block of filled cells, as a spreadsheet does. Home/End go to the row's first and last cell (Ctrl: the page's first and last cell). Tab moves right and wraps to the next row (Shift+Tab back); on the last cell (Shift+Tab: the first) the table does not take the key, so focus moves on out of the table. ArrowDown on the last row stays put. Ctrl+A selects every cell of the page; Escape collapses the range onto the cursor. The cursor stays on the page drawn and is scrolled into view; under `virtualize` its row is drawn. |
+| `getCellSelection()` | `{anchor, focus, range}`. A cell is `{row, col, rowIdx}`: `row` is the position in the order shown (as `getDisplayedRows()` lists them, after sort and filter), `col` the data column, `rowIdx` the original row index. `range` is `{top, bottom, left, right, rows, columns}`: positions, the data columns at its edges, and the original row indices and data columns it covers (a hidden column inside it is not one of them). Null outside cell mode. |
+| `setCellSelection(focus, anchor?)` | Puts the cursor on `{row, col}`, or selects from `anchor` to it; `null` clears. The row is brought into view. |
+| `getSelection()`, `setSelection()`, Ctrl+C | Still about rows: `getSelection()` returns the rows the range touches, `onSelectionChange` hears them, and Ctrl+C and the copy menu copy them. `setSelection(indices)` selects the cells of those rows, first to last as shown. |
+| `onCellSelectionChange(sel)` | Called with `getCellSelection()` after every change. |
+| `editable` | Which cells open an editor: `true`, an array of data column indices, or `(colIdx, row, rowIdx) => boolean`. Needs cell mode. F2, Enter, a double-click or a printable key opens it on the cursor cell (a printable key replaces the value with that character). In the editor Enter commits and moves down, Tab commits and moves right (Shift: up, left), Escape restores the cell and calls nothing; the focus leaving it commits without moving. `editCell(row, col)` opens one from code; `isEditing()` says whether one is open. |
+| `editors: {[colIdx \| type]: factory}` | The editor for a column, looked up by column index and then by type (`columnTypes`, else the detected `num`/`text`). A factory gets `{value, row, rowIdx, colIdx, column: {index, header, type}, initialText, commit(value), cancel()}` and returns an element or `{el, getValue?, focus?, destroy?}`. An input, select or textarea commits its `value` on Enter and Tab; any other editor calls `commit(value)` itself. The default is a text box (`createTextEditor`). |
+| `onCellCommit({rowIdx, colIdx, value, previous})` | Called exactly once per commit; `previous` is the value the row holds, and a value left as the cell showed it is no commit. Return nothing or `{ok: true}` (or a Promise of it) and the value is written into the row the table holds for `rowIdx` when it settles (`rows[rowIdx][colIdx]`, so a row put in by `updateRow` meanwhile keeps its other cells) and drawn. `{ok: false, error}`, a rejection or a throw leaves the typed value in the cell, drawn `twm-dt-cell--error` with the message as its `title` and `data-error`, until a later commit of that cell succeeds, the value the row holds is committed back (no call: nothing to save), or new rows arrive. While the Promise is out the cell is `twm-dt-cell--pending`. The editor always opens with the value the cell shows, a refused or pending one included. |
+| While an editor is open | `render()`, and so `setData`, a sort or a page, waits and runs when the editor closes, so what is being typed is never thrown away. A commit that settles while another editor is open in its row marks its cell at once and draws the row when that editor closes. `updateRow` on the row the editor is in stores the data at once (`config.rows`, the window's row list) and returns `true`, and the row is drawn with it when the editor closes; the editor's cell is left as it is. A row that scrolls out of the virtual window commits its editor first. An editor with no `getValue` (a `{el}` around an element that is not an input, select or textarea) has no value the table can read: Enter, Tab and the focus leaving do nothing, and its row scrolling out cancels it, so what it holds is lost unless it has called `commit(value)` itself. |
+| `headerMenu(colIdx, ctx) => items` | Items for the header's right-click menu, asked for the data column right-clicked (`ctx` is `{colIdx, header, hiddenColumns, table}`). Items are `{label, action, icon?, disabled?, danger?, title?}` or `{separator: true}`. Choosing one calls `onHeaderMenuAction(action, colIdx)`. With `columnChooser` the chooser's items follow behind a separator. `[]` or `null` shows only what would show without the hook: the chooser, or the page's own menu. Works in either selection mode. |
+
+The two modules behind cell mode are exported for a consumer that builds its
+own grid: `CellSelection` (the anchor, the cursor and every key's move, with no
+DOM), `CellEditorHost` (one cell's editor, opened and closed exactly once) and
+`createTextEditor` (the default text box). The table's own half of cell mode
+is internal.
+
+#### Staged edits, undo and redo, one commit (0.17.0)
+
+With `staged: true` beside `editable`, a commit from an editor is STAGED
+rather than sent to `onCellCommit`: it stays in the table, drawn
+`twm-dt-cell--staged`, until `commit()` hands every staged cell to the
+consumer in one call. Ctrl+Z and Ctrl+Y walk the staged edits.
+
+```js
+const grid = DataTable.mount(host, {
+    headers, rows,
+    selectionMode: 'cells',
+    editable: true,
+    staged: true,
+    historyLimit: 100,                      // the default
+    onCommit: async ({ edits }) => {        // [{rowIdx, colIdx, value, previous}, …]
+        const r = await api.saveBatch(edits);
+        return { errors: r.failed };        // [{rowIdx, colIdx, error}] — empty or absent: success
+    },
+    onStagedChange: ({ count, canUndo, canRedo, committing }) => paintSaveButton(count),
+});
+saveButton.onclick = () => grid.commit();
+discardButton.onclick = () => grid.discard();
+```
+
+| Option or method | What it does |
+|---|---|
+| `staged: true` | Needs `editable` (ignored with a warning without it). A commit stages the value: the cell shows it, drawn `twm-dt-cell--staged`, and nothing is called. Staging the value the row holds is no change. The editor opens with the staged value. |
+| Ctrl+Z, Ctrl+Y (focused table) | Ctrl+Z takes the last staged edit back; Ctrl+Y or Ctrl+Shift+Z puts it back. A cell staged as `null` undoes to NO CHANGE, not to a staged null. In an open editor the keys are the editor's. `undo()` and `redo()` do the same from code. |
+| `historyLimit` | The ring keeps the last this-many entries (default 100); the limit counts entries, not cells. The oldest fall off, and their cells stay staged. An entry is one cell's before/after change or one fill (a group of cell changes, undone together), never a copy of the staged set. |
+| `commit()` | Calls `onCommit({edits})` ONCE with every staged cell, `{rowIdx, colIdx, value, previous}` by row then column (`previous` is what the row holds); an open editor's value is staged first. Resolves `{ok: true, committed}` on success: the values are written into the rows the table holds, and the staged cells and the ring are cleared (a Ctrl+Z after a commit does nothing). If `onCommit` resolves `{errors: [{rowIdx, colIdx, error}]}` (non-empty), each of those cells is drawn `twm-dt-cell--error` with the message as its `title` and `data-error`, every staged value stays, and `commit()` resolves `{ok: false, errors}`; `{ok: false, error}`, a rejection or a throw marks every staged cell with the message. Staging a marked cell again clears its mark. While the commit is out no editor opens and undo, redo and `discard()` do nothing. |
+| `discard()` | Drops every staged cell, its marks and the ring. |
+| `getStagedEdits()` | The staged cells, as `onCommit` would get them. |
+| `onStagedChange({count, canUndo, canRedo, committing})` | After every change of the staged cells. |
+| The freeze | While any cell is staged, sorting, filtering and paging are held: the sortable headers, the filter row's controls, the pager's buttons and the `paging` strip are disabled with the reason on them (`data-refusal`, `title`), and `sortBy`, `setFilter`, `clearFilters`, `goToPage`, `goToRow` and the paging calls refuse with a console warning. The export button is not held. `stagedRefusal` (a string, or `(count) => string`) gives the reason in the app's words. |
+| New rows | `setData({rows})` drops the staged cells and the ring: the row indices they named are other rows now. |
+
+`StagedHistory` (the ring, with no DOM: `record`, `beginGroup`/`endGroup`,
+`undo`, `redo`, `reset`, writing through an injected `apply(entry, direction)`)
+is exported with `ACTIONS` and `DEFAULT_HISTORY_LIMIT` for a consumer that
+builds its own grid.
+
+#### Fill handle (0.17.0)
+
+With `fillHandle: true` beside `staged`, the bottom-right cell of the range
+carries a small square (`.twm-dt-fill-handle`). Dragging it up, down, left or
+right over the cells beyond the range fills them as a spreadsheet does, and
+stages the values: nothing is sent until `commit()`.
+
+```js
+const grid = DataTable.mount(host, {
+    headers, rows,
+    selectionMode: 'cells',
+    editable: (colIdx, row) => !row.locked,  // a refused cell is skipped by a fill
+    staged: true,
+    fillHandle: true,
+    onCommit: ({ edits }) => api.saveBatch(edits),
+});
+grid.fill({ row: 20, col: 3 });              // what dragging the handle to (20, 3) does
+```
+
+| Option or method | What it does |
+|---|---|
+| `fillHandle: true` | Needs `staged` (ignored with a warning without it). The handle sits in the range's corner cell (`twm-dt-cell--fill-corner`); it is not drawn while an editor is open or a commit is out. During a drag the cells it covers are drawn `twm-dt-cell--fill-preview`; the direction is the one the pointer is furthest out in (up and down win a tie), up to the page's edge. Escape, or a cancelled pointer, ends the drag without filling. A drag is never a click on the table: the click the browser makes of the press and release (on the corner cell, the row or the body) is swallowed, filled or not, so neither the range nor `onRowClick` / `onRowActivate` sees it. On release the cells are staged as ONE undo entry — one Ctrl+Z takes the whole fill back — and the range grows over them. |
+| What is written | Each column of the range (each row, filling left or right) is a seed, continued by `projectSeries`: one cell repeats its value; numbers a constant step apart continue (`1, 2` filled three further gives `3, 4, 5`); `YYYY-MM-DD` dates or `Date`s a constant number of days apart continue that many days apart; texts like `Item 1, Item 2` continue their number (`INV-001` keeps its zeros); any other block repeats in a cycle. Filling up or left runs the series away from the block (`3, 4` filled up gives `2, 1`). Holding Ctrl (Cmd) at release repeats the block instead of continuing it. A hidden column is stepped over. |
+| A cell `editable` refuses | Is skipped: nothing is staged in it and the row is untouched. It is drawn `twm-dt-cell--fill-skipped` until the selection moves, the next fill or new rows. |
+| `fill(to, {forceCopy})` | The fill a drag to cell `to` (`{row, col}`: position shown, data column) makes, from code; `forceCopy` is Ctrl. Returns `{direction, count, staged, skipped}` (`staged` the NUMBER of cells that changed, `skipped` the refused cells as `{row, col, rowIdx}`), or null when nothing was filled. |
+
+`detectSeries(values)` (what a seed is: `{kind, step}` with kind `copy`,
+`number`, `date`, `text-number` or `cycle`, or null for blanks) and
+`projectSeries(values, count, {forceCopy})` (the next `count` values; a
+series keeps its seed's type) are exported as pure functions for a consumer
+that builds its own grid. `values` is the seed in fill order.
+
+### DataTable: column groups and structural edits (0.17.0)
+
+`columnGroups` draws a second header row over the column headers, and a few
+callbacks let a person add, rename and delete columns and rows from the
+headers and the row menu. The consumer owns the data: every edit is a call,
+and the consumer answers it with `setData`. A table that sets none of these
+options draws exactly as in 0.16.
+
+```js
+const table = DataTable.mount(host, {
+    headers: ['Cash', 'Loans', 'Deposits'],
+    rows,
+    columnGroups: [
+        { key: 'assets', label: 'Assets', columns: [0, 1] },
+        { key: 'liabilities', label: 'Liabilities', columns: [2] },
+        { key: 'equity', label: 'Equity', columns: [] },   // drawn as a placeholder column
+    ],
+    onColumnAdd: (groupKey) => model.addColumn(groupKey),
+    onColumnRename: (colIdx, name) => model.renameColumn(colIdx, name),
+    onColumnDelete: (colIdx) => model.deleteColumn(colIdx),
+    onRowAdd: (afterRowIdx) => model.addRow(afterRowIdx),        // null: from the header
+    onRowDelete: (rowIdx) => model.deleteRow(rowIdx),
+});
+```
+
+| Option | What it does |
+|---|---|
+| `columnGroups: [{key, label?, columns}]` | A group row above the headers: one cell per run of shown columns of a group, spanning them (`th.twm-dt-group`), and a blank cell over the row number, the select column and any column in no group. `columns` are data column indices; a column is in the first group that lists it; a hidden column leaves its group's span; with `columnOrder` the runs follow the order drawn, so a group whose columns are not side by side gets one cell per run. The row is its own table in the header wrap (`table.twm-dt-groups`), which takes the header's column widths, table width and sideways scroll after every fit, auto-size and drag. `setData({columnGroups})` changes the groups. |
+| An empty group | Keeps one placeholder column so it stays visible and its add control reachable: `th.twm-dt-col--placeholder` in the header, an empty filter cell, and an empty `td.twm-dt-cell--placeholder` in every row. It stands after the columns of the groups listed before it, and is no data column: not in a copy, the CSV, a menu's `ctx.colIdx` or cell mode. |
+| `onColumnAdd(groupKey)` | An add button (`.twm-dt-group__add`) in every group's header cell and in a placeholder's header. |
+| `groupActions(group, {key, columns, table}) => items`, `onGroupAction(action, groupKey)` | The consumer's buttons in a group's header cell. Items are `{action, icon?, label?, title?, disabled?}`. |
+| `columnActions(colIdx, {colIdx, header, table}) => items`, `onColumnAction(action, colIdx)` | The consumer's buttons in a column's header (`.twm-dt-col-action`), with the same items. A click on one does not sort. |
+| `onColumnRename(colIdx, name)` | Renames a column in place with `attachInlineRenamer`. "Rename column" in the header's right-click menu, `renameColumn(colIdx)`, or a double-click on the header's label (on a table that is not `sortable`) opens it. Enter, or the focus leaving, with a different non-empty name calls it once. Escape, or the name left as it was, restores the header and calls nothing. The new name shows until the next render; returning `false` or `{ok: false}` (or a Promise of it) restores the old one. |
+| `onColumnDelete(colIdx)` | "Delete column" in the header's right-click menu. |
+| `onRowAdd(afterRowIdx)` | "Insert row below" in a row's right-click menu (the row's original index), and "Add row" in the header's (`null`), so a table with no rows can get its first. |
+| `onRowDelete(rowIdx)` | "Delete row" in a row's right-click menu. |
+
+The structural items follow the consumer's own: in the header menu after the
+`headerMenu` items and before the column chooser, in a row's menu after the
+`contextMenuItems` and before the copy items, each behind a separator.
+
+### DataTable: a crosstab, with spanned header rows and pinned label columns (0.17.0)
+
+`crosstab` draws the table as a matrix: rows of spanned headers over the
+column headers, the leading columns as row labels, and all of it in ONE table
+in ONE scroller. The header rows stick to the top, the label columns (with the
+select and row-number columns in front of them) stick to the left, and the
+corner, the header cells over the label columns, sticks to both. Each header
+row's `top` is the measured height of the rows above it, and each pinned
+column's `left` the measured width of the pinned columns before it. Both are
+read after layout and again whenever a header row or a pinned header cell
+changes size (a label that wraps, a font, a zoom). The consumer supplies every
+value and every label: rows and columns that add others up are ordinary rows
+and columns, marked with `rowClass`, `cellClass` and a header cell's
+`className`. A table without `crosstab` draws exactly as in 0.16.
+
+```js
+const table = DataTable.mount(host, {
+    headers: ['Region', 'City', 'Q1', 'Q2', 'Q1', 'Q2', 'All'],
+    rows,                                   // ['North', 'Oslo', 1, 2, 3, 4, 10], …
+    pagination: false,
+    virtualize: true,                       // a large matrix: draw the rows in view
+    rowClass: (row) => (row[0] === 'All' ? 'my-sum-row' : null),
+    crosstab: {
+        labelColumns: 2,                    // 'Region' and 'City' are row labels
+        headerRows: [[                      // one row of spans per level, top first
+            { label: '2024', columns: [2, 3] },
+            { label: '2025', columns: [4, 5] },
+            { label: 'All', columns: [6], className: 'my-sum-head' },
+        ]],
+    },
+});
+```
+
+| `crosstab` key | What it does |
+|---|---|
+| `labelColumns` | How many of the leading drawn data columns are row labels (default 0). They are marked `twm-dt-pin` in every row, the header and the filter row, and pinned at the measured widths. One column with the depth drawn by the consumer (`cellClass`, `renderCell`), or one per level: both are just a count. |
+| `headerRows: [[{label, columns, className?, title?}]]` | The rows of spans above the column headers, top first. A cell spans the run of drawn body columns it lists (`columns` are data column indices, as in `columnGroups`; a column is in the first cell of its row that lists it); a run of columns in no cell of a row is a blank cell. Every row's spans add up to the body's columns. Above the label columns stands the corner: one `th.twm-dt-crosstab__corner` per pinned column, spanning every header row. |
+| `emptyLabel` | With no body column at all (an empty axis), one column headed with this text (default `'(none)'`) and an empty cell in every row, and no header rows. It is no data column. |
+
+The table carries `twm-dt-crosstab`, the header rows `tr.twm-dt-crosstab__band`
+and the column headers `tr.twm-dt-crosstab__leaf`; the spanned header cells are
+`columnGroups`' group cells (`th.twm-dt-group`) and are styled as those. There
+is no separate header table, so the split layout's column fit, resize grips,
+header right-click menu (`columnChooser`, `headerMenu`, and the header items of
+`onColumnRename`, `onColumnDelete` and `onRowAdd`), `columnActions`,
+`reorderable` and `columnGroups` row do not apply (`columnGroups` is ignored
+with a warning).
+
+A row's background is the custom property `--twm-dt-row-bg` on its `<tr>`
+(the zebra stripe sets it on even rows, at no specificity). Every crosstab row
+paints it, and the pinned label cells lay it over their opaque surface, so a
+coloured row keeps its colour across the label cells too. To colour a row, set
+the property from its `rowClass`, not `background` on the `tr` (the crosstab's
+row rule paints the property instead):
+
+```css
+.my-sum-row { --twm-dt-row-bg: rgba(255, 255, 255, 0.06); }
+```
+The pinned cells' background is one opaque stack the crosstab owns (it is
+`!important`, so neither a state rule nor an animation can make it see-through):
+every tint FlexDesk paints on a cell — hover, the clickable hover, row and cell
+selection, `staged`, the fill's skipped mark, placeholders, `diff` and the
+new-row flash — is drawn as a layer over the row's `--twm-dt-row-bg` over the
+surface (`--surface-0`), the same tint the unpinned cells of that row show.
+Under `virtualize` the columns are held at the widths first measured, so they
+do not shift as rows scroll in and out. With 1,000 rows and 50 body columns
+under `virtualize`, the first draw stays well under 300 ms in jsdom (tests/crosstab.test.mjs §6).
+
 ### Scrollbars
 
 `installAutoScrollbars(root)` (from `@flexdesk/widgets`) replaces the browser's
@@ -966,6 +1530,99 @@ layer, so a container that redraws its contents cannot lose its bar, and
 textareas get one too. Containers that already use `installOverlayScrollbar`
 keep their own.
 
+`installCollapsibleScrollbars(root = document.body)` gives every
+`.twm-collapsible-content.visible` section under `root` a vertical overlay
+bar: the ones already visible at once, and the ones mounted or expanded
+later. It watches `root` only and returns a disconnect. (It used to take no
+argument and look for a `#twm-fixed-200` that nothing created, so visible
+sections got no bar until a class changed — BUG-0006.)
+
+### SliderField: a number box, a readout, a default and an enable toggle (0.17.0)
+
+`new SliderField({ fieldId, field, onChange })` (from `@flexdesk/widgets`)
+draws a range input. Its companions are opt-in through `field`; with none of
+them the DOM is the range and the helper line, as it always was.
+
+```js
+import { SliderField } from '@flexdesk/widgets';
+
+const slider = new SliderField({
+    fieldId: 'rate',
+    field: {
+        min: 0, max: 1, step: 0.01, value: 0.25,
+        numberInput: true,                         // an editable box, kept in sync both ways
+        readout: (v) => `${Math.round(v * 100)}%`, // or true for the plain value
+        defaultValue: 0.25,                        // --modified state and a reset button
+        toggleable: true, disabledValue: null,     // an enable checkbox before the slider
+    },
+    onChange: (value, { immediate }) => save(value),
+});
+host.appendChild(slider.render());
+```
+
+| Field / method | What it does |
+| --- | --- |
+| `numberInput` | A text box beside the slider. Dragging updates it on every frame; Enter (or leaving the box) commits what was typed, clamped to `[min, max]` and snapped to `step`. Text that is not a finite number (`abc`, empty, `Infinity`) changes nothing and the box shows the value again; Escape does the same |
+| `readout` | A span after the slider: `true` shows the value, a function `(value: number) => string` formats it. It follows the drag live |
+| `defaultValue` | While the value differs from it the root carries `twm-slider-field--modified` and the reset button shows; reset restores it and reports it through `onChange`, like a release |
+| `toggleable`, `enabled`, `disabledValue` | A checkbox before the slider (`enabled: false` starts it off). While off, the inputs are disabled, the root carries `twm-slider-field--off`, and `onChange`/`getValue()` report `disabledValue` (default `null`) |
+| `onChange(value, { immediate })` | Called once per commit: a drag release, a typed Enter, a reset, a toggle. The value is the slider's value as a string, as before. With `emitOnInput` it is also called on every drag frame with `immediate: true` |
+| `setValue(x, { silent })`, `setRange({ min, max, step }, { silent })`, `setEnabled(on, { silent })`, `reset({ silent })` | Change the field from code. Each reports at most once, nothing with `silent: true`, and nothing when the reported value did not move, so a caller that writes back from its own `onChange` does not loop. `setValue` refuses a non-finite value (returns `false`); `setRange` refits the value and the default |
+| `getValue()`, `isEnabled()`, `isModified()` | What `onChange` would report now, the toggle state, and whether the value differs from `defaultValue` |
+
+### A stack of collapsible sections: `createSectionStack` (0.17.0)
+
+Inspector-style panel content: titled sections in a column, each opened and
+closed from its header. It is built from the tree's `.twm-collapsible-*`
+pieces plus `.twm-section-stack*` (`@flexdesk/widgets`).
+
+```js
+const stack = createSectionStack(panel, {
+    sections: [
+        { id: 'notes', title: 'Notes', icon: 'edit_note', content: notesEl },
+        { id: 'chat', title: 'Assistant', fill: true,
+          actions: [{ icon: 'delete', label: 'Clear', onClick: (id, event) => clear() }] },
+        { id: 'params', title: 'Parameters', defaultExpanded: false },
+    ],
+    key: 'inspector.sections',
+    stateStore: { read: (key) => saved[key], write: (key, map) => { saved[key] = map; } },
+});
+stack.body('params').appendChild(paramsEl);
+const off = stack.on('toggled', ({ id, expanded, source }) => { /* … */ });
+```
+
+- **The header toggles, its actions do not.** A click anywhere on a header
+  opens or closes the section and turns its arrow. A click on one of its
+  `actions` runs that action's `onClick(sectionId, event)` and nothing else.
+  The toggle is a `<button>`, so Enter and Space work.
+- **`defaultExpanded`** is `true` unless a section says `false`.
+- **One `fill` section** takes the height the others leave, and its body is
+  what scrolls (`min-height: 0`). A long conversation scrolls inside its
+  section and the panel stays the size of the window. The stack is
+  `height: 100%` of its container, so give the container a height. A closed
+  fill section is only its header.
+- **Remembering is injected.** `stateStore` is `{ read(key), write(key, map) }`.
+  `map` is `{ [sectionId]: expanded }`, and it is written on every open and
+  close under `key`. `read` may return a promise. Until it settles the
+  sections show their defaults; a section somebody toggled in the meantime
+  keeps that choice, and that toggle is written once the read has settled,
+  over the stored states of the sections nobody touched. `stack.ready` resolves once the read has been applied. A
+  store that throws, rejects or returns anything other than a map leaves every
+  section on its `defaultExpanded`. Without a store nothing is remembered.
+- **`setVisible(id, false)`** takes a section off the stack and keeps its
+  state, so `setVisible(id, true)` brings it back open or closed as it was.
+  `isVisible(id)` reads it.
+- `expand(id)`, `collapse(id)`, `toggle(id)` and `isExpanded(id)` work on
+  any section, hidden or not. An unknown id throws.
+- **`toggled`** fires on each change with `{ id, expanded, source }`, where
+  `source` is `'user'`, `'api'` or `'restore'` (a stored state that arrived
+  after mount). `on('toggled', fn)` returns the function that stops listening.
+- **`dispose()`** removes the stack's listener and every node it made, along
+  with any `content` you passed in.
+
+`tests/section_stack.test.mjs` covers each of these in jsdom. The fill
+layout was also measured in headless Edge.
+
 ## Flow editors
 
 *New in 0.6.0.* Both entries first ship in FlexDesk 0.6.0.
@@ -1000,7 +1657,7 @@ touches browser storage — and is shown to fail on a planted one.
 
 | Part | What it does |
 |---|---|
-| `createStepCatalogue(types, {categories, idBase})` | The step types the consumer passes in, read as they arrive (`type_id`, `label`, `category`, `role`, `description`, `icon`, `ports`, `config_schema`, `unavailable`; any other key is kept). `get`, `list`, `byCategory`, `role`, `tone`, `inputs(typeId, {flow})`, `outputs`, `port`, `idBase`, and `problems` — a broken type is listed there, never thrown. **Ports keep their declared order**: a lane reads the first input as its own and an outline draws the other outputs as arms in order, so nothing sorts them |
+| `createStepCatalogue(types, {categories, idBase})` | The step types the consumer passes in, read as they arrive (`type_id`, `label`, `category`, `role`, `description`, `icon`, `ports`, `config_schema`, `unavailable`; any other key is kept). `get`, `list`, `byCategory`, `role`, `tone`, `inputs(typeId, {flow})`, `outputs`, `port`, `idBase`, and `problems` — a broken type is listed there, never thrown. A type may also carry `render`, `update`, `size: {w, h}` and `accent` (a tone), which only the canvas editor reads ([Node bodies](#node-bodies-0170)); `size(typeId)`, `accent(typeId)` and `body(typeId)` answer them, `null` when a type has none, and a `size`, `accent` or hook of the wrong kind is a line in `problems` and is not used (0.17.0). `inline: ['key', …]` names settings of its `config_schema` the canvas editor draws on the node ([Edited on the node](#edited-on-the-node-0170)); `inline(typeId)` answers the names the schema has, `[]` when none, and a name it lacks (or an `inline` that is not a list) is a line in `problems` and is not drawn (0.17.0). `rank: 'source' \| 'sink'` is the hint the canvas editor's `layout: 'layered'` Arrange gives the type's steps (the first or the last column); `rank(typeId)` answers it, `null` when a type has none, and any other value is a line in `problems` and is not used (0.17.0). **Ports keep their declared order**: a lane reads the first input as its own and an outline draws the other outputs as arms in order, so nothing sorts them |
 | `checkSettingsSchema(schema)` | The JSON-Schema subset a step's settings may use: `type`, `enum`, `const`, `required`, `properties`, `additionalProperties` (a boolean), `items`, `minItems`/`maxItems`, `minimum`/`maximum`, `minLength`/`maxLength`, `format: "uuid"`, the annotations and any `x-` hint. Returns the first refusal as the server's own sentence, or `null`. `oneOf`, `anyOf`, `$ref` and `pattern` are refused. `tests/fixtures/flow_kit_settings_schema.json` holds 30 schemas and their verdicts. Tables' own `check_schema` gave the same 30 verdicts when the file was written, and is meant to read this file in a test of its own |
 | `createWidgetRegistry()` | The controls, by name. The ten generic widgets are registered already; `register(name, widget)` throws for a name that exists, and replacing one takes `{replace: true}`. A widget is `(spec, value, ctx) => {el, destroy?, focus?, caret?, restoreCaret?}` and reports with `ctx.set(value)`; `undefined` removes the setting |
 | `createSettingsPanel(options)` | One step's settings, or the flow's own, drawn from the schema (below) |
@@ -1012,7 +1669,7 @@ touches browser storage — and is shown to fail on a planted one.
 | `groupFindings(list)`, `createFindingsStrip({onGoTo, nameOf})` | The consumer's findings (`{code, message, severity, node_id?, field?}`) by step, and the strip: *"N things to fix before this can be published."*, a line each, *Go to it* |
 | `new FlowHistory({actions, restore, onState, limit, mergeMs})` | Undo and redo over whole snapshots. The editor passes its own list of actions and `commit` throws on any other, so an edit nobody named fails its first test. Loading and publishing are `baseline`s, never entries. Keyed commits within `mergeMs` merge (typing a name is one entry), never across an undo. `keep()` and `adopt(kept, state)` carry the stacks to a successor that loaded the same bytes |
 | `bindFlowKeys(root, handlers)`, `ownsUndo(target)` | An editor's keys, bound on its root, never on `window` (below) |
-| `emptyGraph`, `normalise`, `serialise`, `nextId`, `addNode`, `removeNode`, `connect`, `canConnect`, `disconnect`, `inputNamesOf` | A logic flow's graph — `{nodes: [{id, type, label?, config, position}], connections: [{source, target, sourcePort, targetPort}]}`, the shape the canvas and the outline both save. `serialise` is byte-stable: a graph opened and saved with no edit is the same text |
+| `emptyGraph`, `normalise`, `serialise`, `nextId`, `addNode`, `removeNode`, `connect`, `addConnection`, `canConnect`, `disconnect`, `inputNamesOf` | A logic flow's graph — `{nodes: [{id, type, label?, config, position}], connections: [{source, target, sourcePort, targetPort}]}`, the shape the canvas and the outline both save. `serialise` is byte-stable: a graph opened and saved with no edit is the same text. `canConnect(graph, catalogue, edge, {strings, dataRead, dataPorts})` refuses only what an editor cannot draw; with `dataPorts: true` a data port connects to a data port, any number of lines out of one. `connect` adds the line when `canConnect` allows it; `addConnection(graph, edge)` adds it asking nothing, for a caller whose own rules already allowed it. It may also carry `groups: [{id, label?, tone?, nodes: [id, …]}]` and `notes: [{id, text, position, size?: {w?, h?}}]` (0.17.0), and only when it has some, so a graph without them is the same text as before. Groups are flat: `normalise` keeps a node in the first group that names it, leaves out ids that are not nodes, and drops a group with no member; `removeNode` takes the node out of its group, and the group with its last member |
 | `createStrings(...layers)`, `FLOW_STRINGS` | Every word drawn, English and domain-free by default; an editor lays its own words over these, and the consumer lays its words over both |
 
 **The settings panel.**
@@ -1069,7 +1726,7 @@ character width and paints a viewport of no lines, and nothing repaints it.
 | `string-list` | Short strings |
 | `enum-chips` | A multi-select of `items.enum`, as chips, in the enum's order |
 | `choice-cards` | One of N as radio rows, each with its words |
-| `upstream-column`, `upstream-columns` | One or several columns of the step's input, by name, from the panel's `columns` |
+| `upstream-column`, `upstream-columns` | One or several columns of the step's input, by name, from the panel's `columns`. While `columns` answers `null` (the columns are not known yet) the name is typed instead — a text box, or a chip list that takes a name on Enter or a comma — under the hint *Columns not known yet*; once columns arrive the same setting is a select (or toggle chips) with the stored name chosen, and a name the columns lack is kept and marked *(not found)* (0.17.0) |
 
 | Schema hint | Meaning |
 |---|---|
@@ -1099,7 +1756,7 @@ configured renames nothing.
 
 **Keys.** `bindFlowKeys(root, handlers)` binds Ctrl/⌘+Z (`undo`), Ctrl/⌘+Y and
 Ctrl/⌘+Shift+Z (`redo`), Delete (`remove`), Ctrl/⌘+D, C, X and V (`duplicate`,
-`copy`, `cut`, `paste`), F2 (`rename`), Alt+↑, Alt+↓ and Alt+← (`moveUp`,
+`copy`, `cut`, `paste`), Ctrl/⌘+A (`selectAll`, 0.17.0), Ctrl/⌘+G and Ctrl/⌘+Shift+G (`group`, `ungroup`, 0.17.0), F2 (`rename`), Alt+↑, Alt+↓ and Alt+← (`moveUp`,
 `moveDown`, `moveOut`), the arrows (`up`, `down`, `left`, `right`), Enter
 (`open`) and Escape (`escape`), and returns an unbind. A key whose handler is
 absent, or returns `false`, is not taken. An editor's own row or card marks
@@ -1147,10 +1804,11 @@ the settings of whatever is picked, under a toolbar. It stands on the
 
 | Part | What it does |
 |---|---|
-| `new CanvasAdapter({container, gridSize = 16, onViewportChange, onBackgroundMenu, nodeSelector})` | A surface you put nodes and lines on: right-, middle- or Shift-drag pans, Ctrl + the wheel zooms about the pointer, a left press on the background draws a marquee (`onMarquee(box)`, `onSelectionChange(selection)`). Fields `root`, `surface`, `edgeLayer` (an SVG), `nodeLayer`, `marquee`, `selection`, `scale`, `tx`, `ty`, `gridSize`. Methods `clientToCanvas`, `canvasToClient`, `snap`, `setViewport`, `viewport`, `zoomAt`, `fit`, `visibleBox`, `contains`, `bringIntoView` (pans and never zooms, and does nothing when the box is already in view), `consumeRightDrag`, `clear`, `destroy`. **A node is whatever you put in `nodeLayer`**: a press inside one starts no pan and no marquee, and a right-click on one keeps your menu (or the browser's). Pass `nodeSelector` when the node layer holds other things too. `onViewportChange` fires once, synchronously, from the constructor, so declare what it reads before you build the adapter |
+| `new CanvasAdapter({container, gridSize = 16, onViewportChange, onBackgroundMenu, nodeSelector})` | A surface you put nodes and lines on: right-, middle- or Shift-drag pans, Ctrl + the wheel zooms about the pointer, a left press on the background draws a marquee (`onMarquee(box)`, `onSelectionChange(selection)`). Fields `root`, `surface`, `edgeLayer` (an SVG), `nodeLayer`, `marquee`, `selection`, `scale`, `tx`, `ty`, `gridSize`. Methods `clientToCanvas`, `canvasToClient`, `snap`, `setViewport`, `viewport`, `zoomAt`, `fit`, `visibleBox`, `contains`, `bringIntoView` (pans and never zooms, and does nothing when the box is already in view), `consumeRightDrag`, `clear`, `destroy`. **A node is whatever you put in `nodeLayer`**: a press inside one starts no pan and no marquee, and a right-click on one keeps your menu (or the browser's). Pass `nodeSelector` when the node layer holds other things too. `onViewportChange` fires once, synchronously, from the constructor, so declare what it reads before you build the adapter. `CanvasAdapter.MIN_SCALE` (0.15) and `CanvasAdapter.MAX_SCALE` (4) are the limits every zoom clamps to (0.17.0) |
 | `routeEdge(from, to, {obstacles, simple})`, `selfLoop`, `returnEdge(from, to, {floor})` | SVG path data between two anchors `{x, y, side}`: a line with horizontal lead-outs (bent round obstacles up to `OBSTACLE_ROUTING_NODE_LIMIT` nodes), a node's line to itself, and a loop's line back, which runs under both nodes |
 | `crowsFoot(point, side, kind)`, `footAnchor(point, side, kind)`, `cardinality({kind, optional})` | Crow's-foot ends (`many`, `one`, `zero-or-many`, `one-or-many`, `zero-or-one`, `exactly-one`) as an SVG group `twm-edge__marker twm-edge__marker--<kind>`, where the line should start so it meets the mark, and the two ends a reference implies |
 | `arrange(nodes, edges, {columnGap, rowGap})` | A layered layout. **Two quirks, kept on purpose:** an edge points from child to parent (a node sits one column right of what it points at), and each column is sorted by `label`, which every node must have |
+| `layeredLayout(nodes, edges, {rank, sizeOf, columnGap = 64, rowGap = 32, componentGap = 80, passes = 8})` (0.17.0) | A layered layout for any directed graph, as a diagram is read: `{from, to}` puts `from` left of `to`. Longest-path columns (cycles broken, never hung on); `rank(node)` answering `'source'` or `'sink'` puts a node in the first or the last column; barycentre sweeps reduce crossings, keeping the order with the fewest (the order given included); `sizeOf(node)` → `{width, height}` (default the node's own `width`/`height`, else 160 × 80) sizes the columns; components no line joins are stacked top to bottom, the largest first, `componentGap` apart. Returns a Map of id → the top-left `{x, y}` from (0, 0). Pure; 300 nodes and 400 edges take a few milliseconds |
 | `new NodePlatform({collapsedPorts})` | The nodes and their ports: `hydrate(nodes)`, `get`, `all`, `port`, `setPosition`, `setCollapsed`, `visiblePorts(id)`, `on(event, fn)` (`hydrated`, `moved`, `collapsed`). A node is `{id, position, size, collapsed, ports, …}`; any other key is kept |
 | `new ConnectorRouter({platform, selfReference, policy, endsOf, disabledEnds, strings})` | Edges and whether a drop may become one. `canConnect(source, target, {pendingEdges})` refuses, in order, a node that is gone, a port that is gone, a disabled port (with its `disabledReason`), a self-reference (unless `selfReference`), and a port at its `maxConnections`. Only then does it ask your `policy(ctx)`, which may refuse, allow, or answer `{ok: true, offer}`. Also `hydrate`, `edges` (a Map), `edgesFor`, `stage`, `unstage`, `remapNodeConnections(nodeId, portIds)` (keeps the edges whose ports survive and reports the rest) |
 | `new HistoryService({actions, apply, onState, limit, requires, refusal})` | Undo over recorded edits (deltas), behind a closed action list: `record` throws on any action you did not declare. Nothing is recorded before `hydrated()`, and a batch (`startBatch`/`endBatch`) is one entry. Also `undo`, `redo`, `reset`, `adopt`, `undoStack`, `redoStack`, `canUndo`, `canRedo`. A missing `actions`, `apply` or anything named in `requires` throws at construction, not at the first silent no-op |
@@ -1197,38 +1855,183 @@ editor.setRunOverlay({ steps, ports, banner });
 | `widgets`, `references`, `strings`, `services` | The kit's widget registry, the reference syntaxes by name, your words (`CANVAS_STRINGS` and the kit's), and your bag, handed to every widget unchanged |
 | `values` | *Insert a value*: called with `{graph, stepId, field, key, before, loops}`, where `before` is the steps that always run before this one (`alwaysBefore`, nearest first) and `loops` the loops around it. Returns groups, or `{groups, note}` |
 | `summarise(node, type)` | A line under a node's ports. `summariseReads(node, type)` is the panel's id line |
-| `dataPortRead(node, port)` | How a data port is read, in your syntax. It is shown on the port, which cannot be connected |
+| `dataPortRead(node, port)` | How a data port is read, in your syntax. It is shown on the port, which cannot be connected (unless `connections.dataPorts` is `'connect'`) |
+| `connections` | `{dataPorts: 'connect', policy(ctx)}`, absent by default, and then nothing below is drawn or bound. With it every line is asked, in order: what the canvas cannot draw (`canConnect` with `dataPorts`: a data port connects only to a data port, and a data output carries any number of lines); the kernel's `ConnectorRouter` over the catalogue ports, which take its descriptor keys (`disabled`, `disabledReason`, `maxConnections`, `allowMultiple`); the port types (an input's `accepts: ['number']` refuses an output whose `provides` names none of them, in a sentence); and your `policy(ctx)` — the router's context plus `connection` and a copy of the `graph` — which may refuse with a `reason`, allow, or answer `{ok: true, offer: {message, accept, apply(draft)}}`. An offer is shown with Accept and Not now: Accept makes the line and runs `apply` on a copy of the graph (change it in place or return a new one), as one undo entry. An output can also be dragged: while it is, the inputs it may end on carry `twm-flow-graph__port--can-drop`; released on one it connects; released on the empty canvas it opens the step picker with the types that have an input it may connect to, and the step picked is added with the line as one `flow:node:add` |
 | `flowSettings` | `{title, schema, value}` — the flow's own settings, edited as `flow:settings` |
 | `readOnly` | `false`, or `{reason}`, which is shown above the editor. Every verb is then refused with that reason, and no gesture writes |
-| `actions` | Your toolbar verbs, `[{id, label, icon, primary, danger, title, run(editor)}]`, after Undo, Redo, Arrange and Fit |
+| `actions` | Your toolbar verbs, `[{id, label, icon, primary, danger, title, run(editor)}]`, after Undo, Redo, Arrange and Fit (and the zoom buttons, with `zoomControls`) |
 | `slots` | `toolbarEnd(el)`, `flowPanel(el, editor)` and `stepPanel(el, node, editor)`, drawn by you; `setRunOverlay` redraws the panel slots and nothing else |
-| `onChange`, `onSelect` | After every committed edit. An undo or a redo is a change too (`action: null`, `via: 'undo' \| 'redo'`), because you autosave what is undone. `onSelect({kind, id})`: `step`, `flow`, `connection` (with `connection`) or `null` |
+| `onChange`, `onSelect` | After every committed edit. An undo or a redo is a change too (`action: null`, `via: 'undo' \| 'redo'`), because you autosave what is undone. `onSelect({kind, id})`: `step`, `flow`, `connection` (with `connection`) or `null`; with `multiSelect`, two or more picked steps are `{kind: 'many', ids}`; with `notes`, a picked note is `{kind: 'note', id}` and a pick with notes in it `{kind: 'many', ids, notes}` |
+| `multiSelect` (0.17.0) | `true` makes the pick a set (below, *Many picked*). Without it none of it is bound or drawn |
+| `groups`, `notes` (0.17.0) | `true` draws the graph's groups as frames behind their steps and its notes as text on the canvas, and lets the reader make and edit them (below, *Groups and notes*). Without them none of it is bound or drawn, and a graph's groups and notes are kept as they are |
+| `clipboard`, `prepareCopy(node, {from, via})` (0.17.0) | `true` keeps what Ctrl/⌘+C copies inside the editor while it is open; `{read(), write(text)}` hands it to you: `write` hears the copied JSON and `read` (text, or a promise of it) supplies what Ctrl/⌘+V pastes. `prepareCopy` may change a copy's `config` and `label` before it is added (`via`: `'paste'` or `'duplicate'`). Unset, Ctrl/⌘+C, X, V and D are not the editor's (below, *Copy and paste*) |
 | `loop`, `waitsForAll` | The loop's port names (`{entry: 'in', next, body, done}`): a line into a loop-role step on any input but `entry` is its body going back round, drawn dashed under both steps. `waitsForAll(join)` goes to `alwaysBefore` |
 | `removable(node, type)` | Whether a step may be removed. By default every step except a start step |
 | `node` | `{width: 208, header: 34, row: 22}` (`CANVAS_NODE`). Lines are anchored by arithmetic over these numbers, and the stylesheet is held to them |
+| `edgeStyle(connection, {source, target, back})` | How a line is drawn, asked for each line on every paint with copies of its two steps (`back`: it is a loop's line back). Returns `null` or `{tone, dashed, width, marker, label}`: `tone` is one of `TONES`, `width` a stroke width, `marker` `'arrow'` or a crow's-foot kind (`'many'`, `'one'`, `'zero-or-many'`, `'one-or-many'`, `'zero-or-one'`, `'exactly-one'`) drawn at the input end, and `label` text drawn at the line's midpoint, above the steps (a press on it picks the line). A picked or highlighted line still shows as one. Unset, the lines are drawn exactly as before |
+| `routing` | `'simple'` (the default: direct curves) or `'obstacles'`: each line is bent round the steps between its ends by the kernel's `routeEdge`, up to `OBSTACLE_ROUTING_NODE_LIMIT` steps. Above that the lines are direct curves and the findings strip says so (code `canvas-routing-simple`) |
+| `hoverHighlight` | `true`: the pointer over a step gives its lines `twm-flow-graph__edge--highlighted`, and over a line that line; leaving takes it away |
 | `history`, `gridSize`, `label` | `{limit, mergeMs}`, the snap grid, and the canvas's accessible name |
+| `viewport`, `onViewportChange(viewport)` | Where the reader looks, kept by you: the editor stores none of it. `viewport` (`{scale, tx, ty}`, as `getViewport()` gives it) is where the first `load` opens, instead of fitting. `onViewportChange` hears ONE report per finished gesture of the reader's (a pan's release, a run of wheel turns once the wheel has been still for 300 ms, Fit, Arrange, a zoom button, a minimap click, *Go to it*), never one per pointer move, never a gesture that ended where it began, and never what you set yourself (`load`, `setViewport`, `fit()`, `arrange()`). A wheel report still waiting is handed on by the next press and by `destroy` (0.17.0) |
+| `zoomControls` | `true` adds Zoom out, Zoom in and 100% after Fit. They step through 15%, 25%, 33%, 50%, 67%, 80%, 100%, 125%, 150%, 200%, 300% and 400%, about the centre of the view. At the kernel's limits the button is refused in place with its sentence. Off by default (0.17.0) |
+| `renameInPlace` | `true`: a double-click on a step's title edits its name on the node ([Edited on the node](#edited-on-the-node-0170)). Off by default, and then a double-click does nothing (0.17.0) |
+| `collapsible` | `true` puts a fold button on every step's header: it folds the step to its header and back, one `flow:node:collapse` entry each way (below, *Live values and folded steps*). Off by default, and then there is no button in the DOM and a `collapsed` flag in a graph is carried through untouched, the step drawn unfolded (0.17.0) |
+| `minimap` | `true` draws a small overview over the canvas's lower right corner, with the steps and the view's frame, redrawn when the canvas changes size as well as when the view moves. A click on it centres the view on that point, at the same scale. Off by default, and then there is no minimap in the DOM (0.17.0) |
+| `layout` (0.17.0) | What Arrange does. `'flow'` (the default): in the order a run takes the steps, from the start step(s). `'layered'`: the kernel's `layeredLayout` over the lines, with each type's `rank` key (`'source'` or `'sink'`, read by the catalogue's `rank(typeId)`) as its hint. Or your own `fn(graph, ctx)` returning a Map of id → `{x, y}` from the origin (a step it leaves out stays where it is; a place that is not finite numbers `{x, y}`, like anything but a Map, throws), handed a copy of what is arranged and `ctx = {catalogue, node, ids, sizeOf(node), layeredLayout}` (`ids` is `null` for the whole graph). With `multiSelect` and several steps picked, the toolbar's Arrange lays out only those steps and the lines between them, and only they move. The places are anchored at the top-left corner of what is arranged and snapped to the grid |
 
 | Method | Does |
 |---|---|
-| `load({graph, flowSettings}, {baseline = true, fit = true})` | Replaces the content. A baseline clears both stacks. With `baseline: false` the stacks are kept, and the loaded content becomes the present they undo from |
+| `load({graph, flowSettings}, {baseline = true, fit = true, viewport})` | Replaces the content. A baseline clears both stacks. With `baseline: false` the stacks are kept, and the loaded content becomes the present they undo from. With `viewport` it opens there and does not fit |
+| `getViewport()`, `setViewport({scale, tx, ty})` | The kernel's viewport, as a copy; and putting the view there, clamped to the kernel's limits. `setViewport` drops a fit still waiting for its frame, is not reported to `onViewportChange`, and answers `false` (changing nothing) for anything that is not three finite numbers with a scale above 0 (0.17.0) |
 | `getGraph()`, `serialise()`, `snapshot()`, `getFlowSettings()` | A copy of the graph; its byte-stable text; the text the history holds (graph and settings); the settings |
 | `setFindings(list)`, `setRunOverlay(overlay \| null)`, `setReadOnly(false \| {reason})` | — |
+| `setNodeValues({[id]: {badge, tone, ports: {[name]: text}}} \| null)` (0.17.0) | What you show on the steps right now, replacing what you showed before. Painted in place: no undo entry, no `onChange`, nothing rebuilt and the panel untouched (below) |
+| `setCollapsed(id, collapsed)` (0.17.0) | With `collapsible`: fold a step to its header (`true`) or unfold it, one `flow:node:collapse` entry. `false` when refused (no `collapsible`, read only, no such step, or no change) |
 | `setActionState(id, {disabled, reason, busy})`, `setStatus(text)`, `setMessage(text, tone)` | A verb refused in place, with its reason printed beside the toolbar; the status line; the gesture line |
-| `select(id \| 'flow' \| null)`, `repaintPanel()`, `focus()`, `undo()`, `redo()`, `arrange()`, `fit({whole})` | — |
+| `align(kind)`, `distribute(axis)` (0.17.0) | With `multiSelect`: line the picked steps up (`'left'`, `'center'`, `'right'`, `'top'`, `'middle'`, `'bottom'`; two or more picked) or give them equal gaps (`'horizontal'`, `'vertical'`; three or more), one `flow:nodes:align` entry. `false` when refused (too few picked, read only, or no `multiSelect`); an unknown kind or axis throws |
+| `copy()`, `cut()`, `paste(text?)`, `duplicate()` (0.17.0) | With `clipboard`: the keys' verbs from code. Each answers `{ok: true, ids}` (the steps copied, cut or made) or `{ok: false, reason}`, the reason also on the message line; `paste()` answers a promise when your `read` is async, and `paste(text)` pastes that text. Without `clipboard`: `{ok: false, reason: null}` |
+| `select(id \| [id, …] \| 'flow' \| null)`, `repaintPanel()`, `focus()`, `undo()`, `redo()`, `fit({whole})` | `select([id, …])` (0.17.0, `multiSelect`) picks several steps at once (unknown ids are left out; one left is one step picked, none lets go) |
+| `group(ids?, {label, tone})`, `ungroup(groupIds?)`, `setGroup(id, {label, tone})`, `setGroupMembers(id, ids)` (0.17.0) | With `groups`: group these steps (by default the picked ones), each leaving the group it was in, and answer the new group's id (`group`, `group-2`, …) or `null`; remove these groups (by default the ones the picked steps are in), their steps staying put; a group's name and tone; exactly these members, none removing the group. One `flow:group:add`, `…:remove`, `…:label` or `…:members` entry each, `false`/`null` when refused (read only, nothing to do) |
+| `addNote({text, position, size})`, `editNote(id, text)`, `moveNote(id, {x, y})`, `removeNote(id)` (0.17.0) | With `notes`: a note at `position` (by default the centre of the view), answered as a copy (`note`, `note-2`, …) or `null`; its text; where it is; taking it away. One `flow:note:add`, `…:edit`, `…:move` or `…:remove` entry each |
+| `setCatalogue(catalogue \| types)` | Swaps the step types while the editor is open, for a type registered after `load`: the palette is redrawn and a node whose type's definition changed is rebuilt, so a node of a type that was unknown now draws. A definition is compared by what the node is drawn from (known or not, `icon`, `label`, tone, ports, `render`, `update` and `inline`), not by object identity: a new catalogue of the same types plus one more rebuilds no node and calls no `render` again. Under the `connections` option the connection rules and the empty-drop picker judge by the new catalogue, and a pending offer is taken away. The graph and the history are untouched (0.17.0) |
+| `arrange({ids})` | Arrange the whole graph, as the toolbar's button does when fewer than two steps are picked. With `ids` (0.17.0), only those steps and the lines between them are laid out and only they move, still one `flow:arrange` entry; fewer than two known steps, or a read-only editor, answers `false` |
 | `history`, `canvas` | The editor's `FlowHistory` (`keep()`, `adopt(kept, editor.snapshot())`, `baseline(editor.snapshot())` for your publish) and its `CanvasAdapter` |
-| `destroy()` | Removes every listener, the ghost of a drag and any picker it opened. It saves nothing, because the editor holds nothing |
+| `destroy()` | Removes every listener, the ghost of a drag, the minimap and any picker it opened. It saves nothing, because the editor holds nothing; a viewport report still waiting for the wheel to settle is handed to `onViewportChange` first |
 
 Its edits are the closed list `CANVAS_ACTIONS`: `flow:node:add`,
 `flow:node:remove`, `flow:node:move` (one per drag), `flow:edge:connect`,
 `flow:edge:disconnect`, `flow:node:label`, `flow:node:config`,
-`flow:settings`, `flow:arrange` (one entry for the whole layout). Typing a name
+`flow:settings`, `flow:arrange` (one entry for the whole layout), and with
+`multiSelect` `flow:nodes:move`, `flow:nodes:remove` and `flow:nodes:align`
+(0.17.0; one entry per gesture on several steps), with `clipboard`
+`flow:paste` and `flow:node:duplicate` (0.17.0; one entry per paste or
+duplicate, however many steps it makes), with `collapsible`
+`flow:node:collapse` (0.17.0), and with `groups` and `notes`
+`flow:group:add`, `flow:group:remove`, `flow:group:label`,
+`flow:group:members`, `flow:note:add`, `flow:note:remove`, `flow:note:edit` and
+`flow:note:move` (0.17.0). Typing a name
 or a setting is one entry. The geometry under it is exported as well, all of it
 pure: `CANVAS_NODE`, `arrangeCanvasGraph(graph, catalogue, {loopEntry})` (where
 Arrange puts each step: a Map of id → `{x, y}` from the origin),
-`canvasPortAnchor`, `canvasNodeBottom` and `isCanvasReturnEdge`.
+`canvasPortAnchor`, `canvasNodeBottom` (both fold a node with `collapsed: true`
+to its header, or as the box's `folded(node)` says; 0.17.0), `canvasNodeWidth` (a type's own
+`size.w`, else the box's; 0.17.0), `isCanvasReturnEdge`,
+`canvasPathPoints(d, {steps})` (the points along a drawn line's path `d`:
+absolute `M`, `L`, `C`, `S` and `Z`, each curve sampled at `steps` points) and
+`canvasPathMidpoint(d)` (the point halfway along it by length, where a style's
+`label` sits).
+
+#### Node bodies (0.17.0)
+
+A catalogue type can draw its own controls and values inside its node:
+
+```js
+const gauge = {
+    type_id: 'gauge', label: 'Gauge', ports, size: { w: 280, h: 170 }, accent: 'teal',
+    render(body, node, ctx) {                 // once, when the node is built
+        const range = document.createElement('input');
+        range.type = 'range';
+        range.addEventListener('change', () => ctx.setConfig({ level: Number(range.value) }));
+        body.append(range);
+    },
+    update(body, node, ctx) {                 // after render, and on every repaint
+        body.querySelector('input').value = node.config.level ?? 50;
+        body.querySelector('input').disabled = ctx.readOnly;
+    },
+};
+editor.setCatalogue(createStepCatalogue([...types, gauge], { categories }));   // after load too
+```
+
+- **The body sits below the ports** and is built once with the node. `update`
+  runs on the same element on every repaint, so a control inside it keeps its
+  focus and what was typed into it. `node` is a copy: the body writes only
+  through `ctx`. A later `setCatalogue` keeps that body too, unless the type's
+  own definition changed (its ports, `label`, `icon`, category tone, `render`
+  or `update`): then the node is built again and `render` runs again. A new
+  `size` or `accent` is applied in place.
+- **`ctx`** is `{setConfig(patch), readOnly, values, services}`. `values` is
+  what `setNodeValues` shows on this step now (`{badge, tone, ports}`, a copy),
+  or `null`. `setConfig` merges
+  `patch` into the node's config (an `undefined` value removes the key) as one
+  `flow:node:config` edit: one undo entry, and `onChange` is called. It is
+  refused (answers `false`) while the editor is read only, from inside
+  `render` or `update`, and when a value in `patch` cannot be cloned (a
+  function, a DOM node): then nothing is written. `services` is the editor's `services` option.
+- **`size: {w, h}`** is the node's box in pixels; either may be left out. Lines
+  leave a node's outputs at its own width, and a node with `h` is exactly that
+  tall, its body taking what is left. A body node without `h` is as tall as
+  it is drawn. Arrange spaces its columns by the widest node.
+- **`accent`** is a tone (`violet`, `teal`, `amber`, `grey`, `blue`, `indigo`),
+  drawn as a stripe over the node's header.
+- **A `render` that throws** leaves that node drawn as a type without a body
+  is, and what it threw is one of the editor's own findings: on the node and
+  in the strip, beside yours from `setFindings`. An `update` that throws keeps
+  the body and says so the same way until it succeeds. No other node is
+  affected.
+- A type without these keys is drawn exactly as before, with the same markup,
+  and `serialise()` is unchanged.
+
+#### Edited on the node (0.17.0)
+
+```js
+const counter = { type_id: 'counter', label: 'Counter', ports, inline: ['count'],
+                  config_schema: { type: 'object', properties: { count: { type: 'number' } } } };
+const editor = createCanvasEditor(host, { catalogue: [counter], renameInPlace: true });
+```
+
+- **`renameInPlace: true`.** A double-click on a step's title puts a text box
+  in its place, the name selected. Enter, or leaving the box, is one
+  `flow:node:label` edit, and none when the name is unchanged. Escape puts the
+  name back and records nothing. An empty name is refused with a sentence on
+  the gesture line and the name stays: on Enter the box stays open
+  (`aria-invalid`), on leaving it the box closes. Read only, a double-click
+  opens nothing, and going read only closes an open box without writing. The
+  settings panel, if it is showing that step, shows the new name.
+- **A type's `inline` settings** are drawn under the node's ports, above its
+  own body, by the same widget registry as the panel (`widgets`), with the
+  same labels and controls. A change on the node is a `flow:node:config` edit,
+  and the panel shows it at once. A change in the panel, or an undo, redraws
+  the node's control. The control being typed in is never redrawn under the
+  reader; a focused control whose value changes elsewhere (an undo pressed
+  while it holds the focus) is redrawn with its focus and caret kept. Typing
+  on the node and then in the panel are two undo entries. Read only disables
+  the node's controls. A node with inline settings and no
+  `size.h` is as tall as it is drawn.
+- Without the option and the key nothing is bound or drawn: the same markup,
+  and `serialise()` is unchanged.
+
+#### Live values and folded steps (0.17.0)
+
+```js
+const editor = createCanvasEditor(host, { catalogue, collapsible: true });
+editor.setNodeValues({ mix: { badge: '0.42', tone: 'teal', ports: { out: '0.42' } } });   // as often as you like
+editor.setNodeValues(null);                                                               // none shown
+```
+
+- **`setNodeValues`** paints what you are showing right now: `badge` is drawn
+  on the step's header, before its id tag, in a tone of `TONES` when `tone`
+  names one, and each `ports[name]` beside that port. It replaces what the
+  last call showed, and a step it leaves out shows nothing. It extends the run
+  overlay: nothing is rebuilt or recorded, `onChange` is not called, and the
+  settings panel is not touched, so a field being typed into keeps its focus
+  and its selection however often you call it. A type with its own body reads
+  them as `ctx.values`, and its `update` runs for each step whose values
+  changed (a `setConfig` from there is refused, as from any `update`). The
+  badge and port-value elements exist only while there is a value to show;
+  the editor keeps nothing of them past the next call.
+- **`collapsible: true`** puts a fold button on each header. A folded step
+  shows its header only: its port rows, its body and what is drawn under them
+  are hidden, and its lines stay, meeting the middle of the header on its left
+  (lines in) and its right (lines out). Each fold or unfold is one
+  `flow:node:collapse` entry, so Ctrl+Z unfolds a step just folded. The graph
+  carries `collapsed: true` on a folded step, written last in its `serialise()`
+  text; an unfolded step has no `collapsed` key, so a graph that never folded
+  a step is the text it always was. Read only refuses it.
 
 **Gestures.** A node's header moves it. A connection is made by clicking an
-output and then an input, and Escape cancels one in progress. A line is picked
+output and then an input, and Escape cancels one in progress. Under the
+`connections` option an output can also be dragged to an input, or onto the
+empty canvas to pick a step that arrives connected. A line is picked
 by clicking it, and Delete removes it or the picked step. A palette step is
 added by clicking it (at the centre of the view) or by dragging it onto the
 canvas (where it is dropped). The drag uses pointer events and a ghost on
@@ -1239,10 +2042,72 @@ on the node it went down on. Arrange lays the run out left to right, a branch's
 arms in their declared order, from the graph's own top-left corner. Fit frames
 the graph at natural size or smaller; pressing Fit frames all of it.
 
+**Many picked** (`multiSelect: true`, 0.17.0). A left drag on the empty canvas
+draws a marquee and picks every step it touches; Shift-, Ctrl- or ⌘-click on
+a step adds it to the pick or takes it away; Ctrl/⌘+A picks every step and
+Escape lets go. `select([id, …])` picks several from code. Dragging any picked
+step moves them all (`flow:nodes:move`), Delete removes every one that may be
+removed, with their lines (`flow:nodes:remove`; a start step stays), and the
+panel says how many are picked, with their Remove. On the canvas the arrow
+keys nudge the pick one grid step (`gridSize`), ten with Shift; a held arrow is
+one entry. Eight icon verbs after Fit align the pick's left edges, centres,
+right edges, tops, middles and bottoms, and distribute it horizontally and
+vertically, each refused in place with fewer than two (three) picked. Arrange
+lays out only the pick and the lines between them, and nothing else moves. Tab and
+Shift+Tab move the focus from step to step in graph order, and past either end
+Tab is the browser's again, so the keyboard can leave the canvas. Every one of
+these is a single undo entry. In read-only mode a marquee still picks, and no
+gesture writes.
+
+**Groups and notes** (`groups: true`, `notes: true`, 0.17.0). A group is a
+named frame, in one of `TONES` if it has a `tone`, drawn behind its steps and
+round all of them wherever they are. Its title bar is its handle: dragging it
+moves every member (one `flow:nodes:move`; with `multiSelect` the press picks
+them), and a double-click renames it in place (Enter keeps, Escape puts it
+back). Groups are flat and a step is in one at most: Ctrl/⌘+G (or Group on the
+toolbar) groups the picked steps, taking each out of the group it was in, and
+a group left empty goes; Ctrl/⌘+Shift+G (or Ungroup) removes the groups the
+picked steps are in. Removing a step shrinks its group, and removing its last
+member removes the group. Between the steps the frame takes no pointer, so a
+marquee or a pan can start inside it. A note is free text on the canvas: Note
+on the toolbar adds one at the centre of the view and opens it for typing; a
+double-click, or Enter on a focused note, opens it again (Ctrl/⌘+Enter or
+leaving the box keeps the text, Escape puts it back); dragging it moves it,
+and Delete removes the picked one. With `multiSelect` a marquee picks notes
+with the steps, Shift/Ctrl+click adds or takes one away, Ctrl/⌘+A picks them
+too, and dragging or deleting the pick takes its notes along, one entry. A
+graph keeps them as `groups` and `notes` (see `normalise` above) and
+`serialise()` writes them after the connections; a graph without any is the
+same text as before.
+
+**Copy and paste** (`clipboard`, 0.17.0). Ctrl/⌘+C copies the picked steps
+and the lines among them; a line to a step left out of the pick is not copied,
+nor is a step whose type the palette does not offer (a start step) or that is
+`unavailable`. What is copied is the graph's own text, `{nodes, connections}`
+as `serialise()` writes it, so a graph from elsewhere pastes too. Ctrl/⌘+V
+gives every pasted step a fresh id (as a new step gets one), keeps the lines
+between them, sets the copy off two grid steps right and down (each further
+paste of the same text one more), picks it, and is one `flow:paste` entry. A
+paste right after Ctrl/⌘+X puts the steps back where they were; a cut is one
+remove entry. A step whose title the flow already has gets a derived label,
+`Title (copy)`, then `Title (copy 2)`, …, as the lanes editor's duplicate does.
+Ctrl/⌘+D does the same beside the pick without touching the clipboard, as one
+`flow:node:duplicate`. With nothing picked Ctrl/⌘+C, X and D are not the
+editor's. What is not steps, or names a type the flow does not have, is refused
+with its sentence on the message line. In read-only mode copying still works,
+and Paste, Cut and Duplicate are refused with the read-only reason and change
+nothing. With `notes` the picked notes are copied, cut and duplicated with the
+steps (a note alone too), and pasted under fresh ids, set off as the steps
+are; with `groups` a group whose every member is copied is in the copy, and a
+paste makes it again round the copies of its members (a fresh id, its name and
+tone kept), while a group with a member left out is not copied. `copy()` and
+`cut()` answer `notes: [id, …]` and `paste()` and `duplicate()` answer `notes`
+and `groups`, each only when there are some.
+
 **Keys** (bound on the editor's root): Ctrl/⌘+Z and Ctrl/⌘+Y or Ctrl/⌘+Shift+Z,
 stopped at the root even inside a text field; Delete; F2 renames the picked
-step; Enter on a focused node opens its settings; Escape. Backspace is never
-the editor's.
+step; Enter on a focused node opens its settings; Escape; with `groups`,
+Ctrl/⌘+G and Ctrl/⌘+Shift+G. Backspace is never the editor's.
 
 **What it does not do.** It does not load, save, validate, publish or run
 anything, and it does not keep the stacks across page loads. Those belong to
@@ -1251,9 +2116,9 @@ flow opens on a start step adds that step to the graph before `load`, so it is
 part of the baseline and the first Ctrl+Z does not take it away.
 
 **Where each claim was checked.** `tests/canvas_adapter.test.mjs`,
-`canvas_edge_router`, `canvas_graph`, `flow_canvas_layout`, `flow_canvas_editor`
-and `flow_canvas_css` check the DOM, the events, the geometry and the stylesheet
-as text. In headless Edge, `demo/flow_canvas_probe.mjs` drives
+`canvas_edge_router`, `canvas_graph`, `flow_canvas_layout`, `flow_canvas_editor`,
+`flow_canvas_multiselect`, `flow_canvas_clipboard`, `flow_canvas_node_body`, `flow_canvas_live_values`, `flow_canvas_groups_notes` and `flow_canvas_css` check the DOM, the events, the
+geometry and the stylesheet as text. In headless Edge, `demo/flow_canvas_probe.mjs` drives
 `demo/flow_canvas.html` with real input:
 - `elementFromPoint` at the centre of Undo, Arrange, Fit, a consumer verb, a
   palette item, a node's header, a port, and the panel's name box, first field
@@ -1266,8 +2131,43 @@ as text. In headless Edge, `demo/flow_canvas_probe.mjs` drives
 - A real click-then-click connected two steps.
 - A header drag moved its node, and a real Ctrl+Z put it back. Backspace removed
   nothing, Delete removed the step, and the focus stayed on the canvas.
+- On a 300-step graph with `multiSelect`, a real marquee picked three steps, a
+  real drag of one moved all three and one real Ctrl+Z put them back; a move
+  of 50 picked steps and its undo each finished in under 100 ms.
+- With `groups` and `notes`, a real Ctrl+G on two picked steps drew one frame
+  round both and not round the third. Its title bar, and a step inside it, were
+  each the element at their own centre, and between the steps the canvas was
+  (the frame takes no pointer). A real drag of the title bar moved both by the
+  pointer's travel as one entry, and one real Ctrl+Z put them back. A real
+  double-click opened a note for typing, real keys and Ctrl+Enter kept the
+  text, a real drag moved it, and a real marquee picked the steps and the note
+  together.
+- With `collapsible`, ten `setNodeValues` calls 100 ms apart each put their
+  value on the step's badge, inside its header, while real keys typed into a
+  settings field: the field kept the focus and every key, and the values made
+  no undo entry and no `onChange`. A real click on a header's fold button hid
+  every port row and left the step as tall as its header, with its lines
+  ending on the header's middle at its edges, within 1px; a real Ctrl+Z
+  unfolded it and its lines met their port dots again.
+- A type registered with `setCatalogue` after the page opened was in the
+  palette. Its node was drawn at its 280×170 size, with its body below its
+  ports and its accent. Every line into and out of it began and ended on its
+  port dots, within 1px.
 - At 700px the canvas took the editor's whole width.
 
+`tests/flow_canvas_edge_style.test.mjs` checks `edgeStyle`, `routing` and
+`hoverHighlight` in the DOM, and `demo/flow_canvas_edges_probe.mjs` in headless
+Edge:
+- A dashed line had a computed dash pattern, and an unstyled line kept its old
+  stroke and width.
+- An arrowhead's tip sat on the input port's centre line, and the line ended at
+  its base.
+- A label sat on its line's midpoint over a step, and `elementFromPoint` there
+  returned the label.
+- With `routing: 'obstacles'`, no point of a line lay inside the drawn box of
+  the step between its ends. Above the node limit the strip said so.
+- A real pointer over a step highlighted its lines, and moving off cleared them.
+
 ### The outline editor
 
 `createOutlineEditor` draws a logic flow as a list of blocks: *If … otherwise*,
@@ -1497,8 +2397,14 @@ input (`lanes_two_inputs`), a cycle (`lanes_cycle`) or two steps with one id
 read only with the sentence, is drawn as well as it can be, and is never
 repaired. The sizes are `LANE_GEOMETRY`: `regular` is 200 × 62 (the editor),
 `small` is 160 × 50 (two lines a card, for a narrower host) and `strip` is
-92 × 26 (`compact`). The pure edits — splice, add a source, remove, set an
-input, the input candidates, parameters — are `lanePipeline`.
+92 × 26 (`compact`). The pure edits — splice, add a source, remove, duplicate,
+set an input, the input candidates, parameters — are `lanePipeline`.
+`lanePipeline.duplicateStep(pipeline, catalogue, id)` (0.17.0) puts a copy right
+after the step: a fresh id, a label derived from its title (`Title (copy)`, then
+`(copy 2)`, …, words in `LANE_PIPELINE_STRINGS`), a deep copy of its config and
+the same lines in, none out. It answers `{ok: true, node}`, or `{ok: false,
+reason}` and changes nothing when there is no such step or its type is
+`unavailable`.
 
 | Option | Meaning |
 |---|---|
@@ -1520,6 +2426,7 @@ input, the input candidates, parameters — are `lanePipeline`.
 | `parameterTypes` | The parameter types a parameter may be: `text`, `number`, `integer`, `boolean`, `date` by default |
 | `select` | The step chosen on load (the first step, left to right, by default) |
 | `history` | `{limit, mergeMs}` |
+| `menuItems(step)` | Your own items on a card's menu, after the built-in ones: `[{id, label, icon?, danger?, disabled?, reason?, run}]`. `run({step, pipeline, editor})` gets a DRAFT of the flow to change in place (it may answer later, with a promise); what it changed is one undoable edit, `flow:step:menu`. Answering `false` takes nothing, and neither does a draft that answers after another edit. `disabled` greys the item with its `reason`; a read-only flow greys every one with the read-only reason (0.17.0) |
 | `onChange`, `onSelect({kind, id})`, `onStepsShow(mode)` | Callbacks |
 
 | Method | Does |
@@ -1532,12 +2439,16 @@ input, the input candidates, parameters — are `lanePipeline`.
 | `setReadOnly(false \| {reason})`, `readOnly` | — |
 | `setActionState(id, {disabled, reason, busy})`, `setStatus(text)` | A refused verb shows its reason beside it |
 | `select(id \| 'flow' \| null)`, `selected`, `focus()` | — |
-| `undo()`, `redo()`, `history` | Over whole snapshots. The actions are `LANE_ACTIONS` (`flow:step:add`, `:remove`, `:label`, `:config`, `flow:join:set`, `flow:source:add`, `flow:parameter:add`, `:change`, `:remove`, `flow:settings`) |
+| `undo()`, `redo()`, `history` | Over whole snapshots. The actions are `LANE_ACTIONS` (`flow:step:add`, `:remove`, `:label`, `:config`, `:duplicate`, `:menu`, `flow:join:set`, `flow:source:add`, `flow:parameter:add`, `:change`, `:remove`, `flow:settings`) |
 | `refreshPreview()` | Asks the providers now, without the debounce |
 | `inputColumns(stepId, port?)` | The columns of the frame a step reads, from the last description, else the last preview. The `upstream-column(s)` widgets read the same |
 | `layout`, `placed` | The current layout and its coordinates |
 | `destroy()` | Removes every listener, popover and table, and aborts the preview in flight |
 
+**Columns that arrive while you are in the settings** are drawn when the focus
+leaves them, so a column typed by name before the columns were known becomes a
+choice then, and nothing is rebuilt under the reader's caret.
+
 **The preview** is one request for the whole flow to each provider. It is sent
 800 ms after the last edit and once after a load. A rename does not send one,
 because it changes no row. Every request carries a sequence number and an
@@ -1550,10 +2461,14 @@ business; the editor knows only what it is handed.
 
 **Keys.** These are the kit's, on the editor's root. ← → ↑ ↓ move between cards
 and between the step tabs. Enter opens a step's settings on their first field,
-and Escape goes back to the card. Delete removes the step and F2 renames it.
+and Escape goes back to the card. Delete removes the step, Ctrl/⌘+D duplicates
+it (the copy is chosen and focused) and F2 renames it.
 Ctrl/⌘+Z and Ctrl/⌘+Y undo and redo, and are stopped at the editor even inside
 a field. The context-menu key or a right press opens a card's menu: *Open its
-settings*, *Add a step after it*, *Remove step*. Backspace is never the
+settings*, *Add a step after it*, *Duplicate*, *Remove step*, then your
+`menuItems`. An item that cannot be chosen — *Duplicate* on a read-only flow, or
+on a step whose type is not available — is greyed with its reason in its own
+line, and a refused Ctrl/⌘+D says the reason beside the status. Backspace is never the
 editor's. The cards are one Tab stop, the chosen one, and its "+" comes next in
 the Tab order. The "+" shows on hover, on focus and on the chosen card, never
 on hover alone.
@@ -1593,9 +2508,15 @@ keystrokes ask the preview once.
 `openForm({ title, fields, defaults, submitLabel })` (in `@flexdesk/widgets`)
 opens a modal form and resolves with `{ [name]: value }`, or `null` when it is
 cancelled. Fields are `text`, `number`, `password`, `select`, `textarea`,
-`checkbox` and `picker`; `{ section: 'Label' }` entries are headings. Each of
-the four additions below is opt-in, and a form that uses none of them renders
-and submits exactly as in 0.9.1.
+`checkbox`, `toggle`, `picker`, `checklist`, `radio`, `color` and `colorList`;
+`{ section: 'Label' }` entries are headings and `{ row: [...] }` entries put
+fields side by side. The additions below are opt-in, with one change every form
+sees, even one that uses none of them: a `select` or `radio` comes back with
+its option's OWN value and type (a numeric option submits `2`, not `'2'`; an
+option whose value is `null` submits `null`), a default of that type selects
+its option (`defaults: { s: 2 }` selects the option whose value is `2`), and an
+option object with no `label` shows its value. A select with no option
+selected still reads and submits `''`.
 
 ### A form that adapts: `onFieldChange`
 
@@ -1619,12 +2540,23 @@ openForm({
 every field's `change`. `api` addresses fields and named sections by name:
 
 - `setVisible(name, on)` hides or shows the row. A hidden row keeps its value
-  and is still submitted, but it is not asked about: its `required` and its
+  and is still submitted (a disabled option it holds submits as no value:
+  `''` for a select or combobox, `null` for a radio), but it is not asked
+  about: its `required` and its
   `validator` stand down until it is shown again.
-- `get(name)` reads the control as it stands: a checkbox as a boolean,
-  anything else as its string.
+- `get(name)` reads the control as it stands: a checkbox as a boolean, a
+  select or radio as its option's own value (a select with no option selected
+  as `''`, a radio with none as `null`), a combobox as the value of the option
+  its text names — exactly what it submits — or as its text when it names
+  none, a checklist as the array of chosen values, anything else as its
+  string.
 - `set(name, value)` writes it. It does not call `onFieldChange` back, so a
-  hook that fills one field from another cannot loop.
+  hook that fills one field from another cannot loop. A value a select or
+  radio does not offer, or offers only disabled, clears it (a select then
+  submits `''`, a radio `null`).
+- `setOptions(name, options)` replaces the options of a `select` (a
+  combobox's suggestions too), `checklist` or `radio` while the form is open
+  — see below.
 
 A hook that throws is logged and the form carries on.
 
@@ -1666,6 +2598,571 @@ submit with "onCreate is not a function".
 `tests/open_form.test.mjs` mounts the real `openForm` in jsdom and covers all
 four, plus a plain form submitting as before.
 
+### Options: typed, unavailable, grouped, and changed while open (0.17.0)
+
+```js
+openForm({
+    fields: [
+        { name: 'country', label: 'Country', type: 'select', options: ['no', 'it'] },
+        { name: 'town', label: 'Town', type: 'select', options: [] },
+        { name: 'plan', label: 'Plan', type: 'select', options: [
+            { value: 1, label: 'Free' },
+            { value: 2, label: 'Pro', disabled: true, reason: 'needs a licence' },
+            { group: 'Teams', options: [{ value: 10, label: 'Small team' }, { value: 50, label: 'Large team' }] },
+        ] },
+        { name: 'days', label: 'Days', type: 'checklist', required: true,
+          options: [{ value: 'mon', label: 'Mon' }, { value: 'tue', label: 'Tue' }] },
+        { name: 'mode', label: 'Mode', type: 'radio', options: [
+            { value: 'fast', label: 'Fast', description: 'Skips the checks.' },
+            { value: 'safe', label: 'Safe' },
+        ] },
+    ],
+    onFieldChange: (name, value, api) => {
+        if (name === null || name === 'country') api.setOptions('town', townsOf(api.get('country')));
+    },
+});
+// → { country: 'it', town: 'Rome', plan: 10, days: ['mon'], mode: 'fast' }
+```
+
+An option is a bare value or `{ value, label?, disabled?, reason?,
+description? }`.
+
+- **Values keep their type.** An option whose value is the number 10 submits
+  10, and `api.get` reads 10 — not `'10'`. A default matches an option of the
+  same text, so `defaults: { plan: '10' }` selects 10. A combobox entry typed
+  as an option's text submits (and `api.get` reads) that option's value. An
+  option whose value IS the given one wins over one that only has its text:
+  with options `[1, '1']`, a default `'1'` submits `'1'`.
+- **A disabled option** is shown with its `reason` (in a select's option text
+  and tooltip, under a radio, on a chip) and is never the submitted value: a
+  default naming it does not select it, `api.set` to it clears a select,
+  radio or combobox and leaves a checklist's chip unpressed, the reader
+  cannot pick it, a combobox does not suggest it, and a submit
+  that finds one selected anyway (a script set `.value`, or every option is
+  disabled) is refused with "Not available: *reason*" on the field. In a
+  hidden row, which is not asked about, it submits as no value instead.
+- **`{ group, options }`** in a select's list is an `<optgroup>` headed
+  *group*. In a checklist or radio it is a `.twm-choice__group` heading over
+  that group's chips or rows (a group with no options draws none). A combobox
+  suggests a group's enabled options, without headings.
+- **`api.setOptions(name, options)`** replaces the list while the form is
+  open and keeps the current value when the new list offers it enabled.
+  Otherwise a select falls to its first enabled option, a radio to none and a
+  checklist drops what is gone. It does not call `onFieldChange` back.
+- **`type: 'checklist'`** draws toggle chips and submits the array of chosen
+  values in the list's order (`[]` for none). `required` means at least one,
+  and nothing chosen is "Required." on the field.
+- **`type: 'radio'`** draws one radio row per option, with its `description`
+  under it, and submits the chosen value, or `null`. `required` means one is
+  chosen.
+
+The select, the chips and the radio list are the flow kit's
+(`src/ui/components/choice_controls.js`): the settings panel's `enum` select,
+`enum-chips`, `upstream-columns` and `choice-cards` draw with the same code, so
+a form and a settings panel cannot drift apart. In a form they are classed
+`.twm-flow-togglechips` / `.twm-flow-togglechip` and `.twm-flow-choices` /
+`.twm-flow-choice`; an unavailable option's reason is `.twm-choice__reason`.
+
+`tests/open_form_choices.test.mjs` covers each of these in jsdom.
+
+### Colours: `type: 'color'` and `type: 'colorList'` (0.17.0)
+
+```js
+openForm({
+    fields: [
+        { name: 'accent', label: 'Accent', type: 'color', default: 'rgb(31,119,180)',
+          presets: ['#1f77b4', '#ff7f0e', '#2ca02c'] },
+        { name: 'palette', label: 'Palette', type: 'colorList', default: ['#1f77b4', '#ff7f0e'] },
+    ],
+});
+// -> { accent: '#1f77b4', palette: ['#1f77b4', '#ff7f0e'] }
+```
+
+A `color` row is a swatch that opens the native picker, a hex box kept in step
+with it (picking writes the box; typing a valid hex moves the swatch), and,
+with `presets`, a strip of preset swatches. It submits lowercase `#rrggbb`, or
+`''` when left empty. A `colorList` row is an ordered list of such fields: add,
+remove, and reorder by drag or by the up / down buttons; `presets` are offered
+on every row, and it submits the colours in their current order as an array of
+`#rrggbb`. An `rgb()` / `rgba()` default (or `api.set` value) is shown as its
+hex; alpha is dropped, because the native picker has none. A box that does not
+hold `#rgb` or `#rrggbb` is a field error ("Not a hex colour", with the row
+numbers for a list) and the form does not resolve; `required` on either is
+checked by the form. `api.get` reads a `color` as its box text and a
+`colorList` as the array of its rows' text.
+
+Both are also components of their own in `@flexdesk/widgets`:
+`new ColorField({ value, presets, name, label, onChange })` and
+`new ColorListField({ value, presets, newColor, addLabel, name, onChange })`,
+each with `render()`, `getValue()` (null while something typed is not a
+colour), `setValue()`, `focus()` and `dispose()`; `onChange(value, { commit })`
+reports every edit and, with `commit: true`, every committed one.
+`normalizeHex(value)` (`#rgb`, `#rrggbb`, `rgb()` -> `#rrggbb` or null) and
+`isHexColor(value)` are exported with them, and `validateField` (in
+`@flexdesk/tiles`) now rejects a `FieldTypes.COLOR` value that is not a hex
+colour. The markup is `.twm-color-field` > `.twm-color-field__swatch` +
+`.twm-color-field__hex` (+ `.twm-color-field__presets`), and `.twm-color-list`
+rows are `.twm-color-list__row`. `tests/color_field.test.mjs` covers all of it.
+
+### Number bounds and fields side by side: `min`, `max` and `{ row }` (0.17.0)
+
+```js
+openForm({
+    fields: [
+        { name: 'steps', label: 'Steps', type: 'number', min: 2, max: 200, step: 1 },
+        { row: [
+            { name: 'lo', label: 'Min', type: 'number', hint: 'lowest value' },
+            { name: 'hi', label: 'Max', type: 'number', min: 0 },
+        ] },
+    ],
+});
+// → { steps: 50, lo: 0, hi: 10 }
+```
+
+- **`min` / `max`** on a `number` field are the input's own `min` and `max`
+  attributes, and a value outside them is refused on submit with an error
+  under that field: "Must be between 2 and 200." (or "Must be at least 2." /
+  "Must be at most 200." with only one). The browser's own range check stops
+  such a submit first; the form cancels its bubble and shows the field error
+  instead, and it checks the range itself as well, before the field's
+  `validator`. An empty field that is not `required` is not out of range. A
+  row hidden by `setVisible` drops its bounds until it is shown again, as it
+  drops `required`. As with any `<input type="number">`, a `min` is also where
+  `step` counts from.
+- **`{ row: [field, ...] }`** puts its fields on one line, sharing the width.
+  The row is layout only and has no name: each field in it is an ordinary
+  field with its own label, hint, error, `setVisible`, value and submitted
+  key, so hiding one hides only that one. The first keeps the form's label
+  column; the others size their label to its text. A form narrower than
+  360px stacks them (a container query, `twm-form`, on a form that has a row;
+  a form without one is not made a container). A form with a row opens at the
+  wide (640px) layout. The row is `.twm-modal__field-group`.
+
+A form with neither renders exactly as before.
+`tests/open_form_rows_bounds.test.mjs` covers both in jsdom.
+
+### A switch: `ToggleField` and `type: 'toggle'` (0.17.0)
+
+```js
+import { ToggleField } from '@flexdesk/widgets';
+
+const autosave = new ToggleField({
+    label: 'Autosave', onText: 'On', offText: 'Off',   // all optional
+    checked: true, compact: false, disabled: false,
+    onChange: (on) => settings.set('autosave', on),
+});
+host.appendChild(autosave.render());
+autosave.get();              // true
+autosave.set(false);         // does not call onChange
+autosave.setDisabled(true);
+autosave.dispose();
+```
+
+A track and a knob drawn over a real checkbox with `role="switch"` and an
+`aria-checked` that follows it. Space and Enter toggle the focused switch, a
+click on the track, the state text or the label toggles it, the focused input
+draws a ring on the track, and a disabled switch ignores clicks and keys alike.
+`ariaLabel` names a switch with no visible label. The markup is
+`label.twm-toggle` (`--compact`, `--disabled`) > `.twm-toggle__control` >
+`input.twm-toggle__input` + `.twm-toggle__track` > `.twm-toggle__knob`, then
+`.twm-toggle__state` and `.twm-toggle__label`; `flexdesk.css` styles it from
+tokens alone, with no colour literal.
+
+In a form, `{ name, label, type: 'toggle', onText?, offText?, disabled?,
+compact? }` mounts one and submits a boolean, like a checkbox; `api.get` reads
+it as a boolean and `api.set` moves it. `tests/toggle_field.test.mjs` covers
+both.
+
+## A settings page: `SettingsView` (0.17.0)
+
+`new SettingsView({ store, eventBus })` (in `@flexdesk/widgets`) draws a
+settings store's schema as a page. `store` is a `createSettingsStore()` handle
+or the app-global binding's own, `getSettingsStore()` from `@flexdesk/core`
+(its `set` is the one `setSetting` calls); `eventBus` is the bus that store
+emits on (`registerSettingsEventBus(bus)` for the binding).
+
+```js
+import { getSettingsStore, registerSettingsEventBus } from '@flexdesk/core';
+import { SettingsView, settingsViewContent } from '@flexdesk/widgets';
+
+registerSettingsEventBus(bus);
+const view = new SettingsView({ store: getSettingsStore(), eventBus: bus });
+view.mount(host);
+view.selectCategory('window');
+view.setQuery('shadow');        // what the filter box does
+await view.resetAll();           // asks first; true when it reset
+view.dispose();
+
+// or as tile content (props.category picks the category shown first):
+createShell({ content: { settings: settingsViewContent({ store: getSettingsStore(), eventBus: bus }) } });
+```
+
+The sidebar holds a filter box, every category in `CategoryDef.order` and
+*Reset all*. Beside it the chosen category's settings are listed under its
+title, description and *Reset category*, grouped by `SettingDef.group` in
+schema order. A row shows the label, a *Modified* marker while the value
+differs from its default, the description, the path, its control and a reset
+button. Text in the filter searches every category's labels, descriptions and
+paths; the matches are listed under "Category › Group", and choosing a
+category clears it.
+
+| `type` | Control |
+| --- | --- |
+| `boolean` | a `ToggleField` |
+| `select` | a select over `options`; a value the options lack (stored, or set elsewhere while the view is open) is kept and shown as *value (not found)* |
+| `number` | a number box with `min`, `max` and `step`; a written value is always in the range and on the step grid (`min + k·step`, or `k·step` with no `min`): snapped to the nearest grid point, and one outside the range moved inward to the nearest grid point inside it (with `max` below `min` the range holds none, and the value is `min`); with no `step` it is only clamped; an empty or unreadable box goes back to the value |
+| `text` | a text box, written `textDebounceMs` (default `SETTINGS_TEXT_DEBOUNCE_MS`, 300) after the last keystroke, or at once on Enter or blur; emptied, it writes `null` when the default is `null` |
+| `colorList` | a `ColorListField`, written on each committed edit while every row holds a colour |
+
+A type it does not know shows the value as text, read only.
+
+The view is live both ways: a control writes with `store.set`, and the view
+listens for `settings:<path>:changed` on every schema path, `settings:changed`
+with a null path (the resets) and `settings:registered`, which the store now
+emits from `extend()` / `registerSettings()` with `{ paths, categories }`. So a
+`setSetting` made anywhere moves the open view, and a slice registered after
+mount adds its categories and rows without a remount. A row's reset button
+resets that one setting; *Reset category* and *Reset all* first ask
+`confirm({ title, message, confirmLabel, danger })` (default `openConfirm`) and
+change nothing unless it resolves true. Every label, description, category name
+and query is set as text, so markup in any of them is shown as typed.
+
+Options: `store`, `eventBus` (both required), `confirm`, `category`,
+`textDebounceMs`, `title` (the sidebar heading, and the content factory's tab
+title; default "Settings"). The markup is `.twm-settings` >
+`.twm-settings__sidebar` + `.twm-settings__content`, with rows
+`.twm-settings__row` (`--modified`); `flexdesk.css` styles it from tokens.
+`tests/settings_view.test.mjs` covers it in jsdom.
+
+## A step wizard: `Wizard` (0.17.0)
+
+`new Wizard({ steps, data, onFinish, onCancel, labels })` (in `@flexdesk/widgets`)
+draws a multi-step flow: a step indicator, a body slot and a footer with Cancel,
+Back and Next (Finish on the last step). Mount it inline with `mount(el)`, or in a
+modal `ManagedWindow` with `openInWindow({ id, title, ... })`.
+
+```js
+const wizard = new Wizard({
+    data: { file: null },
+    steps: [
+        { id: 'source', label: 'Source', icon: 'upload_file',
+          render(bodyEl, ctx) {            // once per visit; may return a cleanup function
+              const input = picker(bodyEl);
+              input.onchange = () => { ctx.data.file = input.files[0]; ctx.revalidate(); };
+          },
+          canAdvance: (ctx) => ctx.data.file
+              ? { ok: true } : { ok: false, hint: 'Choose a file first' } },
+        { id: 'review', label: 'Review', render: (bodyEl, ctx) => review(bodyEl, ctx.data) },
+    ],
+    onFinish: async (ctx) => api.import(ctx.data),   // a rejection marks the step as error
+    onCancel: () => {},
+});
+wizard.openInWindow({ id: 'import', title: 'Import' });
+```
+
+- **Gating.** While the current step's `canAdvance(ctx)` answers `{ok: false, hint}`,
+  Next is disabled and the hint is shown in the footer. `revalidate()` (also
+  `ctx.revalidate()`) asks again and redraws the indicator and the footer; it never
+  re-renders the body, so an input keeps its focus and its value.
+- **Steps** are drawn done / current / upcoming / error, joined by a connector. A
+  done step is a button that jumps back to it; an upcoming step is inert, so the
+  only way forward is Next.
+- **Moves.** `next()`, `back()` and `goTo(idOrIndex)` (back to any earlier step, or
+  forward one step through the gate) resolve `true` when they moved.
+  `setStepState(id, 'error' | null, message)` marks or clears a step.
+- **Finish.** On the last step Next reads Finish and calls `onFinish(ctx)`. Until
+  it settles every button is disabled and moves, cancels and closes are refused,
+  not queued. Resolved, the wizard closes; rejected, the step is marked as error
+  and the rejection's message is shown, and Finish can be pressed again.
+- **Cancel** (the button, `cancel()`, or the window's close button and Escape)
+  closes the wizard and calls `onCancel(ctx)` exactly once. `dispose()` tears it
+  down without calling either callback.
+
+Every transition goes through a core `StateMachine` (`step`, `finishing`,
+`finished`, `cancelled`; pass `eventBus` to see its `fsm:*` events). `ctx` is
+`{data, step, index, revalidate, next, back, goTo, setStepState}`, with `data`
+the object you passed.
+
+## Confirms show text, not markup (0.17.0)
+
+`openConfirm({ title, message, confirmLabel, cancelLabel, danger, icon })`
+resolves `true` or `false`. Its `message` and both labels are **text**: they
+are set with `textContent`, so a `<` shows as a `<`. Until 0.17.0 they went into
+`innerHTML`, and `showDeleteConfirmDialog` / `showCloseConfirmDialog` put
+`itemName` and `itemType` into that message raw: a flow named
+`<img src=x onerror=…>` rendered an image and ran its handler, and a name with
+an unclosed `<` swallowed the rest of the message.
+
+A caller that passed markup in `message` now sees the tags; write a `\n` for a
+line break instead (the message body is `white-space: pre-line`).
+`additionalMessage` on `showDeleteConfirmDialog` follows on its own paragraph
+exactly as before. A body that needs real markup is `openModal`'s job: it takes
+the caller's own DOM.
+
+`tests/confirm_escaping.test.mjs` opens each of them in jsdom with hostile
+names and labels.
+
+## Markdown: `renderMarkdown` (0.17.0)
+
+`renderMarkdown(source, options)` (`@flexdesk/widgets`) returns an HTML
+string. It covers a CommonMark-ish subset — ATX headings, paragraphs,
+emphasis, strong, `~~strike~~`, code spans, fenced code, block quotes, nested
+ordered and unordered lists, GFM pipe tables, rules, links, images, autolinks,
+hard breaks and `$…$` / `$$…$$` math — and is **safe by default**:
+
+- raw HTML is escaped: `<img src=x onerror=alert(1)>` shows as that text.
+  `allowHtml: ['kbd', 'br']` lets named tags through, the tag only and never
+  its attributes; a tag that runs or embeds anything (`script`, `iframe`,
+  `svg`, `img`, …) throws. An allowed tag left open is closed at the end of its
+  paragraph.
+- a link goes out only to `http(s):`, `mailto:` or a `#anchor`, always with
+  `rel="noopener noreferrer"`; a `javascript:` link (or any other) renders its
+  text and no anchor. An image loads from `http(s):` or a relative path, or
+  shows its alt text.
+
+```js
+import { renderMarkdown } from '@flexdesk/widgets';
+
+el.innerHTML = renderMarkdown(source, {
+    highlight: (code, lang) => myHighlighter(code, lang),   // null: escaped
+    math: undefined,      // default: window.katex when present, else the escaped source
+                          // false: `$` is text; or (tex, { display }) => html | null
+    inlineRules: [{ pattern: /\[\[ref:([\w-]+)\]\]/, render: (m, ctx) => `<a href="#${ctx.escape(m[1])}">…</a>` }],
+    blockRules:  [{ start: /^:::(\w+)/, end: /^:::$/, render: ({ lines, match, closed }, ctx) => '…' }],
+    inline: false,        // true: inline markup only, no blocks, no <p>
+});
+```
+
+What the caller returns — the highlighter's, the math hook's and the rules'
+HTML — is trusted and goes in as it is; a rule answering `null` declines.
+`ctx` gives a rule `escape(text)` and `inline(text)`. Not in the subset:
+setext headings, indented code blocks, reference links, raw HTML blocks.
+
+**Streaming.** Every element it opens it closes, so each prefix of a document
+arriving token by token renders to balanced HTML: an open fence is closed at
+the end of the input, and an emphasis or link whose closer has not arrived is
+still text. `tests/markdown.test.mjs` renders every prefix of a document using
+every construct and checks the tags balance; `tests/help_modal_markdown.test.mjs`
+checks jsdom has nothing to repair.
+
+**Help topics in markdown.** A `HelpProvider`'s `loadTopic` may now answer
+`{ title, markdown }`; the modal renders it with `renderMarkdown` and the
+provider's optional `markdownOptions`. `{ title, html }` is unchanged:
+pre-rendered, **trusted** HTML, inserted as it is.
+
+**A table of contents for a help topic.** A topic with two or more headings,
+markdown or html, gets its contents between the breadcrumb and the article: a
+`createDocumentOutline` (below) of its `h1`–`h6`, numbered, the one in view
+marked as the content pane scrolls, a click that scrolls to its heading. The
+outline points at the heading elements themselves, so your markup needs no
+ids and the modal adds none; a topic with one heading or none shows no
+contents (the empty `.help-content__toc` is `hidden`). Until now the modal's
+documentation promised this and drew nothing. `tests/help_modal_toc.test.mjs`
+drives it in jsdom (BUG-0010).
+
+## A document outline: `createDocumentOutline` (0.17.0)
+
+A long document's sections, listed and numbered, the one in view marked while
+the document scrolls, and a click that goes to one (in `@flexdesk/widgets`):
+
+```js
+const outline = createDocumentOutline(sidebarEl, {
+    entries: [{ id: 'intro', level: 1, label: 'Introduction' },
+              { id: 'scope', level: 2, label: 'Scope' }],
+    numbering: true,                 // 1, 1.1, 1.2, 2 …
+    maxDepth: 3,                     // deeper entries are drawn at depth 3
+    scrollContainer: articleEl,      // the element that scrolls; the spy's root
+    resolveTarget: (entry, container) => container.querySelector(`[data-section="${entry.id}"]`),
+    rootMargin: '0px 0px -70% 0px',  // the default: the top 30% is "in view"
+    onSelect: (id, entry) => { /* … */ },
+    emptyState: 'No headings',
+});
+outline.setEntries(next);            // the document has other sections now
+outline.refresh();                   // the same sections, re-rendered: resolve again
+outline.setActive('scope');  outline.getActive();
+const off = outline.onActiveChange((id, entry) => { /* … */ });
+outline.dispose();
+```
+
+Where the entries come from is yours: the outline is told `{id, level, label}`
+and, through `resolveTarget` (by default the element in the container whose
+`id` is the entry's), which element each one stands for. Labels are text.
+Numbers are hierarchical, and a skipped level is one step deeper, not two:
+levels 1, 3, 3, 2 are 1, 1.1, 1.2, 1.3.
+
+Of the targets an IntersectionObserver rooted at `scrollContainer` reports in
+view, the one listed first is active; with none in view the last one stays. An
+entry whose target does not resolve is listed, but never watched and never
+active, and `setActive` refuses it (`false`). A click marks its entry at once,
+scrolls its target into view (`scrollOnSelect: false` leaves that to
+`onSelect`) and suppresses the spy while the scroll passes the sections in
+between, until the container's `scrollend` or, without one, `scrollEndTimeout`
+(1000 ms). `dispose()` disconnects the observer and clears that timer. The
+indent per level is `--twm-doc-outline-indent` (12px).
+
+`tests/document_outline.test.mjs` drives it in jsdom with a hand-fired
+observer.
+
+## Action dropdowns: separators (0.17.0)
+
+`new ActionDropdown({ trigger, options, onSelect })` draws one button per
+option. An entry `{ separator: true }` in `options` draws a divider instead: a
+`<div role="separator" class="twm-action-dropdown-separator">` that takes no
+focus, that ArrowUp/ArrowDown pass over, and that never reaches `onSelect`.
+A separator only separates: one at the start or end of the list, or right
+after another, is dropped, so groups that come out empty leave no stray or
+doubled rule. `setOptions` follows the same rules, and an option's
+`data-index` stays its index in `options`.
+
+`tests/action_dropdown_separators.test.mjs` drives it in jsdom.
+
+## A list of tags: `createTagInput` (0.17.0)
+
+`createTagInput(host, { value, placeholder, readOnly, allowDuplicates, onChange })`
+(in `@flexdesk/widgets`) draws a list of short strings as removable chips
+followed by a text box, and appends it to `host`.
+
+```js
+const tags = createTagInput(host, {
+    value: ['baseline'],
+    placeholder: 'Add a tag…',
+    onChange: (list) => save(list),   // a fresh copy after each change the reader makes
+});
+tags.getValue();            // ['baseline']
+tags.setValue(['a', 'b']);  // redraws; does not call onChange
+tags.dispose();
+```
+
+- **Enter**, a **comma** and **blur** commit what was typed: it is split at
+  commas and each piece trimmed, so `a, b` then Enter adds two chips and
+  `onChange` receives `['a', 'b']`.
+- Empty pieces are ignored, and so is a piece already in the list unless
+  `allowDuplicates` is set. A commit that adds nothing calls no `onChange`.
+- **Backspace** in an empty box removes the last chip.
+- A **paste** that carries a comma is split into chips at once; a paste
+  without one is ordinary text in the box.
+- Each chip's remove button has an `aria-label`, "Remove <tag>" by default;
+  `removeLabel(tag)` words it (for another language). `label` names the text
+  box and the group.
+- `readOnly` draws the chips alone: no remove buttons and no text box.
+
+The handle is `{ element, input, getValue, setValue, focus, dispose }`
+(`input` is `null` when read-only). The styles are the `twm-tag-input` block in
+`flexdesk.css`. `tests/tag_input.test.mjs` covers each of the above in jsdom.
+
+## Progress: bars, lists and phases (0.17.0)
+
+Three classes in `widgets`, each building its own element (`.element`, appended
+to `host` when one is given) and changing it **in place**: an update twenty
+times a second gets the same nodes back every time, so hover, tooltips and the
+fill's transition survive. Names and labels are text.
+
+| Class | Does |
+|---|---|
+| `new ProgressBar(host, { value, max, indeterminate, label, showPercent, showCount, showElapsed, onCancel })` | `update(0.42)` (a fraction) or `update(21)` with `max` (a count, read "42% · 21 / 50"); `update({ value, max, label, indeterminate })`; `setState('done' \| 'error' \| 'cancelled')` ends it and stops the elapsed clock, `setState('running')` resumes it; `fraction`, `state`, `elapsed` |
+| `new ProgressList(host, { items, stats, pulse, emptyText })` | Keyed rows `{ key, name, completed, total?, state, detail? }`, `state` one of `pending`, `running`, `done`, `failed`. `setItems` reconciles by key: a known key keeps its row. A row without `total` is drawn against the largest item. `stats: true` writes a summary line, a function `(items) => string` writes yours, `false` none. Running rows pulse |
+| `new StepProgress(host, { steps })` | Ordered phases (`{ key, label }` or a label). `setStep(keyOrIndex, { pass, passes })` makes one active, those before it done and those after pending, and reads "pass 2 of 5"; `fail()` marks the active one error; `complete()` |
+
+```js
+const list = new ProgressList(panel, { items: [] });
+job.on('tick', (workers) => list.setItems(workers.map((w) => ({
+    key: w.id, name: w.label, completed: w.done, total: w.total, state: w.state }))));
+```
+
+`showRunProgressDialog` and `showComputingWindow` take `progress` (`true`, or
+ProgressBar options) and `steps`, fixed when the dialog opens. Their handles
+gain `setProgress(next)` and `setStep(which, opts)`, which throw when the dialog
+was opened without `progress` or `steps` respectively, and **`result`**, a
+Promise that settles once with
+`{ status, message }`: `complete({ ok })` gives `done` or `error` (the bar and
+the phases show it), `cancelled()` gives `cancelled`, and so does **closing the
+dialog while it runs** (by its ×, Escape, `close()`, or for `showComputingWindow`
+opening another). Closing never calls `onCancel`; only the Stop / Cancel button
+does, as before. `showComputingWindow` also gains `complete` and `cancelled`,
+after which it shows a Close button.
+
+```js
+const dlg = showRunProgressDialog({ title: 'Export', steps: ['Prepare', 'Render', 'Write'],
+                                    progress: { showElapsed: true }, onCancel: () => job.stop() });
+dlg.setStep(1); dlg.setProgress(0.4);
+const { status } = await dlg.result;   // 'done' | 'error' | 'cancelled'
+```
+
+`tests/progress.test.mjs` holds all of it in jsdom.
+
+## Tabs: `createTabs` (0.17.0)
+
+One tab strip, from `@flexdesk/widgets`, keyed by whatever ids you give it — not
+by file path (`NotebookTabBar`) and not by a bus event (`createBottomPanelTabs`,
+which is now built on it). It is a strip and nothing else, or a strip with the
+panes behind it.
+
+```js
+const tabs = createTabs(el, {
+    items: [
+        { id: 'inputs',  label: 'Inputs', icon: 'tune', title: 'Model inputs' },
+        { id: 'results', label: 'Results', badge: { count: 3, level: 'warning' } },
+        { id: 'draft',   label: 'Draft', dirty: true, closable: true },
+    ],
+    active: 'inputs',
+    onSelect: (id, item) => …,
+    onReselect: (id, item) => …,                                       // optional: a click on the tab in front
+    onClose: (id) => tabs.update(items.filter((i) => i.id !== id)),   // optional
+    onReorder: (ids) => …,                                             // optional: tabs drag
+    onContextMenu: (id, event, item) => …,                             // optional
+    mountPane: (item, paneEl, tabs) => ({ onShow() {}, destroy() {} }), // optional: strip only
+    compact: false,
+    label: 'Views',
+});
+tabs.update(nextItems, 'results');
+tabs.setBadge('results', 7, 'alert');
+tabs.setIndicator('inputs', 'info');
+```
+
+| Member | Does |
+|---|---|
+| `update(items, activeId?)` | Replaces the items, keeping the button of every id it keeps. In front: `activeId` if present, else the tab in front now if it is still there, else the first (none when no items are left). Panes of items that went are destroyed |
+| `select(id)`, `active()`, `has(id)`, `ids()` | The tab in front; `select` answers false for an id it does not have |
+| `setBadge(id, n, level?)` | A count, `99+` above 99, none at zero; `level` is `info`, `warning` or `alert` (`TAB_LEVELS`) |
+| `setIndicator(id, value)` | A dot: a level, `true` for the neutral one, falsy for none |
+| `instance(id)`, `instances()` | The mounted panes' instances |
+| `destroy()` | Destroys the panes, lets the bus go, removes the markup |
+
+- **Panes mount on first selection.** The tab in front at creation counts;
+  `eager: true` on an item mounts its pane at once — at creation, or in the
+  `update` that brings the item in, before the tab in front is settled. Each
+  instance hears `onShow()` whenever its tab comes to the front and `destroy()`
+  when its item goes.
+- **`onSelect` hears changes**, not the tab chosen at creation. A click on the
+  tab already in front is not a change; `onReselect(id, item)` hears it. An
+  `update` that leaves no items empties the front, heard as `onSelect(null, null)`.
+- **The bus is opt-in:** pass `eventBus` *and* `selectEvent: 'views:show'` and
+  that event selects `payload.id` (or `selectFrom(payload)`). No event name, no
+  subscription.
+- **Keys** follow the ARIA tabs pattern with automatic activation:
+  ArrowLeft/ArrowRight (wrapping), Home, End; Delete (and a middle click) closes
+  a closable tab. Only the tab in front is in the tab order. When an `update`
+  removes the tab that has focus (Delete, then your `onClose` drops it), focus
+  moves to the tab now in front instead of falling to the page. Focus that the
+  update put somewhere else (a pane that focuses itself in `onShow`) stays there.
+- **Overflow scrolls**, never wraps: a vertical wheel moves the strip sideways and
+  the tab coming to the front is scrolled into view (`revealInStrip`,
+  `wheelStripSideways`, shared with `NotebookTabBar`).
+- **Classes** are BEM under `block` (default `twm-tabs`): `__tabs`, `__tab`,
+  `__tab--on`, `__tab--dirty`, `__tab--closable` (it has a close mark), `__icon`,
+  `__label`, `__badge`, `__indicator`, `__dirty`, `__close`, `__body`,
+  `--compact`, and `twm-tabs-pane`. A dirty tab shows its dot until hovered,
+  then its close mark; one with no close mark keeps the dot. Tabs and panes
+  carry the id in `data-tab-id` (`dataKey`), as a string; callbacks and `ids()`
+  hand back the id as you gave it, so a numeric id stays a number.
+
+`tests/tabs.test.mjs` covers it in jsdom; `tests/bottom_panel_tabs.test.mjs`
+runs on the bottom panel built over it. The bottom panel behaves as it did:
+`api.root` is set inside a pane's `mount`, and a click on the tab in front
+re-shows its pane, fires `onSelect` and is remembered, as `select` does. A
+remembered tab that is already in front when `remember.read` answers is shown
+again: its pane hears `onShow` and `onSelect` fires, and nothing is written back.
+
 ## Notifications: `NotificationCenter`
 
 Toasts, from `toast:show` on the bus (or `toastInfo` / `toastWarn` /
@@ -1687,6 +3184,51 @@ const nc = new NotificationCenter({ eventBus, maxVisible: 3, overflow: 'collapse
 nc.mount(document.body);
 ```
 
+*New in 0.17.0:* **the toast helpers read no global.** `toastInfo` / `toastWarn` /
+`toastError` / `toastSuccess` emit on the bus of the `NotificationCenter` mounted
+last; its `dispose()` hands them back. `setToastBus(bus)` points them at another
+bus (and returns the one it replaced), `setToastBus(null)` back at the console,
+and `getToastBus()` says which is current. With no bus — before any centre is
+mounted — a helper logs to the console and throws nothing. Until 0.17.0 they
+looked for one application's bus on a window global.
+
+### Progress toasts (0.17.0)
+
+A toast can track a job. `show({ progress })` takes a 0..1 fraction,
+`{ value, total }`, or `null` for indeterminate, and draws a `ProgressBar` in
+the toast; `status` is a line under the message and `counts` a label beside the
+bar. A progress toast is persistent, has a collapse toggle (or `collapsed: true`),
+and is not closed by a click on its body or on one of its actions while it runs.
+
+`update(id, patch)` changes only that toast's nodes: `progress`, `status`,
+`counts`, `collapsed`, `message`, `title`, `description`, `severity`. No other
+toast is redrawn, by an update or by toasts arriving and leaving, so a bar, a
+collapsed state and a hover survive (a toast whose title or description appears
+or goes is rebuilt in its place). `update()` also reaches a toast held behind
+"+N more", and `progress` on a plain toast turns it into a running progress
+toast. The toast **runs until a patch gives it an outcome severity**: `success`
+ends the bar done, `error` / `fatal` error; any other severity only restyles it.
+Once finished the bar keeps that state, whatever severity comes later. A
+`durationMs` in a patch to a toast that is not running (re)starts its
+auto-dismiss, and `0` keeps it until closed.
+
+With `overflow: 'collapse'`, a running progress toast is never held behind
+"+N more" and never counted in it (a held toast that starts running through
+`update()` comes on screen at once). It counts toward `maxVisible`, so when the
+screen is full the newest other toast steps back into the queue (first in line
+to return). Once finished it folds like any other toast. With `'drop'`, the
+oldest toast that is not a running job leaves.
+
+```js
+const id = nc.show({ title: 'Batch', message: 'Running', progress: 0, counts: '0 / 200',
+                     actions: [{ label: 'Stop', handler: () => job.stop() }] });
+job.on('tick', (done) => nc.update(id, { progress: { value: done, total: 200 },
+                                         counts: `${done} / 200`, status: job.current }));
+job.on('end', () => nc.update(id, { progress: 1, severity: 'success', message: 'Done', durationMs: 3000 }));
+```
+
+`tests/notification_progress.test.mjs` holds it in jsdom.
+
 ### Alerts with history: a log, a pane, a tab host and a bell (0.14.0)
 
 A toast is the moment. The **alert log** keeps what came in until it is
@@ -1697,7 +3239,7 @@ dismissed, and four pieces draw it. Each works without the others:
 | `createAlertLog({ source, limit })` | `widgets` | Entries `{id, at, level, title, body?, ref?, read}`, newest first; `add`, `receive`, `markRead`, `dismiss`, `unreadCount`, `worstUnread`, `subscribe`, `loadMore` |
 | `localSource({ read, write })` | `widgets` | Keeps the whole log in one stored value (localStorage, a workspace file) |
 | `mountAlertsPane(el, { log, onOpen, onBadge, rules?, stillMatches? })` | `widgets` | Level chips with counts, a filter, day groups, relative times, Open / Dismiss / Mark all read / Clear, *Load older* |
-| `createBottomPanelTabs(el, { panes, remember, store, eventBus })` | `wm` | The `.twm-bp` tab strip: `select`, `setBadge(id, n, level)`, `bottompanel:show {tab}` |
+| `createBottomPanelTabs(el, { panes, remember, store, eventBus })` | `wm` | The `.twm-bp` tab strip, on [`createTabs`](#tabs-createtabs-0170): `select`, `setBadge(id, n, level)`, `bottompanel:show {tab}` |
 | `new NotificationHistory({ alertLog, mountPoint, alertsTab, onOpen })` | `widgets` | The bell shows the log's unread count in the worst level's colour; a click (and "+N more") opens the Alerts tab |
 
 A **source** is where entries live: `load({offset, limit})` answers
@@ -1724,6 +3266,73 @@ before it returns. Reach the host through `mount`'s `api` argument, not the
 variable being assigned. Without `alertLog` and `mountPoint`, `NotificationHistory`
 is the bell it was.
 
+## A conversation: `mountConversationView` (0.17.0)
+
+A transcript of role-tagged messages above a composer, in `@flexdesk/widgets`.
+It has no markdown and no model in it: you draw a message's body, and it tells
+you when the user submits or cancels.
+
+```js
+const view = mountConversationView(el, {
+    render:   (message, bodyEl, { streaming }) => { bodyEl.innerHTML = toHtml(message.text); },
+    onSubmit: (text) => { view.append({ role: 'user', text }); view.setBusy(true); ask(text); },
+    onCancel: () => abort(),
+    placeholder: 'Ask anything',
+});
+view.beginStream({ role: 'assistant' });
+for await (const chunk of reply) view.appendChunk(chunk);  // re-renders this message only
+view.endStream();
+view.setBusy(false);
+```
+
+| Method | Does |
+|---|---|
+| `append({ id?, role, text, meta? })` → id | Adds a message; `role` becomes `twm-chat__msg--<role>` |
+| `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 |
+| `messages()`, `streamingId()` | Copies of the messages; the one streaming |
+| `getScrollTop()`, `setScrollTop(px)`, `scrollToBottom()`, `isPinned()` | The transcript's scroll position, to keep across a remount |
+| `setBusy(bool)`, `isBusy()` | `true` turns Send into Cancel |
+| `getText()`, `setText(text)`, `focus()`, `destroy()` | The composer, and teardown |
+
+- **`render(message, bodyEl, { streaming })`** fills an emptied body. One that
+  throws leaves that message as its plain text and the view carries on; the
+  error goes to `onRenderError(error, message)`. Without `render`, every body
+  is plain text (`textContent`, never markup).
+- **Pinned to the bottom.** The transcript starts out following new content.
+  Any scroll up, even a few px from the end (the first frame of a smooth wheel
+  or arrow-key scroll), stops that and shows *Jump to latest*, and later chunks
+  leave the reader where they are. It follows again only after a scroll down
+  that ends within `pinThreshold` px (32) of the end, a click on *Jump to
+  latest*, `scrollToBottom()`, `replaceAll()` / `clear()`, or a
+  `setScrollTop(px)` that lands within the threshold. Content growing below
+  never unpins it, nor does content shrinking under it (the browser moves
+  `scrollTop` back to the new end, which is not the reader scrolling). A wheel
+  over a scroller nested in a body or a slot (a `<pre>`, a tool-output box)
+  scrolls that scroller (or, at its top with `overscroll-behavior: contain`,
+  keeps the wheel), and a wheel a handler in the transcript cancels, a
+  Ctrl+wheel (page zoom, or a trackpad pinch) and a wheel up over a transcript
+  already at its top move nothing, so in all these cases the transcript keeps
+  following.
+- **The composer** grows with its text up to `composerMaxHeight` (200 px).
+  Enter submits and clears it (blank text is ignored, and so is Enter during
+  IME composition); Shift+Enter is left to the browser, which inserts the
+  newline (so undo and `input` listeners see it). While busy, Enter submits
+  nothing, and Esc (wherever focus is inside the view) or a click on Cancel
+  calls `onCancel` once per busy period. That Esc goes no further
+  (`stopPropagation`), so a `ManagedWindow` or panel holding the view that
+  closes on Escape stays open. An Esc a handler inside the view has already
+  consumed (`preventDefault`, e.g. an inline popup in the transcript closing
+  itself) is left alone: it neither cancels nor is stopped.
+- **Ids are unique.** `append`, `beginStream` or `replaceAll` with an id already
+  in the transcript (or repeated within the `replaceAll` list) throws, and the
+  refused call changes nothing: no row, no open stream, the old transcript kept.
+- `labels: { send, cancel, jump, input }` replaces the four texts.
+
+`tests/conversation_view.test.mjs` drives all of it in jsdom with a fake
+scroll geometry.
+
 ## The host port
 
 FlexDesk never touches `pywebview`, `fetch`, `localStorage` or the filesystem. It
@@ -1734,8 +3343,10 @@ library degrades rather than throwing.
 ```js
 createHost({
     state:   { read, write },              // layout persistence
-    dialogs: { saveFile },                 // optional — CSV export falls back to a Blob
+    dialogs: { saveFile, openFile? },      // optional — CSV export falls back to a Blob;
+                                           // openFile (itself optional) to pickFile()
     window:  { minimize, maximize, ... },  // optional — no native chrome buttons without it
+    gallery: { list },                     // optional (0.17.0) — mountGalleryPicker's entries
 })
 ```
 
@@ -1757,6 +3368,47 @@ const host = createPhotinoHost({ state: myServerState, onEvent: (name, value) =>
 the messages the C# side has to answer are in
 [`src/host/photino_host.md`](src/host/photino_host.md).
 
+**The dialogs a pywebview bridge answers.** `createPywebviewHost()` calls these
+methods on `window.pywebview.api`, positionally. Each is optional: a missing
+one makes its capability answer `null`, and FlexDesk degrades.
+
+| Bridge method | Arguments | Reply | Behind |
+|---|---|---|---|
+| `save_file_dialog` | `(data, filename, kind)`: the file's text (`csv`) or base64 bytes (`png`), the suggested name, the type | `{ok: true, path}` \| `{ok: false, cancelled: true}` \| `{ok: false, error}` | `dialogs.saveFile` |
+| `read_file_dialog` (0.17.0) | `(accept, kind, encoding)`: a list of extensions or MIME types to filter by (`['.json']`, may be empty), a label for the filter or `null`, and `'text'` or `'base64'` | `{ok: true, name, path, text}` (`'text'`, read as UTF-8) or `{ok: true, name, path, data}` (`'base64'`, the bytes) \| `{ok: false, cancelled: true}` \| `{ok: false, error}` | `dialogs.openFile` |
+
+### Opening a file: `pickFile` (0.17.0)
+
+```js
+import { pickFile } from '@flexdesk/host';
+
+const r = await pickFile(host, { accept: ['.json'], kind: 'json' });   // encoding: 'text' (default) or 'base64'
+if (r.ok) load(JSON.parse(r.text));
+else if (r.error) toast(r.error);                                     // r.cancelled: say nothing
+```
+
+`pickFile(host, {accept, kind, encoding})` takes `accept` as a list or as a
+comma-separated string (`'.json,.csv'`); the host always receives the list
+(`['.json', '.csv']`). It asks the host's
+`dialogs.openFile` first, a new optional member of `dialogs`: a host whose
+`dialogs` has only `saveFile` is still complete. Without it, or when it
+answers `null` (no dialog behind it), a transient hidden
+`<input type="file">` opens the browser's chooser, so the same call works in a
+browser tab, under `NULL_HOST`. Either way it resolves one of
+
+```
+{ok: true, name, path?, text}      encoding 'text'
+{ok: true, name, path?, data}      encoding 'base64': the file's bytes
+{ok: false, cancelled: true}       the user closed the chooser
+{ok: false, error}                 show it
+```
+
+`path` comes only from a native host. The pywebview adapter maps `openFile` to
+`read_file_dialog(accept, kind, encoding)` (the table above); the Photino
+adapter sends `dialogs.openFile`, documented in
+[`photino_host.md`](src/host/photino_host.md). The browser chooser reports a
+cancel through the input's `cancel` event, which every current engine fires.
+
 ### A window with its own chrome (0.15.0)
 
 The same app runs three ways, and the page needs no switch for it:
@@ -1815,6 +3467,61 @@ Reload, Print, Inspect) on any right-click that no handler claimed with
 text, where Paste and Copy are the point, and wherever `allow(event)` says so.
 Both calls return `{ dispose }`.
 
+## The state guard: who wrote that attribute (0.17.0)
+
+`StateGuardService` blocks (`strict`) or reports (`warn`) `data-*` writes that
+are on no allow-list. A module override lets one module write a key nobody
+else may:
+
+```js
+import { StateGuardService, DEFAULT_STATE_GUARD_CONFIG } from '@flexdesk/core';
+
+const guard = new StateGuardService({ eventBus, config: { ...DEFAULT_STATE_GUARD_CONFIG, mode: 'strict' } });
+guard.allow('src/app/my_widget.js', ['data-foo']);   // a literal substring of the module, or a RegExp
+```
+
+A write is attributed to the frame that made it: the URL or path of the file
+that called `setAttribute`, `removeAttribute` or `dataset`, without line and
+column, whatever your directory layout. A FlexDesk widget's write is the
+widget's, not that of the app module that called the widget. To attribute
+writes further up the stack instead, pass `moduleFramePattern`: the first
+frame from the writer up whose location matches names the module, by the
+pattern's first capture group if it has one.
+
+```js
+config: { ...DEFAULT_STATE_GUARD_CONFIG, moduleFramePattern: /(src\/app\/[^/]+\.js)/ }
+// a write made inside @flexdesk/widgets on behalf of src/app/my_widget.js
+// is now attributed to 'src/app/my_widget.js'
+```
+
+The defaults are `mode: 'warn'`, no module overrides and no frame pattern.
+Before 0.17.0 the module was only found under a `js_new/` path, the defaults
+carried one application's override, and the mode read one application's debug
+global; choose strict mode in your own code.
+
+### The defaults cover FlexDesk's own keys (0.17.0)
+
+`DEFAULT_STATE_GUARD_CONFIG` includes every data key FlexDesk's own widgets
+write, so the shell, dialogs, forms, tooltips, tiles and flow editors run under
+`mode: 'strict'` with no violation. The list also carries some keys that
+FlexDesk itself does not write. Add your application's keys on top:
+
+```js
+const guard = new StateGuardService({ eventBus, logger, config: {
+    ...DEFAULT_STATE_GUARD_CONFIG,
+    allowedDatasetKeys: [...DEFAULT_STATE_GUARD_CONFIG.allowedDatasetKeys, 'order-id'],
+} });
+```
+
+An allow-list key may be spelled either way: `orderId` and `order-id` are the
+same key, in the allow-list and in module overrides
+(`allow(pattern, attributes, { datasetKeys })` and `config.moduleOverrides`)
+alike. camelCase maps to kebab-case as the DOM does for ordinary keys: each
+capital letter becomes `-` plus its lower-case form. So `rowID` is `row-i-d`
+(what `dataset.rowID` writes), not `rowid`; to allow `data-id`, list `id`.
+Before 0.17.0 a camelCase entry never matched, and some entries named keys no
+element carries.
+
 ## Peer dependencies
 
 `@flexdesk/charts` needs Plotly (4.4 MB). `@flexdesk/editor` needs Monaco (14 MB).
@@ -1833,9 +3540,355 @@ There is deliberately **no default path**. A hardcoded `'vendor/monaco'` is one
 application's directory layout, and for everyone else it is a 404 that surfaces as
 an editor which silently never appears. `initMonaco()` throws instead.
 
+`getEditorFactory()` and `initMonaco()` **reject** when no path was set, when
+`vs/loader.js` fails to load, or when Monaco's AMD loader reports an error, so a
+consumer can show a message instead of waiting forever. What happens next
+depends on which of those it was:
+
+- **`vs/loader.js` failed to load** (a 404, a wrong path): not sticky. Fix the
+  path (`setMonacoBasePath`, or pass it to `initMonaco`) and the next call
+  tries again.
+- **Monaco's AMD loader reported an error** (`vs/editor/editor.main` or a
+  dependency failed): **final for the page**. Monaco's loader caches the failed
+  module and has no way to forget it, so every later call rejects with that
+  same first error, whatever path it is given. Fix the path and reload.
+
+Loading is shared: if you call `initMonaco(path)` yourself, `getEditorFactory()`
+uses that load and needs no `setMonacoBasePath()`. `monacoReady` only ever
+resolves — it is the "Monaco has arrived" signal, not the place to learn that
+an attempt failed.
+
 If you already load Plotly yourself (a `<script>` tag that sets `window.Plotly`),
 the chart loader short-circuits and you can skip `setPlotlySource`.
 
+### Auto-height editors: `maxHeight` (0.17.0)
+
+`createEditor()` sizes its container to the content (80px at least, see
+`setMinHeight`). Cap it with `maxHeight`, in px; `Infinity`, the default, is
+no cap. Past the cap Monaco scrolls internally and takes the mouse wheel;
+below it the wheel reaches whatever scrolls around the editor.
+
+```js
+const h = factory.createEditor(el, source, { maxHeight: 400 });
+h.setMaxHeight(Infinity);   // applies at once: grows to the content
+```
+
+A non-positive or non-number cap throws a `RangeError`. With `noAutoHeight`
+the container's own layout decides the size and `setMaxHeight` has no effect.
+Before 0.17.0 the cap was a fixed 400px, switched on by `data-code-max-height="true"`
+on a `.notebook-editor-container` ancestor; that attribute is no longer read.
+
+## Storage keys and names are yours (0.17.0)
+
+Every localStorage key FlexDesk writes is an option, and so is each name in the
+table below that it registers where other code can see it, except the last row:
+the tile tab MIME is fixed. The defaults are FlexDesk's own; pass yours at boot,
+before the first read:
+
+| What | Default | Set it with |
+|---|---|---|
+| Settings (the `getSetting`/`setSetting` binding) | `'flexdesk.settings.v1'` | `configureSettings({ storageKey })` from `@flexdesk/core` |
+| ManagedWindow geometry | `'flexdesk.managedWindows.v1'` | `ManagedWindow.configure({ storageKey })` from `@flexdesk/widgets` |
+| Saved tile layouts | `'twm.tiles.layouts'` | `configureLayoutPersistence({ layoutsKey })` from `@flexdesk/tiles` |
+| Saved tile configurations | `'twm.tiles.configs'` | `configureLayoutPersistence({ configsKey })` from `@flexdesk/tiles` |
+| Built-in Monaco themes | `'flexdesk-dark'`, `'flexdesk-light'` | `setEditorThemeNames({ dark, light })` from `@flexdesk/editor` |
+| MIME type of a dragged editor tab | `'application/x-flexdesk-tab'` | `setTabDragMime(mime)` from `@flexdesk/editor` |
+| Chart PNG export file name | `'chart'` (saved as `chart.png`) | `setChartExportFilename(name)` from `@flexdesk/charts` |
+| `LoggingService` service name on each entry | `'flexdesk'` | `new LoggingService({ name })` from `@flexdesk/core` |
+| MIME type of a dragged tile tab | `'application/x-twm-tile-tab'` | fixed: not an option; read it as `TILE_TAB_MIME` (or `TileRenderer.TAB_MIME`) from `@flexdesk/wm` |
+
+```js
+import { configureSettings } from '@flexdesk/core';
+import { ManagedWindow } from '@flexdesk/widgets';
+import { setEditorThemeNames, setTabDragMime } from '@flexdesk/editor';
+import { setChartExportFilename } from '@flexdesk/charts';
+
+configureSettings({ storageKey: 'myapp.settings.v1' });
+ManagedWindow.configure({ storageKey: 'myapp.windows.v1' });
+setEditorThemeNames({ dark: 'myapp-dark', light: 'myapp-light' });
+setTabDragMime('application/x-myapp-tab');
+setChartExportFilename('myapp_chart');
+```
+
+Each default is exported beside its setter (`DEFAULT_SETTINGS_STORAGE_KEY`,
+`DEFAULT_WINDOW_STORAGE_KEY`, `DEFAULT_EDITOR_THEME_NAMES`,
+`DEFAULT_TAB_DRAG_MIME`, `DEFAULT_CHART_EXPORT_FILENAME`), and each setter has a
+getter (`getSettingsStorageKey()`, `ManagedWindow.storageKey`,
+`getEditorThemeNames()`, `getTabDragMime()`, `getChartExportFilename()`). An
+embedder that passes nothing gets the defaults silently: nothing is logged.
+
+- **Settings** are read lazily: importing `@flexdesk/core` touches no storage,
+  and the binding reads its key on the first `getSetting`/`setSetting`/reset.
+  `registerSettings()` and `registerSettingsEventBus()` may come before or after
+  `configureSettings()`. Configured after the binding was in use, it moves: values
+  return to their defaults, are reloaded from the new key, and one
+  `settings:changed` (`path: null`) is emitted. The old key is not touched. A
+  private store from `createSettingsStore()` moves the same way with
+  `store.setStorageKey(key)` (and answers `store.getStorageKey()`).
+- **ManagedWindow** reads geometry when a window is first shown; configure it
+  before the first `show()`.
+- **Editor themes**: a factory starts on the dark name current when it is
+  created, and `init()` defines the built-in themes under the names current
+  then. An app with a theme of its own defines it with `monaco.editor.defineTheme`
+  and passes its name to `factory.setTheme(name)`.
+- **The tab MIME** is read at drag time by every `NotebookTabBar` and
+  `EditorPane`, so the two always agree.
+
+**Upgrading from 0.16.** The old defaults were one application's names:
+`'ecosim.settings.v1'`, `'ecosim.managedWindows.v1'`, `'ecosim-dark'` /
+`'ecosim-light'`, `'application/x-ecosim-tab'`, `'ecosim_chart'` and the log
+service name `'ecosim'`. If your users have settings or window geometry saved
+under the old keys, pass those keys explicitly and nothing is lost:
+
+```js
+configureSettings({ storageKey: 'ecosim.settings.v1' });
+ManagedWindow.configure({ storageKey: 'ecosim.managedWindows.v1' });
+```
+
+Code that called `factory.setTheme('ecosim-light')` now calls
+`factory.setTheme(getEditorThemeNames().light)` (or names the themes back with
+`setEditorThemeNames`), and code that read `'application/x-ecosim-tab'` off a drag
+reads `getTabDragMime()`.
+
+## Derived series: `seriesTransforms` (0.17.0)
+
+A plot can draw series worked out from its own: a trend, a moving average, a
+decomposition. `@flexdesk/charts` ships none; you pass them to
+`PlotPopoutWindow` (or `openPlotPopoutWindow`) as `seriesTransforms`:
+
+```js
+import { openPlotPopoutWindow, renderSeriesTransformControls } from '@flexdesk/charts';
+
+const seriesTransforms = {
+    hp: {
+        label: 'HP filter',
+        params: { lambda: { label: 'Lambda', default: 1600, min: 1, step: 100 } },
+        outputs: {
+            trend: { label: 'Trend', suffix: ' (HP Trend)', lineStyle: 'dashed' },
+            cycle: { label: 'Cycle', suffix: ' (HP Cycle)', lineStyle: 'dotted', lineWidth: 1 },
+        },
+        run: (y, { lambda }) => myBackend.hpFilter(y, lambda),   // -> { trend: [...], cycle: [...] }
+    },
+};
+
+openPlotPopoutWindow({ id, title, plotConfig, getResults, services, seriesTransforms,
+    configRenderer: (el) => renderSeriesTransformControls(el, plotConfig.subplots[0],
+                                                           seriesTransforms, { onChange: redraw }) });
+```
+
+What a subplot switches on is in the subplot:
+`subplot.transforms = { hp: { outputs: { trend: true }, params: { lambda: 100 } } }`.
+For every transform with an output switched on, `run(y, params)` is called
+once per line or scatter trace of the subplot (params: the declared defaults
+under the subplot's own), and each switched-on output it returns is drawn as
+an extra trace in the source trace's colour, on its axis, named
+`<source name><suffix>`, with the output's `lineStyle` and `lineWidth`
+(default 2). A transform that throws or rejects is skipped for that trace,
+reported to `services.logger.warn`, and the figure is drawn without it.
+`deriveSeriesTraces(traces, subplot, seriesTransforms, { onError })` is that
+step on its own, for a renderer of your own.
+
+`renderSeriesTransformControls(container, subplot, seriesTransforms, { onChange })`
+renders, per transform, a toggle for each output and a number field for each
+parameter (disabled while no output is on); it edits `subplot.transforms` in
+place and returns `{ dispose }`. With no transforms it renders nothing.
+
+Until 0.17.0 the plot window called one application's backend for a
+Hodrick-Prescott filter, and every default subplot carried `showHpTrend`,
+`showHpCycle` and `hpLambda`. Those keys are gone and are ignored in saved
+configs; without `seriesTransforms` no derived trace is drawn.
+`tests/series_transforms.test.mjs` pins all of it.
+
+## No application globals: the gallery picker and plot-window events (0.17.0)
+
+Nothing under `src/` outside `src/host` reads `window.pywebview` or an
+application's global; `tests/no_app_globals.test.mjs` pins it, with the toast
+helpers ([Notifications](#notifications-notificationcenter)) and these two:
+
+**`mountGalleryPicker(el, { entries | host, kind, ... })`** takes its entries from
+`entries`, or else from the host's optional `gallery` capability:
+`host.gallery.list(kind)` answers `[{id, kind, label, description?, fields?}]`
+(or a promise of them). Neither shipped adapter advertises it; add your own:
+
+```js
+const host = createHost({ ...createPywebviewHost({ bridgeRef }),
+                          gallery: { list: (kind) => myBackend.starters(kind) } });
+await mountGalleryPicker(el, { host, kind: 'report', onChange });
+```
+
+With neither `entries` nor the capability, the picker shows its `emptyLabel`
+and logs one warning; a `list` that throws does the same. Until 0.17.0 it
+called one application's bridge method.
+
+**`PlotPopoutWindow({ streamEvents })`** names the bus events a live data
+source emits, next to `refreshEvent`: `{ delta, complete }`. The window
+redraws on each while live update is on. There are no default names: without
+`streamEvents`, or for a name left out or given as `null`, nothing is listened
+for, and the window updates through `refreshEvent` and explicit calls only.
+
+```js
+openPlotPopoutWindow({ id, title, plotConfig, getResults, services,
+                       refreshEvent: 'run:finished',
+                       streamEvents: { delta: 'sim:delta', complete: 'sim:done' } });
+```
+
+## A plot config in any container: `renderPlotGrid` (0.17.0)
+
+`PlotPopoutWindow` used to keep its subplot renderer private, so anything else
+that showed the same plot config (a notebook cell, a dashboard tile) had to
+copy it. It is now exported, and the window is one of its callers:
+
+```js
+import { renderPlotGrid, migrateData } from '@flexdesk/charts';
+
+const grid = renderPlotGrid(el, migrateData(savedConfig), { time, series }, {
+    overlays,                 // { [series.id]: { years, values } } for series with an `overlay`
+    seriesTransforms,         // as above
+    hiddenSeries: new Set(),  // trace names not to draw
+});
+await grid.update({ results: next });   // any of plotConfig, results, overlays, hiddenSeries
+grid.resize();
+grid.dispose();
+```
+
+It lays a `.twm-plot-grid` out from `PLOT_LAYOUTS` (a cell per slot, a
+`.twm-plot-grid__cell` in that slot's grid area) and draws one figure per
+subplot: its chart type, interpolation, data points and stack groups, every
+y-axis (left or right, linear or log, min, max, step), reference lines and
+shaded bands, the NaN strategy, the x-axis clipped to the results' time
+range, or an x variable instead of time (`xAxis: { useTime: false, variable }`).
+A subplot with nothing to draw shows `emptyMessage` (default `No data yet.`); a
+slot with no subplot shows `noSubplotMessage` (`No subplot configured.`); null
+results empty every subplot. A cell that is detached or has no size is not
+drawn: the grid's own ResizeObserver draws it once it has one. `dispose()`
+purges every figure and removes the grid; `grid.charts` is the cells, for
+Plotly calls of your own (relayout, toImage), and `grid.plotted` is the cells
+that show a figure right now, however it got there (an `update()`, or a
+deferred draw on a resize). `update()` resolves whether it drew anything, but a
+cell it deferred is drawn later, so ask `grid.plotted`, not that value, before
+acting on a figure.
+
+The other options:
+
+| Option | What it does |
+|---|---|
+| `resolveSeries(series, results, subplot)` | Returns `{ y, x? }` or null. Default `resolveSeriesData`: `series[_resultKey ?? variable]`, then `variable`, then the name after its first `.`; `x` is `_resultTime`. Also resolves the x variable. |
+| `derivedTraces(traces, subplot, { results, index })` | Extra Plotly traces (or a promise of them) appended to a subplot's figure. |
+| `onTransformError`, `onError` | A transform that failed (`{ transformId, traceName, error }`); a subplot that failed to draw (`{ index, error }`), on an `update()` or on the resize that draws a deferred one, which then shows the empty message. |
+| `theme` | Overrides for `PLOT_GRID_THEME`: `fontFamily`, `fontColor`, `fontSize`, `paperBackground`, `plotBackground`, `gridColor`, `lineColor`, `tickColor`, `zeroLineColor`, `hoverBackground`, `hoverBorder`. |
+| `alwaysShowLegend` | Draws a subplot whose legend is `'hidden'` with one at the top. |
+| `layout` | Plotly layout fields merged over every figure's (`hovermode`, `margin`, ...). |
+
+`PlotPopoutWindow` takes `resolveSeries` too, for its chart and its data
+table. Its chart cells were `div.plot-tile-chart` and are now
+`div.twm-plot-grid__cell` inside a `.twm-plot-grid`. An overlay is drawn for
+any series with an `overlay` and data under its id in `actuals`; it used to
+need `overlay.etlKey` as well. More changes to what the window draws, for
+configs outside the fixtures:
+
+- On an `'area-stacked'` subplot, overlays are stacked too, in a group of their
+  own per y-axis (`stackgroup: 'overlay-<y ref>'`, `groupnorm: 'fraction'`,
+  `mode: 'lines'`, no fill), so they read on the same 0..1 scale as the stack.
+  They used to be drawn unstacked, at their raw values.
+- A subplot with no traces draws an empty figure, not the empty message, only
+  when **all of its own** series are hidden (its overlays and derived traces do
+  not count). It used to do that for every subplot as soon as any series
+  anywhere in the window was hidden. Null results win over that rule: with no
+  results every configured subplot shows `emptyMessage`, hidden series or not.
+- While `getResults()` answers null and nothing has been drawn yet, every cell
+  shows `emptyMessage`; the cells used to stay blank. Figures already drawn
+  stay while the results are briefly null, as before.
+- A y axis's positive `step` sets the Plotly `dtick` of that axis. The window
+  used to ignore `step`, so Plotly chose the tick spacing.
+- A subplot with `xAxis: { useTime: false, variable }` is drawn against that
+  variable, with an x-axis title (`xAxis.label`, else the variable's name) and
+  no clip of the x axis to the time range. The window used to ignore `xAxis`
+  and always drew against time, clipped to the first and last time point.
+
+Its zoom and pan buttons and Download PNG act on `grid.plotted`, so a figure the
+grid drew on a resize (the window opened while its plot area had no size) is
+zoomable and exportable; Download PNG exports the first subplot that shows a
+figure, where it used to try the first slot whatever it held.
+`tests/plot_grid.test.mjs` pins all of it,
+including that the window draws the same traces, names and axes for the
+fixture configs (`tests/fixtures/plot_grid_fixtures.mjs`) as it did before.
+
+## Editing a plot config: `renderPlotConfigEditor` (0.17.0)
+
+`renderPlotGrid` draws a plot config; `renderPlotConfigEditor` edits one, in
+place, so an embedder no longer writes its own panel for it:
+
+```js
+import { renderPlotConfigEditor, renderPlotGrid, migrateData } from '@flexdesk/charts';
+
+const plotConfig = migrateData(savedConfig);
+const editor = renderPlotConfigEditor(el, plotConfig, {
+    onChange: () => grid.update({ plotConfig }),            // after every edit
+    seriesProvider: ({ value, role, subplot }) => names(value),   // items, or a promise of them
+    seriesTransforms,                                       // their toggles, per subplot
+    overlaySources: () => mySources(),                      // optional
+    extraSeriesFields: (el, series, { subplot, axis, onChange }) => { /* your fields */ },
+});
+editor.dispose();
+```
+
+It draws a layout picker (every `PLOT_LAYOUTS` entry), a tab per subplot slot
+when the layout has more than one, and for the subplot in front: its title;
+its chart type, legend, interpolation, NaN handling and data points; its x
+axis (time, or a series); its y axes (label, scale, position, min, max, step)
+and, under each, its series (a picker, legend label, colour, width, dash and
+stack group); its z axis while the chart type is 3D; its reference lines and
+shaded bands; and the toggles of any `seriesTransforms`. Every edit writes the
+config it was given and then calls `onChange(config)`.
+
+- A layout with more slots than there are subplots adds default subplots
+  (`makeDefaultSubplot`); one with fewer keeps the extra subplots, so switching
+  back restores them.
+- **Add Y axis** adds `makeDefaultYAxis(index)` (left for an even index, right
+  for an odd one) and **Add series** adds `makeDefaultSeries(index)` (coloured
+  by its place among the subplot's series). Both come from `@flexdesk/charts`,
+  and `makeDefaultSubplot` and `migrateData` build their axes and series from
+  them, so an axis added in the editor matches a default subplot's.
+- A 3D chart type gives the subplot a z axis (label, scale, min, max, step and
+  a series) and uses its first y axis only: the other y axes are shown disabled
+  and **Add Y axis** is disabled. A 2D chart type sets `zAxis` back to `null`.
+- Every series picker is an `AutocompleteField` fed by `seriesProvider`, asked
+  `{ value, role, subplot }`, where `role` is `'series'`, `'x'` or `'z'`. It
+  answers AutocompleteField items (`{ label, insertText?, type? }`) or a promise
+  of them. A provider that throws or rejects shows no suggestions and leaves
+  the typed text as it is (`logger.warn` hears it when you pass `logger`).
+  Without `seriesProvider` the pickers suggest nothing and take typed text.
+- `overlaySources()` answers choice options (`{ value, label }`, or
+  `{ group, options }`), or a promise of them, asked once per draw. With it,
+  every series row gets an overlay source select; choosing one writes
+  `series.overlay = { source, ... }` and shows the overlay's label, colour,
+  dash, width and mode. `renderPlotGrid` draws it from the data you pass under
+  the series' id in `overlays`. **None** removes `series.overlay`. Without
+  `overlaySources` there are no overlay controls.
+- `extraSeriesFields(el, series, { subplot, axis, onChange })` puts fields of
+  your own in each series row; call `onChange()` after you edit the series. What
+  it returns is disposed (`dispose()`) when the row is redrawn or the editor
+  is disposed. A `dispose()` that throws is reported to `logger.warn` and does
+  not stop the rest of the editor being disposed.
+
+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
+outside; `selectSubplot(index)` brings a subplot to the front. It fits
+`PlotPopoutWindow`'s `configRenderer` slot, `(container) => { dispose() } | void`:
+the window disposes what the renderer returns when it closes, so return the
+editor and its dropdowns leave `document.body` with the window.
+`openPlotPopoutWindow` is async; await it:
+
+```js
+const win = await openPlotPopoutWindow({ id, title, plotConfig, getResults, services,
+    configRenderer: (el) => renderPlotConfigEditor(el, plotConfig,
+                                { onChange: () => win.updateConfig(plotConfig) }) });
+```
+
+Its classes are under `.twm-plot-config` in `flexdesk.css`.
+`tests/plot_config_editor.test.mjs` pins all of it.
+
 ## Layouts are keyed by whatever you key them by
 
 `@flexdesk/tiles` stores layouts under keys **you** choose and resolves a starting
@@ -1895,15 +3948,181 @@ A chart tile's **Download PNG** (0.14.1) goes through the grid's `host`
 toasts where the file went, a cancel says nothing — and with no host, or a
 `saveFile` that answers null, the browser download it always was.
 
+### Figure tiles: one override, the draw is the base's (0.17.0)
+
+`FigureTile` is the base every Plotly tile draws through — `ChartTile` is one.
+A subclass overrides **one** method, `figure(data)`, answering
+`{traces, layout?, config?, frames?}` or `null`, synchronously:
+
+```js
+import { FigureTile, registerWidget } from '@flexdesk/tiles';
+import { buildHistogramTrace } from '@flexdesk/charts';
+
+class SpreadTile extends FigureTile {
+    static TYPE = 'myapp.spread';
+    static TITLE = 'Spread';
+    figure(data) {
+        if (!data?.values?.length) return null;          // the empty state
+        return { traces: [buildHistogramTrace({ x: data.values })], layout: { margin: { t: 8 } } };
+    }
+}
+registerWidget(SpreadTile);
+```
+
+The base awaits `ensurePlotly()` (so a page using `setPlotlySource` draws on
+first view, and data that changes while Plotly loads draws once), draws through
+`createChart` with `scrollZoom` and the mode bar off (`config` goes over that),
+adds `frames`, and discards a draw that lands after a newer one. `null` is the
+empty state with `static EMPTY_MESSAGE` — call `this.showEmpty(why)` yourself
+first to say why. A `figure()` that throws, or a draw that fails, is the error
+state plus `tile:render-failed {tileId, message}`. Loading, empty, error and
+`dispose()` purge the figure; a resize that settles relayouts it once. The ⋯
+menu is `TileBase`'s entries plus **Download PNG** (through `host.dialogs`, as
+above); extend it with `[...super.menuItems(), …]` and route your actions
+through `_onMenuAction`, calling `super` for the rest. **Expand** opens
+`openRawTracesWindow` with the last figure drawn (`getExpandData()`), and
+`onPointClick({customdata, point, tile})` — an option or a property — hears a
+click on a mark. `setData(data)` feeds one tile; `null` clears it.
+
+`ChartTile` is now a `FigureTile`: its menu stays Download PNG alone, and its
+header gains the Expand button.
+
+### List and people tiles, and one scope for the board (0.16.1)
+
+Two more widgets, registered by `registerListTiles()` (idempotent, nothing at
+import). Like the chart tile they take **rows you have already worked out**;
+what they own is what every list on a board needs: the count ("7 of 12"), the
+line that says what empty means, a button in the bar, a click, the keyboard and
+a right-click menu per row.
+
+```js
+import { registerListTiles, createScopePicker } from '@flexdesk/tiles';
+registerListTiles();
+const late = grid.addTile('flexdesk.list', { x: 0, y: 0, w: 12, h: 4 },
+                          { title: 'Overdue', empty_text: 'Nothing is late.', max_rows: 0 });
+late.onRowActivate = ({ row, event }) => open(row.key, { modified: event.ctrlKey });
+late.rowMenu = ({ row }) => [{ label: 'Open', icon: 'open_in_new', action: 'open' }];
+late.onRowMenuAction = ({ action, row }) => { /* … */ };
+late.onAction = () => openAsList();
+late.setData({
+    rows: [{ key: '7', icon: 'task', lead: 'TASK-0007', title: 'Sign-off',
+             cells: [{ text: 'priya' }, { text: '9 days late', tone: 'danger' }] }],
+    action: { label: 'Open as a list', icon: 'list' },
+});
+grid.addTile('flexdesk.people', { x: 0, y: 4, w: 6, h: 4 }, { title: 'Who has what' })
+    .setData({ people: [{ key: '', name: 'Nobody', muted: true, count: 2,
+                          pills: [{ text: '2 undated', tone: 'muted' }] }] });
+```
+
+- A row is `role="button"`: click, Enter and Space call `onRowActivate` with the
+  event; Up/Down/Home/End move. Right-click, the context-menu key and Shift+F10
+  open the row's menu (`showContextMenu`'s items; none means no menu). A row
+  carries `data-row-key`; `rowsDraggable` makes rows draggable.
+- `{rows: []}` keeps the bar and says `empty` (or `config.empty_text`) where the
+  rows would be; `setData(null)` is the empty state. Text is always text.
+- `tone` (`danger`, `warning`, `ok`, `muted`) picks a colour only; `className`
+  on a row or a cell is yours, added as it is.
+- `groupByPerson(items, personOf)` groups for a people tile, most first.
+
+**One scope for the whole board.** `createScopePicker({options, value, onChange})`
+is a row of buttons, one pressed. `grid.setScope(value)` (or
+`new TileGrid({ scope, onScopeChange })`) hands the value to every tile as
+`tile.scope` and `tile.onScopeChange(scope)`, a tile added later starts with
+it, a grid with a data source reloads its tiles, and the grid's `onScopeChange`
+is told. What a scope means is yours; it is not part of the layout.
+
+### A tile's settings as a form: `mountTileConfigForm` (0.17.0)
+
+`getConfigSchema()` answers `{fields}`; `mountTileConfigForm` draws them, so a
+config panel is no longer a control written by hand per field:
+
+```js
+import { mountTileConfigForm, openTileConfig } from '@flexdesk/tiles';
+const form = mountTileConfigForm(host, {
+    schema: tile.getConfigSchema(),
+    config: tile.config,                       // defaults filled by mergeWithDefaults
+    data,                                      // what getFieldOptions reads for dynamic options
+    onChange: (key, value, config) => tile.update(undefined, config),
+    renderers: { variable: ({ field, value, data, readonly, commit }) => myPicker(...) },
+});
+form.getValues(); form.setValues(next); form.isValid(); form.focusFirstInvalid();
+form.flush(); form.dispose();
+```
+
+- A field is `{key, type, label?, description?, default?, required?, readonly?,
+  min?, max?, step?, options?, visibleWhen?}`. Without a `label` the field is
+  called by its `key`, on its label and in its error messages. Every `FieldTypes` entry has a
+  control (text, number, checkbox, select, multiselect, color, range); any other
+  `type` needs a renderer, which answers an element or
+  `{element, setValue?, dispose?}` and calls `commit(value)` on an edit.
+- An edit is checked by `validateField`. An invalid one shows its error under the
+  field and is **not applied**; a valid one calls `onChange` with the field's key.
+  `isValid()` is false while a shown row has an error; `focusFirstInvalid()`
+  focuses the first such row's control (a renderer's element, or the first
+  focusable element inside it) and answers whether there was one.
+- `commitOn: 'input'` (the default) checks text, number, range and colour
+  controls on every keystroke; `commitOn: 'change'` checks them once the edit is
+  finished (blur, Enter, a released slider), for an `onChange` that is expensive.
+  `flush()` commits an edit typed but not yet finished.
+- `visibleWhen: {field, in: [...]}` (or `{field, equals}`) hides the row, never
+  rebuilds the form, so the control being typed into keeps its focus.
+- A field with no `key` throws. **The built-in tiles' schemas now use `key` and
+  `description`** (they said `name` and `help`, which `validateConfig` and
+  `mergeWithDefaults` never read: BUG-0021). A consumer that read `field.name`
+  or `field.help` from them reads `field.key` and `field.description`.
+
+The grid's cogwheel emits `grid:config-modal-show`, which now also carries the
+grid's `data`. Nothing listens unless you ask:
+`openTileConfig(eventBus, {mode: 'slide-out', host})` shows the form in a
+`SlideOutPanel` over `host` and saves every finished, valid edit (it runs the
+form with `commitOn: 'change'`, so typing a title is one save, not one per
+keystroke; closing the panel saves an edit still being typed);
+`{mode: 'modal'}` (the default) saves on Save, and refuses Save while a field
+shows an error (the modal stays open and the first invalid field is focused). A request that arrives while a
+modal is open is ignored. It answers a function that unsubscribes and closes the
+slide-out; an open modal is left to the user, keeps its form and still saves on
+Save. A renderer's `commit` on a `readonly` field applies nothing and answers
+`{valid: false, error}`.
+
 ## Styling
 
 Three stylesheets, and that is the whole CSS contract:
 
-| | |
-|---|---|
-| `dist/tokens.css` | Every rule reads `var(--…)` from here. Swap this one file and the shell restyles. |
-| `dist/reset.css` | The reset. |
-| `dist/flexdesk.css` | The library. Every class is `twm-` prefixed (the original working name; the prefix is stable and not worth a breaking rename). |
+| | Specifier | Resolves to | |
+|---|---|---|---|
+| `dist/tokens.css` | `flexdesk/css/tokens` | `css/tokens.css` | Every rule reads `var(--…)` from here. Swap this one file and the shell restyles. |
+| `dist/reset.css` | `flexdesk/css/reset` | `dist/reset.css` | The reset. |
+| `dist/flexdesk.css` | `flexdesk/css` | `dist/flexdesk.css` | The library. Every class is `twm-` prefixed (the original working name; the prefix is stable and not worth a breaking rename). |
+
+A bundler, an import-map generator or `require.resolve` reaches each one by its
+specifier, through the package's `exports` map, which closes every other path
+into the package. The map sends `flexdesk/css/tokens` to the source
+`css/tokens.css`, not `dist/tokens.css`. The two are identical in a release,
+since `dist/` is rebuilt in the release commit, but can differ on a working
+checkout. `flexdesk/css/reset` is missing from 0.16.1 and earlier,
+where it fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+`createDetailHeader` follows the prefix too: a badge is a `.twm-detail-header__badge`
+pill (a badge's `className` is added beside it, to recolour it), and an action is a
+`.twm-btn` — `variant: 'primary'` adds `.twm-btn--primary`, `'danger'` adds
+`.twm-btn--danger` — that also carries `.twm-detail-header__btn` and
+`.twm-detail-header__btn--<variant>`. The unprefixed `detail-header__badge` and
+`detail-header__btn--<variant>` it emitted before, which no FlexDesk rule styled, are
+gone.
+
+`@flexdesk/editor`'s components keep the class names they were extracted with, and
+`flexdesk.css` styles them: `SplitPaneContainer` (`.split-pane-container`,
+`.split-pane`, a 4px `.split-pane-divider` with a 10px hit target),
+`EditorPane` (`.editor-pane`, `.editor-pane__body`, `.notebook-editor-container`)
+and `NotebookSearchBar` (`.nb-search-bar*`). `setPanes()` adds `.split-pane` to the
+elements you hand it and leaves their own classes alone (it used to replace them,
+which stripped `.editor-pane` off an `EditorPane`).
+
+One exception to the prefix: `HelpModal` (`@flexdesk/widgets`) keeps its older
+`help-` classes (`help-modal-overlay`, `help-modal`, `help-index`, …), and
+`flexdesk.css` styles them — a centred dialog on a dimmed overlay, drawn over
+managed windows. `.help-article` holds your provider's rendered HTML and styles
+its plain elements (headings, code, tables, lists).
 
 Icons are rendered by applying the `material-symbols-outlined` class. FlexDesk does
 not ship the font — supply it from Google Fonts or self-host. Without it, icons fall