flexdesk 0.5.0 → 0.6.1

package/src/flow/canvas_editor/index.js

@@ -0,0 +1,16 @@
+/**
+ * What `@flexdesk/flow` exports for the CANVAS editor (36 §5).
+ *
+ * OWNED BY the canvas agent (B, 36 §2 and §5): `createCanvasEditor`, its
+ * closed action list, its words, the node box its edges are anchored by, and
+ * the pure geometry under it. The geometry is exported under canvas-prefixed
+ * names, because `flow.js` re-exports three editors with `export *`, and two
+ * modules exporting one name make that name silently vanish from the barrel.
+ */
+
+export { createCanvasEditor, CANVAS_ACTIONS } from './editor.js';
+export { CANVAS_STRINGS } from './strings.js';
+export {
+    CANVAS_NODE, layoutGraph as arrangeCanvasGraph, portAnchor as canvasPortAnchor, nodeBottom as canvasNodeBottom,
+    isReturnEdge as isCanvasReturnEdge,
+} from './layout.js';

package/src/flow/canvas_editor/layout.js

@@ -0,0 +1,118 @@
+/**
+ * The canvas editor's geometry — PURE: no DOM, runs under plain node.
+ *
+ *   CANVAS_NODE      a node's box: its width, its header's height and the
+ *                    height of one row of ports. The edges are anchored by
+ *                    ARITHMETIC over these, never by measuring, so the
+ *                    stylesheet must agree with them — `flow_canvas_css` reads
+ *                    the sheet and holds it to them.
+ *   portAnchor       where a port's line starts or ends
+ *   nodeBottom       where a node's drawn box ends
+ *   isReturnEdge     is this line a loop's body going back round?
+ *   layoutGraph      ARRANGE: every step's place, left to right in run order
+ */
+
+import { arrange } from '../../canvas/edge_router.js';
+
+export const CANVAS_NODE = Object.freeze({ width: 208, header: 34, row: 22 });
+
+/** The space under a node's last row of ports (its findings, its run line). */
+const FOOT = 12;
+
+const inputsOf = (catalogue, node) => (catalogue?.inputs ? catalogue.inputs(node?.type) : []);
+const outputsOf = (catalogue, node) => (catalogue?.outputs ? catalogue.outputs(node?.type) : []);
+const roleOf = (catalogue, node) => (catalogue?.role ? catalogue.role(node?.type) : 'step');
+
+/**
+ * The point a line meets `node`'s port `portName`: an input on the node's
+ * left edge, an output on its right, one row of ports down from the header
+ * per port before it — in the order the type DECLARES its ports, the order
+ * they are drawn in. A port the type does not have anchors at the first row.
+ */
+export function portAnchor(catalogue, node, portName, direction, box = CANVAS_NODE) {
+    const list = direction === 'input' ? inputsOf(catalogue, node) : outputsOf(catalogue, node);
+    const i = Math.max(0, list.findIndex((p) => p.name === portName));
+    return {
+        x: node.position.x + (direction === 'input' ? 0 : box.width),
+        y: node.position.y + box.header + box.row * i + box.row / 2,
+        side: direction === 'input' ? 'left' : 'right',
+    };
+}
+
+/** Where `node`'s drawn box ends — computed, because jsdom and a node not yet
+ *  laid out both answer 0 for `offsetHeight`. */
+export function nodeBottom(catalogue, node, box = CANVAS_NODE) {
+    const rows = Math.max(inputsOf(catalogue, node).length, outputsOf(catalogue, node).length, 1);
+    return node.position.y + box.header + box.row * rows + FOOT;
+}
+
+/**
+ * Is `connection` a loop's body handing back to its loop — a line into a
+ * `loop`-role step on any input but the one the loop is ENTERED by
+ * (`loopEntry`)? The editor's reading of the shape, for drawing it; whether
+ * the graph is a valid loop is the consumer's validator's.
+ */
+export function isReturnEdge(connection, target, catalogue, loopEntry = 'in') {
+    return Boolean(target) && roleOf(catalogue, target) === 'loop' && connection.targetPort !== loopEntry;
+}
+
+/**
+ * ARRANGE: where every step goes, left to right in the order a run takes them.
+ * Returns a Map of node id → `{x, y}` from (0, 0); the editor anchors it at
+ * the graph's current corner, so arranging never throws the graph off screen.
+ *
+ * It is the kernel's `arrange` (a layered layout), given what that function
+ * needs and does not check for:
+ *
+ *  - **lines REVERSED.** `arrange` puts an edge's `from` one column right of
+ *    its `to` (a reference points at what it references); a flow's line points
+ *    at what runs NEXT, so `source → target` is handed over as
+ *    `{from: target, to: source}`.
+ *  - **a label on every node.** `arrange` sorts each column with
+ *    `a.label.localeCompare`, which throws on a missing one. The label handed
+ *    over is an ORDER KEY — a step's place in a breadth-first walk from the
+ *    start step(s) that follows each step's outputs in the order its type
+ *    declares them — so a condition's first arm sits above its second
+ *    whatever the two steps are called.
+ *  - **a loop's return lines left out.** The line from a loop's body back into
+ *    the loop is the loop, not a dependency; followed, it would pull the body
+ *    left of the loop that runs it. Any other cycle is broken by `arrange`.
+ */
+export function layoutGraph(graph, catalogue, { width = CANVAS_NODE.width, header = CANVAS_NODE.header,
+                                                row = CANVAS_NODE.row, gap = 96, rowGap = 40,
+                                                loopEntry = 'in' } = {}) {
+    const nodes = graph?.nodes || [];
+    const connections = graph?.connections || [];
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const portOrder = (n, port) => {
+        const outs = outputsOf(catalogue, n);
+        const i = outs.findIndex((p) => p.name === port);
+        return i < 0 ? outs.length : i;
+    };
+    const isReturn = (c) => isReturnEdge(c, byId.get(c.target), catalogue, loopEntry);
+
+    // The order key: breadth first from the start step(s), outputs in port order.
+    const order = new Map();
+    const queue = nodes.filter((n) => roleOf(catalogue, n) === 'start').map((n) => n.id);
+    for (const id of queue) order.set(id, order.size);
+    while (queue.length) {
+        const id = queue.shift();
+        const out = connections
+            .map((c, i) => ({ c, i }))
+            .filter(({ c }) => c.source === id && byId.has(c.target) && !isReturn(c))
+            .sort((a, b) => (portOrder(byId.get(id), a.c.sourcePort) - portOrder(byId.get(id), b.c.sourcePort))
+                || (a.i - b.i));
+        for (const { c } of out) {
+            if (!order.has(c.target)) { order.set(c.target, order.size); queue.push(c.target); }
+        }
+    }
+    for (const n of nodes) if (!order.has(n.id)) order.set(n.id, order.size);
+
+    const rows = (n) => Math.max(inputsOf(catalogue, n).length, outputsOf(catalogue, n).length);
+    return arrange(
+        nodes.map((n) => ({ id: n.id, label: String(order.get(n.id)).padStart(6, '0'),
+                            height: header + row * rows(n) + 24 })),
+        connections.filter((c) => !isReturn(c)).map((c) => ({ from: c.target, to: c.source })),
+        { columnGap: width + gap, rowGap },
+    );
+}

