flexdesk 0.5.0 → 0.6.1

package/src/flow/kit/findings.js

@@ -0,0 +1,129 @@
+/**
+ * FINDINGS — what the consumer's validator said, drawn where it applies
+ * (36 §3.8). The kit decides none of them.
+ *
+ * A finding is the server's shape: `{code, message, severity: 'error' |
+ * 'warning', node_id?, field?}`.
+ *
+ *  - one with a `node_id` is drawn ON THAT STEP (each editor draws its own
+ *    mark) and, while that step's settings are open, under its field;
+ *  - one without a `node_id` is drawn in the STRIP;
+ *  - the strip lists every one of them, with *Go to it*;
+ *  - one naming a step the graph no longer has goes to the strip as well —
+ *    never nowhere.
+ */
+
+import { button, el } from './dom.js';
+import { createStrings, say } from './strings.js';
+
+/** A list, or a validator result `{errors, warnings}`, as one list. */
+export function findingsList(input) {
+    if (Array.isArray(input)) return input.filter((f) => f && typeof f === 'object');
+    if (input && typeof input === 'object') {
+        return [...(input.errors || []), ...(input.warnings || [])].filter((f) => f && typeof f === 'object');
+    }
+    return [];
+}
+
+/**
+ * The findings grouped by the step they are drawn on: a Map keyed by
+ * `node_id`, `null` for the flow. With `graph`, a finding naming a step the
+ * graph no longer has is filed under `null`.
+ */
+export function groupFindings(input, { graph = null } = {}) {
+    const ids = graph ? new Set((graph.nodes || []).map((n) => n.id)) : null;
+    const out = new Map();
+    for (const f of findingsList(input)) {
+        let key = f.node_id ?? null;
+        if (key !== null && ids && !ids.has(key)) key = null;
+        if (!out.has(key)) out.set(key, []);
+        out.get(key).push(f);
+    }
+    return out;
+}
+
+/** Is `prefix` a path prefix of `path` at a segment boundary? */
+export function isPathPrefix(prefix, path) {
+    if (!prefix || !path) return false;
+    if (path === prefix) return true;
+    if (!path.startsWith(prefix)) return false;
+    const next = path[prefix.length];
+    return next === '.' || next === '[';
+}
+
+/**
+ * The field a finding is drawn under: the LONGEST of `paths` that is a
+ * segment-boundary prefix of the finding's `field`, or null.
+ */
+export function matchFindingField(paths, field) {
+    if (!field) return null;
+    let best = null;
+    for (const p of paths) {
+        if (isPathPrefix(p, field) && (best === null || p.length > best.length)) best = p;
+    }
+    return best;
+}
+
+/** `error` before `warning`, otherwise as given. */
+function bySeverity(list) {
+    return list.map((f, i) => ({ f, i }))
+        .sort((a, b) => ((a.f.severity === 'warning') - (b.f.severity === 'warning')) || (a.i - b.i))
+        .map((x) => x.f);
+}
+
+/**
+ * The strip: "N things to fix before this can be published." and one line per
+ * finding with *Go to it*. `aria-live="polite"`, hidden while empty.
+ *
+ * @param {object} [o]
+ * @param {(finding: object) => void} [o.onGoTo]   select the step and focus the field
+ * @param {(nodeId: string|null) => string} [o.nameOf]   a step's name for its line
+ * @param {object} [o.strings]
+ */
+export function createFindingsStrip({ onGoTo = null, nameOf = null, strings = null } = {}) {
+    const S = createStrings(strings);
+    const root = el('div', 'twm-flow-strip');
+    root.setAttribute('role', 'status');
+    root.setAttribute('aria-live', 'polite');
+    root.hidden = true;
+    let list = [];
+
+    const paint = () => {
+        root.replaceChildren();
+        root.hidden = list.length === 0;
+        if (!list.length) return;
+        const errors = list.filter((f) => f.severity !== 'warning').length;
+        root.classList.toggle('twm-flow-strip--warning', errors === 0);
+        const head = el('div', 'twm-flow-strip__head');
+        head.append(el('span', 'twm-flow-strip__icon material-symbols-outlined', errors ? 'error' : 'warning'),
+                    el('span', 'twm-flow-strip__title', errors
+                        ? say(S, 'toFix', errors) : say(S, 'toLookAt', list.length)));
+        head.firstChild.setAttribute('aria-hidden', 'true');
+        root.appendChild(head);
+        const lines = el('ul', 'twm-flow-strip__list');
+        for (const f of bySeverity(list)) {
+            const li = el('li', `twm-flow-strip__line${f.severity === 'warning' ? ' twm-flow-strip__line--warning' : ''}`);
+            li.dataset.code = String(f.code ?? '');
+            if (f.node_id !== undefined && f.node_id !== null) li.dataset.node = String(f.node_id);
+            const where = f.node_id ? (nameOf?.(f.node_id) || String(f.node_id)) : (nameOf?.(null) || '');
+            li.appendChild(el('span', 'twm-flow-strip__text', say(S, 'findingLine', where, String(f.message ?? ''))));
+            if (onGoTo) {
+                li.appendChild(button({ label: say(S, 'goToIt'), className: 'twm-flow-strip__go',
+                                        onClick: () => onGoTo(f) }));
+            }
+            lines.appendChild(li);
+        }
+        root.appendChild(lines);
+    };
+
+    return {
+        el: root,
+        /** Draw `input` (a list or `{errors, warnings}`). */
+        set(input) {
+            list = findingsList(input);
+            paint();
+        },
+        get findings() { return [...list]; },
+        destroy() { root.remove(); },
+    };
+}

