@woosh/meep-engine 3.15.0 → 3.16.0

package/src/core/model/node-graph/visual/NodeGraphVisualData.js

@@ -1,12 +1,41 @@
 import { assert } from "../../../assert.js";
-import { HashMap } from "../../../collection/map/HashMap.js";
 import { Color } from "../../../color/Color.js";
-import { BoxLayoutSpec } from "./layout/BoxLayoutSpec.js";
-import { ConnectedBoxLayouter } from "./layout/ConnectedBoxLayouter.js";
-import { ConnectionEndpointLayoutSpec } from "./layout/ConnectionEndpointLayoutSpec.js";
-import { ConnectionLayoutSpec } from "./layout/ConnectionLayoutSpec.js";
+import AABB2 from "../../../geom/2d/aabb/AABB2.js";
+
+import { ConnectionVisualData } from "./ConnectionVisualData.js";
+import { layout_build_problem } from "./layout/layout_build_problem.js";
+import { layout_node_graph, layout_route_node_graph } from "./layout/layout_node_graph.js";
+import { NodeGraphLayoutOptions } from "./layout/NodeGraphLayoutOptions.js";
 import { NodeVisualData } from "./NodeVisualData.js";
 
+/**
+ * Colour a data type is drawn in when nothing has been registered for it.
+ *
+ * A graph is usable before anyone has chosen a palette for it, and a type added to a registry after
+ * the fact should not take the editor down — so an unstyled type is neutral grey rather than
+ * undefined. Callers draw with what they are given and do not check.
+ *
+ * @readonly
+ * @type {Color}
+ */
+export const NODE_GRAPH_DEFAULT_DATA_COLOR = Object.freeze(new Color(0.72, 0.74, 0.78));
+
+/**
+ * What {@link NodeGraphVisualData#layout} uses when the caller expresses no preference.
+ *
+ * Shared rather than constructed per call: it is read-only to the layout, and a caller who wants
+ * different numbers passes their own.
+ *
+ * @readonly
+ * @type {NodeGraphLayoutOptions}
+ */
+const DEFAULT_LAYOUT_OPTIONS = new NodeGraphLayoutOptions();
+
+/**
+ * @type {AABB2}
+ */
+const _connection_bounds = new AABB2();
+
 export class NodeGraphVisualData {
 
     /**
@@ -15,6 +44,17 @@ export class NodeGraphVisualData {
      */
     nodes = new Map();
 
+    /**
+     * Path each connection is drawn along, by connection id.
+     *
+     * A connection with no entry here has never been routed and is drawn as a plain curve between
+     * its two ports — which is what a wire the author is in the middle of dragging is, and what
+     * every wire is until the graph is laid out once.
+     *
+     * @type {Map<number, ConnectionVisualData>}
+     */
+    connections = new Map();
+
     /**
      *
      * @type {Map<number, Color>}
@@ -22,11 +62,33 @@ export class NodeGraphVisualData {
     dataColors = new Map();
 
     /**
+     * Grow `result` to cover everything drawn: the nodes, and the wires between them.
+     *
+     * The wires count. A wire routed around the outside of the graph reaches past every node, and a
+     * caller framing the drawing by the nodes alone would cut it off.
      *
      * @param {AABB2} result
      */
     computeBoundingBox(result) {
 
+        this.connections.forEach(connection => {
+
+            if (connection.knot_count === 0) {
+                // nothing drawn, and its empty bounds sit at the origin
+                return;
+            }
+
+            connection.computeBounds(_connection_bounds);
+
+            result._expandToFit(
+                _connection_bounds.x0,
+                _connection_bounds.y0,
+                _connection_bounds.x1,
+                _connection_bounds.y1
+            );
+
+        });
+
         this.nodes.forEach(node => {
 
             /**
@@ -44,129 +106,88 @@ export class NodeGraphVisualData {
     }
 
     /**
+     * Arrange the nodes and route the wires.
+     *
+     * Both halves of the result land here: nodes are moved, and every connection gets a path. See
+     * {@link layout_node_graph} for what it does and why.
      *
      * @param {NodeGraph} graph
+     * @param {NodeGraphLayoutOptions} [options]
+     * @returns {{width: number, height: number, crossings: number}}
      */
-    layout(graph) {
-        //collect node data
-
-        /**
-         *
-         * @type {NodeVisualData[]}
-         */
-        const nodes = [];
-
-        this.nodes.forEach(v => {
-            nodes.push(v);
-        });
-
-        const PADDING = 30;
-
-        const layouter = new ConnectedBoxLayouter();
-
-        /**
-         *
-         * @type {ConnectionLayoutSpec[]}
-         */
-        const connections = [];
-
-        /**
-         *
-         * @type {Map<number, BoxLayoutSpec>}
-         */
-        const node_id_to_box_map = new Map();
-
-        /**
-         *
-         * @type {BoxLayoutSpec[]}
-         */
-        const boxes = nodes.map(v => {
-            const d = v.dimensions;
-
-            const p = d.position;
-            const s = d.size;
-
-            const box = new BoxLayoutSpec();
-
-            box.bounds.set(
-                p.x - PADDING,
-                p.y - PADDING,
-                p.x + s.x + PADDING,
-                p.y + s.y + PADDING
-            );
-
-            node_id_to_box_map.set(v.id, box);
-
-            return box;
-        });
-
-        /**
-         *
-         * @type {HashMap<NodeInstancePortReference,ConnectionEndpointLayoutSpec>}
-         */
-        const endpoints = new HashMap();
-
-        /**
-         *
-         * @param {NodeInstancePortReference} ref
-         */
-        const getEndpointLayoutSpec = (ref) => {
-            const endpoint = endpoints.get(ref);
-
-            if (endpoint !== undefined) {
-                return endpoint;
-            } else {
-
-
-                const r = new ConnectionEndpointLayoutSpec();
-
-                const id = ref.instance.id;
+    layout(graph, options = DEFAULT_LAYOUT_OPTIONS) {
+        return layout_node_graph(graph, this, options);
+    }
 
-                const node_visual_data = this.getNode(id);
-                const port_visual_data = node_visual_data.getPort(ref.port.id);
+    /**
+     * Route the wires again, leaving the nodes where they are.
+     *
+     * What to call after somebody has moved a node by hand. Re-running the whole layout would
+     * rearrange the drawing under them, which is not what moving one node asks for; this finds the
+     * wires their way around where the nodes have actually ended up.
+     *
+     * @param {NodeGraph} graph
+     * @param {NodeGraphLayoutOptions} [options]
+     * @returns {void}
+     */
+    route(graph, options = DEFAULT_LAYOUT_OPTIONS) {
+        layout_route_node_graph(layout_build_problem(graph, this), this, options);
+    }
 
-                const box = node_id_to_box_map.get(id);
+    /**
+     *
+     * @param {number} id connection id
+     * @param {ConnectionVisualData} connection
+     */
+    addConnection(id, connection) {
+        assert.isNumber(id, 'id');
 
-                r.box = box;
-                r.point = port_visual_data.position;
+        connection.id = id;
 
+        this.connections.set(id, connection);
+    }
 
-                endpoints.set(ref, r);
+    /**
+     *
+     * @param {number} id connection id
+     * @returns {ConnectionVisualData|undefined}
+     */
+    getConnection(id) {
+        return this.connections.get(id);
+    }
 
-                return r;
+    /**
+     * Path of a connection, created empty if it has none yet.
+     * @param {number} id connection id
+     * @returns {ConnectionVisualData}
+     */
+    ensureConnection(id) {
+        const existing = this.connections.get(id);
 
-            }
+        if (existing !== undefined) {
+            return existing;
         }
 
-        graph.traverseConnections(connection => {
-            const source = getEndpointLayoutSpec(connection.source);
-            const target = getEndpointLayoutSpec(connection.target);
-
-            const spec = ConnectionLayoutSpec.from(
-                source,
-                target
-            );
-
-            source.box.connections.push(spec);
-            target.box.connections.push(spec);
-
-            connections.push(spec);
-        });
-
-        layouter.initialize(boxes, connections);
-
-        layouter.layout();
+        const created = new ConnectionVisualData();
 
+        created.id = id;
 
-        boxes.forEach((box, i) => {
+        this.connections.set(id, created);
 
-            const bounds = box.bounds;
-
-            const node = nodes[i];
+        return created;
+    }
 
-            node.dimensions.position.set(bounds.x0 + PADDING, bounds.y0 + PADDING);
-            node.dimensions.size.set(bounds.width - PADDING * 2, bounds.height - PADDING * 2);
-        });
+    /**
+     * Forget the path of a connection.
+     *
+     * Connection ids are pooled and re-used, so the path of a deleted connection must not survive
+     * to be drawn for an unrelated future one.
+     *
+     * @param {number} id connection id
+     * @returns {boolean} true if a path was removed
+     */
+    removeConnection(id) {
+        return this.connections.delete(id);
     }
 
     /**
@@ -181,12 +202,25 @@ export class NodeGraphVisualData {
     }
 
     /**
+     * Colour for a data type, or {@link NODE_GRAPH_DEFAULT_DATA_COLOR} when none was registered.
+     *
+     * Never undefined: every caller of this draws with the result, and one that has to guard is one
+     * that will eventually forget to.
      *
      * @param {number} id
      * @returns {Color}
      */
     getDataColor(id) {
-        return this.dataColors.get(id);
+        return this.dataColors.get(id) ?? NODE_GRAPH_DEFAULT_DATA_COLOR;
+    }
+
+    /**
+     * Whether a colour was registered for a data type, as opposed to it falling back to the default.
+     * @param {number} id
+     * @returns {boolean}
+     */
+    hasDataColor(id) {
+        return this.dataColors.has(id);
     }
 
     /**
@@ -274,8 +308,15 @@ export class NodeGraphVisualData {
             dataColors[id] = dataColor.toJSON();
         }
 
+        const connections = {};
+
+        for (const [id, connection] of this.connections) {
+            connections[id] = connection.toJSON();
+        }
+
         return {
             nodes,
+            connections,
             dataColors
         };
     }
@@ -293,6 +334,16 @@ export class NodeGraphVisualData {
             this.nodes.set(node.id, node);
         }
 
+        this.connections.clear();
+
+        for (const prop in json.connections) {
+            const connection = new ConnectionVisualData();
+
+            connection.fromJSON(json.connections[prop]);
+
+            this.connections.set(connection.id, connection);
+        }
+
         this.dataColors.clear();
 
         for (const prop in json.dataColors) {

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

@@ -0,0 +1,162 @@
+/**
+ * A box standing for a node of the graph.
+ * @type {number}
+ */
+export const LAYOUT_BOX_NODE: number;
+/**
+ * A box standing for one column's worth of a wire that is only passing through.
+ *
+ * It is not drawn. Its whole purpose is to occupy room in a column so that the ordering and
+ * coordinate stages leave a lane for the wire, rather than packing the boxes tight and letting the
+ * wire be drawn across them.
+ *
+ * @type {number}
+ */
+export const LAYOUT_BOX_LANE: number;
+/**
+ * The placement problem, flat.
+ *
+ * Boxes and the links between them, and nothing about node graphs: no ports, no data types, no
+ * connection identity. Every placement stage — cycles, layers, ordering, coordinates — reads and
+ * writes this and only this, which is what keeps them testable against a hand-written graph and
+ * reusable for anything else that needs boxes arranged in columns.
+ *
+ * A **link** is one column boundary crossed by one wire. An edge of the source graph that spans
+ * several columns is several links joined by lane boxes, so every link here connects boxes in
+ * adjacent columns and every stage can assume that.
+ *
+ * Links carry the height *within* each box at which they attach, because that is where the wire is
+ * actually drawn and it is not the middle: a node twelve ports tall is joined near its top by one
+ * edge and near its bottom by another, and lining up the two boxes' middles lines up nothing a
+ * reader can see.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class LayoutBoxGraph {
+    /**
+     * @param {number} box_count
+     * @param {number} link_count
+     */
+    constructor(box_count?: number, link_count?: number);
+    /**
+     * @type {number}
+     */
+    box_count: number;
+    /**
+     * Left edge of each box. Written by the coordinate stage.
+     * @type {Float64Array}
+     */
+    box_x: Float64Array;
+    /**
+     * Top edge of each box. Written by the coordinate stage.
+     * @type {Float64Array}
+     */
+    box_y: Float64Array;
+    /**
+     * @type {Float64Array}
+     */
+    box_w: Float64Array;
+    /**
+     * @type {Float64Array}
+     */
+    box_h: Float64Array;
+    /**
+     * Column each box sits in. Written by the layering stage.
+     * @type {Int32Array}
+     */
+    box_layer: Int32Array;
+    /**
+     * One of {@link LAYOUT_BOX_NODE}, {@link LAYOUT_BOX_LANE}.
+     * @type {Uint8Array}
+     */
+    box_kind: Uint8Array;
+    /**
+     * @type {number}
+     */
+    link_count: number;
+    /**
+     * @type {Int32Array}
+     */
+    link_from: Int32Array;
+    /**
+     * @type {Int32Array}
+     */
+    link_to: Int32Array;
+    /**
+     * Offset down the source box at which the link leaves it.
+     * @type {Float64Array}
+     */
+    link_from_y: Float64Array;
+    /**
+     * Offset down the target box at which the link arrives.
+     * @type {Float64Array}
+     */
+    link_to_y: Float64Array;
+    /**
+     * Start of each box's outgoing links in {@link out_link}. Length `box_count + 1`.
+     * @type {Int32Array}
+     */
+    out_offset: Int32Array;
+    /**
+     * @type {Int32Array}
+     */
+    out_link: Int32Array;
+    /**
+     * @type {Int32Array}
+     */
+    in_offset: Int32Array;
+    /**
+     * @type {Int32Array}
+     */
+    in_link: Int32Array;
+    /**
+     * Give the graph a new size, keeping whatever fits.
+     *
+     * Growing happens exactly once, when the number of lane boxes becomes known — the layering
+     * stage settles it, and until then it cannot be predicted. Everything else works in place.
+     *
+     * @param {number} box_count
+     * @param {number} link_count
+     * @returns {void}
+     */
+    resize(box_count: number, link_count: number): void;
+    /**
+     * @param {number} index
+     * @param {number} width
+     * @param {number} height
+     * @param {number} kind
+     * @returns {void}
+     */
+    set_box(index: number, width: number, height: number, kind: number): void;
+    /**
+     * @param {number} index
+     * @param {number} from box
+     * @param {number} to box
+     * @param {number} from_y offset down `from`
+     * @param {number} to_y offset down `to`
+     * @returns {void}
+     */
+    set_link(index: number, from: number, to: number, from_y: number, to_y: number): void;
+    /**
+     * Rebuild the adjacency indices from the link arrays.
+     *
+     * Called after anything that changes the links, and by the stages that walk them. Counting
+     * sort, so it is one pass to count and one to fill and it allocates nothing beyond the two
+     * pairs of arrays it hands back.
+     *
+     * @returns {void}
+     */
+    build_adjacency(): void;
+    /**
+     * @param {number} box
+     * @returns {number}
+     */
+    out_degree(box: number): number;
+    /**
+     * @param {number} box
+     * @returns {number}
+     */
+    in_degree(box: number): number;
+}
+//# sourceMappingURL=LayoutBoxGraph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutBoxGraph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/LayoutBoxGraph.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;;;;;;GAQG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAyFI;;;OAGG;IACH,wBAHW,MAAM,eACN,MAAM,EAIhB;IA7FD;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,OAFU,YAAY,CAEhB;IAEN;;;OAGG;IACH,OAFU,YAAY,CAEhB;IAEN;;OAEG;IACH,OAFU,YAAY,CAEhB;IAEN;;OAEG;IACH,OAFU,YAAY,CAEhB;IAEN;;;OAGG;IACH,WAFU,UAAU,CAEV;IAEV;;;OAGG;IACH,UAFU,UAAU,CAEX;IAET;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,WAFU,UAAU,CAEV;IAEV;;OAEG;IACH,SAFU,UAAU,CAEZ;IAER;;;OAGG;IACH,aAFU,YAAY,CAEV;IAEZ;;;OAGG;IACH,WAFU,YAAY,CAEZ;IAEV;;;OAGG;IACH,YAFU,UAAU,CAET;IAEX;;OAEG;IACH,UAFU,UAAU,CAEX;IAET;;OAEG;IACH,WAFU,UAAU,CAEV;IAEV;;OAEG;IACH,SAFU,UAAU,CAEZ;IAUR;;;;;;;;;OASG;IACH,kBAJW,MAAM,cACN,MAAM,GACJ,IAAI,CAwBhB;IAED;;;;;;OAMG;IACH,eANW,MAAM,SACN,MAAM,UACN,MAAM,QACN,MAAM,GACJ,IAAI,CAMhB;IAED;;;;;;;OAOG;IACH,gBAPW,MAAM,QACN,MAAM,MACN,MAAM,UACN,MAAM,QACN,MAAM,GACJ,IAAI,CAOhB;IAED;;;;;;;;OAQG;IACH,mBAFa,IAAI,CAsChB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}