package/src/flow/canvas_editor/strings.js

@@ -0,0 +1,37 @@
+/**
+ * The canvas editor's own words (36 §3.13), laid over the kit's `FLOW_STRINGS`
+ * and under the consumer's: `createStrings(CANVAS_STRINGS, options.strings)`.
+ *
+ * English, and they name no domain. What a consumer calls a loop's next pass
+ * ("the next row") or how a data port is read (`${…}`) is the consumer's, given
+ * through `strings` and the `dataPortRead` option.
+ */
+
+export const CANVAS_STRINGS = Object.freeze({
+    palette: 'Steps',
+    canvasLabel: 'Flow canvas',
+    toolbarLabel: 'Flow',
+    arrange: 'Arrange',
+    arrangeTitle: 'Lay the steps out left to right, in the order a run takes them',
+    fit: 'Fit',
+    fitTitle: 'Show the whole flow',
+    nothingToUndo: 'There is nothing to undo.',
+    nothingToRedo: 'There is nothing to redo.',
+    arrangeNeedsTwo: 'Arrange needs two steps or more.',
+    readOnlyRefusal: 'This flow is read only.',
+    connectFrom: 'Click, then click the input to connect to',
+    connectTo: 'Connect an output here',
+    connectStarted: 'Now click the input to connect to. Esc cancels.',
+    connectFirst: 'Click an output first, then this input.',
+    dataPort: (how) => (how ? `Read it in a later step as ${how}` : 'A data port: it is read, not connected.'),
+    dropHere: 'Drop a step on the canvas to add it.',
+    returnLine: 'Back to the loop for its next pass',
+    connectedReturn: 'Goes round the loop again.',
+    unknownType: (type) => `There is no step type "${type}".`,
+    stepId: (id) => `Step id: ${id}`,
+    connection: 'Connection',
+    connectionLine: (e) => `${e.source} · ${e.sourcePort} → ${e.target} · ${e.targetPort}`,
+    removeConnection: 'Remove connection',
+    portCount: (n) => `×${n}`,
+    portNotTaken: 'not taken',
+});