package/src/flow/kit/history.js

@@ -0,0 +1,173 @@
+/**
+ * UNDO AND REDO OVER WHOLE SNAPSHOTS, BEHIND A CLOSED ACTION LIST (36 §3.9).
+ * PURE: no DOM, runs under plain node.
+ *
+ * Generalised from Tables' designer history in exactly one respect: the
+ * closed list of actions is the EDITOR's, passed in, and `commit` still throws
+ * on any other. Everything else is kept, behaviour and reason.
+ *
+ * ══ WHY SNAPSHOTS ══════════════════════════════════════════════════════
+ *
+ * A flow is small — a few dozen steps and their settings — and one serialised
+ * snapshot IS the whole flow (its graph and its own settings), so "undo" is
+ * "put the text back" and there is no inverse to get wrong.
+ *
+ * ══ THE CLOSED LIST ════════════════════════════════════════════════════
+ *
+ * A future mutation path that forgets to name its action cannot silently fold
+ * itself into the next entry; it fails the first test that drives it. Loading
+ * a flow and a consumer's publish are absent from every list BY DESIGN: they
+ * are BASELINES (both stacks cleared), never entries — the first Ctrl+Z after
+ * opening must not "undo" the opening, and a publish is the boundary.
+ *
+ * ══ MERGING ════════════════════════════════════════════════════════════
+ *
+ * Typing a label is one edit to a reader, not one per keystroke. A commit with
+ * a `key` equal to the top entry's, within `mergeMs` of that entry's last
+ * commit, and with no undo or redo since, updates the top entry instead of
+ * pushing a new one — so the entry still restores the text from BEFORE the
+ * typing began. A merge that lands back on that text drops the entry: a label
+ * typed and deleted again is no edit. The first commit after an undo or a redo
+ * never merges, even inside the window: the entry it would merge into is an
+ * older one the undo exposed, and the next undo would skip a state.
+ *
+ * ══ SURVIVING A DESTROY ════════════════════════════════════════════════
+ *
+ * A host may destroy an editor on a tab switch. `keep()` hands the stacks to
+ * the caller; `adopt(kept, state)` takes them back only when the state the
+ * successor loaded is BYTE-IDENTICAL to the state the stacks were settled on.
+ * Bytes are this class's half of the rule: a consumer whose publish turns a
+ * draft into a published version byte-identical to it must also check that
+ * the successor holds the SAME DRAFT — a fact only the consumer can see — and
+ * check it before calling `adopt`.
+ */
+
+export class FlowHistory {
+    /**
+     * @param {object} options
+     * @param {readonly string[]} options.actions  the edits this editor records — anything else throws
+     * @param {(state: string) => void} options.restore  puts a snapshot back
+     * @param {() => void} [options.onState]  after every change to the stacks
+     * @param {number} [options.limit]  entries kept; the oldest goes first
+     * @param {number} [options.mergeMs]  how close two keyed commits must be
+     * @param {() => number} [options.now]  the clock, for a test
+     */
+    constructor({ actions, restore, onState = null, limit = 100, mergeMs = 1000, now = () => Date.now() } = {}) {
+        if (!Array.isArray(actions) || actions.length === 0 || !actions.every((a) => typeof a === 'string')) {
+            throw new Error('FlowHistory needs its editor\'s closed list of actions: an edit nobody named '
+                            + 'must fail rather than fold itself into the next entry.');
+        }
+        if (typeof restore !== 'function') {
+            throw new Error('FlowHistory needs a restore(state) function: undo has nothing to put back without one.');
+        }
+        this.actions = Object.freeze([...actions]);
+        this._restore = restore;
+        this._onState = onState;
+        this._limit = limit;
+        this._mergeMs = mergeMs;
+        this._now = now;
+        this._undo = [];
+        this._redo = [];
+        this._settled = null;
+        this._travelled = true;
+        this.applying = false;
+    }
+
+    get canUndo() { return this._undo.length > 0; }
+    get canRedo() { return this._redo.length > 0; }
+    get depth() { return this._undo.length; }
+    /** The state the stacks describe the present as. */
+    get settled() { return this._settled; }
+    /** The action the next undo would undo, or null. */
+    get undoAction() { return this._undo[this._undo.length - 1]?.action ?? null; }
+    /** The action the next redo would redo, or null. */
+    get redoAction() { return this._redo[this._redo.length - 1]?.action ?? null; }
+
+    /** The hydration gate: `state` is where history starts, and nothing before it is undoable. */
+    baseline(state) {
+        this._undo = [];
+        this._redo = [];
+        this._settled = state;
+        this._travelled = true;
+        this._changed();
+    }
+
+    /**
+     * Record that the flow is now `state`, by `action`. A no-op when nothing
+     * changed or while a restore is being applied. Returns whether the stacks moved.
+     */
+    commit(state, action, key = null) {
+        if (!this.actions.includes(action)) {
+            throw new Error(`"${action}" is not an edit this editor records (its actions are `
+                            + `${this.actions.join(', ')}).`);
+        }
+        if (this.applying || state === this._settled) return false;
+        const at = this._now();
+        const top = this._undo[this._undo.length - 1];
+        if (key !== null && top && top.key === key && !this._travelled && at - top.at < this._mergeMs) {
+            top.at = at;
+            // Typed, then typed away again: the entry changes nothing.
+            if (top.before === state) this._undo.pop();
+        } else {
+            this._undo.push({ action, key, at, before: this._settled });
+            if (this._undo.length > this._limit) this._undo.shift();
+        }
+        this._redo = [];
+        this._settled = state;
+        this._travelled = false;
+        this._changed();
+        return true;
+    }
+
+    undo() {
+        const entry = this._undo.pop();
+        if (!entry) return false;
+        this._redo.push({ action: entry.action, after: this._settled });
+        this._travel(entry.before);
+        return true;
+    }
+
+    redo() {
+        const entry = this._redo.pop();
+        if (!entry) return false;
+        this._undo.push({ action: entry.action, key: null, at: 0, before: this._settled });
+        this._travel(entry.after);
+        return true;
+    }
+
+    /** The stacks, to be handed back to a successor through `adopt`. */
+    keep() {
+        return {
+            undo: this._undo.map((e) => ({ ...e })),
+            redo: this._redo.map((e) => ({ ...e })),
+            settled: this._settled,
+        };
+    }
+
+    /** Take `kept`'s stacks when they were settled on exactly `state`. */
+    adopt(kept, state) {
+        if (!kept || typeof kept.settled !== 'string' || kept.settled !== state) return false;
+        this._undo = (kept.undo || []).map((e) => ({ ...e }));
+        this._redo = (kept.redo || []).map((e) => ({ ...e }));
+        this._settled = state;
+        this._travelled = true;
+        this._changed();
+        return true;
+    }
+
+    _travel(state) {
+        this._settled = state;
+        this._travelled = true;
+        this.applying = true;
+        try {
+            this._restore(state);
+        } finally {
+            this.applying = false;
+        }
+        this._changed();
+    }
+
+    _changed() {
+        this._onState?.();
+    }
+}

