@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,202 @@
+/**
+ * Sweeps of the tightening pass.
+ *
+ * Each sweep leaves every box at least as well placed as it found it, and the loop stops as soon as
+ * one changes nothing, so this caps effort rather than quality.
+ *
+ * @type {number}
+ */
+const TIGHTENING_SWEEPS = 8;
+
+/**
+ * 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, position) {
+    const box_count = graph.box_count;
+
+    const layer = graph.box_layer;
+
+    layer.fill(0, 0, box_count);
+
+    if (box_count === 0) {
+        return 0;
+    }
+
+    const order = new Int32Array(box_count);
+
+    for (let box = 0; box < box_count; box++) {
+        order[position[box]] = box;
+    }
+
+    let layer_count = 1;
+
+    for (let i = 0; i < box_count; i++) {
+        const box = order[i];
+
+        const at = layer[box];
+
+        const start = graph.out_offset[box];
+        const end = graph.out_offset[box + 1];
+
+        for (let k = start; k < end; k++) {
+            const to = graph.link_to[graph.out_link[k]];
+
+            if (layer[to] < at + 1) {
+                layer[to] = at + 1;
+
+                if (layer[to] + 1 > layer_count) {
+                    layer_count = layer[to] + 1;
+                }
+            }
+        }
+    }
+
+    for (let sweep = 0; sweep < TIGHTENING_SWEEPS; sweep++) {
+        if (!tighten(graph, order, layer_count)) {
+            break;
+        }
+    }
+
+    // tightening only ever moves a box within its window, so the column count cannot have grown,
+    // but it can have shrunk — the last column may have emptied
+    return normalise(graph, layer_count);
+}
+
+/**
+ * One pass of moving every box to whichever end of its window its links pull it towards.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} order boxes in topological order
+ * @param {number} layer_count
+ * @returns {boolean} whether anything moved
+ */
+function tighten(graph, order, layer_count) {
+    const layer = graph.box_layer;
+
+    let moved = false;
+
+    for (let i = 0; i < order.length; i++) {
+        const box = order[i];
+
+        const in_start = graph.in_offset[box];
+        const in_end = graph.in_offset[box + 1];
+
+        const out_start = graph.out_offset[box];
+        const out_end = graph.out_offset[box + 1];
+
+        const in_degree = in_end - in_start;
+        const out_degree = out_end - out_start;
+
+        if (in_degree === 0 && out_degree === 0) {
+            continue;
+        }
+
+        let window_start = 0;
+
+        for (let k = in_start; k < in_end; k++) {
+            const from = graph.link_from[graph.in_link[k]];
+
+            if (layer[from] + 1 > window_start) {
+                window_start = layer[from] + 1;
+            }
+        }
+
+        // With nothing depending on it a box has no reason to move right: doing so only lengthens
+        // what arrives. Its own column is therefore the end of its window.
+        let window_end = out_degree === 0 ? layer[box] : layer_count - 1;
+
+        for (let k = out_start; k < out_end; k++) {
+            const to = graph.link_to[graph.out_link[k]];
+
+            if (layer[to] - 1 < window_end) {
+                window_end = layer[to] - 1;
+            }
+        }
+
+        if (window_end < window_start) {
+            // the window closed; longest path already put it at the only place it fits
+            continue;
+        }
+
+        const wanted = in_degree > out_degree ? window_start : window_end;
+
+        if (wanted !== layer[box]) {
+            layer[box] = wanted;
+
+            moved = true;
+        }
+    }
+
+    return moved;
+}
+
+/**
+ * Close up columns that tightening emptied, and report how many are left.
+ *
+ * An empty column is a strip of blank picture the reader has to cross for nothing. It happens
+ * whenever every box that longest path put in a column had somewhere better to be.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {number} layer_count
+ * @returns {number}
+ */
+function normalise(graph, layer_count) {
+    const occupied = new Uint8Array(layer_count);
+
+    const layer = graph.box_layer;
+
+    for (let box = 0; box < graph.box_count; box++) {
+        occupied[layer[box]] = 1;
+    }
+
+    const remap = new Int32Array(layer_count);
+
+    let next = 0;
+
+    for (let i = 0; i < layer_count; i++) {
+        remap[i] = next;
+
+        if (occupied[i] === 1) {
+            next++;
+        }
+    }
+
+    if (next === layer_count) {
+        return layer_count;
+    }
+
+    for (let box = 0; box < graph.box_count; box++) {
+        layer[box] = remap[layer[box]];
+    }
+
+    return next;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Put the boxes in an order that as few links as possible point backwards along.
+ *
+ * Everything after this stage assumes the graph flows one way. A cycle makes that impossible, so
+ * the cycle has to be cut somewhere; the question is only where, and the answer wanted is the one
+ * that turns the fewest links around, because a link drawn against the flow is the one a reader
+ * has to work to follow.
+ *
+ * This is the greedy heuristic of Eades, Lin and Smyth. Repeatedly:
+ *
+ * - a box nothing depends on goes to the **end** of the order — it can never be the source of a
+ *   backwards link there;
+ * - a box that depends on nothing goes to the **start**, for the same reason in reverse;
+ * - failing both, the box with the largest excess of outgoing over incoming links goes to the
+ *   start, because it is the one placing early saves the most.
+ *
+ * It never reverses more than `|E|/2 - |V|/6` links, and on a graph that is already acyclic it
+ * reverses none — the first two rules alone consume the whole graph, and what comes out is a
+ * topological order.
+ *
+ * Deterministic: boxes are picked from their bucket in index order, so the same graph gives the
+ * same answer every time it is laid out.
+ *
+ * @see Eades, Lin, Smyth — *A fast and effective heuristic for the feedback arc set problem* (1993)
+ *
+ * @param {LayoutBoxGraph} graph adjacency must be current
+ * @returns {Int32Array} position of each box in the order. A link is backwards when the position of
+ *          its source is not less than the position of its target.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_break_cycles(graph: LayoutBoxGraph): Int32Array;
+//# sourceMappingURL=layout_break_cycles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout_break_cycles.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_break_cycles.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,4DANa,UAAU,CAmOtB"}

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

@@ -0,0 +1,254 @@
+/**
+ * Put the boxes in an order that as few links as possible point backwards along.
+ *
+ * Everything after this stage assumes the graph flows one way. A cycle makes that impossible, so
+ * the cycle has to be cut somewhere; the question is only where, and the answer wanted is the one
+ * that turns the fewest links around, because a link drawn against the flow is the one a reader
+ * has to work to follow.
+ *
+ * This is the greedy heuristic of Eades, Lin and Smyth. Repeatedly:
+ *
+ * - a box nothing depends on goes to the **end** of the order — it can never be the source of a
+ *   backwards link there;
+ * - a box that depends on nothing goes to the **start**, for the same reason in reverse;
+ * - failing both, the box with the largest excess of outgoing over incoming links goes to the
+ *   start, because it is the one placing early saves the most.
+ *
+ * It never reverses more than `|E|/2 - |V|/6` links, and on a graph that is already acyclic it
+ * reverses none — the first two rules alone consume the whole graph, and what comes out is a
+ * topological order.
+ *
+ * Deterministic: boxes are picked from their bucket in index order, so the same graph gives the
+ * same answer every time it is laid out.
+ *
+ * @see Eades, Lin, Smyth — *A fast and effective heuristic for the feedback arc set problem* (1993)
+ *
+ * @param {LayoutBoxGraph} graph adjacency must be current
+ * @returns {Int32Array} position of each box in the order. A link is backwards when the position of
+ *          its source is not less than the position of its target.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_break_cycles(graph) {
+    const box_count = graph.box_count;
+
+    const position = new Int32Array(box_count);
+
+    if (box_count === 0) {
+        return position;
+    }
+
+    const out_degree = new Int32Array(box_count);
+    const in_degree = new Int32Array(box_count);
+
+    for (let box = 0; box < box_count; box++) {
+        out_degree[box] = graph.out_degree(box);
+        in_degree[box] = graph.in_degree(box);
+    }
+
+    /*
+     * Buckets, as intrusive doubly linked lists over the box indices so that a box can be pulled
+     * out of the middle of one in constant time when a neighbour is removed and its degree changes.
+     *
+     *   0                      boxes nothing depends on
+     *   1                      boxes depending on nothing
+     *   2 + delta + box_count  everything else, by out minus in
+     */
+    const SINK_BUCKET = 0;
+    const SOURCE_BUCKET = 1;
+    const DELTA_BASE = 2 + box_count;
+
+    const bucket_count = 2 + box_count * 2 + 1;
+
+    const bucket_head = new Int32Array(bucket_count).fill(-1);
+
+    const next = new Int32Array(box_count).fill(-1);
+    const previous = new Int32Array(box_count).fill(-1);
+    const bucket_of = new Int32Array(box_count).fill(-1);
+
+    /**
+     * @param {number} box
+     * @returns {number}
+     */
+    function bucket_for(box) {
+        if (out_degree[box] === 0) {
+            return SINK_BUCKET;
+        }
+
+        if (in_degree[box] === 0) {
+            return SOURCE_BUCKET;
+        }
+
+        return DELTA_BASE + out_degree[box] - in_degree[box];
+    }
+
+    /**
+     * @param {number} box
+     * @param {number} bucket
+     * @returns {void}
+     */
+    function attach(box, bucket) {
+        const head = bucket_head[bucket];
+
+        next[box] = head;
+        previous[box] = -1;
+
+        if (head !== -1) {
+            previous[head] = box;
+        }
+
+        bucket_head[bucket] = box;
+        bucket_of[box] = bucket;
+    }
+
+    /**
+     * @param {number} box
+     * @returns {void}
+     */
+    function detach(box) {
+        const bucket = bucket_of[box];
+
+        if (bucket === -1) {
+            return;
+        }
+
+        const p = previous[box];
+        const n = next[box];
+
+        if (p === -1) {
+            bucket_head[bucket] = n;
+        } else {
+            next[p] = n;
+        }
+
+        if (n !== -1) {
+            previous[n] = p;
+        }
+
+        bucket_of[box] = -1;
+        next[box] = -1;
+        previous[box] = -1;
+    }
+
+    // Highest delta bucket holding anything. Only ever needs to fall: removing a box can raise a
+    // neighbour's delta by at most one, and that case is handled where it happens.
+    let delta_ceiling = bucket_count - 1;
+
+    for (let box = box_count - 1; box >= 0; box--) {
+        // descending, so each bucket ends up holding its boxes in ascending index order
+        attach(box, bucket_for(box));
+    }
+
+    const removed = new Uint8Array(box_count);
+
+    let head_cursor = 0;
+    let tail_cursor = box_count - 1;
+    let remaining = box_count;
+
+    /**
+     * Take a box out of the graph, dropping the degrees of everything it touched and moving those
+     * neighbours to the buckets their new degrees put them in.
+     *
+     * @param {number} box
+     * @returns {void}
+     */
+    function remove(box) {
+        detach(box);
+
+        removed[box] = 1;
+        remaining--;
+
+        const out_start = graph.out_offset[box];
+        const out_end = graph.out_offset[box + 1];
+
+        for (let k = out_start; k < out_end; k++) {
+            const other = graph.link_to[graph.out_link[k]];
+
+            if (removed[other] === 1) {
+                continue;
+            }
+
+            in_degree[other]--;
+
+            const bucket = bucket_for(other);
+
+            detach(other);
+            attach(other, bucket);
+
+            // losing an incoming link raises delta, which is the one way the ceiling can rise
+            if (bucket > delta_ceiling) {
+                delta_ceiling = bucket;
+            }
+        }
+
+        const in_start = graph.in_offset[box];
+        const in_end = graph.in_offset[box + 1];
+
+        for (let k = in_start; k < in_end; k++) {
+            const other = graph.link_from[graph.in_link[k]];
+
+            if (removed[other] === 1) {
+                continue;
+            }
+
+            out_degree[other]--;
+
+            const bucket = bucket_for(other);
+
+            detach(other);
+            attach(other, bucket);
+        }
+    }
+
+    while (remaining > 0) {
+        let progressed = false;
+
+        while (bucket_head[SINK_BUCKET] !== -1) {
+            const box = bucket_head[SINK_BUCKET];
+
+            position[box] = tail_cursor--;
+
+            remove(box);
+
+            progressed = true;
+        }
+
+        while (bucket_head[SOURCE_BUCKET] !== -1) {
+            const box = bucket_head[SOURCE_BUCKET];
+
+            position[box] = head_cursor++;
+
+            remove(box);
+
+            progressed = true;
+        }
+
+        if (remaining === 0) {
+            break;
+        }
+
+        if (progressed) {
+            // sinks may have appeared while sources were being taken, and the other way round
+            continue;
+        }
+
+        // Everything left is in a cycle. Take whichever box gains the most from going early.
+        while (delta_ceiling >= DELTA_BASE - box_count && bucket_head[delta_ceiling] === -1) {
+            delta_ceiling--;
+        }
+
+        const box = bucket_head[delta_ceiling];
+
+        if (box === -1) {
+            // cannot happen while remaining > 0, but a layout must not hang on a malformed graph
+            break;
+        }
+
+        position[box] = head_cursor++;
+
+        remove(box);
+    }
+
+    return position;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Read a node graph and the visual data describing it into the flat form every layout stage works
+ * on.
+ *
+ * **Nodes are taken in ascending order of id, and connections likewise.** The visual data holds
+ * them in a map, and a map is in insertion order — which is the order the editor happened to create
+ * them in, not a property of the graph. Two graphs that are the same would then lay out
+ * differently, and the same graph reloaded from a file would lay out differently from the one on
+ * screen. Sorting by id is what makes the layout a function of the graph.
+ *
+ * A node the visual data knows nothing about is skipped, and so is any connection touching it: this
+ * runs against whatever the caller has, and half-populated visual data is a reason to lay out what
+ * is there rather than to fail.
+ *
+ * A connection from a node to itself becomes a connection with no link. It is drawn — the router
+ * takes it as a loop out of one side of the box and back into the other — but it says nothing about
+ * which column anything belongs in, and a link from a box to itself is something none of the
+ * placement stages has an answer for.
+ *
+ * @param {NodeGraph} graph
+ * @param {NodeGraphVisualData} visual
+ * @returns {LayoutProblem}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_build_problem(graph: NodeGraph, visual: NodeGraphVisualData): LayoutProblem;
+import { LayoutProblem } from "./LayoutProblem.js";
+//# sourceMappingURL=layout_build_problem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout_build_problem.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_build_problem.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qFALa,aAAa,CA+GzB;8BAtI6C,oBAAoB"}