@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,34 @@
+/**
+ * Work out which lines wires are allowed to travel along, and mark the boxes solid.
+ *
+ * The lines come from four places, and each of them answers a different question:
+ *
+ * - **Around every box**, a line a clearance outside each of its four edges. This is how a wire
+ *   gets past a box, and how it runs alongside one without appearing to touch it.
+ * - **At every port**, a line at the height it sits at. This is what lets a wire arrive at a port
+ *   horizontally instead of sloping into it, and it is most of the reason the grid is as tall as
+ *   it is.
+ * - **At every lane** the layout reserved, a line at its height and one at its x — the middle of
+ *   its column. A wire crossing a column it does not stop at was promised empty space there, and
+ *   it is routed through the point where the two meet.
+ * - **Across every channel**, a few evenly spaced tracks. Without them the only places a wire can
+ *   turn in a channel are the box edges either side of it, so every wire turning in that channel
+ *   turns in the same place and they are drawn on top of each other.
+ *
+ * Plus a margin all the way round, which is where a wire running against the flow goes to get past
+ * everything in its way.
+ *
+ * When all of that comes to more grid than the budget allows, the port lines are the ones dropped:
+ * they are the most numerous by far, and losing them costs a short sloped approach at each end
+ * rather than a route that cannot be found.
+ *
+ * @param {LayoutProblem} problem
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {RouteGrid}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_grid_build(problem: LayoutProblem, options: NodeGraphLayoutOptions): RouteGrid;
+import { RouteGrid } from "./RouteGrid.js";
+//# sourceMappingURL=route_grid_build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route_grid_build.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/route_grid_build.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,2FALa,SAAS,CA8GrB;0BA1I6C,gBAAgB"}

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

@@ -0,0 +1,229 @@
+import { LAYOUT_BOX_LANE } from "./LayoutBoxGraph.js";
+import { number_compare_ascending } from "../../../../primitives/numbers/number_compare_ascending.js";
+import { LAYOUT_SIDE_BOTTOM, LAYOUT_SIDE_TOP } from "./LayoutProblem.js";
+import { ROUTE_GRID_EPSILON, RouteGrid } from "./RouteGrid.js";
+
+/**
+ * Work out which lines wires are allowed to travel along, and mark the boxes solid.
+ *
+ * The lines come from four places, and each of them answers a different question:
+ *
+ * - **Around every box**, a line a clearance outside each of its four edges. This is how a wire
+ *   gets past a box, and how it runs alongside one without appearing to touch it.
+ * - **At every port**, a line at the height it sits at. This is what lets a wire arrive at a port
+ *   horizontally instead of sloping into it, and it is most of the reason the grid is as tall as
+ *   it is.
+ * - **At every lane** the layout reserved, a line at its height and one at its x — the middle of
+ *   its column. A wire crossing a column it does not stop at was promised empty space there, and
+ *   it is routed through the point where the two meet.
+ * - **Across every channel**, a few evenly spaced tracks. Without them the only places a wire can
+ *   turn in a channel are the box edges either side of it, so every wire turning in that channel
+ *   turns in the same place and they are drawn on top of each other.
+ *
+ * Plus a margin all the way round, which is where a wire running against the flow goes to get past
+ * everything in its way.
+ *
+ * When all of that comes to more grid than the budget allows, the port lines are the ones dropped:
+ * they are the most numerous by far, and losing them costs a short sloped approach at each end
+ * rather than a route that cannot be found.
+ *
+ * @param {LayoutProblem} problem
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {RouteGrid}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_grid_build(problem, options) {
+    const boxes = problem.boxes;
+
+    const clearance = options.clearance;
+
+    const xs = [];
+    const ys = [];
+
+    let min_x = Infinity;
+    let min_y = Infinity;
+    let max_x = -Infinity;
+    let max_y = -Infinity;
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        const x0 = boxes.box_x[box];
+        const y0 = boxes.box_y[box];
+        const x1 = x0 + boxes.box_w[box];
+        const y1 = y0 + boxes.box_h[box];
+
+        if (x0 < min_x) {
+            min_x = x0;
+        }
+
+        if (y0 < min_y) {
+            min_y = y0;
+        }
+
+        if (x1 > max_x) {
+            max_x = x1;
+        }
+
+        if (y1 > max_y) {
+            max_y = y1;
+        }
+
+        if (boxes.box_kind[box] === LAYOUT_BOX_LANE) {
+            // A lane is a point, not an obstacle: it is the promise of empty space, so all it
+            // contributes is the two lines through it.
+            xs.push(x0);
+            ys.push(y0);
+
+            continue;
+        }
+
+        xs.push(x0 - clearance, x1 + clearance);
+        ys.push(y0 - clearance, y1 + clearance);
+    }
+
+    if (boxes.box_count === 0) {
+        min_x = 0;
+        min_y = 0;
+        max_x = 0;
+        max_y = 0;
+    }
+
+    const margin_x = options.layer_gap;
+    const margin_y = options.node_gap + options.wire_gap;
+
+    xs.push(min_x - margin_x, max_x + margin_x);
+    ys.push(min_y - margin_y, max_y + margin_y);
+
+    add_channel_tracks(xs, boxes, options);
+
+    const port_ys = [];
+
+    for (let i = 0; i < problem.connection_count; i++) {
+        port_ys.push(boxes.box_y[problem.from_box[i]] + problem.from_dy[i]);
+        port_ys.push(boxes.box_y[problem.to_box[i]] + problem.to_dy[i]);
+
+        // A port on the top or bottom edge is left going up or down, so what it needs is a line
+        // along its x rather than its y. There are few of these — a node's inputs and outputs are
+        // on its sides — so they go in unconditionally.
+        if (problem.from_side[i] === LAYOUT_SIDE_TOP || problem.from_side[i] === LAYOUT_SIDE_BOTTOM) {
+            xs.push(boxes.box_x[problem.from_box[i]] + problem.from_dx[i]);
+        }
+
+        if (problem.to_side[i] === LAYOUT_SIDE_TOP || problem.to_side[i] === LAYOUT_SIDE_BOTTOM) {
+            xs.push(boxes.box_x[problem.to_box[i]] + problem.to_dx[i]);
+        }
+    }
+
+    const x_axis = sorted_unique(xs);
+
+    let y_axis = sorted_unique(ys.concat(port_ys));
+
+    if (x_axis.length * y_axis.length > options.max_grid_vertices) {
+        y_axis = sorted_unique(ys);
+    }
+
+    const grid = new RouteGrid(x_axis, y_axis);
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        if (boxes.box_kind[box] === LAYOUT_BOX_LANE) {
+            continue;
+        }
+
+        grid.block_rectangle(
+            boxes.box_x[box] - clearance,
+            boxes.box_y[box] - clearance,
+            boxes.box_x[box] + boxes.box_w[box] + clearance,
+            boxes.box_y[box] + boxes.box_h[box] + clearance
+        );
+    }
+
+    return grid;
+}
+
+/**
+ * Put a few evenly spaced vertical lines in the gap between each pair of neighbouring columns.
+ *
+ * The gap is measured from the boxes rather than taken from the options, because a column is as
+ * wide as its widest box and the narrow ones in it leave more room than the gap alone suggests.
+ *
+ * @param {number[]} xs appended to
+ * @param {LayoutBoxGraph} boxes
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {void}
+ */
+function add_channel_tracks(xs, boxes, options) {
+    let layer_count = 0;
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        if (boxes.box_layer[box] + 1 > layer_count) {
+            layer_count = boxes.box_layer[box] + 1;
+        }
+    }
+
+    if (layer_count < 2) {
+        return;
+    }
+
+    const left = new Float64Array(layer_count).fill(Infinity);
+    const right = new Float64Array(layer_count).fill(-Infinity);
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        if (boxes.box_kind[box] === LAYOUT_BOX_LANE) {
+            continue;
+        }
+
+        const layer = boxes.box_layer[box];
+
+        if (boxes.box_x[box] < left[layer]) {
+            left[layer] = boxes.box_x[box];
+        }
+
+        const edge = boxes.box_x[box] + boxes.box_w[box];
+
+        if (edge > right[layer]) {
+            right[layer] = edge;
+        }
+    }
+
+    const tracks = options.channel_tracks;
+
+    for (let i = 0; i + 1 < layer_count; i++) {
+        const start = right[i];
+        const end = left[i + 1];
+
+        if (!(start < end)) {
+            // a column with no real boxes in it, or columns that touch; nothing to divide
+            continue;
+        }
+
+        for (let k = 1; k <= tracks; k++) {
+            xs.push(start + (end - start) * k / (tracks + 1));
+        }
+    }
+}
+
+/**
+ * @param {number[]} values
+ * @returns {Float64Array}
+ */
+function sorted_unique(values) {
+    values.sort(number_compare_ascending);
+
+    const packed = new Float64Array(values.length);
+
+    let count = 0;
+
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+
+        if (count > 0 && value - packed[count - 1] < ROUTE_GRID_EPSILON) {
+            continue;
+        }
+
+        packed[count++] = value;
+    }
+
+    // a copy rather than a view, so that the room the duplicates took is given back
+    return packed.slice(0, count);
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Pull apart wires that ended up drawn on top of each other.
+ *
+ * The router does most of this itself — negotiating over the lines is exactly the business of not
+ * sharing them — but it cannot always finish. Two wires that genuinely have one route between them
+ * both take it, and what the drawing then shows is one wire where there are two. Congestion has no
+ * answer to that, because there is no second route to move to; the answer is to stop insisting they
+ * are on a line at all and spread them a few units either side of it.
+ *
+ * **Which one goes on which side** is not a free choice. Wires arriving at a shared run from above
+ * and leaving it above have to stay above, or the two of them cross twice for nothing — once to
+ * swap and once to swap back. So a group is ordered by where its members come from and where they
+ * go, and gets spread in that order.
+ *
+ * **Wires of one net stay together.** The wires leaving one port are one signal, and where they
+ * run along the same line they are one line that forks — the router lets them share it for
+ * nothing for exactly that reason. Pulled apart they would be several lines, and the one that
+ * forks first would cross every one outside it. So a group is spread by net, every wire of a net
+ * moving by the same amount, and a group that is all one net does not move.
+ *
+ * Only the middle of a wire moves. The two ends meet ports, and a port is where it is.
+ *
+ * @param {RouteSet} routes mutated in place
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {number} how many runs were moved
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_nudge(routes: RouteSet, options: NodeGraphLayoutOptions): number;
+//# sourceMappingURL=route_nudge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route_nudge.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/route_nudge.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,gFALa,MAAM,CA6DlB"}

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