package/src/flow/kit/index.js

@@ -0,0 +1,38 @@
+/**
+ * The shared flow-editor kit (36 §3) — what every one of the three editors
+ * stands on, and what `@flexdesk/flow` exports for a consumer that builds its
+ * own. OWNED BY the kit agent (A); frozen once it lands.
+ */
+
+export { FLOW_STRINGS, createStrings, say } from './strings.js';
+export {
+    TONES, el, icon, button, toneClass, toneOf, uid, openPopover, closeFlowPopovers, openFlowPopover, nextOption,
+} from './dom.js';
+export {
+    SETTINGS_SCHEMA_ANNOTATIONS, SETTINGS_SCHEMA_KEYWORDS, SETTINGS_SCHEMA_TYPES, UI_HINTS,
+    checkSettingsSchema, fieldsFromSchema, fieldVisible, visibleFields, whenKeys, titleOf, enumLabel,
+    primaryType, admittedTypes, pyRepr,
+} from './settings_schema.js';
+export { createStepCatalogue, defaultIdBase } from './catalogue.js';
+export {
+    createReferenceSyntax, TEMPLATE_REFERENCES, FORMULA_REFERENCES, PARAMETER_REFERENCES,
+    findReferences, tokenize, describeReference, resolveSyntaxes, pathSegments,
+} from './references.js';
+export { createChipInput } from './chip_input.js';
+export {
+    createWidgetRegistry, GENERIC_WIDGETS, DEFAULT_WIDGET_REFERENCES, renderField, shownValue, typedValue,
+    fitToText,
+} from './widgets.js';
+export { createSettingsPanel } from './settings_panel.js';
+export { openStepPicker } from './step_picker.js';
+export { openValuePicker } from './value_picker.js';
+export { alwaysBefore, enclosingLoops, enclosingArms, flowStructure, DEFAULT_LOOP_PORTS } from './always_before.js';
+export {
+    groupFindings, findingsList, createFindingsStrip, matchFindingField, isPathPrefix,
+} from './findings.js';
+export { FlowHistory } from './history.js';
+export { bindFlowKeys, ownsUndo, isTextField, isOwnControl } from './keys.js';
+export {
+    ID_OK, LOGIC_GRAPH_STRINGS, emptyGraph, normalise, serialise, nextId, addNode, removeNode, moveNode,
+    canConnect, connect, disconnect, sameEdge, inputNamesOf,
+} from './logic_graph.js';

