@woosh/meep-engine 2.155.0 → 2.157.0

package/src/core/math/physics/mie/ri_soot.js

@@ -1,6 +1,4 @@
-import {
-    ParameterLookupTable
-} from "../../../../engine/graphics/particles/particular/engine/parameter/ParameterLookupTable.js";
+import { ParameterLookupTable } from "../../lookup/ParameterLookupTable.js";
 
 /**
  * Complex refractive index of soot (black carbon): n + i k, wavelength in nm.

package/src/core/math/physics/mie/ri_water.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ri_water.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/physics/mie/ri_water.js"],"names":[],"mappings":"AA4IA;;;;GAIG;AACH,iCAHW,MAAM,EAAE,iBACR,MAAM,QAIhB"}
+{"version":3,"file":"ri_water.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/physics/mie/ri_water.js"],"names":[],"mappings":"AA0IA;;;;GAIG;AACH,iCAHW,MAAM,EAAE,iBACR,MAAM,QAIhB"}

package/src/core/math/physics/mie/ri_water.js

@@ -1,6 +1,4 @@
-import {
-    ParameterLookupTable
-} from "../../../../engine/graphics/particles/particular/engine/parameter/ParameterLookupTable.js";
+import { ParameterLookupTable } from "../../lookup/ParameterLookupTable.js";
 
 /**
  * Refractive index of pure liquid water (n + i k), wavelength in nm.

package/src/core/math/random/randomIntegerBetween.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"randomIntegerBetween.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/random/randomIntegerBetween.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,4DAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAclB"}
+{"version":3,"file":"randomIntegerBetween.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/random/randomIntegerBetween.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,4DAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAiBlB"}

package/src/core/math/random/randomIntegerBetween.js

@@ -18,5 +18,8 @@ export function randomIntegerBetween(random, min, max) {
     assert.greaterThanOrEqual(roll, 0, 'random should return value between 0 and 1');
     assert.lessThanOrEqual(roll, 1, 'random should return value between 0 and 1');
 
-    return Math.round(roll * span) + min;
+    // Inclusive AND uniform: give each of the (span + 1) integers an equal-width slice of [0, 1).
+    // Math.round(roll * span) would halve the probability of the two endpoints. random() may return
+    // exactly 1.0, which would overshoot by one, so clamp the top.
+    return Math.min(max, min + Math.floor(roll * (span + 1)));
 }

package/src/core/math/random/random_pick_weighted_index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pick an index at random, weighted by a cumulative (prefix-sum) weight array.
+ *
+ * @param {function():number} random RNG returning values in [0, 1)
+ * @param {number[]} cumulativeWeights cumulativeWeights[i] = sum of weights of entries 0..i; non-decreasing
+ * @param {number} count number of valid entries in the array
+ * @returns {number} picked index, or -1 when the total weight is not positive (the RNG is not consumed)
+ */
+export function random_pick_weighted_index(random: () => number, cumulativeWeights: number[], count: number): number;
+//# sourceMappingURL=random_pick_weighted_index.d.ts.map

package/src/core/math/random/random_pick_weighted_index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random_pick_weighted_index.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/random/random_pick_weighted_index.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,yDALsB,MAAM,qBACjB,MAAM,EAAE,SACR,MAAM,GACJ,MAAM,CAgBlB"}

package/src/core/math/random/random_pick_weighted_index.js

@@ -0,0 +1,26 @@
+import { binarySearchHighIndex } from "../../collection/array/binarySearchHighIndex.js";
+import { number_compare_ascending } from "../../primitives/numbers/number_compare_ascending.js";
+
+/**
+ * Pick an index at random, weighted by a cumulative (prefix-sum) weight array.
+ *
+ * @param {function():number} random RNG returning values in [0, 1)
+ * @param {number[]} cumulativeWeights cumulativeWeights[i] = sum of weights of entries 0..i; non-decreasing
+ * @param {number} count number of valid entries in the array
+ * @returns {number} picked index, or -1 when the total weight is not positive (the RNG is not consumed)
+ */
+export function random_pick_weighted_index(random, cumulativeWeights, count) {
+    if (count <= 0) {
+        return -1;
+    }
+
+    const totalWeight = cumulativeWeights[count - 1];
+
+    if (totalWeight <= 0) {
+        return -1;
+    }
+
+    const targetWeight = random() * totalWeight;
+
+    return binarySearchHighIndex(cumulativeWeights, targetWeight, number_compare_ascending, 0, count - 1);
+}

