@woosh/meep-engine 3.15.0 → 3.16.0

package/src/core/model/node-graph/visual/layout/layout_assign_coordinates.js

@@ -0,0 +1,555 @@
+import { LAYOUT_BOX_LANE } from "./LayoutBoxGraph.js";
+
+/**
+ * Give every box a position.
+ *
+ * **Columns** are the easy half. A column is as wide as its widest box, columns are spaced by
+ * `layer_gap`, and a box narrower than its column sits in the middle of it.
+ *
+ * **Rows** are the half that decides whether the drawing is readable, and this is the algorithm of
+ * Brandes and Köpf. Four passes run over the graph — aligning towards the top and towards the
+ * bottom, working forwards and working backwards — each producing a complete arrangement, and every
+ * box ends up at the average of the middle two of its four candidates. One pass alone has a bias it
+ * cannot see out of: aligning downwards and towards the top straightens the chains it meets first
+ * and bends everything else around them. Four passes have four different biases, and the median of
+ * them has none.
+ *
+ * Within a pass, a box is aligned with the **median** of what it connects to. Not the average: what
+ * is being minimised is the total vertical distance the wires cover, the median is the point that
+ * minimises it, and an average is dragged about by one distant neighbour until every other wire is
+ * slightly crooked to accommodate it. Boxes that align with each other form a **block** which is
+ * then placed as one rigid piece, which is what makes a chain of them come out as a straight line
+ * rather than a staircase.
+ *
+ * **Wires, not middles.** The published algorithm aligns vertices, which for a box means its middle.
+ * That is the wrong thing to line up here. A wire is drawn between two *ports*, and a node twelve
+ * ports tall is met near its top by one wire and near its bottom by another — line up the two boxes'
+ * middles and nothing the reader can see is lined up at all. So a block here is not a set of boxes
+ * sharing one coordinate but a set of boxes with a fixed offset between them, chosen so that the
+ * wire joining each consecutive pair comes out horizontal. Everything else about the algorithm is
+ * unchanged; the offsets simply travel along with the block and appear as a constant in the
+ * separation constraints.
+ *
+ * @see Brandes, Köpf — *Fast and Simple Horizontal Coordinate Assignment* (2002)
+ *
+ * @param {LayoutBoxGraph} graph mutated: `box_x` and `box_y` are written. Adjacency must be current.
+ * @param {number} layer_count
+ * @param {Int32Array} order boxes grouped by column, in order
+ * @param {Int32Array} rank position of each box within its column
+ * @param {Int32Array} layer_start where each column begins in `order`
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {{width: number, height: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_assign_coordinates(graph, layer_count, order, rank, layer_start, options) {
+    const box_count = graph.box_count;
+
+    if (box_count === 0) {
+        return { width: 0, height: 0 };
+    }
+
+    const width = place_columns(graph, layer_count, order, layer_start, options);
+
+    const neighbours = build_sorted_neighbours(graph, rank);
+
+    const marked = mark_conflicts(graph, layer_count, order, rank, layer_start, neighbours);
+
+    const candidates = [];
+
+    for (let pass = 0; pass < 4; pass++) {
+        const down = (pass & 1) === 0;
+        const top = (pass & 2) === 0;
+
+        const block = align(graph, layer_count, order, rank, layer_start, neighbours, marked, down, top);
+
+        candidates.push(compact(graph, order, rank, layer_start, block, options));
+    }
+
+    const height = balance(graph, candidates);
+
+    return { width, height };
+}
+
+/**
+ * Space the columns and put every box in the middle of its own.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {number} layer_count
+ * @param {Int32Array} order
+ * @param {Int32Array} layer_start
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {number} total width
+ */
+function place_columns(graph, layer_count, order, layer_start, options) {
+    let x = 0;
+
+    for (let i = 0; i < layer_count; i++) {
+        const start = layer_start[i];
+        const end = layer_start[i + 1];
+
+        let column_width = 0;
+
+        for (let k = start; k < end; k++) {
+            const w = graph.box_w[order[k]];
+
+            if (w > column_width) {
+                column_width = w;
+            }
+        }
+
+        for (let k = start; k < end; k++) {
+            const box = order[k];
+
+            graph.box_x[box] = x + (column_width - graph.box_w[box]) / 2;
+        }
+
+        x += column_width;
+
+        if (i + 1 < layer_count) {
+            x += options.layer_gap;
+        }
+    }
+
+    return x;
+}
+
+/**
+ * Every box's links, each side sorted by where the box at the other end sits in its column.
+ *
+ * The alignment pass takes the median of these and the marking pass walks them in order, so both
+ * need them sorted; sorting once here is the difference between doing it and doing it four times.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} rank
+ * @returns {{in_link: Int32Array, out_link: Int32Array}}
+ */
+function build_sorted_neighbours(graph, rank) {
+    const in_link = graph.in_link.slice(0, graph.link_count);
+    const out_link = graph.out_link.slice(0, graph.link_count);
+
+    const by_source = (a, b) => rank[graph.link_from[a]] - rank[graph.link_from[b]];
+    const by_target = (a, b) => rank[graph.link_to[a]] - rank[graph.link_to[b]];
+
+    for (let box = 0; box < graph.box_count; box++) {
+        const in_start = graph.in_offset[box];
+        const in_end = graph.in_offset[box + 1];
+
+        if (in_end - in_start > 1) {
+            in_link.subarray(in_start, in_end).sort(by_source);
+        }
+
+        const out_start = graph.out_offset[box];
+        const out_end = graph.out_offset[box + 1];
+
+        if (out_end - out_start > 1) {
+            out_link.subarray(out_start, out_end).sort(by_target);
+        }
+    }
+
+    return { in_link, out_link };
+}
+
+/**
+ * The link by which a lane box continues a wire it did not start.
+ *
+ * A wire crossing several columns is a chain of lane boxes, and the pieces of it between two lanes
+ * are the ones worth keeping straight — they are the middle of a long wire, and a long wire that
+ * bends twice in the middle is the one a reader loses. Those pieces are what the marking pass
+ * protects.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {number} box
+ * @returns {number} link index, or -1
+ */
+function inner_link_of(graph, box) {
+    if (graph.box_kind[box] !== LAYOUT_BOX_LANE) {
+        return -1;
+    }
+
+    const start = graph.in_offset[box];
+
+    if (graph.in_offset[box + 1] === start) {
+        return -1;
+    }
+
+    const link = graph.in_link[start];
+
+    return graph.box_kind[graph.link_from[link]] === LAYOUT_BOX_LANE ? link : -1;
+}
+
+/**
+ * Find the links that cross the middle of a long wire, and forbid aligning along them.
+ *
+ * A wire that runs straight through several columns and a wire that crosses it cannot both be
+ * straight. This decides in favour of the long one: the links crossing it are marked, and the
+ * alignment pass refuses to build a block along a marked link. Long wires therefore come out
+ * straight and the short ones bend around them, which is the right way round — a short wire is
+ * easy to follow at any angle and a long one is not.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {number} layer_count
+ * @param {Int32Array} order
+ * @param {Int32Array} rank
+ * @param {Int32Array} layer_start
+ * @param {{in_link: Int32Array}} neighbours
+ * @returns {Uint8Array} per link
+ */
+function mark_conflicts(graph, layer_count, order, rank, layer_start, neighbours) {
+    const marked = new Uint8Array(graph.link_count);
+
+    for (let i = 0; i + 1 < layer_count; i++) {
+        const upper_count = layer_start[i + 1] - layer_start[i];
+
+        const lower_start = layer_start[i + 1];
+        const lower_count = layer_start[i + 2] - lower_start;
+
+        let k0 = 0;
+        let l = 0;
+
+        for (let l1 = 0; l1 < lower_count; l1++) {
+            const v = order[lower_start + l1];
+
+            const inner = inner_link_of(graph, v);
+
+            if (l1 !== lower_count - 1 && inner === -1) {
+                continue;
+            }
+
+            const k1 = inner === -1 ? upper_count - 1 : rank[graph.link_from[inner]];
+
+            for (; l <= l1; l++) {
+                const w = order[lower_start + l];
+
+                const start = graph.in_offset[w];
+                const end = graph.in_offset[w + 1];
+
+                for (let k = start; k < end; k++) {
+                    const link = neighbours.in_link[k];
+
+                    const at = rank[graph.link_from[link]];
+
+                    if (at < k0 || at > k1) {
+                        marked[link] = 1;
+                    }
+                }
+            }
+
+            k0 = k1;
+        }
+    }
+
+    return marked;
+}
+
+/**
+ * Build the blocks of one pass: which boxes move together, and by how much they are offset from the
+ * one leading them.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {number} layer_count
+ * @param {Int32Array} order
+ * @param {Int32Array} rank
+ * @param {Int32Array} layer_start
+ * @param {{in_link: Int32Array, out_link: Int32Array}} neighbours
+ * @param {Uint8Array} marked
+ * @param {boolean} down align each box with what feeds it, rather than with what it feeds
+ * @param {boolean} top prefer the neighbour nearer the top of its column when two are equally median
+ * @returns {{root: Int32Array, align: Int32Array, offset: Float64Array}}
+ */
+function align(graph, layer_count, order, rank, layer_start, neighbours, marked, down, top) {
+    const box_count = graph.box_count;
+
+    const root = new Int32Array(box_count);
+    const next = new Int32Array(box_count);
+    const offset = new Float64Array(box_count);
+
+    for (let box = 0; box < box_count; box++) {
+        root[box] = box;
+        next[box] = box;
+    }
+
+    for (let step = 0; step < layer_count; step++) {
+        const i = down ? step : layer_count - 1 - step;
+
+        const start = layer_start[i];
+        const end = layer_start[i + 1];
+
+        // How far along the adjacent column the last box in this one reached. A box may only align
+        // with something past that, which is what stops two blocks from crossing.
+        let reached = top ? -1 : Number.MAX_SAFE_INTEGER;
+
+        const count = end - start;
+
+        for (let step_k = 0; step_k < count; step_k++) {
+            const v = order[top ? start + step_k : end - 1 - step_k];
+
+            const link_start = down ? graph.in_offset[v] : graph.out_offset[v];
+            const link_end = down ? graph.in_offset[v + 1] : graph.out_offset[v + 1];
+
+            const degree = link_end - link_start;
+
+            if (degree === 0) {
+                continue;
+            }
+
+            const list = down ? neighbours.in_link : neighbours.out_link;
+
+            // With an even number of neighbours neither middle one is the median, so the pass tries
+            // both, and which it tries first is the bias this pass exists to have. With an odd
+            // number the two are the same neighbour and there is only one thing to try.
+            const first = top ? (degree - 1) >> 1 : degree >> 1;
+            const second = top ? degree >> 1 : (degree - 1) >> 1;
+
+            for (let m = 0; m < 2; m++) {
+                const index = m === 0 ? first : second;
+
+                if (m === 1 && second === first) {
+                    break;
+                }
+
+                const link = list[link_start + index];
+
+                if (marked[link] === 1) {
+                    continue;
+                }
+
+                const u = down ? graph.link_from[link] : graph.link_to[link];
+
+                const at = rank[u];
+
+                if (top ? at <= reached : at >= reached) {
+                    continue;
+                }
+
+                // straight means the two ports meet: y[v] + anchor(v) === y[u] + anchor(u)
+                const delta = down
+                    ? graph.link_from_y[link] - graph.link_to_y[link]
+                    : graph.link_to_y[link] - graph.link_from_y[link];
+
+                next[u] = v;
+                root[v] = root[u];
+                next[v] = root[v];
+                offset[v] = offset[u] + delta;
+
+                reached = at;
+
+                break;
+            }
+        }
+    }
+
+    return { root, align: next, offset };
+}
+
+/**
+ * Push the blocks of one pass as far towards the top as the boxes below them allow, and read off a
+ * coordinate for every box.
+ *
+ * Blocks are placed by longest path through the constraints between neighbours in a column, which
+ * is what makes the arrangement as tight as the ordering permits. Blocks that turn out not to
+ * constrain each other at all form separate classes, and a class is then shifted up until it meets
+ * whatever is above it — without that, a block hanging off the bottom of the drawing pins every
+ * class that follows it down there too.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} order
+ * @param {Int32Array} rank
+ * @param {Int32Array} layer_start
+ * @param {{root: Int32Array, align: Int32Array, offset: Float64Array}} block
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {Float64Array} top edge of every box
+ */
+function compact(graph, order, rank, layer_start, block, options) {
+    const box_count = graph.box_count;
+
+    const root = block.root;
+    const next = block.align;
+    const offset = block.offset;
+
+    const sink = new Int32Array(box_count);
+    const shift = new Float64Array(box_count).fill(Infinity);
+    const place = new Float64Array(box_count).fill(NaN);
+
+    for (let box = 0; box < box_count; box++) {
+        sink[box] = box;
+    }
+
+    /**
+     * @param {number} above
+     * @param {number} below
+     * @returns {number} smallest distance from the top of `above` to the top of `below`
+     */
+    function separation(above, below) {
+        const gap = graph.box_kind[above] === LAYOUT_BOX_LANE || graph.box_kind[below] === LAYOUT_BOX_LANE
+            ? options.wire_gap
+            : options.node_gap;
+
+        return graph.box_h[above] + gap;
+    }
+
+    /**
+     * @param {number} v a block root
+     * @returns {void}
+     */
+    function place_block(v) {
+        if (!Number.isNaN(place[v])) {
+            return;
+        }
+
+        place[v] = 0;
+
+        let w = v;
+
+        do {
+            const at = rank[w];
+
+            if (at > 0) {
+                const above = order[layer_start[graph.box_layer[w]] + at - 1];
+                const u = root[above];
+
+                place_block(u);
+
+                // top(w) >= top(above) + separation, with both expressed through their block roots
+                const need = offset[above] - offset[w] + separation(above, w);
+
+                if (sink[v] === v) {
+                    sink[v] = sink[u];
+                }
+
+                if (sink[v] === sink[u]) {
+                    if (place[u] + need > place[v]) {
+                        place[v] = place[u] + need;
+                    }
+                } else {
+                    const slack = place[v] - place[u] - need;
+
+                    if (slack < shift[sink[u]]) {
+                        shift[sink[u]] = slack;
+                    }
+                }
+            }
+
+            w = next[w];
+        } while (w !== v);
+    }
+
+    for (let box = 0; box < box_count; box++) {
+        if (root[box] === box) {
+            place_block(box);
+        }
+    }
+
+    const y = new Float64Array(box_count);
+
+    for (let box = 0; box < box_count; box++) {
+        const r = root[box];
+
+        y[box] = place[r] + offset[box];
+
+        const carried = shift[sink[r]];
+
+        if (carried < Infinity) {
+            y[box] += carried;
+        }
+    }
+
+    return y;
+}
+
+/**
+ * Combine the four passes into one arrangement.
+ *
+ * The passes are first slid over each other — the ones biased towards the top lined up by their
+ * top edge, the ones biased towards the bottom by their bottom edge — against whichever of them
+ * came out shortest. Only then can they be compared box by box, and each box takes the average of
+ * the middle two of its four candidates: an average of all four is pulled about by whichever single
+ * pass went furthest astray, and the middle two are the ones the passes agree on.
+ *
+ * @param {LayoutBoxGraph} graph mutated: `box_y` is written
+ * @param {Float64Array[]} candidates
+ * @returns {number} total height
+ */
+function balance(graph, candidates) {
+    const box_count = graph.box_count;
+
+    let reference = 0;
+    let narrowest = Infinity;
+
+    const low = new Float64Array(candidates.length);
+    const high = new Float64Array(candidates.length);
+
+    for (let c = 0; c < candidates.length; c++) {
+        const y = candidates[c];
+
+        let min = Infinity;
+        let max = -Infinity;
+
+        for (let box = 0; box < box_count; box++) {
+            if (y[box] < min) {
+                min = y[box];
+            }
+
+            const bottom = y[box] + graph.box_h[box];
+
+            if (bottom > max) {
+                max = bottom;
+            }
+        }
+
+        low[c] = min;
+        high[c] = max;
+
+        if (max - min < narrowest) {
+            narrowest = max - min;
+            reference = c;
+        }
+    }
+
+    for (let c = 0; c < candidates.length; c++) {
+        // passes 0 and 1 align towards the top, 2 and 3 towards the bottom — see the pass loop
+        const shift = c < 2 ? low[reference] - low[c] : high[reference] - high[c];
+
+        if (shift === 0) {
+            continue;
+        }
+
+        const y = candidates[c];
+
+        for (let box = 0; box < box_count; box++) {
+            y[box] += shift;
+        }
+    }
+
+    const sample = new Float64Array(candidates.length);
+
+    let min = Infinity;
+    let max = -Infinity;
+
+    for (let box = 0; box < box_count; box++) {
+        for (let c = 0; c < candidates.length; c++) {
+            sample[c] = candidates[c][box];
+        }
+
+        sample.sort();
+
+        const middle = (sample[1] + sample[2]) / 2;
+
+        graph.box_y[box] = middle;
+
+        if (middle < min) {
+            min = middle;
+        }
+
+        if (middle + graph.box_h[box] > max) {
+            max = middle + graph.box_h[box];
+        }
+    }
+
+    for (let box = 0; box < box_count; box++) {
+        graph.box_y[box] -= min;
+    }
+
+    return max - min;
+}