package/src/flow/kit/keys.js

@@ -0,0 +1,127 @@
+/**
+ * AN EDITOR'S KEYS, BOUND ON ITS ROOT AND NEVER ON `window` (36 §3.10).
+ *
+ *   Ctrl/⌘+Z · Ctrl/⌘+Y, Ctrl/⌘+Shift+Z   undo · redo
+ *   Delete                                 remove the selection
+ *   Ctrl/⌘+D · C · X · V                   duplicate · copy · cut · paste
+ *   F2                                     rename
+ *   Alt+↑ · Alt+↓ · Alt+←                  move up · down · out of its block
+ *   ↑ ↓ ← →                                move the selection
+ *   Enter                                  open the selection's settings
+ *   Escape                                 close a picker, cancel a gesture
+ *
+ * ══ UNDO STOPS AT THE ROOT, EVEN IN A TEXT FIELD ═══════════════════════
+ *
+ * Ctrl+Z inside a text field is the field's own undo — the browser's default
+ * action on its text, which stopping propagation leaves alone. It is STOPPED
+ * all the same: another tile on the page may listen for Ctrl+Z on `window`
+ * (a diagram does), and an editor split beside it would otherwise undo both.
+ * A `<select>`, a checkbox or a button has no undo of its own, so Ctrl+Z there
+ * is the editor's. `ownsUndo` is the one answer to "does this control undo its
+ * own text": a textarea, an editable `contenteditable`, Monaco, an `<input>` of
+ * a text-like type.
+ *
+ * Every other key inside ANY field — a select included — is the field's, and
+ * Enter on a button, a link or a summary is that control's own activation.
+ *
+ * ══ BACKSPACE IS NEVER AN EDITOR'S KEY ═════════════════════════════════
+ *
+ * It belongs to the host's navigation (a page trail may climb one level on it),
+ * so outside a text field an editor neither acts on Backspace nor stops it.
+ * Delete removes a step.
+ */
+
+/** The `<input>` types whose text the browser can undo. */
+const TEXT_INPUTS = new Set(['', 'text', 'search', 'url', 'tel', 'email', 'password', 'number']);
+const EDITABLE = '[contenteditable]:not([contenteditable="false"])';
+
+/** Does Ctrl+Z here belong to the control rather than to the editor? */
+export function ownsUndo(target) {
+    if (!target?.closest) return false;
+    if (target.closest(`textarea, ${EDITABLE}, .monaco-editor`)) return true;
+    const input = target.closest('input');
+    return Boolean(input) && TEXT_INPUTS.has(String(input.getAttribute('type') || '').toLowerCase());
+}
+
+/**
+ * Is `target` a control whose Enter is its own — a button, a link, a summary?
+ * An editor's own item (a row, a card, a node) marks itself
+ * `data-twm-flow-item`, and Enter there opens its settings.
+ */
+export function isOwnControl(target) {
+    const c = target?.closest?.('button, a[href], summary, [role="button"], [role="menuitem"], '
+                                + '[role="option"], [role="tab"], [role="radio"], [role="checkbox"]');
+    return Boolean(c) && !c.closest('[data-twm-flow-item]');
+}
+
+/** Is `target` inside a field, whose keys are its own? */
+export function isTextField(target) {
+    return Boolean(target?.closest?.(`input, textarea, select, ${EDITABLE}, .monaco-editor`));
+}
+
+/**
+ * Bind the editor keys on `root`. Each handler is optional; a key whose
+ * handler is absent is not handled (nothing is prevented). A handler that
+ * returns `false` declines the key and it goes on as if unbound.
+ *
+ * @param {HTMLElement} root
+ * @param {object} handlers  undo, redo, remove, duplicate, copy, cut, paste,
+ *        rename, moveUp, moveDown, moveOut, up, down, left, right, open, escape
+ * @returns {() => void} unbind
+ */
+export function bindFlowKeys(root, handlers = {}) {
+    const run = (name, ev) => {
+        const h = handlers[name];
+        if (typeof h !== 'function') return false;
+        if (h(ev) === false) return false;
+        ev.preventDefault();
+        return true;
+    };
+
+    const onKey = (ev) => {
+        if (ev.isComposing || ev.keyCode === 229) return;
+        const mod = (ev.ctrlKey || ev.metaKey) && !ev.altKey;
+        const k = String(ev.key || '');
+        const lower = k.toLowerCase();
+
+        if (mod && (lower === 'z' || lower === 'y')) {
+            // HERE AND NO FURTHER, wherever in the editor it was pressed.
+            ev.stopPropagation();
+            if (ownsUndo(ev.target)) return;
+            run(lower === 'y' || ev.shiftKey ? 'redo' : 'undo', ev);
+            return;
+        }
+        if (k === 'Backspace') return;
+        if (isTextField(ev.target)) return;
+        if (ev.defaultPrevented) return;
+
+        if (mod && !ev.shiftKey) {
+            if (lower === 'd') { run('duplicate', ev); return; }
+            if (lower === 'c') { run('copy', ev); return; }
+            if (lower === 'x') { run('cut', ev); return; }
+            if (lower === 'v') { run('paste', ev); return; }
+            return;
+        }
+        if (ev.altKey && !ev.ctrlKey && !ev.metaKey) {
+            if (k === 'ArrowUp') run('moveUp', ev);
+            else if (k === 'ArrowDown') run('moveDown', ev);
+            else if (k === 'ArrowLeft') run('moveOut', ev);
+            return;
+        }
+        if (ev.ctrlKey || ev.metaKey) return;
+        switch (k) {
+            case 'Delete': run('remove', ev); break;
+            case 'F2': run('rename', ev); break;
+            case 'ArrowUp': run('up', ev); break;
+            case 'ArrowDown': run('down', ev); break;
+            case 'ArrowLeft': run('left', ev); break;
+            case 'ArrowRight': run('right', ev); break;
+            case 'Enter': if (!ev.shiftKey && !isOwnControl(ev.target)) run('open', ev); break;
+            case 'Escape': run('escape', ev); break;
+            default: break;
+        }
+    };
+
+    root.addEventListener('keydown', onKey);
+    return () => root.removeEventListener('keydown', onKey);
+}