package/src/flow/kit/always_before.js

@@ -0,0 +1,325 @@
+/**
+ * WHICH STEPS ALWAYS RUN BEFORE THIS ONE — the one place the rule lives
+ * (36 §3.7). PURE: no DOM, runs under plain node.
+ *
+ * *Insert a value* lists only the steps that ALWAYS run before the step being
+ * edited, so a reference to a step that may not have run — the other arm of a
+ * condition, a step that ends the run on an error — cannot be picked. The
+ * answer is computed over FLOW edges with every loop's RETURN edges set aside
+ * (an edge into a loop step's input other than its entry port is the line back
+ * from the body, not a way in):
+ *
+ *  - a step's DOMINATORS from the start step — the steps on EVERY path to it;
+ *  - EXCEPT that a fanout whose join waits for ALL its branches makes every
+ *    step that always runs on each branch run before the join (and before
+ *    everything after it): dominators read a parallel's branches as
+ *    alternatives, and they are not. A join that goes on when the FIRST branch
+ *    finishes contributes only the fanout, which dominates it anyway;
+ *  - a step inside a loop's body has the loop before it, and the body steps
+ *    before it on every path; a BODY STEP IS NEVER BEFORE A STEP AFTER THE
+ *    LOOP, because the loop may visit no row;
+ *  - a step in an arm has the arm's earlier steps, the block's head and
+ *    whatever runs before the block — never a sibling arm's steps (which is
+ *    what dominators give).
+ *
+ * The answer is nearest first: by the length of the shortest flow path from
+ * each step to this one, then in the graph's node order.
+ *
+ * Roles are the catalogue's: `start`, `fanout`, `join`, `loop`. Which input a
+ * loop is entered by, and which output its body leaves from, are the
+ * consumer's port names (`loopPorts`); whether a join waits for every branch is
+ * the consumer's setting (`waitsForAll`).
+ */
+
+export const DEFAULT_LOOP_PORTS = Object.freeze({ entry: 'in', next: 'next', body: 'body', done: 'done' });
+
+const defaultWaitsForAll = (node) => (node?.config?.join ?? 'all') !== 'any';
+
+function isFlowPort(catalogue, typeId, name, direction) {
+    const port = catalogue?.port ? catalogue.port(typeId, name, direction) : null;
+    return port ? (port.port_type || 'FLOW') === 'FLOW' : true;
+}
+
+/** The graph's flow structure: successors and predecessors, return edges left out. */
+export function flowStructure(graph, catalogue, { loopPorts = DEFAULT_LOOP_PORTS, kindOf = null } = {}) {
+    const ports = { ...DEFAULT_LOOP_PORTS, ...loopPorts };
+    const nodes = Array.isArray(graph?.nodes) ? graph.nodes : [];
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    // `kindOf` (optional) reads a type's role through a consumer's mapping —
+    // an outline whose catalogue spells its roles differently (36 §6.2).
+    const role = typeof kindOf === 'function'
+        ? (id) => kindOf(byId.get(id)?.type)
+        : (id) => (catalogue?.role ? catalogue.role(byId.get(id)?.type) : 'step');
+    const succ = new Map(nodes.map((n) => [n.id, []]));
+    const pred = new Map(nodes.map((n) => [n.id, []]));
+    const returns = [];
+    for (const c of Array.isArray(graph?.connections) ? graph.connections : []) {
+        const from = byId.get(c.source);
+        const to = byId.get(c.target);
+        if (!from || !to) continue;
+        if (!isFlowPort(catalogue, from.type, c.sourcePort, 'output')
+            || !isFlowPort(catalogue, to.type, c.targetPort, 'input')) continue;
+        if (role(c.target) === 'loop' && c.targetPort !== ports.entry) { returns.push(c); continue; }
+        succ.get(c.source).push({ id: c.target, port: c.sourcePort });
+        pred.get(c.target).push({ id: c.source, port: c.sourcePort });
+    }
+    return { nodes, byId, role, succ, pred, returns, ports };
+}
+
+/** Every node reachable from `roots`, not entering `stop`. */
+function reach(roots, succ, stop = null) {
+    const seen = new Set();
+    const queue = [...roots].filter((r) => r !== stop);
+    for (const r of queue) seen.add(r);
+    while (queue.length) {
+        const id = queue.shift();
+        for (const s of succ.get(id) || []) {
+            if (s.id === stop || seen.has(s.id)) continue;
+            seen.add(s.id);
+            queue.push(s.id);
+        }
+    }
+    return seen;
+}
+
+/**
+ * Dominator sets over the nodes reachable from `roots` (several roots behave
+ * as one virtual root above them). Map: node → Set of its dominators, itself
+ * included. The iterative set-intersection form — a flow is a few dozen steps.
+ */
+function dominators(roots, succ, pred) {
+    const live = reach(roots, succ);
+    const rootSet = new Set(roots);
+    const order = [...live];
+    const dom = new Map();
+    for (const id of order) dom.set(id, rootSet.has(id) ? new Set([id]) : new Set(order));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const id of order) {
+            if (rootSet.has(id)) continue;
+            let acc = null;
+            for (const p of pred.get(id) || []) {
+                if (!live.has(p.id)) continue;
+                const d = dom.get(p.id);
+                acc = acc === null ? new Set(d) : new Set([...acc].filter((x) => d.has(x)));
+            }
+            const next = new Set(acc ?? []);
+            next.add(id);
+            const cur = dom.get(id);
+            if (next.size !== cur.size || [...next].some((x) => !cur.has(x))) {
+                dom.set(id, next);
+                changed = true;
+            }
+        }
+    }
+    return dom;
+}
+
+/** A loop's body: what its body port leads to, not passing back through the loop. */
+function bodyOf(structure, loopId) {
+    const starts = (structure.succ.get(loopId) || [])
+        .filter((s) => s.port === structure.ports.body).map((s) => s.id);
+    return reach(starts, structure.succ, loopId);
+}
+
+/** Every loop and its body, for the loops in the graph. */
+function loopBodies(structure) {
+    const out = new Map();
+    for (const n of structure.nodes) {
+        if (structure.role(n.id) === 'loop') out.set(n.id, bodyOf(structure, n.id));
+    }
+    return out;
+}
+
+/** The roots a flow is walked from: its start steps, else the steps nothing leads to. */
+function rootsOf(st) {
+    const roots = st.nodes.filter((n) => st.role(n.id) === 'start').map((n) => n.id);
+    return roots.length ? roots : st.nodes.filter((n) => !(st.pred.get(n.id) || []).length).map((n) => n.id);
+}
+
+/**
+ * The ids of the steps that always run before `stepId`, nearest first.
+ *
+ * @param {object} graph       `{nodes, connections}` (the logic-graph shape)
+ * @param {object} catalogue   `createStepCatalogue`'s
+ * @param {string} stepId
+ * @param {object} [options]
+ * @param {object} [options.loopPorts]          `{entry, next, body, done}`
+ * @param {(node: object) => boolean} [options.waitsForAll]  does this join wait for every branch?
+ */
+export function alwaysBefore(graph, catalogue, stepId, { loopPorts = DEFAULT_LOOP_PORTS,
+                                                         waitsForAll = defaultWaitsForAll } = {}) {
+    const st = flowStructure(graph, catalogue, { loopPorts });
+    if (!st.byId.has(stepId)) return [];
+    const dom = dominators(rootsOf(st), st.succ, st.pred);
+    if (!dom.has(stepId)) return [];
+
+    /** The nearest dominator of `id` (by `domMap`) whose role is `fanout`. */
+    const nearestFanout = (id, domMap) => {
+        const mine = domMap.get(id);
+        if (!mine) return null;
+        let best = null;
+        for (const d of mine) {
+            if (d === id || st.role(d) !== 'fanout') continue;
+            if (best === null || domMap.get(d).size > domMap.get(best).size) best = d;
+        }
+        return best;
+    };
+
+    // What always runs on the branches of the fanout a join closes, memoised.
+    const branchMemo = new Map();
+    const branchSteps = (joinId, domMap) => {
+        if (branchMemo.has(joinId)) return branchMemo.get(joinId);
+        branchMemo.set(joinId, new Set());                       // a cycle guard
+        const out = new Set();
+        const fan = nearestFanout(joinId, domMap);
+        if (fan !== null && waitsForAll(st.byId.get(joinId))) {
+            for (const s of st.succ.get(fan) || []) {
+                if (s.id === joinId) continue;                   // an empty branch
+                const sub = dominators([s.id], st.succ, st.pred);
+                const onEvery = sub.get(joinId);
+                if (!onEvery) continue;                          // this branch never reaches the join
+                for (const x of onEvery) {
+                    if (x === joinId) continue;
+                    out.add(x);
+                    if (st.role(x) === 'join') for (const y of branchSteps(x, sub)) out.add(y);
+                }
+            }
+        }
+        branchMemo.set(joinId, out);
+        return out;
+    };
+
+    const before = new Set([...dom.get(stepId)].filter((x) => x !== stepId));
+    for (const j of [...before, stepId]) {
+        if (st.role(j) === 'join') for (const x of branchSteps(j, dom)) if (x !== stepId) before.add(x);
+    }
+
+    // A body step is never before a step after (or outside) its loop.
+    for (const [, body] of loopBodies(st)) {
+        if (body.has(stepId)) continue;
+        for (const b of body) before.delete(b);
+    }
+
+    // Nearest first: the shortest flow path from each step to this one.
+    const dist = new Map([[stepId, 0]]);
+    const queue = [stepId];
+    while (queue.length) {
+        const id = queue.shift();
+        for (const p of st.pred.get(id) || []) {
+            if (dist.has(p.id)) continue;
+            dist.set(p.id, dist.get(id) + 1);
+            queue.push(p.id);
+        }
+    }
+    const index = new Map(st.nodes.map((n, i) => [n.id, i]));
+    return [...before].sort((a, b) => ((dist.get(a) ?? Infinity) - (dist.get(b) ?? Infinity))
+        || (index.get(a) - index.get(b)));
+}
+
+/** The loops `stepId` is inside, innermost first. */
+export function enclosingLoops(graph, catalogue, stepId, { loopPorts = DEFAULT_LOOP_PORTS } = {}) {
+    const st = flowStructure(graph, catalogue, { loopPorts });
+    const around = [];
+    for (const [loopId, body] of loopBodies(st)) {
+        if (body.has(stepId)) around.push({ loopId, size: body.size });
+    }
+    return around.sort((a, b) => a.size - b.size).map((x) => x.loopId);
+}
+
+/**
+ * THE ARMS `stepId` IS INSIDE, innermost first: `[{head, port}]` (36 §3.7).
+ *
+ * *Insert a value* must know when the step being edited sits in an arm taken
+ * on its head's FAILURE: there the head ran and failed, and on failure a
+ * step's data output is empty — so the consumer offers that head by its error
+ * output alone. The kit only REPORTS the port; which port means failure is
+ * the consumer's mapping (an outline's `arms.error`).
+ *
+ * An arm is a line out of a step that is not the step's continuation: every
+ * output of a branch, every line out of a fanout, a loop's outputs but `done`
+ * (its `body` included), and an ordinary step's FLOW outputs but its continue
+ * port. `stepId` is inside the arm `(head, port)` when EVERY flow path from
+ * the start to it leaves `head` by that line (each loop's return lines set
+ * aside, as `alwaysBefore` sets them aside) and it is not past the Merge that
+ * closes the block — the run reaches it only after the head left by `port`.
+ * So a step after the place the arms meet is inside none of them, and where a
+ * branch's other arms all END, the rest of the flow is inside its live arm:
+ * what the outline draws (36 §6.3).
+ *
+ * Over a block-shaped graph this IS the outline's nesting (the recogniser
+ * suite holds the two equal over its corpus); over any other graph it is
+ * still true of every run, which is why the canvas editor passes it too.
+ *
+ * @param {object} graph       `{nodes, connections}` (the logic-graph shape)
+ * @param {object} catalogue   `createStepCatalogue`'s
+ * @param {string} stepId
+ * @param {object} [options]
+ * @param {object} [options.loopPorts]          `{entry, next, body, done}`
+ * @param {string|((node: object) => string|null)} [options.continuePort]  an ordinary step's
+ *        continuation (default: its `out` FLOW output, else its first)
+ * @param {(typeId: string) => string} [options.kindOf]  a type's role — `start`, `branch`, `fanout`,
+ *        `join`, `loop`, or anything else for an ordinary step; default the catalogue's `role`
+ */
+export function enclosingArms(graph, catalogue, stepId, { loopPorts = DEFAULT_LOOP_PORTS, continuePort = null,
+                                                         kindOf = null } = {}) {
+    const st = flowStructure(graph, catalogue, { loopPorts, kindOf });
+    if (!st.byId.has(stepId)) return [];
+    const flowOutputs = (typeId) => (catalogue?.outputs ? catalogue.outputs(typeId, { flow: true }) : [])
+        .map((p) => p.name);
+    const cont = (node) => {
+        if (typeof continuePort === 'function') return continuePort(node);
+        if (typeof continuePort === 'string') return continuePort;
+        const outs = flowOutputs(node?.type);
+        return outs.includes('out') ? 'out' : (outs[0] ?? 'out');
+    };
+    const isArm = (headId, port) => {
+        const r = st.role(headId);
+        if (r === 'branch' || r === 'fanout') return true;
+        if (r === 'loop') return port !== st.ports.done;
+        return port !== cont(st.byId.get(headId));
+    };
+
+    // Each flow line becomes a node of its own, so that a LINE can dominate a step.
+    const LINE = '\u0000line:';
+    const succ = new Map();
+    const pred = new Map();
+    const lines = new Map();
+    for (const n of st.nodes) { succ.set(n.id, []); pred.set(n.id, []); }
+    for (const n of st.nodes) {
+        for (const s of st.succ.get(n.id) || []) {
+            const key = `${LINE}${lines.size}`;
+            lines.set(key, { head: n.id, port: s.port });
+            succ.set(key, [{ id: s.id }]);
+            pred.set(key, [{ id: n.id }]);
+            succ.get(n.id).push({ id: key });
+            pred.get(s.id).push({ id: key });
+        }
+    }
+    const dom = dominators(rootsOf(st), succ, pred);
+    const mine = dom.get(stepId);
+    if (!mine) return [];
+
+    const out = [];
+    for (const key of mine) {
+        const line = lines.get(key);
+        if (!line || !isArm(line.head, line.port)) continue;
+        // Walk from the line down to the step: a Merge met with no Parallel
+        // opened below the line closes the block, and the step is past it.
+        const chain = [...mine].filter((x) => !lines.has(x) && dom.get(x).has(key))
+            .sort((a, b) => dom.get(a).size - dom.get(b).size);
+        let depth = 0;
+        let past = false;
+        for (const x of chain) {
+            const r = st.role(x);
+            if (r === 'join') {
+                if (depth === 0) { past = true; break; }
+                depth -= 1;
+            } else if (r === 'fanout' && x !== stepId) depth += 1;
+        }
+        if (past || out.some((a) => a.head === line.head && a.port === line.port)) continue;
+        out.push({ head: line.head, port: line.port, depth: dom.get(key).size });
+    }
+    return out.sort((a, b) => b.depth - a.depth).map(({ head, port }) => ({ head, port }));
+}

