@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,184 @@
+import { number_compare_ascending } from "../../../../primitives/numbers/number_compare_ascending.js";
+import { LayoutBoxGraph, LAYOUT_BOX_NODE } from "./LayoutBoxGraph.js";
+import { LayoutProblem, layout_side_of } from "./LayoutProblem.js";
+
+/**
+ * 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, visual) {
+    const node_ids = [];
+
+    graph.traverseNodes(node => {
+        if (visual.getNode(node.id) !== undefined) {
+            node_ids.push(node.id);
+        }
+    });
+
+    node_ids.sort(number_compare_ascending);
+
+    const node_count = node_ids.length;
+
+    const box_of_node = new Map();
+
+    for (let i = 0; i < node_count; i++) {
+        box_of_node.set(node_ids[i], i);
+    }
+
+    const problem = new LayoutProblem();
+
+    problem.node_count = node_count;
+    problem.node_of_box = new Int32Array(node_count);
+
+    for (let i = 0; i < node_count; i++) {
+        problem.node_of_box[i] = node_ids[i];
+    }
+
+    const connections = [];
+
+    graph.traverseConnections(connection => {
+        const source = connection.source;
+        const target = connection.target;
+
+        if (source === null || target === null) {
+            return;
+        }
+
+        if (!box_of_node.has(source.instance.id) || !box_of_node.has(target.instance.id)) {
+            return;
+        }
+
+        connections.push(connection);
+    });
+
+    connections.sort((a, b) => number_compare_ascending(a.id, b.id));
+
+    const connection_count = connections.length;
+
+    problem.connection_count = connection_count;
+    problem.connection_id = new Int32Array(connection_count);
+    problem.from_box = new Int32Array(connection_count);
+    problem.to_box = new Int32Array(connection_count);
+    problem.from_dx = new Float64Array(connection_count);
+    problem.from_dy = new Float64Array(connection_count);
+    problem.to_dx = new Float64Array(connection_count);
+    problem.to_dy = new Float64Array(connection_count);
+    problem.from_side = new Uint8Array(connection_count);
+    problem.to_side = new Uint8Array(connection_count);
+
+    let link_count = 0;
+
+    for (let i = 0; i < connection_count; i++) {
+        if (box_of_node.get(connections[i].source.instance.id) !== box_of_node.get(connections[i].target.instance.id)) {
+            link_count++;
+        }
+    }
+
+    const boxes = new LayoutBoxGraph(node_count, link_count);
+
+    problem.boxes = boxes;
+
+    for (let i = 0; i < node_count; i++) {
+        const dimensions = visual.getNode(node_ids[i]).dimensions;
+
+        boxes.set_box(i, dimensions.size.x, dimensions.size.y, LAYOUT_BOX_NODE);
+
+        // Where the node is now. The placement stages overwrite this, but routing on its own does
+        // not run them, and then this is the only thing saying where anything is.
+        boxes.box_x[i] = dimensions.position.x;
+        boxes.box_y[i] = dimensions.position.y;
+    }
+
+    let link = 0;
+
+    for (let i = 0; i < connection_count; i++) {
+        const connection = connections[i];
+
+        const from_box = box_of_node.get(connection.source.instance.id);
+        const to_box = box_of_node.get(connection.target.instance.id);
+
+        problem.connection_id[i] = connection.id;
+        problem.from_box[i] = from_box;
+        problem.to_box[i] = to_box;
+
+        write_endpoint(problem, i, true, visual, node_ids[from_box], connection.source.port.id, boxes, from_box);
+        write_endpoint(problem, i, false, visual, node_ids[to_box], connection.target.port.id, boxes, to_box);
+
+        if (from_box !== to_box) {
+            boxes.set_link(link++, from_box, to_box, problem.from_dy[i], problem.to_dy[i]);
+        }
+    }
+
+    boxes.build_adjacency();
+
+    return problem;
+}
+
+/**
+ * Fill in where one end of a connection meets its box.
+ *
+ * A port the visual data has no entry for falls back to the middle of the side its direction
+ * implies — the wire is then drawn to a plausible place rather than to the box's top left corner,
+ * which is where an unset offset would otherwise put it.
+ *
+ * @param {LayoutProblem} problem
+ * @param {number} index connection
+ * @param {boolean} leaving whether this is the end the connection leaves by
+ * @param {NodeGraphVisualData} visual
+ * @param {number} node_id
+ * @param {number} port_id
+ * @param {LayoutBoxGraph} boxes
+ * @param {number} box
+ * @returns {void}
+ */
+function write_endpoint(problem, index, leaving, visual, node_id, port_id, boxes, box) {
+    const width = boxes.box_w[box];
+    const height = boxes.box_h[box];
+
+    const port = visual.getNode(node_id).getPort(port_id);
+
+    let dx;
+    let dy;
+
+    if (port === undefined) {
+        dx = leaving ? width : 0;
+        dy = height / 2;
+    } else {
+        dx = port.position.x;
+        dy = port.position.y;
+    }
+
+    const side = layout_side_of(dx, dy, width, height);
+
+    if (leaving) {
+        problem.from_dx[index] = dx;
+        problem.from_dy[index] = dy;
+        problem.from_side[index] = side;
+    } else {
+        problem.to_dx[index] = dx;
+        problem.to_dy[index] = dy;
+        problem.to_side[index] = side;
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Give every wire that crosses a column it does not stop at somewhere to be in that column.
+ *
+ * A link spanning three columns is replaced by three links joined by two **lane boxes**, one in each
+ * column it passes through. A lane box is never drawn. It is as wide as nothing and as tall as a
+ * wire, and it exists so that the two stages that follow — which know only about boxes — leave a
+ * gap for the wire instead of packing the real boxes tight and letting it be drawn across them.
+ *
+ * This is what a layered layout normally calls a dummy node, and it does three jobs here:
+ *
+ * - **Room.** The coordinate stage separates boxes; a lane box is what makes it separate them
+ *   enough for the wire between them.
+ * - **Crossings.** Every link now spans exactly one column boundary, so two wires cross at a known
+ *   boundary and the ordering stage can count crossings exactly instead of estimating them.
+ * - **Straightness.** A chain of lane boxes is a chain of links the coordinate stage will try to
+ *   align, and aligning them is what makes a long wire straight rather than a slow diagonal.
+ *
+ * The router is never told which lane belongs to which wire. It does not need to be: the lanes put
+ * empty horizontal space where wires want to go, and a router minimising length and bends finds it.
+ *
+ * @param {LayoutBoxGraph} graph mutated in place; adjacency is rebuilt. Layers must be assigned, and
+ *        every link must point forwards by at least one column.
+ * @returns {number} how many lane boxes were added
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_insert_lanes(graph: LayoutBoxGraph): number;
+//# sourceMappingURL=layout_insert_lanes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout_insert_lanes.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_insert_lanes.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,4DALa,MAAM,CAsElB"}

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

@@ -0,0 +1,95 @@
+import { LAYOUT_BOX_LANE } from "./LayoutBoxGraph.js";
+
+/**
+ * Give every wire that crosses a column it does not stop at somewhere to be in that column.
+ *
+ * A link spanning three columns is replaced by three links joined by two **lane boxes**, one in each
+ * column it passes through. A lane box is never drawn. It is as wide as nothing and as tall as a
+ * wire, and it exists so that the two stages that follow — which know only about boxes — leave a
+ * gap for the wire instead of packing the real boxes tight and letting it be drawn across them.
+ *
+ * This is what a layered layout normally calls a dummy node, and it does three jobs here:
+ *
+ * - **Room.** The coordinate stage separates boxes; a lane box is what makes it separate them
+ *   enough for the wire between them.
+ * - **Crossings.** Every link now spans exactly one column boundary, so two wires cross at a known
+ *   boundary and the ordering stage can count crossings exactly instead of estimating them.
+ * - **Straightness.** A chain of lane boxes is a chain of links the coordinate stage will try to
+ *   align, and aligning them is what makes a long wire straight rather than a slow diagonal.
+ *
+ * The router is never told which lane belongs to which wire. It does not need to be: the lanes put
+ * empty horizontal space where wires want to go, and a router minimising length and bends finds it.
+ *
+ * @param {LayoutBoxGraph} graph mutated in place; adjacency is rebuilt. Layers must be assigned, and
+ *        every link must point forwards by at least one column.
+ * @returns {number} how many lane boxes were added
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_insert_lanes(graph) {
+    const old_link_count = graph.link_count;
+
+    let extra_boxes = 0;
+    let new_link_count = 0;
+
+    for (let i = 0; i < old_link_count; i++) {
+        const span = graph.box_layer[graph.link_to[i]] - graph.box_layer[graph.link_from[i]];
+
+        extra_boxes += span - 1;
+        new_link_count += span;
+    }
+
+    if (extra_boxes === 0) {
+        return 0;
+    }
+
+    // The links are about to be rewritten in place and a spanning link becomes several, so the
+    // originals have to be read from somewhere the writing cannot reach.
+    const from = graph.link_from.slice(0, old_link_count);
+    const to = graph.link_to.slice(0, old_link_count);
+    const from_y = graph.link_from_y.slice(0, old_link_count);
+    const to_y = graph.link_to_y.slice(0, old_link_count);
+
+    const first_lane = graph.box_count;
+
+    graph.resize(graph.box_count + extra_boxes, new_link_count);
+
+    let lane = first_lane;
+    let link = 0;
+
+    for (let i = 0; i < old_link_count; i++) {
+        const tail = from[i];
+        const head = to[i];
+
+        const tail_layer = graph.box_layer[tail];
+        const span = graph.box_layer[head] - tail_layer;
+
+        if (span === 1) {
+            graph.set_link(link++, tail, head, from_y[i], to_y[i]);
+
+            continue;
+        }
+
+        let previous = tail;
+        let previous_y = from_y[i];
+
+        for (let step = 1; step < span; step++) {
+            graph.set_box(lane, 0, 0, LAYOUT_BOX_LANE);
+            graph.box_layer[lane] = tail_layer + step;
+
+            graph.set_link(link++, previous, lane, previous_y, 0);
+
+            previous = lane;
+            previous_y = 0;
+
+            lane++;
+        }
+
+        graph.set_link(link++, previous, head, previous_y, to_y[i]);
+    }
+
+    graph.build_adjacency();
+
+    return extra_boxes;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Arrange a node graph and route every wire in it.
+ *
+ * Two halves, and they are not the same problem.
+ *
+ * **Placement** decides where the nodes go, and the whole of it is the observation that a node graph
+ * is read left to right. Everything a node waits on is put strictly to its left, boxes within a
+ * column are ordered so that as few wires cross as can be managed, and then each box is put level
+ * with the things it connects to. What that produces is a drawing where following a wire means
+ * moving your eye in one direction, and where things that belong together have ended up together —
+ * not because anything measured how related they are, but because being joined is what put them in
+ * neighbouring columns and being joined to the same things is what put them next to each other.
+ *
+ * **Routing** decides where the wires go, which the placement has deliberately left open. Each wire
+ * finds its own way through the space between the boxes, avoiding them and, as far as it can, each
+ * other. This is where the drawing stops looking like a diagram of the algorithm and starts looking
+ * like something somebody drew: wires that run alongside each other rather than through each other,
+ * that go around a node instead of behind it, and that leave and arrive square to the ports they
+ * belong to.
+ *
+ * The two halves are separate on purpose. Placement can be re-run without re-routing when only the
+ * structure changed, and routing can be re-run without re-placing when somebody has dragged a node
+ * — which is the common case in an editor, and the one where moving everything else in response
+ * would be the wrong answer.
+ *
+ * Nothing here is random and nothing depends on iteration order of a map: the same graph laid out
+ * twice gives the same drawing, and a graph saved and reloaded gives the drawing it had.
+ *
+ * @param {NodeGraph} graph
+ * @param {NodeGraphVisualData} visual mutated: node positions and connection paths are written
+ * @param {NodeGraphLayoutOptions} [options]
+ * @returns {{width: number, height: number, crossings: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_node_graph(graph: NodeGraph, visual: NodeGraphVisualData, options?: NodeGraphLayoutOptions): {
+    width: number;
+    height: number;
+    crossings: number;
+};
+/**
+ * Route the wires of an already placed graph.
+ *
+ * Split out because it is the half worth doing on its own: a node dragged by hand moves its wires
+ * and nothing else, and re-running the placement in response would rearrange the drawing under
+ * somebody who was only trying to move one node.
+ *
+ * @param {LayoutProblem} problem must carry current box positions
+ * @param {NodeGraphVisualData} visual mutated: connection paths are written
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {void}
+ */
+export function layout_route_node_graph(problem: LayoutProblem, visual: NodeGraphVisualData, options: NodeGraphLayoutOptions): void;
+import { NodeGraphLayoutOptions } from "./NodeGraphLayoutOptions.js";
+//# sourceMappingURL=layout_node_graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout_node_graph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_node_graph.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,2FANW,sBAAsB;WACZ,MAAM;YAAU,MAAM;eAAa,MAAM;EA+C7D;AAED;;;;;;;;;;;GAWG;AACH,sGAHW,sBAAsB,GACpB,IAAI,CA2BhB;uCA3HsC,6BAA6B"}

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

@@ -0,0 +1,131 @@
+import { layout_assign_coordinates } from "./layout_assign_coordinates.js";
+import { layout_assign_layers } from "./layout_assign_layers.js";
+import { layout_break_cycles } from "./layout_break_cycles.js";
+import { layout_build_problem } from "./layout_build_problem.js";
+import { layout_insert_lanes } from "./layout_insert_lanes.js";
+import { layout_order_layers } from "./layout_order_layers.js";
+import { layout_orient_links } from "./layout_orient_links.js";
+import { NodeGraphLayoutOptions } from "./NodeGraphLayoutOptions.js";
+import { route_connections } from "./route_connections.js";
+import { route_grid_build } from "./route_grid_build.js";
+import { route_nudge } from "./route_nudge.js";
+import { route_to_spline } from "./route_to_spline.js";
+
+/**
+ * Arrange a node graph and route every wire in it.
+ *
+ * Two halves, and they are not the same problem.
+ *
+ * **Placement** decides where the nodes go, and the whole of it is the observation that a node graph
+ * is read left to right. Everything a node waits on is put strictly to its left, boxes within a
+ * column are ordered so that as few wires cross as can be managed, and then each box is put level
+ * with the things it connects to. What that produces is a drawing where following a wire means
+ * moving your eye in one direction, and where things that belong together have ended up together —
+ * not because anything measured how related they are, but because being joined is what put them in
+ * neighbouring columns and being joined to the same things is what put them next to each other.
+ *
+ * **Routing** decides where the wires go, which the placement has deliberately left open. Each wire
+ * finds its own way through the space between the boxes, avoiding them and, as far as it can, each
+ * other. This is where the drawing stops looking like a diagram of the algorithm and starts looking
+ * like something somebody drew: wires that run alongside each other rather than through each other,
+ * that go around a node instead of behind it, and that leave and arrive square to the ports they
+ * belong to.
+ *
+ * The two halves are separate on purpose. Placement can be re-run without re-routing when only the
+ * structure changed, and routing can be re-run without re-placing when somebody has dragged a node
+ * — which is the common case in an editor, and the one where moving everything else in response
+ * would be the wrong answer.
+ *
+ * Nothing here is random and nothing depends on iteration order of a map: the same graph laid out
+ * twice gives the same drawing, and a graph saved and reloaded gives the drawing it had.
+ *
+ * @param {NodeGraph} graph
+ * @param {NodeGraphVisualData} visual mutated: node positions and connection paths are written
+ * @param {NodeGraphLayoutOptions} [options]
+ * @returns {{width: number, height: number, crossings: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_node_graph(graph, visual, options = new NodeGraphLayoutOptions()) {
+    const problem = layout_build_problem(graph, visual);
+
+    const boxes = problem.boxes;
+
+    let crossings = 0;
+    let width = 0;
+    let height = 0;
+
+    if (problem.node_count > 0) {
+        const position = layout_break_cycles(boxes);
+
+        layout_orient_links(boxes, position);
+
+        const layer_count = layout_assign_layers(boxes, position);
+
+        layout_insert_lanes(boxes);
+
+        const ordering = layout_order_layers(boxes, layer_count, options.order_sweeps);
+
+        crossings = ordering.crossings;
+
+        const extent = layout_assign_coordinates(
+            boxes,
+            layer_count,
+            ordering.order,
+            ordering.rank,
+            ordering.layer_start,
+            options
+        );
+
+        width = extent.width;
+        height = extent.height;
+
+        for (let box = 0; box < problem.node_count; box++) {
+            visual.getNode(problem.node_of_box[box]).dimensions.position.set(boxes.box_x[box], boxes.box_y[box]);
+        }
+    }
+
+    layout_route_node_graph(problem, visual, options);
+
+    return { width, height, crossings };
+}
+
+/**
+ * Route the wires of an already placed graph.
+ *
+ * Split out because it is the half worth doing on its own: a node dragged by hand moves its wires
+ * and nothing else, and re-running the placement in response would rearrange the drawing under
+ * somebody who was only trying to move one node.
+ *
+ * @param {LayoutProblem} problem must carry current box positions
+ * @param {NodeGraphVisualData} visual mutated: connection paths are written
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {void}
+ */
+export function layout_route_node_graph(problem, visual, options) {
+    const grid = route_grid_build(problem, options);
+
+    const routes = route_connections(problem, grid, options);
+
+    route_nudge(routes, options);
+
+    const drawn = new Set();
+
+    for (let i = 0; i < problem.connection_count; i++) {
+        const id = problem.connection_id[i];
+
+        route_to_spline(routes, i, options, visual.ensureConnection(id));
+
+        drawn.add(id);
+    }
+
+    // A connection deleted since the last layout leaves a path behind. Connection ids are handed out
+    // afresh, so a stale path is one that will eventually be drawn for a connection it has nothing
+    // to do with.
+    for (const id of Array.from(visual.connections.keys())) {
+        if (!drawn.has(id)) {
+            visual.removeConnection(id);
+        }
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Decide the order of boxes within each column.
+ *
+ * Two heuristics alternating, then a local fix-up, and the best arrangement any of them reaches is
+ * what is kept — a sweep can leave the drawing worse than it found it, and there is no reason to
+ * keep the last one rather than the best one.
+ *
+ * - **Sweeps.** Every box moves to the average, or to the median, of where its neighbours in the
+ *   adjacent column sit. Median wins where a box's neighbours fall into groups, average where they
+ *   are spread evenly, and alternating them escapes the local minimum either one alone settles
+ *   into. Exact crossing minimisation is NP-hard and nobody reading a graph is counting crossings.
+ * - **Exchanges.** After each sweep, adjacent pairs swap wherever that removes crossings. A sweep
+ *   moves a box to where its neighbours are on average; an exchange fixes the case where two boxes
+ *   simply want each other's place, which no average will ever tell them.
+ *
+ * Every link spans exactly one column boundary by this point — {@link layout_insert_lanes} saw to
+ * that — so the crossing count here is the number of crossings the drawing will actually show,
+ * counted rather than estimated.
+ *
+ * @param {LayoutBoxGraph} graph adjacency must be current
+ * @param {number} layer_count
+ * @param {number} sweeps
+ * @returns {{order: Int32Array, rank: Int32Array, layer_start: Int32Array, crossings: number}}
+ *          `order` holds box indices grouped by column, `layer_start` where each column begins in
+ *          it, and `rank` where each box sits within its own column.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_order_layers(graph: LayoutBoxGraph, layer_count: number, sweeps: number): {
+    order: Int32Array;
+    rank: Int32Array;
+    layer_start: Int32Array;
+    crossings: number;
+};
+//# sourceMappingURL=layout_order_layers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout_order_layers.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_order_layers.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wEATW,MAAM,UACN,MAAM;WACI,UAAU;UAAQ,UAAU;iBAAe,UAAU;eAAa,MAAM;EAsI5F"}