@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,300 @@
+import { BitSet } from "../../../../binary/BitSet.js";
+import { Uint32Heap } from "../../../../collection/heap/Uint32Heap.js";
+
+/**
+ * Travelling along a line of constant y.
+ * @type {number}
+ */
+export const ROUTE_AXIS_H = 0;
+
+/**
+ * Travelling along a line of constant x.
+ * @type {number}
+ */
+export const ROUTE_AXIS_V = 1;
+
+/**
+ * One wire's path through the grid, found by A*.
+ *
+ * **A state is a vertex together with the direction the wire arrived in**, not a vertex alone.
+ * Turning costs something here — it has to, or the shortest route is a staircase and the drawing
+ * is unreadable — and a cost that depends on how you arrived is a cost the search cannot see
+ * unless arriving is part of what it searches over. Two states per vertex is the whole price of
+ * that: the wire cares which axis it is on, not which of the two ways along it.
+ *
+ * **The scratch outlives the search.** A route is found several hundred times over one layout — once
+ * per wire, once per round of rip-up — and the arrays it needs are the size of the grid. Clearing
+ * them each time costs more than the search does, so the scores carry a stamp instead and a score
+ * left over from a previous route reads as absent rather than as a very good one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RouteSearch {
+
+    /**
+     * @type {RouteGrid}
+     */
+    grid = null;
+
+    /**
+     * @type {Uint32Heap}
+     */
+    open = new Uint32Heap(1024);
+
+    /**
+     * @type {BitSet}
+     */
+    closed = new BitSet();
+
+    /**
+     * Cost to reach each state, meaningful only where `stamp` matches the current search.
+     * @type {Float64Array}
+     */
+    score;
+
+    /**
+     * @type {Int32Array}
+     */
+    stamp;
+
+    /**
+     * @type {Int32Array}
+     */
+    came_from;
+
+    /**
+     * @type {number}
+     */
+    generation = 0;
+
+    /**
+     * Vertices of the route just found, from start to goal.
+     * @type {Int32Array}
+     */
+    path;
+
+    /**
+     * @type {number}
+     */
+    path_length = 0;
+
+    /**
+     * @param {RouteGrid} grid
+     */
+    constructor(grid) {
+        this.grid = grid;
+
+        const state_count = grid.vertex_count * 2;
+
+        this.score = new Float64Array(state_count);
+        this.stamp = new Int32Array(state_count);
+        this.came_from = new Int32Array(state_count);
+
+        this.closed.preventShrink();
+        this.closed.setCapacity(state_count);
+
+        // Enough for a route that goes straight there. One that has to go around something grows
+        // this when it is unwound, which happens rarely and once.
+        this.path = new Int32Array(grid.nx + grid.ny);
+    }
+
+    /**
+     * Find a wire's way from one vertex to another.
+     *
+     * The cost being minimised is length, plus a fixed price per turn, plus what the grid charges
+     * for lines other wires are already on. The estimate driving the search is the straight
+     * rectilinear distance remaining, which never exceeds what the route will actually cost — turns
+     * and congestion only ever add — so the first route found is the cheapest one.
+     *
+     * @param {number} start vertex
+     * @param {number} start_axis the axis the wire is already travelling on as it arrives here,
+     *        one of {@link ROUTE_AXIS_H}, {@link ROUTE_AXIS_V}
+     * @param {number} goal vertex
+     * @param {number} goal_axis the axis the wire must be on to meet the port it is heading for
+     * @param {NodeGraphLayoutOptions} options
+     * @returns {boolean} whether a route was found. The route is left in {@link path}.
+     */
+    find(start, start_axis, goal, goal_axis, options) {
+        const grid = this.grid;
+
+        const nx = grid.nx;
+        const ny = grid.ny;
+
+        const xs = grid.xs;
+        const ys = grid.ys;
+
+        this.path_length = 0;
+
+        if (start === goal) {
+            this.path[0] = start;
+            this.path_length = 1;
+
+            return true;
+        }
+
+        const generation = ++this.generation;
+
+        this.closed.reset();
+        this.open.clear();
+
+        const goal_x = xs[goal % nx];
+        const goal_y = ys[(goal / nx) | 0];
+
+        const bend = options.bend_penalty;
+
+        const start_state = start * 2 + start_axis;
+
+        this.score[start_state] = 0;
+        this.stamp[start_state] = generation;
+        this.came_from[start_state] = -1;
+
+        this.open.insert(start_state, Math.abs(xs[start % nx] - goal_x) + Math.abs(ys[(start / nx) | 0] - goal_y));
+
+        let expansions = 0;
+
+        while (!this.open.is_empty()) {
+            const state = this.open.pop_min();
+
+            if (this.closed.get(state)) {
+                // a cheaper way here was found after this entry was queued
+                continue;
+            }
+
+            const vertex = state >> 1;
+
+            if (vertex === goal) {
+                return this.__unwind(state);
+            }
+
+            this.closed.set(state, true);
+
+            if (++expansions > options.max_route_expansions) {
+                break;
+            }
+
+            const axis = state & 1;
+
+            const i = vertex % nx;
+            const j = (vertex / nx) | 0;
+
+            const cost = this.score[state];
+
+            if (i + 1 < nx && !grid.blocked_h.get(vertex)) {
+                this.__relax(
+                    state, cost, axis, vertex + 1, ROUTE_AXIS_H, goal, goal_axis, bend, options,
+                    xs[i + 1] - xs[i] + grid.use_h[vertex] * options.present_cost + grid.history_h[vertex],
+                    Math.abs(xs[i + 1] - goal_x) + Math.abs(ys[j] - goal_y),
+                    generation
+                );
+            }
+
+            if (i > 0 && !grid.blocked_h.get(vertex - 1)) {
+                this.__relax(
+                    state, cost, axis, vertex - 1, ROUTE_AXIS_H, goal, goal_axis, bend, options,
+                    xs[i] - xs[i - 1] + grid.use_h[vertex - 1] * options.present_cost + grid.history_h[vertex - 1],
+                    Math.abs(xs[i - 1] - goal_x) + Math.abs(ys[j] - goal_y),
+                    generation
+                );
+            }
+
+            if (j + 1 < ny && !grid.blocked_v.get(vertex)) {
+                this.__relax(
+                    state, cost, axis, vertex + nx, ROUTE_AXIS_V, goal, goal_axis, bend, options,
+                    ys[j + 1] - ys[j] + grid.use_v[vertex] * options.present_cost + grid.history_v[vertex],
+                    Math.abs(xs[i] - goal_x) + Math.abs(ys[j + 1] - goal_y),
+                    generation
+                );
+            }
+
+            if (j > 0 && !grid.blocked_v.get(vertex - nx)) {
+                this.__relax(
+                    state, cost, axis, vertex - nx, ROUTE_AXIS_V, goal, goal_axis, bend, options,
+                    ys[j] - ys[j - 1] + grid.use_v[vertex - nx] * options.present_cost + grid.history_v[vertex - nx],
+                    Math.abs(xs[i] - goal_x) + Math.abs(ys[j - 1] - goal_y),
+                    generation
+                );
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * @param {number} from state
+     * @param {number} from_cost
+     * @param {number} from_axis
+     * @param {number} vertex being moved to
+     * @param {number} axis being moved along
+     * @param {number} goal
+     * @param {number} goal_axis
+     * @param {number} bend
+     * @param {NodeGraphLayoutOptions} options
+     * @param {number} step what the move itself costs
+     * @param {number} remaining estimate from `vertex` to the goal
+     * @param {number} generation
+     * @returns {void}
+     * @private
+     */
+    __relax(from, from_cost, from_axis, vertex, axis, goal, goal_axis, bend, options, step, remaining, generation) {
+        const state = vertex * 2 + axis;
+
+        if (this.closed.get(state)) {
+            return;
+        }
+
+        let cost = from_cost + step;
+
+        if (axis !== from_axis) {
+            cost += bend;
+        }
+
+        if (vertex === goal && axis !== goal_axis) {
+            // meeting a port along the wrong axis means one more turn than the route shows, made
+            // in the stub between the grid and the port itself
+            cost += bend;
+        }
+
+        if (this.stamp[state] === generation && this.score[state] <= cost) {
+            return;
+        }
+
+        this.score[state] = cost;
+        this.stamp[state] = generation;
+        this.came_from[state] = from;
+
+        // Queued rather than updated in place: finding an existing entry costs a scan of the heap,
+        // and a superseded entry is recognised and dropped for nothing when it surfaces.
+        this.open.insert(state, cost + remaining);
+    }
+
+    /**
+     * @param {number} state the goal, reached
+     * @returns {boolean}
+     * @private
+     */
+    __unwind(state) {
+        let length = 0;
+
+        for (let at = state; at !== -1; at = this.came_from[at]) {
+            length++;
+        }
+
+        if (length > this.path.length) {
+            this.path = new Int32Array(length);
+        }
+
+        const path = this.path;
+
+        let at = state;
+
+        // written back to front, so what comes out reads from the start of the wire to its end
+        for (let i = length - 1; i >= 0; i--, at = this.came_from[at]) {
+            path[i] = at >> 1;
+        }
+
+        this.path_length = length;
+
+        return true;
+    }
+}

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

@@ -0,0 +1,86 @@
+/**
+ * The routes of every wire, as corner points, flat.
+ *
+ * A route is the point it leaves its port at, every corner it turns, and the point it meets the
+ * other port at. Points in the middle of a straight run are not kept: they say nothing, and the
+ * stage that nudges routes apart works on runs, which it would otherwise have to reconstruct.
+ *
+ * All of them share two coordinate arrays, indexed by `offset`, because there are a few hundred of
+ * them and they are read together — once to nudge, once to turn into curves — and a few hundred
+ * small arrays is a few hundred allocations and no locality.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RouteSet {
+    /**
+     * @param {number} count routes
+     * @param {number} capacity points to start with
+     */
+    constructor(count: number, capacity?: number);
+    /**
+     * @type {number}
+     */
+    count: number;
+    /**
+     * Where each route starts in {@link x}. Length `count + 1`.
+     * @type {Int32Array}
+     */
+    offset: Int32Array;
+    /**
+     * @type {Float64Array}
+     */
+    x: Float64Array;
+    /**
+     * @type {Float64Array}
+     */
+    y: Float64Array;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __length;
+    /**
+     * Where the route currently being written began.
+     * @type {number}
+     * @private
+     */
+    private __start;
+    /**
+     * Discard every route, keeping the room they occupied.
+     * @returns {void}
+     */
+    clear(): void;
+    /**
+     * Begin the route of the given wire. Routes must be written in order.
+     * @param {number} index
+     * @returns {void}
+     */
+    begin(index: number): void;
+    /**
+     * Add a corner to the route being written, unless it is on the straight the last two were on.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {void}
+     */
+    push(x: number, y: number): void;
+    /**
+     * Finish the route being written.
+     * @param {number} index
+     * @returns {void}
+     */
+    end(index: number): void;
+    /**
+     * @param {number} needed
+     * @returns {void}
+     * @private
+     */
+    private __ensure;
+    /**
+     * @param {number} index
+     * @returns {number} corners in this route
+     */
+    length_of(index: number): number;
+}
+//# sourceMappingURL=RouteSet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RouteSet.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/RouteSet.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH;IAoCI;;;OAGG;IACH,mBAHW,MAAM,aACN,MAAM,EAShB;IA7CD;;OAEG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,UAAU,CAEb;IAEP;;OAEG;IACH,GAFU,YAAY,CAEpB;IAEF;;OAEG;IACH,GAFU,YAAY,CAEpB;IAEF;;;OAGG;IACH,iBAAa;IAEb;;;;OAIG;IACH,gBAAY;IAeZ;;;OAGG;IACH,SAFa,IAAI,CAOhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;;;;;OAMG;IACH,QAJW,MAAM,KACN,MAAM,GACJ,IAAI,CAiChB;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,iBAmBC;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

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

@@ -0,0 +1,168 @@
+/**
+ * The routes of every wire, as corner points, flat.
+ *
+ * A route is the point it leaves its port at, every corner it turns, and the point it meets the
+ * other port at. Points in the middle of a straight run are not kept: they say nothing, and the
+ * stage that nudges routes apart works on runs, which it would otherwise have to reconstruct.
+ *
+ * All of them share two coordinate arrays, indexed by `offset`, because there are a few hundred of
+ * them and they are read together — once to nudge, once to turn into curves — and a few hundred
+ * small arrays is a few hundred allocations and no locality.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RouteSet {
+
+    /**
+     * @type {number}
+     */
+    count = 0;
+
+    /**
+     * Where each route starts in {@link x}. Length `count + 1`.
+     * @type {Int32Array}
+     */
+    offset;
+
+    /**
+     * @type {Float64Array}
+     */
+    x;
+
+    /**
+     * @type {Float64Array}
+     */
+    y;
+
+    /**
+     * @type {number}
+     * @private
+     */
+    __length = 0;
+
+    /**
+     * Where the route currently being written began.
+     * @type {number}
+     * @private
+     */
+    __start = 0;
+
+    /**
+     * @param {number} count routes
+     * @param {number} capacity points to start with
+     */
+    constructor(count, capacity = count * 4) {
+        this.count = count;
+
+        this.offset = new Int32Array(count + 1);
+
+        this.x = new Float64Array(capacity);
+        this.y = new Float64Array(capacity);
+    }
+
+    /**
+     * Discard every route, keeping the room they occupied.
+     * @returns {void}
+     */
+    clear() {
+        this.__length = 0;
+        this.__start = 0;
+
+        this.offset.fill(0);
+    }
+
+    /**
+     * Begin the route of the given wire. Routes must be written in order.
+     * @param {number} index
+     * @returns {void}
+     */
+    begin(index) {
+        this.__start = this.__length;
+
+        this.offset[index] = this.__length;
+    }
+
+    /**
+     * Add a corner to the route being written, unless it is on the straight the last two were on.
+     *
+     * @param {number} x
+     * @param {number} y
+     * @returns {void}
+     */
+    push(x, y) {
+        const start = this.__start;
+
+        if (this.__length > start) {
+            const last = this.__length - 1;
+
+            if (this.x[last] === x && this.y[last] === y) {
+                return;
+            }
+
+            if (this.__length - start >= 2) {
+                const before = last - 1;
+
+                const straight_x = this.x[before] === x && this.x[last] === x;
+                const straight_y = this.y[before] === y && this.y[last] === y;
+
+                if (straight_x || straight_y) {
+                    this.x[last] = x;
+                    this.y[last] = y;
+
+                    return;
+                }
+            }
+        }
+
+        this.__ensure(this.__length + 1);
+
+        this.x[this.__length] = x;
+        this.y[this.__length] = y;
+
+        this.__length++;
+    }
+
+    /**
+     * Finish the route being written.
+     * @param {number} index
+     * @returns {void}
+     */
+    end(index) {
+        this.offset[index + 1] = this.__length;
+    }
+
+    /**
+     * @param {number} needed
+     * @returns {void}
+     * @private
+     */
+    __ensure(needed) {
+        if (needed <= this.x.length) {
+            return;
+        }
+
+        let capacity = this.x.length === 0 ? 64 : this.x.length;
+
+        while (capacity < needed) {
+            capacity *= 2;
+        }
+
+        const x = new Float64Array(capacity);
+        const y = new Float64Array(capacity);
+
+        x.set(this.x);
+        y.set(this.y);
+
+        this.x = x;
+        this.y = y;
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number} corners in this route
+     */
+    length_of(index) {
+        return this.offset[index + 1] - this.offset[index];
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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: LayoutBoxGraph, layer_count: number, order: Int32Array, rank: Int32Array, layer_start: Int32Array, options: NodeGraphLayoutOptions): {
+    width: number;
+    height: number;
+};
+//# sourceMappingURL=layout_assign_coordinates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout_assign_coordinates.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_assign_coordinates.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,8EAVW,MAAM,SACN,UAAU,QACV,UAAU,eACV,UAAU;WAEA,MAAM;YAAU,MAAM;EAgC1C"}