package/src/core/math/solveCubic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solveCubic.d.ts","sourceRoot":"","sources":["../../../../src/core/math/solveCubic.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,mCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA+DlB"}
+{"version":3,"file":"solveCubic.d.ts","sourceRoot":"","sources":["../../../../src/core/math/solveCubic.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,mCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA4ElB"}

package/src/core/math/solveCubic.js

@@ -1,82 +1,95 @@
-import { assert } from "../assert.js";
-import { EPSILON } from "./EPSILON.js";
-import { solveQuadratic } from "./solveQuadratic.js";
-
-const ONE_THIRD = 1.0 / 3.0;
-const TWO_THIRDS_PI = 2.0 * Math.PI / 3.0;
-
-/**
- * Return real solutions for a cubic polynomial: ax³ + bx² + cx + d
- * Repeated roots are written once each — multiplicity is not duplicated in the output.
- * Imaginary roots are not provided.
- *
- * @param {number[]|Float32Array|Float64Array} result solutions are written here
- * @param {number} result_offset offset into result array where solutions are written to
- * @param {number} a
- * @param {number} b
- * @param {number} c
- * @param {number} d
- * @returns {number} number of real roots found (0, 1, 2, or 3)
- */
-export function solveCubic(result, result_offset, a, b, c, d) {
-    assert.isNumber(a, 'a');
-    assert.isNumber(b, 'b');
-    assert.isNumber(c, 'c');
-    assert.isNumber(d, 'd');
-
-    if (Math.abs(a) < EPSILON) {
-        // degrade to quadratic
-        return solveQuadratic(result, result_offset, b, c, d);
-    }
-
-    // normalize: x³ + B·x² + C·x + D = 0
-    const inv_a = 1 / a;
-    const B = b * inv_a;
-    const C = c * inv_a;
-    const D = d * inv_a;
-
-    // depress via x = y - B/3 → y³ + p·y + q = 0
-    const B_third = B * ONE_THIRD;
-    const p = C - B * B_third;
-    const q = 2 * B_third * B_third * B_third - C * B_third + D;
-
-    if (Math.abs(p) < EPSILON && Math.abs(q) < EPSILON) {
-        // triple root at y = 0
-        result[result_offset] = -B_third;
-        return 1;
-    }
-
-    // Cardano's discriminant criterion. ratio = (q/2)² + (p/3)³.
-    //   ratio > 0  → one real root, two complex
-    //   ratio = 0  → repeated real roots (single + double, or triple covered above)
-    //   ratio < 0  → three distinct real roots
-    const half_q = q * 0.5;
-    const third_p = p * ONE_THIRD;
-    const ratio = half_q * half_q + third_p * third_p * third_p;
-
-    if (ratio > EPSILON) {
-        const sqrt_ratio = Math.sqrt(ratio);
-        const u = Math.cbrt(-half_q + sqrt_ratio);
-        const v = Math.cbrt(-half_q - sqrt_ratio);
-
-        result[result_offset] = u + v - B_third;
-        return 1;
-    }
-
-    if (ratio < -EPSILON) {
-        // p must be negative for ratio < 0; sqrt(-p/3) is real
-        const m = 2 * Math.sqrt(-third_p);
-        const theta_third = ONE_THIRD * Math.acos(3 * q / (p * m));
-
-        result[result_offset]     = m * Math.cos(theta_third) - B_third;
-        result[result_offset + 1] = m * Math.cos(theta_third - TWO_THIRDS_PI) - B_third;
-        result[result_offset + 2] = m * Math.cos(theta_third - 2 * TWO_THIRDS_PI) - B_third;
-        return 3;
-    }
-
-    // ratio ≈ 0: simple + double root
-    const u = Math.cbrt(-half_q);
-    result[result_offset]     = 2 * u - B_third;
-    result[result_offset + 1] = -u - B_third;
-    return 2;
-}
+import { assert } from "../assert.js";
+import { EPSILON } from "./EPSILON.js";
+import { solveQuadratic } from "./solveQuadratic.js";
+
+const ONE_THIRD = 1.0 / 3.0;
+const TWO_THIRDS_PI = 2.0 * Math.PI / 3.0;
+
+/**
+ * Return real solutions for a cubic polynomial: ax³ + bx² + cx + d
+ * Repeated roots are written once each — multiplicity is not duplicated in the output.
+ * Imaginary roots are not provided.
+ *
+ * @param {number[]|Float32Array|Float64Array} result solutions are written here
+ * @param {number} result_offset offset into result array where solutions are written to
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @returns {number} number of real roots found (0, 1, 2, or 3)
+ */
+export function solveCubic(result, result_offset, a, b, c, d) {
+    assert.isNumber(a, 'a');
+    assert.isNumber(b, 'b');
+    assert.isNumber(c, 'c');
+    assert.isNumber(d, 'd');
+
+    if (Math.abs(a) < EPSILON) {
+        // degrade to quadratic
+        return solveQuadratic(result, result_offset, b, c, d);
+    }
+
+    // normalize: x³ + B·x² + C·x + D = 0
+    const inv_a = 1 / a;
+    const B = b * inv_a;
+    const C = c * inv_a;
+    const D = d * inv_a;
+
+    // depress via x = y - B/3 → y³ + p·y + q = 0
+    const B_third = B * ONE_THIRD;
+    const p = C - B * B_third;
+    const q = 2 * B_third * B_third * B_third - C * B_third + D;
+
+    // Scale-invariant triple-root test. p has the units of root² and q of root³, so compare each against the
+    // coefficient scale raised to the matching power. An absolute `< EPSILON` test wrongly classified cubics
+    // whose roots are merely small (p and q tiny in absolute terms but the roots well separated) as a triple
+    // root. Exact p === 0 && q === 0 still passes here, routing to the triple-root branch.
+    const coeff_scale = Math.max(1, Math.abs(B));
+    if (
+        Math.abs(p) < EPSILON * coeff_scale * coeff_scale
+        && Math.abs(q) < EPSILON * coeff_scale * coeff_scale * coeff_scale
+    ) {
+        // triple root at y = 0
+        result[result_offset] = -B_third;
+        return 1;
+    }
+
+    // Cardano's discriminant criterion. ratio = (q/2)² + (p/3)³.
+    //   ratio > 0  → one real root, two complex
+    //   ratio = 0  → repeated real roots (single + double, or triple covered above)
+    //   ratio < 0  → three distinct real roots
+    const half_q = q * 0.5;
+    const third_p = p * ONE_THIRD;
+    const ratio = half_q * half_q + third_p * third_p * third_p;
+
+    // Relative dead-band: ratio has the units of root⁶, exactly like its two constituent terms. An absolute
+    // EPSILON band dropped a real root for small-magnitude roots (ratio tiny but genuinely non-zero); scale the
+    // tolerance by the magnitude of the constituent terms instead.
+    const ratio_tol = EPSILON * Math.max(half_q * half_q, Math.abs(third_p * third_p * third_p));
+
+    if (ratio > ratio_tol) {
+        const sqrt_ratio = Math.sqrt(ratio);
+        const u = Math.cbrt(-half_q + sqrt_ratio);
+        const v = Math.cbrt(-half_q - sqrt_ratio);
+
+        result[result_offset] = u + v - B_third;
+        return 1;
+    }
+
+    if (ratio < -ratio_tol) {
+        // p must be negative for ratio < 0; sqrt(-p/3) is real
+        const m = 2 * Math.sqrt(-third_p);
+        const theta_third = ONE_THIRD * Math.acos(3 * q / (p * m));
+
+        result[result_offset]     = m * Math.cos(theta_third) - B_third;
+        result[result_offset + 1] = m * Math.cos(theta_third - TWO_THIRDS_PI) - B_third;
+        result[result_offset + 2] = m * Math.cos(theta_third - 2 * TWO_THIRDS_PI) - B_third;
+        return 3;
+    }
+
+    // ratio ≈ 0: simple + double root
+    const u = Math.cbrt(-half_q);
+    result[result_offset]     = 2 * u - B_third;
+    result[result_offset + 1] = -u - B_third;
+    return 2;
+}

package/src/core/math/spline/computeCatmullRomSplineUniformDistance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computeCatmullRomSplineUniformDistance.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/computeCatmullRomSplineUniformDistance.js"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,+DAPW,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,cACN,MAAM,gBACN,MAAM,UACN,MAAM,QAuFhB"}
+{"version":3,"file":"computeCatmullRomSplineUniformDistance.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/computeCatmullRomSplineUniformDistance.js"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,+DAPW,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,cACN,MAAM,gBACN,MAAM,UACN,MAAM,QAoGhB"}

package/src/core/math/spline/computeCatmullRomSplineUniformDistance.js

@@ -69,6 +69,19 @@ export function computeCatmullRomSplineUniformDistance(result, input, input_leng
 
     const step_distance = distances_sum / (sample_count - 1);
 
+    if (!(step_distance > 0)) {
+        // Degenerate input. When the total path length is 0 (all control points coincide) step_distance is 0,
+        // which would make the sampling loop below spin forever (next_point_distance never advances). When
+        // sample_count < 2 it is Infinity/NaN. In every such case collapse all requested samples onto the first
+        // input point. The `!(step_distance > 0)` test also covers NaN and -0. Note: when sample_count is 0 this
+        // loop is a no-op, which is the correct (empty) result.
+        for (let i = 0; i < sample_count; i++) {
+            array_copy(input, 0, result, i * dimensions, dimensions);
+        }
+
+        return;
+    }
+
     let cursor_index = 0;
 
     let current_input_distance = 0;

package/src/core/math/statistics/softmax.js

@@ -14,7 +14,7 @@ export function softmax(z, i, k) {
     // NOTE that if we want to compute softmax for an entire vector, it could be far more efficient
     let sum = 0;
 
-    for (let j = 1; j < k; j++) {
+    for (let j = 0; j < k; j++) {
 
         sum += Math.exp(z[j]);
 

package/src/core/model/node-graph/NodeGraph.d.ts

@@ -210,6 +210,15 @@ export class NodeGraph {
      * @throws if any node or port are not found
      */
     createConnection(sourceNode: number, sourcePort: number, targetNode: number, targetPort: number): number;
+    /**
+     * Add an existing connection object to the graph. Counterpart of {@link #addNode}.
+     * Useful for re-attaching a previously deleted connection while preserving its identity,
+     * such as during UNDO/REDO.
+     * NOTE: both endpoint nodes must already be part of the graph
+     * @param {Connection} connection
+     * @returns {number} ID of the connection
+     */
+    addConnection(connection: Connection): number;
     /**
      *
      * @param {number} id

package/src/core/model/node-graph/NodeGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/node-graph/NodeGraph.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IAEI;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,6BAAyB;IAEzB;;;;;OAKG;IACH,4BAA0B;IAE1B;;;;;OAKG;IACH,kCAAgC;IAQhC;;;;;OAKG;IACH,+BAEC;IAED;;OAEG;IACH;QACI;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;MAEL;IAEF;;OAEG;IACH,cAQC;IAED;;;OAGG;IACH,YAFW,SAAS,QAYnB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;;;OAMG;IACH,aAHW,SAAS,GACP;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAe5D;IAED;;;;;;;;OAQG;IACH,sCAJW,YAAY,EAAE,GAEZ;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAmF5D;IAED;;;;OAIG;IACH,8BAHoB,YAAY,+BAK/B;IAED;;;;OAIG;IACH,oCAHoB,UAAU,+BAK7B;IAED;;;;OAIG;IACH,YAFY,YAAY,EAAE,CAIzB;IAED;;;;OAIG;IACH,kBAFY,UAAU,EAAE,CAIvB;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAgBnB;IAED;;;;OAIG;IACH,qDAFa,YAAY,EAAE,CAsB1B;IAED;;;;OAIG;IACH,0DAFa,YAAY,EAAE,CAqB1B;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAkBlC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,GACJ,YAAY,CAWxB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,UAAU,GAAC,SAAS,CAgBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,WACN,MAAM,GACJ,4BAA0B,SAAS,CAY/C;IAED;;;;OAIG;IACH,mCAFa,MAAM,CAclB;IAED;;;OAGG;IACH,cAFW,YAAY,QAkBtB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqClB;IAED;;;;;;;;OAQG;IACH,6BAPW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CAyBnB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CAyBlB;IAED,mBAEC;IAGL;;;;;;;;OAQG;IACH,sBAFU,OAAO,CAEc;;CAX9B;6BA1qB4B,wBAAwB;2BAD1B,iBAAiB"}
+{"version":3,"file":"NodeGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/node-graph/NodeGraph.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IAEI;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,6BAAyB;IAEzB;;;;;OAKG;IACH,4BAA0B;IAE1B;;;;;OAKG;IACH,kCAAgC;IAQhC;;;;;OAKG;IACH,+BAEC;IAED;;OAEG;IACH;QACI;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;MAEL;IAEF;;OAEG;IACH,cAQC;IAED;;;OAGG;IACH,YAFW,SAAS,QAYnB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;;;OAMG;IACH,aAHW,SAAS,GACP;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAe5D;IAED;;;;;;;;OAQG;IACH,sCAJW,YAAY,EAAE,GAEZ;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAmF5D;IAED;;;;OAIG;IACH,8BAHoB,YAAY,+BAK/B;IAED;;;;OAIG;IACH,oCAHoB,UAAU,+BAK7B;IAED;;;;OAIG;IACH,YAFY,YAAY,EAAE,CAIzB;IAED;;;;OAIG;IACH,kBAFY,UAAU,EAAE,CAIvB;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAgBnB;IAED;;;;OAIG;IACH,qDAFa,YAAY,EAAE,CAsB1B;IAED;;;;OAIG;IACH,0DAFa,YAAY,EAAE,CAqB1B;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAkBlC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,GACJ,YAAY,CAWxB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,UAAU,GAAC,SAAS,CAgBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,WACN,MAAM,GACJ,4BAA0B,SAAS,CAY/C;IAED;;;;OAIG;IACH,mCAFa,MAAM,CAclB;IAED;;;OAGG;IACH,cAFW,YAAY,QAkBtB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqClB;IAED;;;;;;;;OAQG;IACH,6BAPW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;;;;OAOG;IACH,0BAHW,UAAU,GACR,MAAM,CA2BlB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CA4BnB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CAyBlB;IAED,mBAEC;IAGL;;;;;;;;OAQG;IACH,sBAFU,OAAO,CAEc;;CAX9B;6BAhtB4B,wBAAwB;2BAD1B,iBAAiB"}

package/src/core/model/node-graph/NodeGraph.js

@@ -622,6 +622,41 @@ export class NodeGraph {
         return id;
     }
 
+    /**
+     * Add an existing connection object to the graph. Counterpart of {@link #addNode}.
+     * Useful for re-attaching a previously deleted connection while preserving its identity,
+     * such as during UNDO/REDO.
+     * NOTE: both endpoint nodes must already be part of the graph
+     * @param {Connection} connection
+     * @returns {number} ID of the connection
+     */
+    addConnection(connection) {
+        assert.defined(connection, 'connection');
+        assert.notNull(connection, 'connection');
+
+        const id_obtained = this.__idpConnections.getSpecific(connection.id);
+
+        if (id_obtained === false) {
+            throw new Error(`Connection with id '${connection.id}' already exists`);
+        }
+
+        const sourceEndpoint = connection.source;
+        const targetEndpoint = connection.target;
+
+        this.connections.add(connection);
+
+        // add connection links to the nodes
+        sourceEndpoint.instance.connections.addUnique(connection);
+        targetEndpoint.instance.connections.addUnique(connection);
+
+        array_push_if_unique(sourceEndpoint.connections, connection);
+        array_push_if_unique(targetEndpoint.connections, connection);
+
+        this.#version++;
+
+        return connection.id;
+    }
+
     /**
      *
      * @param {number} id
@@ -647,6 +682,9 @@ export class NodeGraph {
         array_remove_first(sourceEndpoint.connections, connection);
         array_remove_first(targetEndpoint.connections, connection);
 
+        //release id, mirroring deleteNode
+        this.__idpConnections.release(id);
+
         this.#version++;
 
         return true;

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

@@ -37,14 +37,38 @@ export class NodeGraphVisualData {
      * @param {NodeVisualData} node
      */
     addNode(id: number, node: NodeVisualData): void;
+    /**
+     * Remove visual data of a node.
+     * Node IDs are pooled and may be re-used; visual data of a deleted node must not
+     * survive to be picked up by an unrelated future node.
+     * @param {number} id
+     * @returns {boolean} true if removed, false if no data existed
+     */
+    removeNode(id: number): boolean;
     /**
      *
      * @param {number} id
      * @returns {NodeVisualData|undefined}
      */
     getNode(id: number): NodeVisualData | undefined;
+    /**
+     * Ensure visual data exists for a node instance, generating it from the registry when missing
+     * @param {NodeInstance} node
+     * @param {NodeDescriptionVisualRegistry} registry
+     * @returns {NodeVisualData}
+     * @throws when the node's description has no visual data in the registry
+     */
+    ensureNode(node: NodeInstance, registry: NodeDescriptionVisualRegistry): NodeVisualData;
+    /**
+     * Ensure visual data exists for every node of the graph.
+     * Makes {@link #layout} and serialization independent of any view having been built.
+     * @param {NodeGraph} graph
+     * @param {NodeDescriptionVisualRegistry} registry
+     */
+    ensure(graph: NodeGraph, registry: NodeDescriptionVisualRegistry): void;
     toJSON(): {
         nodes: {};
+        dataColors: {};
     };
     fromJSON(json: any): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"NodeGraphVisualData.d.ts","sourceRoot":"","sources":["../../../../../../src/core/model/node-graph/visual/NodeGraphVisualData.js"],"names":[],"mappings":"AASA;IAEI;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE,cAAc,CAAC,CAEnB;IAElB;;;OAGG;IACH,YAFU,IAAI,MAAM,EAAE,KAAK,CAAC,CAEL;IAEvB;;;OAGG;IACH,wCAgBC;IAED;;;OAGG;IACH,+BAwHC;IAED;;;;OAIG;IACH,iBAHW,MAAM,SACN,KAAK,QAMf;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAIjB;IAED;;;;OAIG;IACH,YAHW,MAAM,QACN,cAAc,QAIxB;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,cAAc,GAAC,SAAS,CAIpC;IAED;;MAgBC;IAED,0BA0BC;CACJ;+BAvP8B,qBAAqB;sBAL9B,yBAAyB"}
+{"version":3,"file":"NodeGraphVisualData.d.ts","sourceRoot":"","sources":["../../../../../../src/core/model/node-graph/visual/NodeGraphVisualData.js"],"names":[],"mappings":"AASA;IAEI;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE,cAAc,CAAC,CAEnB;IAElB;;;OAGG;IACH,YAFU,IAAI,MAAM,EAAE,KAAK,CAAC,CAEL;IAEvB;;;OAGG;IACH,wCAgBC;IAED;;;OAGG;IACH,+BAwHC;IAED;;;;OAIG;IACH,iBAHW,MAAM,SACN,KAAK,QAMf;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAIjB;IAED;;;;OAIG;IACH,YAHW,MAAM,QACN,cAAc,QAIxB;IAED;;;;;;OAMG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,cAAc,GAAC,SAAS,CAIpC;IAED;;;;;;OAMG;IACH,yEAHa,cAAc,CAyB1B;IAED;;;;;OAKG;IACH,wEAIC;IAED;;;MAiBC;IAED,0BA0BC;CACJ;+BA9S8B,qBAAqB;sBAL9B,yBAAyB"}

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

@@ -198,6 +198,17 @@ export class NodeGraphVisualData {
         this.nodes.set(id, node);
     }
 
+    /**
+     * Remove visual data of a node.
+     * Node IDs are pooled and may be re-used; visual data of a deleted node must not
+     * survive to be picked up by an unrelated future node.
+     * @param {number} id
+     * @returns {boolean} true if removed, false if no data existed
+     */
+    removeNode(id) {
+        return this.nodes.delete(id);
+    }
+
     /**
      *
      * @param {number} id
@@ -207,6 +218,49 @@ export class NodeGraphVisualData {
         return this.nodes.get(id);
     }
 
+    /**
+     * Ensure visual data exists for a node instance, generating it from the registry when missing
+     * @param {NodeInstance} node
+     * @param {NodeDescriptionVisualRegistry} registry
+     * @returns {NodeVisualData}
+     * @throws when the node's description has no visual data in the registry
+     */
+    ensureNode(node, registry) {
+        const existing = this.nodes.get(node.id);
+
+        if (existing !== undefined) {
+            return existing;
+        }
+
+        const description = node.description;
+
+        const prototype = registry.get(description.id);
+
+        if (prototype === undefined) {
+            throw new Error(`Node (name='${description.name}', id=${description.id}) not found in registry`);
+        }
+
+        const visual = prototype.clone();
+
+        visual.id = node.id;
+
+        this.nodes.set(node.id, visual);
+
+        return visual;
+    }
+
+    /**
+     * Ensure visual data exists for every node of the graph.
+     * Makes {@link #layout} and serialization independent of any view having been built.
+     * @param {NodeGraph} graph
+     * @param {NodeDescriptionVisualRegistry} registry
+     */
+    ensure(graph, registry) {
+        graph.traverseNodes(node => {
+            this.ensureNode(node, registry);
+        });
+    }
+
     toJSON() {
         const nodes = {};
 
@@ -221,7 +275,8 @@ export class NodeGraphVisualData {
         }
 
         return {
-            nodes
+            nodes,
+            dataColors
         };
     }
 

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

@@ -64,6 +64,6 @@ export class NodeVisualData {
     fromJSON(json) {
         this.id = json.id;
         this.dimensions.fromJSON(json.dimensions);
-        this.ports.fromJSON(json, PortVisualData);
+        this.ports.fromJSON(json.ports, PortVisualData);
     }
 }

package/src/core/model/object/ImmutableObjectPool.d.ts

@@ -44,6 +44,13 @@ export class ImmutableObjectPool<Key, Value> {
      */
     size: number;
     get(key: any): Value;
+    /**
+     * Detach an element from the global eviction list, keeping the head/tail pointers consistent.
+     * Does NOT touch the per-key bucket, size, or the onRemoved signal.
+     * @param {CacheElement<Key,Value>} el
+     * @private
+     */
+    private __unlinkFromList;
     /**
      * Removed all elements from cache
      * NOTE: {@link onRemoved} signal *does* get triggered for each element

package/src/core/model/object/ImmutableObjectPool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImmutableObjectPool.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/object/ImmutableObjectPool.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAyBI;;;OAoBC;IA5CD;;;OAGG;IACH,oBAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEH;IACxB;;;OAGG;IACH,MAFU,QAAQ,GAAG,EAAE,aAAa,GAAG,EAAC,KAAK,CAAC,EAAE,CAAC,CAE5B;IAErB;;;;OAIG;IACH,gBAAe;IACf;;;;OAIG;IACH,eAAc;IAKV;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,MAAM,CAEoB;IAEpC;;;OAGG;IACH,MAFU,MAAM,CAEH;IAGjB,qBAuBC;IAED;;;OAGG;IACH,cAIC;IAED;;;;OAIG;IACH,wBA0BC;IAED,mCA2CC;CACJ;mBApKkB,+BAA+B;wBAD1B,iCAAiC;6BAD5B,6BAA6B"}
+{"version":3,"file":"ImmutableObjectPool.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/object/ImmutableObjectPool.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAyBI;;;OAoBC;IA5CD;;;OAGG;IACH,oBAFU,OAAO,GAAG,EAAC,KAAK,CAAC,CAEH;IACxB;;;OAGG;IACH,MAFU,QAAQ,GAAG,EAAE,aAAa,GAAG,EAAC,KAAK,CAAC,EAAE,CAAC,CAE5B;IAErB;;;;OAIG;IACH,gBAAe;IACf;;;;OAIG;IACH,eAAc;IAKV;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,MAAM,CAEoB;IAEpC;;;OAGG;IACH,MAFU,MAAM,CAEH;IAGjB,qBAuBC;IAED;;;;;OAKG;IACH,yBAUC;IAED;;;OAGG;IACH,cAIC;IAED;;;;OAIG;IACH,wBAkBC;IAED,mCA2CC;CACJ;mBA9KkB,+BAA+B;wBAD1B,iCAAiC;6BAD5B,6BAA6B"}

package/src/core/model/object/ImmutableObjectPool.js

@@ -70,13 +70,31 @@ export class ImmutableObjectPool {
             this.data.delete(key);
         }
 
-        element.unlink();
+        this.__unlinkFromList(element);
 
         this.size--;
 
         return element.value;
     }
 
+    /**
+     * Detach an element from the global eviction list, keeping the head/tail pointers consistent.
+     * Does NOT touch the per-key bucket, size, or the onRemoved signal.
+     * @param {CacheElement<Key,Value>} el
+     * @private
+     */
+    __unlinkFromList(el) {
+        if (el === this.__first) {
+            this.__first = el.next;
+        }
+
+        if (el === this.__last) {
+            this.__last = el.previous;
+        }
+
+        el.unlink();
+    }
+
     /**
      * Removed all elements from cache
      * NOTE: {@link onRemoved} signal *does* get triggered for each element
@@ -93,15 +111,7 @@ export class ImmutableObjectPool {
      * @private
      */
     __removeElement(el) {
-        if (el === this.__first) {
-            this.__first = el.next;
-        }
-
-        if (el === this.__last) {
-            this.__last = el.previous;
-        }
-
-        el.unlink();
+        this.__unlinkFromList(el);
 
         const key = el.key;
 

package/src/core/model/reactive/evaluation/MultiPredicateEvaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MultiPredicateEvaluator.d.ts","sourceRoot":"","sources":["../../../../../../src/core/model/reactive/evaluation/MultiPredicateEvaluator.js"],"names":[],"mappings":"AAuGA;;GAEG;AACH;IACI;;;OAGG;IACH,4DAFwC,MAAM,EA4E7C;IAzEG;;;OAGG;IACH,+CAFwC,MAAM,CAER;IAEtC;;;OAGG;IACH,YAFU,oBAAoB,CAEV;IAEpB;;;OAGG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;OAIG;IACH,iCAA4C;IAE5C;;;OAGG;IACH,aAFU,MAAM,CAEe;IAG/B;;;;OAIG;IACH,+BAA2C;IAE3C;;;;OAIG;IACH,iCAAkC;IAElC;;;;OAIG;IACH,sCAAuC;IAEvC;;;;OAIG;IACH,kBAAmB;IAEnB;;;;OAIG;IACH,oBAAoB;IAEpB;;;;OAIG;IACH,0BAA0B;IAG9B;;;OAGG;IACH,kBAFW,oBAAoB,QAsC9B;IAED;;;;;;OAMG;IACH,2BAuCC;IAED;;;;;OAKG;IACH,uBAiCC;IAED;;;;OAIG;IACH,0BAcC;IAED;;;;;OAKG;IACH,uBA2FC;IAGD,+BAOC;IAED,iBAEC;IAED;;OAEG;IACH,QAFa,qBAAmB,SAAS,CA4BxC;CACJ;uBAjesB,2BAA2B"}
+{"version":3,"file":"MultiPredicateEvaluator.d.ts","sourceRoot":"","sources":["../../../../../../src/core/model/reactive/evaluation/MultiPredicateEvaluator.js"],"names":[],"mappings":"AAuGA;;GAEG;AACH;IACI;;;OAGG;IACH,4DAFwC,MAAM,EA4E7C;IAzEG;;;OAGG;IACH,+CAFwC,MAAM,CAER;IAEtC;;;OAGG;IACH,YAFU,oBAAoB,CAEV;IAEpB;;;OAGG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;OAIG;IACH,iCAA4C;IAE5C;;;OAGG;IACH,aAFU,MAAM,CAEe;IAG/B;;;;OAIG;IACH,+BAA2C;IAE3C;;;;OAIG;IACH,iCAAkC;IAElC;;;;OAIG;IACH,sCAAuC;IAEvC;;;;OAIG;IACH,kBAAmB;IAEnB;;;;OAIG;IACH,oBAAoB;IAEpB;;;;OAIG;IACH,0BAA0B;IAG9B;;;OAGG;IACH,kBAFW,oBAAoB,QAsC9B;IAED;;;;;;OAMG;IACH,2BAuCC;IAED;;;;;OAKG;IACH,uBAiCC;IAED;;;;OAIG;IACH,0BAcC;IAED;;;;;OAKG;IACH,uBAgIC;IAGD,+BAOC;IAED,iBAEC;IAED;;OAEG;IACH,QAFa,qBAAmB,SAAS,CA4BxC;CACJ;uBAtgBsB,2BAA2B"}