flexdesk 0.17.3 → 0.17.4

package/docs/components/flow-editors.md

@@ -0,0 +1,176 @@
+# Flow editors and the flow kit
+
+> **Packages:** `@flexdesk/flow`, `@flexdesk/canvas` · **Editors:** [canvas](flow-canvas-editor.md), [outline](flow-outline-editor.md), [lanes](flow-lane-editor.md) · [All docs](../README.md)
+
+This page introduces the flow editors and the kit they share. Each editor has its own page: the [canvas editor](flow-canvas-editor.md) (which stands on the `@flexdesk/canvas` kernel), the [outline editor](flow-outline-editor.md) and the [lane editor](flow-lane-editor.md).
+
+## 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. A type may also carry `render`, `update`, `size: {w, h}` and `accent` (a tone), which only the canvas editor reads ([Node bodies](flow-canvas-editor.md#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](flow-canvas-editor.md#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) |
+| `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`, `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.**
+
+```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`. 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 |
+|---|---|
+| `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`), 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
+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.

package/docs/components/flow-lane-editor.md

@@ -0,0 +1,165 @@
+# Flow lane editor
+
+> **Package:** `@flexdesk/flow` · **Shared kit:** [Flow editors and the flow kit](flow-editors.md) · [All docs](../README.md)
+
+## 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, 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 |
+|---|---|
+| `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}` |
+| `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 |
+|---|---|
+| `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`, `: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
+`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, 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*, *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.
+
+**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.

package/docs/components/flow-outline-editor.md

@@ -0,0 +1,176 @@
+# Flow outline editor
+
+> **Package:** `@flexdesk/flow` · **Shared kit:** [Flow editors and the flow kit](flow-editors.md) · [All docs](../README.md)
+
+## 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.
+
+**In a narrow editor** (under 1000px the list, the settings and the aside are
+stacked and the body scrolls as one), a step picked with the mouse, with Enter,
+with *Go to it* or with `select()` scrolls its settings on screen (`'nearest'`)
+when they lie outside the body's visible box. ↑ and ↓ leave the list where it
+is, and side by side nothing scrolls. `demo/flow_outline_narrow_probe.mjs`
+pressed a step at a 900px viewport and found the panel's first field with
+`elementFromPoint`. At 1440px the same press moved no scroll position.