package/src/flow/kit/logic_graph.js

@@ -0,0 +1,210 @@
+/**
+ * A LOGIC FLOW'S GRAPH, as the canvas and the outline both edit it — PURE: no
+ * DOM, runs under plain node (36 §3.14). Moved from Tables' designer graph
+ * model, minus everything that was Tables'.
+ *
+ * The shape is the consumer server's:
+ *
+ *     { nodes: [{ id, type, label?, config, position: {x, y} }],
+ *       connections: [{ source, target, sourcePort, targetPort }] }
+ *
+ * **The editors decide nothing a publish depends on.** Whether a graph is a
+ * valid flow is the consumer's validator, drawn as findings. What `canConnect`
+ * refuses is only what an editor cannot DRAW honestly — a port that does not
+ * exist, a flow line into a data port, a second line out of a port that
+ * carries one, a step connected to itself — and every refusal is a sentence,
+ * returned, never thrown into a console.
+ *
+ * `serialise` is byte-stable: node keys in the order `id, type, label?, config,
+ * position`, config keys sorted, nodes and connections in the order they were
+ * drawn — so a graph opened and saved with no edit is the identical text.
+ */
+
+import { createStrings } from './strings.js';
+
+/** The node ids a server accepts: letters, digits, `-` and `_`, at most 64. */
+export const ID_OK = /^[A-Za-z0-9_-]{1,64}$/;
+
+export const LOGIC_GRAPH_STRINGS = Object.freeze({
+    connectSelf: 'A step cannot connect to itself.',
+    connectMissing: 'Both ends must be steps in this flow.',
+    connectNoOutput: (port) => `This step has no output called ${port}.`,
+    connectNoInput: (port) => `That step has no input called ${port}.`,
+    connectNotFlow: (how) => (how
+        ? `Only flow ports connect; a data port is read as ${how}.`
+        : 'Only flow ports connect; a data port is read, not connected.'),
+    connectTwice: 'These two are already connected.',
+    connectOneLine: (port) => `The ${port} port takes one connection; `
+        + 'use a step that runs several branches.',
+});
+
+export function emptyGraph() {
+    return { nodes: [], connections: [] };
+}
+
+/** A deep copy with every field the graph carries, and nothing else. */
+export function normalise(graph) {
+    const g = graph && typeof graph === 'object' ? graph : emptyGraph();
+    return {
+        nodes: (Array.isArray(g.nodes) ? g.nodes : []).map((n) => ({
+            id: String(n.id),
+            type: String(n.type),
+            ...(n.label ? { label: String(n.label) } : {}),
+            config: n.config && typeof n.config === 'object' ? structuredClone(n.config) : {},
+            position: { x: Math.round(Number(n.position?.x) || 0), y: Math.round(Number(n.position?.y) || 0) },
+        })),
+        connections: (Array.isArray(g.connections) ? g.connections : []).map((c) => ({
+            source: String(c.source),
+            target: String(c.target),
+            sourcePort: String(c.sourcePort || 'out'),
+            targetPort: String(c.targetPort || 'in'),
+        })),
+    };
+}
+
+function sortedKeys(value) {
+    if (Array.isArray(value)) return value.map(sortedKeys);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortedKeys(value[k])]));
+    }
+    return value;
+}
+
+/** The text a save sends and a reload must reproduce exactly. */
+export function serialise(graph) {
+    const g = normalise(graph);
+    return JSON.stringify({
+        nodes: g.nodes.map((n) => ({
+            id: n.id, type: n.type, ...(n.label ? { label: n.label } : {}),
+            config: sortedKeys(n.config), position: n.position,
+        })),
+        connections: g.connections.map((c) => ({
+            source: c.source, target: c.target, sourcePort: c.sourcePort, targetPort: c.targetPort,
+        })),
+    });
+}
+
+/**
+ * A new id for a step of `typeId`: `stem`, `stem-2`, … — readable inside a
+ * reference. The stem is the catalogue's `idBase` when a catalogue is given,
+ * else the type id, made safe for an id.
+ */
+export function nextId(graph, typeId, { catalogue = null } = {}) {
+    const base = catalogue?.idBase
+        ? catalogue.idBase(typeId)
+        : (String(typeId || 'step').replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 40) || 'step');
+    const taken = new Set((graph?.nodes || []).map((n) => n.id));
+    if (!taken.has(base)) return base;
+    for (let i = 2; ; i += 1) {
+        if (!taken.has(`${base}-${i}`)) return `${base}-${i}`;
+    }
+}
+
+/**
+ * Append a step of `typeId`. A wanted `id` is used when it is a valid id nobody
+ * holds; otherwise `nextId`. A step with no position is at (0, 0), the
+ * position `normalise` gives one.
+ */
+export function addNode(graph, typeId, position = null, { id = null, label = null, config = null,
+                                                          catalogue = null } = {}) {
+    const nid = id && ID_OK.test(id) && !graph.nodes.some((n) => n.id === id)
+        ? id : nextId(graph, typeId, { catalogue });
+    const node = {
+        id: nid, type: typeId, ...(label ? { label } : {}),
+        config: config && typeof config === 'object' ? structuredClone(config) : {},
+        position: { x: Math.round(position?.x || 0), y: Math.round(position?.y || 0) },
+    };
+    graph.nodes.push(node);
+    return node;
+}
+
+export function removeNode(graph, nodeId) {
+    graph.nodes = graph.nodes.filter((n) => n.id !== nodeId);
+    graph.connections = graph.connections.filter((c) => c.source !== nodeId && c.target !== nodeId);
+}
+
+export function moveNode(graph, nodeId, position) {
+    const node = graph.nodes.find((n) => n.id === nodeId);
+    if (node) node.position = { x: Math.round(position.x), y: Math.round(position.y) };
+}
+
+export const sameEdge = (a, b) => a.source === b.source && a.target === b.target
+    && a.sourcePort === b.sourcePort && a.targetPort === b.targetPort;
+
+function portOf(catalogue, node, name, direction) {
+    if (!node) return null;
+    if (catalogue?.port) return catalogue.port(node.type, name, direction);
+    const def = catalogue?.get?.(node.type);
+    return def?.ports?.find((p) => p.name === name && p.direction === direction) || null;
+}
+
+/**
+ * May `source.sourcePort` connect to `target.targetPort`? `{ok: true}` or
+ * `{ok: false, reason}` — the editor shows the reason where the gesture failed.
+ * `dataRead` is the consumer's words for how a data port is read instead
+ * (`syntax.format(...)`), put in the refusal.
+ */
+export function canConnect(graph, catalogue, { source, sourcePort, target, targetPort },
+                           { strings = null, dataRead = null } = {}) {
+    const S = createStrings(LOGIC_GRAPH_STRINGS, strings);
+    if (source === target) return { ok: false, reason: S.connectSelf };
+    const from = graph.nodes.find((n) => n.id === source);
+    const to = graph.nodes.find((n) => n.id === target);
+    if (!from || !to) return { ok: false, reason: S.connectMissing };
+    const out = portOf(catalogue, from, sourcePort, 'output');
+    const inp = portOf(catalogue, to, targetPort, 'input');
+    if (!out) return { ok: false, reason: S.connectNoOutput(sourcePort) };
+    if (!inp) return { ok: false, reason: S.connectNoInput(targetPort) };
+    if ((out.port_type || 'FLOW') !== 'FLOW' || (inp.port_type || 'FLOW') !== 'FLOW') {
+        return { ok: false, reason: S.connectNotFlow(dataRead) };
+    }
+    if (graph.connections.some((c) => c.source === source && c.sourcePort === sourcePort
+                                    && c.target === target && c.targetPort === targetPort)) {
+        return { ok: false, reason: S.connectTwice };
+    }
+    if (!out.multiple && graph.connections.some((c) => c.source === source && c.sourcePort === sourcePort)) {
+        return { ok: false, reason: S.connectOneLine(out.label || sourcePort) };
+    }
+    return { ok: true };
+}
+
+/** Connect when `canConnect` allows it; returns its verdict either way. */
+export function connect(graph, catalogue, edge, options = {}) {
+    const verdict = canConnect(graph, catalogue, edge, options);
+    if (verdict.ok) {
+        graph.connections.push({ source: edge.source, target: edge.target,
+                                 sourcePort: edge.sourcePort, targetPort: edge.targetPort });
+    }
+    return verdict;
+}
+
+export function disconnect(graph, edge) {
+    graph.connections = graph.connections.filter((c) => !sameEdge(c, edge));
+}
+
+/**
+ * The names a graph reads from one SCOPE of a reference syntax — every
+ * reference whose path starts `scope.` in any step's config, the segment after
+ * it, in first-seen order. (`inputNamesOf(graph, TEMPLATE_REFERENCES, 'run')`
+ * lists what a run must be given.)
+ */
+export function inputNamesOf(graph, syntax, scope) {
+    const names = new Set();
+    const prefix = `${scope}.`;
+    const walk = (value) => {
+        if (typeof value === 'string') {
+            for (const m of syntax.find(value)) {
+                if (!m.path.startsWith(prefix)) continue;
+                const rest = m.path.slice(prefix.length);
+                const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(rest)?.[0];
+                if (name) names.add(name);
+            }
+        } else if (Array.isArray(value)) {
+            value.forEach(walk);
+        } else if (value && typeof value === 'object') {
+            Object.values(value).forEach(walk);
+        }
+    };
+    for (const n of graph?.nodes || []) walk(n.config);
+    return [...names];
+}