package/src/core/model/node-graph/visual/layout/layout_assign_layers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Put every box in a column, as near to what it connects to as its dependencies allow.
+ *
+ * **Longest path.** A box goes one column past its latest dependency. That is what makes the
+ * drawing readable as a flow — everything a node waits on is strictly to its left — and it is the
+ * only part of this that is forced.
+ *
+ * **Then tightening, which is the part that decides how it looks.** Longest path answers "how early
+ * *can* this go", and that answer is regularly wrong: a constant used once, ten columns later, still
+ * lands in the first column, and the drawing becomes a first column full of things nothing has
+ * needed yet, joined to the rest by wires running the whole width of the picture.
+ *
+ * Every box has a window between its latest dependency and its earliest dependent, and inside that
+ * window the cost is linear — one column later lengthens every arriving wire by one and shortens
+ * every leaving wire by one. So a box with more arriving than leaving belongs at the start of its
+ * window, one with more leaving than arriving belongs at the end, and repeating that until nothing
+ * moves is a descent on total wire length.
+ *
+ * Ties go late. A value with one producer and one consumer costs the same either way, and the two
+ * readings are "here is what that node made" against "here is what this node needs" — the second is
+ * what somebody following a wire is looking for, and it keeps a chain of such boxes collapsed
+ * against its consumer instead of strung out from its producer.
+ *
+ * @param {LayoutBoxGraph} graph mutated: `box_layer` is written. Must be acyclic — see
+ *        {@link layout_orient_links}. Adjacency must be current.
+ * @param {Int32Array} position from {@link layout_break_cycles}, a topological order of the graph
+ *        once its links are oriented
+ * @returns {number} number of columns
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_assign_layers(graph: LayoutBoxGraph, position: Int32Array): number;
+//# sourceMappingURL=layout_assign_layers.d.ts.map

package/src/core/model/node-graph/visual/layout/layout_assign_layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout_assign_layers.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_assign_layers.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,sEAPW,UAAU,GAER,MAAM,CAsDlB"}