@@ -0,0 +1,249 @@
+import { overlap1D } from "../../../../math/interval/overlap1D.js";
+
+/**
+ * Fraction of the clearance around a box that nudged wires are allowed to spread into.
+ *
+ * Nudging moves a wire off the line the router put it on, and the nearest thing to that line is
+ * usually a box. Spreading past this would push the outermost wire of a group into whatever the
+ * clearance was protecting it from.
+ *
+ * @type {number}
+ */
+const SPREAD_LIMIT = 0.7;
+
+/**
+ * Pull apart wires that ended up drawn on top of each other.
+ *
+ * The router does most of this itself — negotiating over the lines is exactly the business of not
+ * sharing them — but it cannot always finish. Two wires that genuinely have one route between them
+ * both take it, and what the drawing then shows is one wire where there are two. Congestion has no
+ * answer to that, because there is no second route to move to; the answer is to stop insisting they
+ * are on a line at all and spread them a few units either side of it.
+ *
+ * **Which one goes on which side** is not a free choice. Wires arriving at a shared run from above
+ * and leaving it above have to stay above, or the two of them cross twice for nothing — once to
+ * swap and once to swap back. So a group is ordered by where its members come from and where they
+ * go, and gets spread in that order.
+ *
+ * **Wires of one net stay together.** The wires leaving one port are one signal, and where they
+ * run along the same line they are one line that forks — the router lets them share it for
+ * nothing for exactly that reason. Pulled apart they would be several lines, and the one that
+ * forks first would cross every one outside it. So a group is spread by net, every wire of a net
+ * moving by the same amount, and a group that is all one net does not move.
+ *
+ * Only the middle of a wire moves. The two ends meet ports, and a port is where it is.
+ *
+ * @param {RouteSet} routes mutated in place
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {number} how many runs were moved
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_nudge(routes, options) {
+    const segments = collect(routes);
+
+    const count = segments.count;
+
+    if (count === 0) {
+        return 0;
+    }
+
+    const separation = options.wire_gap / 2;
+    const limit = options.clearance * SPREAD_LIMIT;
+
+    const order = new Int32Array(count);
+
+    for (let i = 0; i < count; i++) {
+        order[i] = i;
+    }
+
+    // grouped by the line they sit on, then by where along it they start
+    order.sort((a, b) =>
+        (segments.axis[a] - segments.axis[b])
+        || (segments.fixed[a] - segments.fixed[b])
+        || (segments.low[a] - segments.low[b])
+    );
+
+    let moved = 0;
+
+    let start = 0;
+
+    while (start < count) {
+        let end = start + 1;
+
+        // one cluster: same line, and every member overlapping something already in it
+        let reach = segments.high[order[start]];
+
+        while (
+            end < count
+            && segments.axis[order[end]] === segments.axis[order[start]]
+            && segments.fixed[order[end]] === segments.fixed[order[start]]
+            && overlap1D(segments.low[order[start]], reach, segments.low[order[end]], segments.high[order[end]])
+        ) {
+            if (segments.high[order[end]] > reach) {
+                reach = segments.high[order[end]];
+            }
+
+            end++;
+        }
+
+        if (end - start > 1) {
+            moved += spread(routes, segments, order, start, end, separation, limit);
+        }
+
+        start = end;
+    }
+
+    return moved;
+}
+
+/**
+ * Move one group of overlapping runs off their shared line, evenly either side of it — one place
+ * per net, and every run of a net by the same amount.
+ *
+ * @param {RouteSet} routes
+ * @param {object} segments
+ * @param {Int32Array} order
+ * @param {number} start
+ * @param {number} end exclusive
+ * @param {number} separation
+ * @param {number} limit largest distance any of them may be moved
+ * @returns {number} how many runs were moved
+ */
+function spread(routes, segments, order, start, end, separation, limit) {
+    const group = order.subarray(start, end);
+
+    // Where each wire comes into the run from and where it leaves it for, across the line rather
+    // than along it. A wire that was above stays above.
+    group.sort((a, b) =>
+        (segments.before[a] - segments.before[b])
+        || (segments.after[a] - segments.after[b])
+        || (segments.route[a] - segments.route[b])
+    );
+
+    // each net takes the place its first run sorted to
+    const place = new Map();
+
+    for (let i = 0; i < group.length; i++) {
+        const net = segments.net[group[i]];
+
+        if (!place.has(net)) {
+            place.set(net, place.size);
+        }
+    }
+
+    const size = place.size;
+
+    if (size < 2) {
+        return 0;
+    }
+
+    const step = Math.min(separation, limit * 2 / (size - 1));
+
+    let moved = 0;
+
+    for (let i = 0; i < group.length; i++) {
+        const segment = group[i];
+
+        const shift = (place.get(segments.net[segment]) - (size - 1) / 2) * step;
+
+        if (shift === 0) {
+            continue;
+        }
+
+        const at = segments.point[segment];
+
+        if (segments.axis[segment] === 0) {
+            routes.y[at] += shift;
+            routes.y[at + 1] += shift;
+        } else {
+            routes.x[at] += shift;
+            routes.x[at + 1] += shift;
+        }
+
+        moved++;
+    }
+
+    return moved;
+}
+
+/**
+ * Gather every straight run that is free to move.
+ *
+ * A run of a wire that is not along an axis cannot be nudged along one, and the first and last runs
+ * of a wire are pinned to its ports. Everything else is a candidate.
+ *
+ * @param {RouteSet} routes
+ * @returns {object}
+ */
+function collect(routes) {
+    let capacity = 0;
+
+    for (let i = 0; i < routes.count; i++) {
+        const length = routes.length_of(i);
+
+        if (length > 3) {
+            capacity += length - 3;
+        }
+    }
+
+    const segments = {
+        count: 0,
+        route: new Int32Array(capacity),
+        net: new Int32Array(capacity),
+        point: new Int32Array(capacity),
+        axis: new Uint8Array(capacity),
+        fixed: new Float64Array(capacity),
+        low: new Float64Array(capacity),
+        high: new Float64Array(capacity),
+        before: new Float64Array(capacity),
+        after: new Float64Array(capacity)
+    };
+
+    for (let i = 0; i < routes.count; i++) {
+        const start = routes.offset[i];
+        const end = routes.offset[i + 1];
+
+        // a route nobody has put in a net is a net of its own
+        const net = routes.net === null ? i : routes.net[i];
+
+        for (let p = start + 1; p + 2 < end; p++) {
+            const ax = routes.x[p];
+            const ay = routes.y[p];
+            const bx = routes.x[p + 1];
+            const by = routes.y[p + 1];
+
+            const horizontal = ay === by;
+            const vertical = ax === bx;
+
+            if (horizontal === vertical) {
+                // a diagonal, or a run of no length: neither is something to line up with anything
+                continue;
+            }
+
+            const at = segments.count++;
+
+            segments.route[at] = i;
+            segments.net[at] = net;
+            segments.point[at] = p;
+            segments.axis[at] = horizontal ? 0 : 1;
+
+            if (horizontal) {
+                segments.fixed[at] = ay;
+                segments.low[at] = Math.min(ax, bx);
+                segments.high[at] = Math.max(ax, bx);
+                segments.before[at] = routes.y[p - 1];
+                segments.after[at] = routes.y[p + 2];
+            } else {
+                segments.fixed[at] = ax;
+                segments.low[at] = Math.min(ay, by);
+                segments.high[at] = Math.max(ay, by);
+                segments.before[at] = routes.x[p - 1];
+                segments.after[at] = routes.x[p + 2];
+            }
+        }
+    }
+
+    return segments;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Turn a route into the curve that gets drawn.
+ *
+ * The router works in straight lines and right angles because that is what can be reasoned about —
+ * what is blocked, what is shared, what is shortest. None of that is what should be drawn. A node
+ * graph drawn in right angles reads as a circuit board, and the thing a reader is doing with it is
+ * following one wire with their eye, which a corner interrupts and a curve does not.
+ *
+ * So every corner becomes a curve, and the radius is **as large as the space allows**: the whole
+ * corner radius where there is room, and half the shorter of the two runs meeting there where there
+ * is not. A long run therefore stays a long straight line that turns at the end, and a short jog
+ * between two runs disappears into a single smooth S. What comes out is a wire that happens to be
+ * well organised, rather than a trace.
+ *
+ * Straight runs stay exactly straight. A knot's tangent points along the run leaving it, and a cubic
+ * whose end tangents are both parallel to the line between its ends *is* that line — the curve only
+ * travels along it at an uneven rate, which nothing can see.
+ *
+ * @param {RouteSet} routes
+ * @param {number} index which route
+ * @param {NodeGraphLayoutOptions} options
+ * @param {ConnectionVisualData} target written into
+ * @returns {void}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_to_spline(routes: RouteSet, index: number, options: NodeGraphLayoutOptions, target: ConnectionVisualData): void;
+//# sourceMappingURL=route_to_spline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route_to_spline.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/route_to_spline.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,yDARW,MAAM,kEAGJ,IAAI,CAsFhB"}