flexdesk 0.5.0 → 0.6.1

package/README.md

@@ -33,7 +33,7 @@ That is exactly what EcoAgent does:
 <link href="./vendor/flexdesk/flexdesk.css" rel="stylesheet" />
 ```
 
-## Seven entry points
+## Nine entry points
 
 Because someone who wants a DataTable should not have to download a window
 manager, and neither of them should drag in a plotting engine or a code editor.
@@ -47,6 +47,12 @@ manager, and neither of them should drag in a plotting engine or a code editor.
 | `@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 |
 | `@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)) |
+
+The sizes of `@flexdesk/canvas` and `@flexdesk/flow` are the entry files as
+`node build.mjs` reported them for the flow editors' integration build; like
+every entry they also import shared chunks. The other rows are older figures.
 
 They share code through chunks, so importing two of them does **not** give you two
 event buses — and therefore not two copies of every module-level singleton. A test
@@ -315,6 +321,39 @@ behaves as it did in 0.4, except for these:
   to it if it is in a cascade layer, or has zero specificity and loads before
   `flexdesk.css`. A rule for the cells, the rows or the table does not.
 
+### Comparing two tables: `diff` and `createScrollLock`
+
+A side-by-side comparison is two `DataTable`s drawn from ONE aligned row list:
+the rows as they are on one side, as they were on the other, and a gap where
+a side has no row. Both options are off until you set them.
+
+```js
+import { DataTable, createScrollLock } from '@flexdesk/widgets';
+
+const lock = createScrollLock({ axis: 'y' });   // 'x', 'y' or 'both'
+const side = (host, pick) => DataTable.mount(host, {
+    headers, rows: aligned.map((r) => pick(r) ?? blank), pagination: false,
+    scrollLock: lock,
+    diff: (_row, i) => ({ status: statusOf(aligned[i], pick), cells: changedCols(aligned[i]) }),
+});
+side(left,  (r) => r.now);
+side(right, (r) => r.then);
+lock.setEnabled(false);   // scroll each side on its own; true brings them level
+```
+
+- `diff: (row, rowIdx) => {status, cells?}` draws the row
+  `twm-dt-diff twm-dt-diff--<status>`, for `added`, `removed`, `changed`,
+  `same` or `gap`, and each column index in `cells` (an array or a Set)
+  `twm-dt-diff__cell--changed`. `null` or any other status draws the row as
+  without `diff`. A `gap` row's cells are drawn empty, whatever its values and
+  `renderCell`, so the two sides keep their rows level. `updateRow` asks again.
+- `scrollLock` takes a group from `createScrollLock()`. The table's body box
+  joins it on every render and leaves on the next render and on `dispose()`.
+  Any element can join with `lock.attach(el)`, which returns its detach. A
+  box that joins starts at the group's last position, and the echo of a
+  position the lock itself wrote moves nobody back. The lock copies pixels, so
+  it lines rows up only when both sides draw rows of the same height.
+
 ### Scrollbars
 
 `installAutoScrollbars(root)` (from `@flexdesk/widgets`) replaces the browser's
@@ -325,6 +364,620 @@ 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.
 
+## Flow editors
+
+*New in 0.6.0.* Both entries first ship in FlexDesk 0.6.0.
+
+`@flexdesk/flow` holds three editors for flows — a graph of steps, each with
+settings — and the kit they share: a **canvas** (nodes and lines), an
+**outline** (the graph drawn as a list of blocks) and **lanes** (data flows,
+left to right). All three are domain-neutral. An editor never fetches, never
+saves and never starts a timer that writes: the step types, the reference
+grammar, every finding and every byte of I/O are the consumer's, handed in as
+options and handed back through callbacks. `@flexdesk/canvas` is the kernel
+under the canvas editor (and under any other diagram), on its own so that a
+diagram does not download the editors.
+
+Nothing here changes an existing entry. Both are new entry points, and their
+CSS is four new sections at the end of `flexdesk.css`, read only by the classes
+these modules set.
+
+```js
+import {
+    createStepCatalogue, createWidgetRegistry, createSettingsPanel,
+    TEMPLATE_REFERENCES, FlowHistory, bindFlowKeys,
+} from '@flexdesk/flow';
+```
+
+### The kit
+
+The parts every editor stands on, exported for a consumer that builds its own.
+A test (`tests/flow_kit_vocabulary.test.mjs`) fails when a file under
+`src/flow/` or `src/canvas/` names a consumer's vocabulary, calls `fetch` or
+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 |
+| `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) |
+| `createReferenceSyntax({name, pattern, format, describe, stepScope})` | What a chip is. Three are ready: `TEMPLATE_REFERENCES` (`${a.b[0]}`), `FORMULA_REFERENCES` (`[a.b]`), `PARAMETER_REFERENCES` (`{{name}}`). `find`, `format`, `rename(text, map)` and the consumer's `describe(match, ctx) → {label, tone, known}` |
+| `createChipInput({value, syntaxes, multiline, readOnly, onInput})` | Text with references drawn as chips. **The value is always the plain text**; a chip is a view of it |
+| `openStepPicker({anchor, entries, categories, where, paste})` | What "+" opens: grouped, searchable, ↑ ↓ and Enter; a refused entry is shown greyed with its reason. Resolves `{entry}`, `{paste: true}` or `null` |
+| `openValuePicker({anchor, groups, note, onPick})` | *Insert a value*: the consumer's groups of values, a level down for a value with children (`body ›`), searchable across levels |
+| `alwaysBefore(graph, catalogue, stepId, {loopPorts, waitsForAll})` | The steps that run before this one on every path, nearest first: the only ones *Insert a value* should offer. A parallel whose merge waits for every branch counts each branch's steps; a loop's body never counts for a step after the loop. `enclosingLoops` lists the loops around a step |
+| `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 |
+| `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.**
+
+```js
+const panel = createSettingsPanel({
+    widgets, references: { template: TEMPLATE_REFERENCES },
+    onChange: (stepId, key, value) => apply(stepId, key, value),   // you write it into your graph
+    onRename: (stepId, label) => rename(stepId, label),
+    onFocusLost: () => surface.focus(),
+    values: async ({ stepId, field }) => groupsFor(stepId),         // Insert a value; absent, no "{ }"
+    columns: (step) => inputColumnsOf(step),                         // upstream-column(s); null in a logic flow
+    host,
+});
+panel.show({ step, type, title, typeLabel, where, description, idLine, icon, tone,
+             rename: true, extra: [...], actions: [...], slots: { before, after } });
+panel.setFindings(findings);     // under each field, the rest at the top; rebuilds nothing
+panel.focusField('retry.max_attempts');
+panel.repaintSlots();            // your areas only; no field is rebuilt
+```
+
+It never writes into the step: a change is reported to `onChange`, and the
+consumer writes it. A redraw puts focus back on the rebuilt control of the same
+field, with the caret where it was, or hands it to `onFocusLost`, never to
+`<body>`. Findings and slot redraws rebuild no field, so a run overlay that
+refreshes every second leaves a name being typed alone. A control that cannot
+be used is disabled and its reason is shown next to it, not only in a tooltip.
+`extra` holds the editor's own fields (a port shown as a setting) and notes,
+placed with `after: '<key>'` or `at: 'start'`.
+
+**The widgets.** A schema type with no `x-ui-widget` draws its plain control: an
+`enum` a select (writing the enum's own value, so a number stays a number), a
+string a text box, a number a number box, a boolean a checkbox, an object with
+properties a group of its own fields. A control never writes a value the reader
+did not give it. An untouched setting stays absent, and emptying one removes it.
+A list or map entry keeps its stored type when another entry is edited. A widget
+name nobody registered is refused on screen, by name, and its value is kept.
+
+**A widget is built before it is in the document.** The panel calls the widget,
+then attaches what it returns, and a field inside a folded (`x-ui-fold`) group
+is built inside a closed `<details>`. A widget that measures itself — a Monaco
+editor registered as `expression` — must create that editor once its element is
+connected and has a size (a `ResizeObserver` on `el` will tell it), never inside
+the widget call: an editor built into a box with no size measures a zero
+character width and paints a viewport of no lines, and nothing repaints it.
+
+| Generic widget | Draws |
+|---|---|
+| `template` | Text with chips and *Insert a value*. A setting that may also be a list or an object is shown as JSON and written back as one when the text parses |
+| `expression` | A formula: monospace, with chips. Replace it with your own editor (`{replace: true}`) |
+| `json-body` | JSON when the text parses, text otherwise |
+| `key-value-map` | Names to values |
+| `key-value-list` | Ordered assignments: `{variable, value}` or `{variable, expression}` |
+| `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` |
+
+| Schema hint | Meaning |
+|---|---|
+| `x-ui-widget` | The widget that draws the field |
+| `x-ui-references` | The syntaxes its chips are recognised in, by name. Without it, `template`, `json-body` and the two key-value widgets use `template`, and `expression` uses `formula` |
+| `x-ui-when` | `{field, in}`: drawn only while that sibling holds one of those values (its stored value, else its default) |
+| `x-ui-placeholder`, `x-ui-multiline` | A placeholder; a string as a growing textarea |
+| `x-ui-enum-labels`, `x-ui-enum-descriptions` | An enum's words, and a sentence under each choice card |
+| `x-ui-fold` | An object drawn folded, with a one-line summary of what is set in it |
+| `x-ui-add-label` | The words on a list's *Add* button |
+| `x-ui-formula-references` | `key-value-list`: the syntaxes of a formula row (default `formula`) |
+
+**References and chips.** A syntax recognises references in order to draw them.
+It is not a grammar. A reference your server would refuse is still drawn as a chip
+(`describe` can mark it `known: false`) and kept as text. Each syntax has a
+default tone for its chips (`PARAMETER_REFERENCES` is violet, the others blue),
+so two syntaxes in one field read as two kinds of chip. In the chip input the
+browser does the typing, so an IME works. After every input the text is read
+back and re-tokenised. Everything else the control does on the text itself:
+← and → step over a chip, one Backspace removes a whole chip, a paste is plain
+text, a copy puts the exact text on the clipboard, and Enter adds a line only in
+a multi-line field. It keeps its own undo, because a script that redraws a
+`contenteditable` breaks the browser's. `rename(text, map)` rewrites only the
+path segment that names a step, and only once the syntax is told which segment
+that is (`stepScope: 'steps'`, or a `stepSegment` function). A syntax nobody
+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`,
+`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
+itself `data-twm-flow-item`, so Enter on it opens it. Inside a text field Ctrl+Z is the field's own, but it is
+still stopped at the editor's root, so a tile beside the editor never hears it.
+In a field every other key belongs to the field, and Enter on a button belongs
+to the button. **Backspace is never an editor key.** It is not handled and not
+stopped, because a host may use it to go back a level.
+
+**Tones and strings.** A category names a tone (`violet`, `teal`, `amber`,
+`grey`, `blue`, `indigo`), and `tokens.css` maps each tone to colours:
+`--twm-flow-<tone>-bg`, `-fg`, `-line`, `-icon-bg`, `-text-bg` and `-dot`.
+
+**What it does not do.** It does not validate a value against its schema, decide
+whether a reference is valid, save, fetch, or keep anything between page loads.
+Those belong to the consumer.
+
+**Where each claim was checked.** jsdom computes no layout and does no editing,
+so the suites (`tests/flow_kit_*.test.mjs`) assert the DOM, the events and the
+text. The rest was checked in headless Edge with real input over the DevTools
+protocol: `demo/flow_kit_probe.mjs` serves the repository, opens
+`demo/flow_kit.html` and drives it (`demo/flow_cdp.mjs` is the small driver it
+uses, for the editors' pages too). The demo pages load the source barrels;
+`FLOW_DIST=1 node demo/flow_<kit|canvas|outline|lanes>_probe.mjs` redirects
+`flow.js`, `canvas.js` and the three sheets to `dist/`, so the same checks run
+against the built bundle. All four probes passed both ways on the integration
+build. In the chip input, typing on either side of
+a chip, ← and → over it, one Backspace removing it, a real paste of `${a.b}`
+becoming a chip, a real copy giving the exact text, an IME composition leaving
+the text alone until it committed, and the field's own Ctrl+Z all passed. The
+same Backspace in a plain `contenteditable` whose chips are not
+`contenteditable="false"` split its chip. A pointer drag across a chip started
+no native drag. `elementFromPoint` at the centre of Undo, "+", the panel's
+first field, its title, a field's "{ }", an action, a choice and the strip's
+*Go to it* returned each one. Both pickers opened inside the viewport, their
+search box focused, and gave the focus back to "+" on Escape.
+
+### The canvas editor
+
+A flow drawn as nodes and lines: a palette of step types, a pannable canvas and
+the settings of whatever is picked, under a toolbar. It stands on the
+`@flexdesk/canvas` kernel, which is also usable on its own for any diagram.
+
+**The kernel** (`@flexdesk/canvas`).
+
+| 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 |
+| `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 |
+| `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 |
+
+A diagram with its own rules subclasses the three and passes them in. For
+example, a schema diagram's router answers the generic refusals in its own
+words and keeps its foreign-key rules in the policy:
+
+```js
+class ConnectorRouter extends Base.ConnectorRouter {
+    constructor({ platform }) {
+        super({ platform, selfReference: true, disabledEnds: ['source'],
+                endsOf: (e) => ({ from: `col:${e.from_col}`, to: `col:${e.to_col}` }),
+                strings: { nodeGone: 'That table is no longer on the diagram.' },
+                policy: (ctx) => myForeignKeyRules(ctx) });
+    }
+}
+```
+
+`tests/canvas_graph.test.mjs` §7 builds such a diagram on the generic layer.
+
+**The editor.**
+
+```js
+import { createCanvasEditor, createStepCatalogue } from '@flexdesk/flow';
+
+const editor = createCanvasEditor(host, {
+    catalogue: createStepCatalogue(types, { categories }),
+    flowSettings: { title: 'Sync', schema, value },          // the flow's own settings, shown when nothing is picked
+    actions: [{ id: 'publish', label: 'Publish', icon: 'publish', primary: true, run: (ed) => publish(ed) }],
+    onChange: ({ graph, flowSettings, text, action, key, via }) => autosave(text),
+    values: async ({ stepId, field, before, loops }) => groups,   // Insert a value
+    dataPortRead: (node, port) => `\${steps.${node.id}.${port.name}}`,
+    summariseReads: (node) => `Later steps read it as \${steps.${node.id}.…}`,
+});
+editor.load({ graph });                  // a baseline: there is nothing to undo after it
+editor.setFindings(validatorResult);     // on the nodes, under the fields, in the strip
+editor.setRunOverlay({ steps, ports, banner });
+```
+
+| Option | Meaning |
+|---|---|
+| `catalogue` | `createStepCatalogue(...)`, or the raw list of types. The palette shows them by category, except start-role types (`paletteTypes(type)` decides). A type with `unavailable` is shown greyed, with its sentence under it |
+| `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 |
+| `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 |
+| `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` |
+| `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 |
+| `history`, `gridSize`, `label` | `{limit, mergeMs}`, the snap grid, and the canvas's accessible name |
+
+| 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 |
+| `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})` | — |
+| `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})` | — |
+| `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 |
+
+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
+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`.
+
+**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
+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
+`document.body`. It never uses `draggable`, which cancels the pointer after
+about 5px, and never `setPointerCapture`, which would send the release, and so
+a second click, to the palette button. No press rebuilds a node, so a click lands
+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.
+
+**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.
+
+**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
+the consumer. Nor does it add anything a flow must have: a consumer whose new
+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
+`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
+  and Remove step returned each one, and the panel was not covered.
+- Every line began and ended within 1px of its ports' dots, measured.
+- The loop's line back ran below both of its steps.
+- A real pointer drag from the palette added exactly one step, under the
+  pointer, with a `dragstart` counter of 0. A drag ending off the canvas added
+  nothing.
+- 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.
+- At 700px the canvas took the editor's whole width.
+
+### The outline editor
+
+`createOutlineEditor` draws a logic flow as a list of blocks: *If … otherwise*,
+*For each row* with its *Next row* foot, *At the same time* with its *Then wait
+for every branch* foot, and a step's other ports (an error port, an empty-result
+port) as arms under it. **The outline is the graph.** It reads the same
+`{nodes, connections}` JSON the canvas edits, holds no second model, and every
+edit is an operation on that graph. A graph opened and saved with no edit is the
+same text, byte for byte, and node positions are kept and never used. A graph
+that is not block-shaped is refused, never repaired: it opens read-only, as a
+flat list in the order it runs, with the reason above it.
+
+```js
+import { createOutlineEditor, createStepCatalogue, createWidgetRegistry, TEMPLATE_REFERENCES } from '@flexdesk/flow';
+
+const editor = createOutlineEditor(host, {
+    catalogue, widgets: createWidgetRegistry(), references: { template: TEMPLATE_REFERENCES },
+    blocks,                                            // which roles are blocks, and their words (below)
+    values: async ({ stepId, field, before, loops }) => groupsFor(before, loops),   // Insert a value
+    valuesNote: 'Only steps that always run before this one are listed.',
+    summarise: (node, type) => oneLine(node),          // a row's line; {text, mono: true} for code
+    summariseReads: (node, type) => howLaterStepsRead(node),   // the panel's id line
+    flowSettings: { schema, value, title, typeLabel, where, description, idLine },
+    actions: [{ id: 'publish', label: 'Publish', icon: 'publish', primary: true, run: () => publish() }],
+    slots: { toolbarEnd: (el) => {}, flowPanel: (el) => {}, stepPanel: (el, node) => {} },
+    initialFolds: saved, onFoldChange: (ids) => keep(ids),
+    onChange: ({ graph, flowSettings, text, action, key }) => autosave(text),
+    onSelect: ({ kind, id }) => {},                    // kind: 'flow' or 'step'
+    readOnly: false,                                   // or {reason}
+    history: { limit: 100, mergeMs: 1000 },
+});
+editor.load({ graph, flowSettings });                  // a baseline: nothing to undo
+```
+
+| Method | Does |
+|---|---|
+| `load({graph, flowSettings}, {baseline = true})` | Replaces the content; a baseline clears both undo stacks and emits nothing |
+| `getGraph()`, `serialise()`, `getFlowSettings()` | A copy of the graph; its byte-stable text; the flow's own settings |
+| `setFindings(list)` | A finding with a `node_id` replaces that row's line with its message, in the error or warning tone, marks the row, and is drawn under its field; the others go to the strip, with *Go to it* |
+| `setRunOverlay({steps, ports, banner} \| null)` | A run drawn on the outline (below) |
+| `setReadOnly(false \| {reason})`, `setActionState(id, {disabled, reason, busy})`, `setStatus(text)` | A refused verb is disabled with its reason beside it |
+| `select(id \| 'flow' \| null)`, `focus()`, `undo()`, `redo()`, `history`, `folds`, `setFolds(ids)` | `select` unfolds the blocks around the step |
+| `describe()`, `refusal` | The outline as text (`describeOutline`), or why the graph could not be drawn as one |
+| `destroy()` | Removes every listener, popover and ghost. It flushes nothing, because it holds nothing |
+
+**The block mapping.** The consumer says which catalogue roles are blocks and
+what their parts are called. Nothing here guesses a domain:
+
+```js
+const blocks = {
+    start:  { role: 'start', label: 'When it runs' },        // the flow row
+    end:    { role: 'end', entry: { label: 'End the run', sub: 'End' } },
+    step:   { input: 'in', continue: 'out' },                 // an ordinary step's two ports
+    branch: { role: 'branch', arms: { true: 'Then', false: 'Otherwise' },
+              entry: { label: 'If … otherwise', sub: 'Condition' }, note: 'Either arm may be empty.' },
+    fanout: { role: 'fanout', join: { role: 'join', type: 'merge', field: 'join',
+                                      foot: { all: 'Then wait for every branch', any: 'Then go on when the first finishes' } },
+              arm: 'Branch {n}', addArm: 'Add a branch', entry: { label: 'At the same time', sub: 'Parallel + Merge' } },
+    loop:   { role: 'loop', ports: { entry: 'in', next: 'next', body: 'body', done: 'done' },
+              foot: 'Next row', skip: 'Go on with the next row', addInside: 'Add a step to the loop',
+              entry: { label: 'For each row', sub: 'Loop over rows' } },
+    arms:   { error: { label: (step) => `If ${step.label} fails`, unconnected: 'fail',
+                       setting: { label: 'If it fails', unconnected: 'Fail the run', after: 'timeout_seconds',
+                                  connected: (arm) => `Run the steps under “${arm}”` } } },
+    types:  { 'http-request': { arms: { error: { label: 'If the request fails' } } } },
+};
+```
+
+`unconnected` is what your runtime does with a port nothing is connected to,
+`'fail'` or `'stop'`, and only you can say it. An ordinary step's other flow
+outputs are its arms, in the order the type declares them. **Ports become
+settings** in the panel. An arm is a choice between "Fail the run" (or "Stop
+here") and "Run the steps under …", which connects or disconnects the port. An
+arm inside a loop also chooses between carrying on with the next step and going
+on with the next row. A parallel step carries its merge's *When the branches
+finish*, written to the merge step's config.
+
+**What "block-shaped" means.** From the start step, every step is placed exactly
+once: as a step, a branch, a parallel closed by one merge, a loop whose body
+ends at its Next, or an end. An arm ends by rejoining what follows its block,
+by going on with the loop's next row, by ending, or by leaving its port
+unconnected. Anything else is refused with a code and the step it names:
+`outline_no_start`, `outline_two_starts`, `outline_unknown_type`,
+`outline_unknown_port`, `outline_broken_line`, `outline_unreachable`,
+`outline_shared_step`, `outline_jump_out`, `outline_two_continuations`,
+`outline_parallel_unjoined`, `outline_merge_unpaired`, `outline_loop_shape`,
+`outline_after_end`, `outline_cycle`. Where a branch's arms meet nowhere
+(every arm but one ends), the arm that goes on holds the rest of its list. The
+lines cannot say more than that, and the outline does not pretend they do.
+
+**Edits.** "+" between rows (shown on hover and on focus) and the add rows open
+the kit's step picker. It says where the step will land (*"inside For each new
+application, after Check eligibility"*) and offers the blocks as blocks: *At
+the same time* is one entry and two steps. A step's menu (its "…", a
+right-click, or the ContextMenu key) moves it up, down or out, wraps it in a
+block, duplicates, copies, cuts, pastes after, renames and removes it. An entry
+or a verb that would leave a graph the outline cannot draw is shown greyed with
+its reason: *"Move down — already last in For each new application"*. A step is
+dragged by its grip, with pointer events and a ghost after 4 px, never
+`draggable` and never `setPointerCapture`. Its drop line names the place
+(*"Into Branch 2 · after Write a summary"*) or says why the place is refused.
+Each edit is one history entry from a closed list: `flow:step:add`, `remove`,
+`move`, `wrap`, `duplicate`, `paste`, `label` and `config`, `flow:arm`,
+`flow:branch:add`, `flow:branch:remove` and `flow:settings`.
+
+**Keys.** ↑ and ↓ move the selection, ← and → fold and unfold, and Enter opens
+the settings at their first field. Alt+↑, Alt+↓ and Alt+← move a step, Ctrl+D
+duplicates, Ctrl+C, Ctrl+X and Ctrl+V copy, cut and paste after the selection,
+F2 renames, Delete removes, and Ctrl+Z and Ctrl+Y undo and redo. All of them are
+bound on the editor's root. Backspace is never the editor's.
+
+***Insert a value*.** A field's "{ }" calls your `values` provider with
+`before`, the steps that always run before this one, nearest first
+(`alwaysBefore`), and `loops`, the loops the step is inside, innermost first. A
+step on the other arm of a condition is never in `before`, and neither is a
+loop's body for a step after the loop.
+
+**A run drawn on the outline.** `setRunOverlay({steps: {[id]: {state, line,
+tone}}, ports: {[id]: {[port]: {taken, count}}}, banner})` puts a pill beside
+each step. The pill shows `line` as you give it, toned by `state`
+(`completed`, `failed`, `skipped`, `running`, `cancelled`, `not-reached`). Each
+arm says *taken*, *not taken* or a count, an untaken arm and its steps are
+dimmed, a loop's *Next row* shows its count (`ports[loop].next.count`), and
+your banner is shown above the list. It draws only what you pass, and it
+rebuilds no field in the panel. A redraw you did not ask for (findings, a run
+refresh, a read-only switch) waits while a press is held in the editor, because
+a browser fires a click only when the press and the release land on the same
+element.
+
+**The pure parts** are exported for a consumer that reads or checks an outline
+without drawing one. `outlineFromGraph(graph, catalogue, blocks)` returns
+`{ok: true, tree}` or `{ok: false, code, message, node_id}`, and
+`graphFromOutline(tree)` is its inverse (`outlineGraphsEqual(a, b)` compares
+two graphs as sets). `describeOutline(tree)` gives the tree as text.
+`createOutlineOperations({catalogue, blocks, references})` gives every edit as
+a function from a graph to `{ok, graph, select}` or `{ok: false, reason}`. Also
+exported: `createOutlineBlocks`, `outlineRunOrder`, `outlineFlatOrder`,
+`indexOutline`, `openOutlineStepMenu`, `OUTLINE_STRINGS`, `OUTLINE_ACTIONS` and
+`OUTLINE_INDENT` (22 px a level, which the stylesheet also uses).
+
+**What it does not do.** It does not fetch, save, validate or start a timer
+that writes. Your validator's findings are drawn, never made. The folds are
+yours to keep (`initialFolds`, `onFoldChange`).
+
+**Where each claim was checked.** The round trip is tested over a corpus
+(`tests/fixtures/flow_outline_corpus.json`). Every block-shaped graph is
+recognised as the tree the corpus states and written back equal as sets (I1).
+Opened and saved with no edit, it is the same text (I2). Random sequences of
+operations keep it block-shaped (I3). Every refusal names a code and a step and
+leaves the graph untouched (I4). `tests/flow_outline_editor.test.mjs` mounts
+the editor in jsdom, and `tests/flow_outline_css.test.mjs` checks that every
+class the editor sets has a rule and every rule names a class it sets. jsdom
+computes no layout and starts no drag, so `demo/flow_outline_probe.mjs` drives
+`demo/flow_outline.html` in headless Edge with real input. `elementFromPoint`
+at the centre of Undo, an action, Fold all, the find box, the flow row, a row,
+its menu, its "+" (with its row hovered), an add row, the panel's first field,
+a port drawn as a setting and the strip's *Go to it* returned each one. A "+"
+whose row was not hovered caught no press, and a level measured 22 px. The step
+picker and the step menu opened inside the viewport on a real press, real keys
+filtered and chose, and Escape gave the focus back. Real Alt+↑, Ctrl+Z, Ctrl+D
+and Delete edited the flow, and Backspace reached the window unprevented. A real
+grip drag drew its ghost and a drop line naming the place, moved the step as
+one edit and started no native drag (a `dragstart` counter at 0). A refused
+place said why and moved nothing, and Escape cancelled the drag.
+
+### The lane editor
+
+`createLaneEditor(host, options)` draws a data flow as lanes, left to right.
+Every source starts a lane, and each step follows the one before it. A join
+brings another lane in from below, and its line is laid out for you. Cards sit
+where the layout puts them: **nothing is dragged and no line is drawn by
+hand.** A step is added with the "+" on a card's right tip, which splices it in
+between the card and what the card led to (`A → new → B`). *Add a source* starts
+a new lane. A join's other lanes are settings (*Joined with*), not lines. Under
+the lanes are a tab per step and a dock: the kit's settings panel on the left,
+and on the right what the step gives — **Preview**, **Columns** and, for a sink,
+**Would be rejected**. A toolbar toggle, **Steps show: The preview | The last
+run**, picks what each card's status line says.
+
+```js
+import { createLaneEditor, createStepCatalogue, createWidgetRegistry, PARAMETER_REFERENCES } from '@flexdesk/flow';
+
+const editor = createLaneEditor(host, {
+    catalogue: createStepCatalogue(types, { categories }),   // roles: source | transform | operation | sink
+    widgets: createWidgetRegistry(),
+    references: { parameter: PARAMETER_REFERENCES },
+    summarise: (step, type) => '…',            // a card's second line
+    preview: async ({ pipeline, text, parameters, signal }) => ({ nodes: { [id]: {
+        status, rows, total, columns: [{ name, type }], head: [[…]], caption, rejects, error } } }),
+    describe: async ({ pipeline, text, parameters, signal }) => ({ nodes: { [id]: {
+        columns: [{ name, type, origin, change }] } } }),
+    lastRun: async ({ pipeline, signal }) => runOverlay,      // asked when Steps show turns to The last run
+    actions: [{ id: 'publish', label: 'Publish', primary: true, run }],
+    onChange: ({ pipeline, text, action, key }) => save(text),   // after every edit, undo and redo
+});
+editor.load({ graph: pipeline });
+```
+
+It edits the data flow's JSON — `{nodes: [{id, type, label?, config, position?}],
+connections: [{id, sourceId, sourcePort, targetId, targetPort}], parameters:
+{name: {type, default?, description?}}}` — with two rules added. A step's name
+is a top-level `label`, never a key inside `config`. Connection ids are
+deterministic: `c1`, `c2`, … the lowest free number. `serialisePipeline` is
+byte-stable, so a flow opened and saved with no edit is the same text. Keys the
+editor does not know are kept, and a node's `position` is kept and never used.
+**A step's ports keep their declared order**: the first FLOW input is the lane
+input, and every further input takes another lane. The first output is the
+continuation.
+
+**The layout** is `layoutLanes(pipeline, catalogue)` and `placeLanes(layout,
+size)`. Both are pure, and the wires are computed from the grid, never measured
+from the page. A step belongs to the lane that feeds its lane input, not to
+whichever lane reaches it first. An output that feeds two steps' lane inputs
+forks a new lane below. A feeder lane is moved right until its last card sits
+one column before the join it feeds, and never so far that the join moves.
+Under each lane come its feeders, then its forks. A wire that would run through a card that is not one of its ends (a feeder that goes on past its feed, a fork drawn under a feeder) goes round by the gutters, the gaps between columns and between lanes, which hold no card. A step two lines feed on one
+input (`lanes_two_inputs`), a cycle (`lanes_cycle`) or two steps with one id
+(`lanes_duplicate_step`) cannot be drawn honestly as lanes. Such a flow opens
+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`.
+
+| Option | Meaning |
+|---|---|
+| `catalogue` | The kit's step catalogue (or a list of types and `categories`) |
+| `widgets`, `references`, `services`, `strings` | As for the kit's panel. `references.parameter` decides how the parameters strip spells a reference |
+| `values` | *Insert a value*: `({pipeline, stepId, field, key, upstream, parameters}) => groups`. `upstream` is every step whose output reaches this one, nearest first |
+| `summarise(step, type)`, `summariseReads(step, type)` | A card's second line; the panel's id line |
+| `preview`, `describe` | The providers (above). Absent, the dock has no Preview, or no Columns |
+| `previewDelayMs` | The debounce, 800 by default |
+| `lastRun` | Asked once, when *Steps show* first turns to *The last run* and no overlay is set |
+| `flowSettings` | `{schema, value}`: the flow's own settings, under a first tab, *The flow* |
+| `readOnly` | `false`, or `{reason}`, drawn above the editor |
+| `actions` | Toolbar verbs after Undo and Redo: `[{id, label, icon?, primary?, run}]` |
+| `slots` | `toolbarStart(el)`, `toolbarEnd(el)`, `flowPanel(el)`, `stepPanel(el, step)` |
+| `size` | `'regular'` or `'small'` |
+| `stepTabs`, `parameters` | `false` leaves out the step tabs or the parameters strip |
+| `height` | `'fill'` (the default: the editor fills its host, which must have a height) or `'auto'` (the editor flows, and the dock is `dockHeight`, 360 by default) |
+| `compact` | `true` (or `{size: 'small'}`): the lanes alone, read only, nothing to press. This is what a step that runs a data flow shows as *What it does, left to right* |
+| `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}` |
+| `onChange`, `onSelect({kind, id})`, `onStepsShow(mode)` | Callbacks |
+
+| Method | Does |
+|---|---|
+| `load({graph, flowSettings}, {baseline = true})` | Replaces the content. A baseline clears both undo stacks, and a preview is asked for at once |
+| `getGraph()`, `serialise()`, `getFlowSettings()` | A copy of the flow; its byte-stable text |
+| `setFindings(list)` | On the card (its status line becomes the message), under the field, and in the strip with *Go to it* |
+| `setRunOverlay({steps: {[id]: {state, line, tone}}, banner})` | The last run, shown when *Steps show* is *The last run*. `line` is drawn as given |
+| `setStepsShow('preview' \| 'run')`, `stepsShow` | — |
+| `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`) |
+| `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 |
+
+**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
+`AbortSignal`. A newer edit aborts the request in flight, and an answer that is
+not the newest is dropped even when it arrives. A failure is shown as the
+provider's own sentence in the dock, and nothing else changes. The rows are a
+FlexDesk `DataTable` in a box with a definite height. How many rows a preview
+reads, as whom it reads them and that it writes nothing are all the provider's
+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.
+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
+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.
+
+**What it does not do.** It does not fetch, save, validate, propagate a schema,
+coerce a value or run anything. Steps are never dragged and lines are never
+drawn by hand. The editor does not draw a page trail, a breadcrumb or a "you
+are editing the shared flow" banner either: a host draws those around it.
+
+**Where each claim was checked.** The layout, the JSON, the edits and the
+preview runner are pure, and `tests/flow_lanes_layout.test.mjs`,
+`flow_lanes_pipeline.test.mjs` and `flow_lanes_preview.test.mjs` test them under
+plain node. The layout suite reproduces the mock and shows that the earlier
+layout (EcoSim's `buildLanes`, copied verbatim) puts the join in the feeder's
+lane when the feeder is listed first. The preview suite has a provider that
+answers out of order, and the stale answer is shown to be dropped.
+`flow_lanes_editor.test.mjs` mounts the editor in jsdom: choosing a card
+rebuilds no node, every edit is one undo entry, and a flow that cannot be drawn
+is never written. `flow_lanes_css.test.mjs` holds the classes and the rules to
+each other and the sheet's card sizes to `LANE_GEOMETRY`. The rest was checked
+in headless Edge with real input (`node demo/flow_lanes_probe.mjs`, which opens
+`demo/flow_lanes.html` at all three sizes). In a laid-out page every wire
+starts at its card's tip and ends in the next card's notch, and the join's line
+and its port dot meet the join's bottom centre. `elementFromPoint` at the centre
+of Undo, a card, a "+", *Add a source*, a step tab, *Steps show*, a parameter,
+the panel's first field, its name, *Remove step*, a dock tab and a preview cell
+returns each one, and the settings are covered by nothing. The preview's
+`DataTable` draws its rows with a height, and every card's words stay inside
+the card. A real press on "+" opens the picker inside the viewport with its
+search focused, and real keys filter it and add the step. A real drag across a
+card starts no native drag (a `dragstart` counter at 0) and moves nothing. Real
+arrows, Delete, Ctrl+Z and Backspace do what is said above, and three real
+keystrokes ask the preview once.
+
 ## The host port
 
 FlexDesk never touches `pywebview`, `fetch`, `localStorage` or the filesystem. It