package/src/flow/kit/catalogue.js

@@ -0,0 +1,170 @@
+/**
+ * THE STEP CATALOGUE — the list of step types a consumer passes in (36 §3.1).
+ *
+ * Its field names are the consumer's WIRE names, so a server's node-type list
+ * is handed to an editor as it arrives:
+ *
+ *     { type_id, label, category, role, description, icon,
+ *       ports: [{ name, direction: 'input'|'output', port_type: 'FLOW'|'DATA',
+ *                 label, required, multiple }],
+ *       config_schema, unavailable }
+ *
+ * Any other key a type carries is kept and ignored.
+ *
+ * ══ DECLARED PORT ORDER IS MEANING ═════════════════════════════════════
+ *
+ * A lane reads an operation's first FLOW input as its own lane and the rest as
+ * joined lanes; an outline draws a step's other FLOW outputs, after its
+ * continuation, as arms in declared order. So `inputs()` and `outputs()` keep
+ * the order the type DECLARES and never sort: an earlier pipeline engine
+ * sorted a join's inputs by port name, and `in_bottom` came before `in_top`.
+ *
+ * ══ TONES, NOT COLOURS ═════════════════════════════════════════════════
+ *
+ * A category names a tone (`dom.js`'s TONES); the stylesheet maps tones to
+ * tokens. A category's `layout: 'grid'` draws its entries two to a row in the
+ * step picker (the mocks' Data, Integration and Utility groups).
+ *
+ * ══ A BROKEN TYPE IS LISTED, NEVER THROWN ══════════════════════════════
+ *
+ * A duplicate id (the first is kept), a type without an id, a port without a
+ * name (the port is dropped), a schema outside the subset (the type is kept,
+ * its form drawn from what can be drawn): each is a line in `problems`, so a
+ * consumer's catalogue with one bad entry still opens an editor.
+ */
+
+import { checkSettingsSchema } from './settings_schema.js';
+import { TONES } from './dom.js';
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** The default id stem for a new step: the type id, made safe for an id. */
+export function defaultIdBase(type) {
+    return String(type?.type_id ?? type ?? 'step');
+}
+
+function cleanStem(stem) {
+    return String(stem ?? '').replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 40) || 'step';
+}
+
+function normalisePort(p) {
+    return {
+        ...p,
+        name: String(p.name),
+        direction: p.direction === 'output' ? 'output' : 'input',
+        port_type: p.port_type ? String(p.port_type) : 'FLOW',
+        label: p.label ?? String(p.name),
+        required: Boolean(p.required),
+        multiple: Boolean(p.multiple),
+    };
+}
+
+/**
+ * @param {object[]} types     the consumer's step types
+ * @param {object} [options]
+ * @param {{id: string, label: string, tone?: string, layout?: 'list'|'grid'}[]} [options.categories]
+ * @param {(type: object) => string} [options.idBase]  a new step's id stem
+ */
+export function createStepCatalogue(types, { categories = [], idBase = defaultIdBase } = {}) {
+    const problems = [];
+    const byId = new Map();
+    const order = [];
+
+    for (const raw of Array.isArray(types) ? types : []) {
+        if (!isPlainObject(raw)) {
+            problems.push({ type_id: null, message: 'A step type must be an object.' });
+            continue;
+        }
+        const id = raw.type_id;
+        if (typeof id !== 'string' || !id) {
+            problems.push({ type_id: null, message: `A step type has no type_id (label: ${raw.label ?? '—'}).` });
+            continue;
+        }
+        if (byId.has(id)) {
+            problems.push({ type_id: id, message: `A second step type is called "${id}"; the first is kept.` });
+            continue;
+        }
+        const ports = [];
+        for (const p of Array.isArray(raw.ports) ? raw.ports : []) {
+            if (!isPlainObject(p) || typeof p.name !== 'string' || !p.name) {
+                problems.push({ type_id: id, message: `"${id}" declares a port without a name; it is left out.` });
+                continue;
+            }
+            ports.push(normalisePort(p));
+        }
+        const schema = isPlainObject(raw.config_schema) ? raw.config_schema : {};
+        const refused = raw.config_schema === undefined ? null : checkSettingsSchema(raw.config_schema);
+        if (refused) problems.push({ type_id: id, message: `"${id}"'s settings schema: ${refused}` });
+        const type = Object.freeze({
+            ...raw,
+            label: raw.label ?? id,
+            category: raw.category ?? null,
+            role: raw.role || 'step',
+            description: raw.description ?? '',
+            icon: raw.icon ?? '',
+            ports: Object.freeze(ports.map((p) => Object.freeze(p))),
+            config_schema: schema,
+            unavailable: raw.unavailable ?? null,
+        });
+        byId.set(id, type);
+        order.push(type);
+    }
+
+    const cats = (Array.isArray(categories) ? categories : []).filter(isPlainObject).map((c) => Object.freeze({
+        id: String(c.id),
+        label: c.label ?? String(c.id),
+        tone: TONES.includes(c.tone) ? c.tone : 'grey',
+        layout: c.layout === 'grid' ? 'grid' : 'list',
+    }));
+    const catIndex = new Map(cats.map((c, i) => [c.id, i]));
+    // A type whose category nobody listed is not lost: it goes under a group of
+    // its own category id, after the listed ones, in the order first seen.
+    const extra = [];
+    for (const t of order) {
+        if (t.category !== null && !catIndex.has(t.category) && !extra.some((c) => c.id === t.category)) {
+            extra.push(Object.freeze({ id: String(t.category), label: String(t.category), tone: 'grey', layout: 'list' }));
+        }
+    }
+    if (order.some((t) => t.category === null)) {
+        extra.push(Object.freeze({ id: '', label: '', tone: 'grey', layout: 'list' }));
+    }
+    const allCats = Object.freeze([...cats, ...extra]);
+    const rank = (t) => {
+        const id = t.category === null ? '' : t.category;
+        return allCats.findIndex((c) => c.id === id);
+    };
+    const sorted = [...order].sort((a, b) => (rank(a) - rank(b))
+        || String(a.label).localeCompare(String(b.label)));
+
+    const portsOf = (typeId, direction, flow) => {
+        const t = byId.get(typeId);
+        if (!t) return [];
+        return t.ports.filter((p) => p.direction === direction && (!flow || p.port_type === 'FLOW'));
+    };
+
+    return Object.freeze({
+        problems: Object.freeze(problems.map((p) => Object.freeze(p))),
+        categories: allCats,
+        get: (typeId) => byId.get(typeId) ?? null,
+        has: (typeId) => byId.has(typeId),
+        list: () => [...sorted],
+        byCategory: () => allCats
+            .map((category) => ({ category, types: sorted.filter((t) => (t.category ?? '') === category.id) }))
+            .filter((g) => g.types.length > 0),
+        role: (typeId) => byId.get(typeId)?.role || 'step',
+        category: (typeId) => {
+            const t = byId.get(typeId);
+            return t ? allCats.find((c) => c.id === (t.category ?? '')) ?? null : null;
+        },
+        tone: (typeId) => {
+            const t = byId.get(typeId);
+            return (t && allCats.find((c) => c.id === (t.category ?? ''))?.tone) || 'grey';
+        },
+        inputs: (typeId, { flow = false } = {}) => portsOf(typeId, 'input', flow),
+        outputs: (typeId, { flow = false } = {}) => portsOf(typeId, 'output', flow),
+        port: (typeId, name, direction) => byId.get(typeId)?.ports
+            .find((p) => p.name === name && (!direction || p.direction === direction)) ?? null,
+        /** A new step's id stem for `typeId`, safe to put in an id. */
+        idBase: (typeId) => cleanStem(idBase(byId.get(typeId) ?? { type_id: typeId })),
+    });
+}