@woosh/meep-engine 2.169.1 → 2.169.2

package/src/core/geom/vec2/v2_rotate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2_rotate.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec2/v2_rotate.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,kCANW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,iBAClC,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,QAIhB"}

package/src/core/geom/vec2/v2_rotate.js

@@ -0,0 +1,21 @@
+import { v2_rotate_cos_sin } from "./v2_rotate_cos_sin.js";
+
+/**
+ * Rotate a 2d vector around the origin by an angle.
+ *
+ * Before this existed the four-line body was inlined at every site that needed it, which made the
+ * sign convention a copy-paste artifact instead of a documented contract. Keep new callers here.
+ *
+ * The rotation matches the standard 2d rotation matrix `[cos, -sin; sin, cos]`, i.e.
+ * counter-clockwise in a Y-up frame and clockwise in the Y-down frames used by grid/screen space.
+ * Callers own any rounding or snapping of the result.
+ *
+ * @param {Float64Array|Float32Array|number[]} result
+ * @param {number} result_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} angle in radians
+ */
+export function v2_rotate(result, result_offset, x, y, angle) {
+    v2_rotate_cos_sin(result, result_offset, x, y, Math.cos(angle), Math.sin(angle));
+}

package/src/core/geom/vec2/v2_rotate_cos_sin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rotate a 2d vector around the origin, given the cosine and sine of the angle.
+ *
+ * This exists so that a loop rotating many vectors by the *same* angle pays for `Math.cos`/`Math.sin`
+ * once instead of once per vector. Prefer {@link v2_rotate} when only a single vector is rotated.
+ *
+ * The rotation matches the standard 2d rotation matrix
+ * `[cos, -sin; sin, cos]`, i.e. counter-clockwise in a Y-up frame and clockwise in the Y-down
+ * frames used by grid/screen space. Callers own any rounding or snapping of the result.
+ *
+ * @param {Float64Array|Float32Array|number[]} result
+ * @param {number} result_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} cos cosine of the rotation angle
+ * @param {number} sin sine of the rotation angle
+ */
+export function v2_rotate_cos_sin(result: Float64Array | Float32Array | number[], result_offset: number, x: number, y: number, cos: number, sin: number): void;
+//# sourceMappingURL=v2_rotate_cos_sin.d.ts.map

package/src/core/geom/vec2/v2_rotate_cos_sin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2_rotate_cos_sin.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec2/v2_rotate_cos_sin.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,0CAPW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,iBAClC,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,OACN,MAAM,QAKhB"}

package/src/core/geom/vec2/v2_rotate_cos_sin.js

@@ -0,0 +1,21 @@
+/**
+ * Rotate a 2d vector around the origin, given the cosine and sine of the angle.
+ *
+ * This exists so that a loop rotating many vectors by the *same* angle pays for `Math.cos`/`Math.sin`
+ * once instead of once per vector. Prefer {@link v2_rotate} when only a single vector is rotated.
+ *
+ * The rotation matches the standard 2d rotation matrix
+ * `[cos, -sin; sin, cos]`, i.e. counter-clockwise in a Y-up frame and clockwise in the Y-down
+ * frames used by grid/screen space. Callers own any rounding or snapping of the result.
+ *
+ * @param {Float64Array|Float32Array|number[]} result
+ * @param {number} result_offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} cos cosine of the rotation angle
+ * @param {number} sin sine of the rotation angle
+ */
+export function v2_rotate_cos_sin(result, result_offset, x, y, cos, sin) {
+    result[result_offset] = x * cos - y * sin;
+    result[result_offset + 1] = x * sin + y * cos;
+}

package/src/core/graph/csr/csr_graph_from_undirected_edge_list.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Build a symmetric {@link CSRGraph} from an undirected edge list — the producer `core/graph/csr` was
+ * missing.
+ *
+ * WHY this exists: the package ships plenty of CSR *consumers* (`csr_graph_find_edge`,
+ * `csr_graph_build_distance_field`, `csr_graph_find_shortest_path`) but nothing that turns an
+ * `{a[], b[], weights[]}` edge list into one, so every caller re-derived the same three-pass idiom by hand:
+ * count degrees, prefix-sum them into row offsets, then fill both half-edges through a per-vertex write
+ * cursor. It is short but easy to get subtly wrong (forgetting that an undirected edge occupies a slot at
+ * BOTH endpoints, or advancing the cursor for only one of them), and a bug shows up as silently truncated
+ * adjacency rather than a crash.
+ *
+ * Each undirected edge `(a[e], b[e])` contributes a row entry at both endpoints, so
+ * `adjacency_length === 2 · edge_count`. Rows come out SORTED ascending by neighbour id, with
+ * `edge_weights` permuted alongside — the conventional CSR form, which makes the adjacency a canonical
+ * function of the edge SET rather than of the order the edges happened to be appended in, and lets callers
+ * binary-search a row. Degrees in the graphs this serves are small, so the per-row sort is an insertion
+ * sort and costs nothing measurable next to building the edge list itself.
+ *
+ * A self-loop `a[e] === b[e]` would occupy two slots in the same row; callers are expected not to emit one.
+ *
+ * @param {number} vertex_count
+ * @param {ArrayLike<number>} a per-edge first endpoint, each in `[0, vertex_count)`
+ * @param {ArrayLike<number>} b per-edge second endpoint, each in `[0, vertex_count)`; parallel to `a`
+ * @param {ArrayLike<number>} edge_weights per-edge weight, parallel to `a`/`b`; both half-edges get it
+ * @returns {CSRGraph}
+ */
+export function csr_graph_from_undirected_edge_list(vertex_count: number, a: ArrayLike<number>, b: ArrayLike<number>, edge_weights: ArrayLike<number>): CSRGraph;
+import { CSRGraph } from "./CSRGraph.js";
+//# sourceMappingURL=csr_graph_from_undirected_edge_list.d.ts.map

package/src/core/graph/csr/csr_graph_from_undirected_edge_list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csr_graph_from_undirected_edge_list.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/csr/csr_graph_from_undirected_edge_list.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,kEANW,MAAM,KACN,UAAU,MAAM,CAAC,KACjB,UAAU,MAAM,CAAC,gBACjB,UAAU,MAAM,CAAC,GACf,QAAQ,CAiEpB;yBA5FwB,eAAe"}

package/src/core/graph/csr/csr_graph_from_undirected_edge_list.js

@@ -0,0 +1,94 @@
+import { assert } from "../../assert.js";
+import { CSRGraph } from "./CSRGraph.js";
+
+/**
+ * Build a symmetric {@link CSRGraph} from an undirected edge list — the producer `core/graph/csr` was
+ * missing.
+ *
+ * WHY this exists: the package ships plenty of CSR *consumers* (`csr_graph_find_edge`,
+ * `csr_graph_build_distance_field`, `csr_graph_find_shortest_path`) but nothing that turns an
+ * `{a[], b[], weights[]}` edge list into one, so every caller re-derived the same three-pass idiom by hand:
+ * count degrees, prefix-sum them into row offsets, then fill both half-edges through a per-vertex write
+ * cursor. It is short but easy to get subtly wrong (forgetting that an undirected edge occupies a slot at
+ * BOTH endpoints, or advancing the cursor for only one of them), and a bug shows up as silently truncated
+ * adjacency rather than a crash.
+ *
+ * Each undirected edge `(a[e], b[e])` contributes a row entry at both endpoints, so
+ * `adjacency_length === 2 · edge_count`. Rows come out SORTED ascending by neighbour id, with
+ * `edge_weights` permuted alongside — the conventional CSR form, which makes the adjacency a canonical
+ * function of the edge SET rather than of the order the edges happened to be appended in, and lets callers
+ * binary-search a row. Degrees in the graphs this serves are small, so the per-row sort is an insertion
+ * sort and costs nothing measurable next to building the edge list itself.
+ *
+ * A self-loop `a[e] === b[e]` would occupy two slots in the same row; callers are expected not to emit one.
+ *
+ * @param {number} vertex_count
+ * @param {ArrayLike<number>} a per-edge first endpoint, each in `[0, vertex_count)`
+ * @param {ArrayLike<number>} b per-edge second endpoint, each in `[0, vertex_count)`; parallel to `a`
+ * @param {ArrayLike<number>} edge_weights per-edge weight, parallel to `a`/`b`; both half-edges get it
+ * @returns {CSRGraph}
+ */
+export function csr_graph_from_undirected_edge_list(vertex_count, a, b, edge_weights) {
+    assert.isNonNegativeInteger(vertex_count, 'vertex_count');
+    assert.equal(b.length, a.length, 'b.length !== a.length');
+    assert.greaterThanOrEqual(edge_weights.length, a.length, 'edge_weights shorter than the edge list');
+
+    const edge_count = a.length;
+
+    const graph = new CSRGraph(vertex_count, edge_count * 2);
+
+    const edge_addresses = graph.edge_addresses;
+    const adjacency = graph.adjacency;
+    const weights = graph.edge_weights;
+
+    // pass 1 — degree of every vertex (both endpoints of each undirected edge)
+    for (let e = 0; e < edge_count; e++) {
+        edge_addresses[a[e] + 1]++;
+        edge_addresses[b[e] + 1]++;
+    }
+
+    // pass 2 — prefix-sum the degrees into row offsets (edge_addresses[v] is now the start of v's row)
+    for (let v = 0; v < vertex_count; v++) {
+        edge_addresses[v + 1] += edge_addresses[v];
+    }
+
+    // pass 3 — fill both half-edges through a per-vertex write cursor
+    const cursor = edge_addresses.slice(0, vertex_count);
+
+    for (let e = 0; e < edge_count; e++) {
+        const u = a[e];
+        const v = b[e];
+        const w = edge_weights[e];
+
+        adjacency[cursor[u]] = v;
+        weights[cursor[u]] = w;
+        cursor[u]++;
+
+        adjacency[cursor[v]] = u;
+        weights[cursor[v]] = w;
+        cursor[v]++;
+    }
+
+    // pass 4 — canonicalise each row (ascending neighbour id), carrying the weights along
+    for (let v = 0; v < vertex_count; v++) {
+        const start = edge_addresses[v];
+        const end = edge_addresses[v + 1];
+
+        for (let i = start + 1; i < end; i++) {
+            const neighbour = adjacency[i];
+            const weight = weights[i];
+
+            let j = i - 1;
+            while (j >= start && adjacency[j] > neighbour) {
+                adjacency[j + 1] = adjacency[j];
+                weights[j + 1] = weights[j];
+                j--;
+            }
+
+            adjacency[j + 1] = neighbour;
+            weights[j + 1] = weight;
+        }
+    }
+
+    return graph;
+}

package/src/core/graph/layout/CircleLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CircleLayout.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/layout/CircleLayout.js"],"names":[],"mappings":"AAiJA;;;;;GAKG;AACH,yCAJW,MAAM,EAAE,yBAER,OAAO,QAyEjB;AAsBD;;;;GAIG;AACH,kDAHW,MAAM,EAAE,UACR,OAAO,QAcjB;AA2TD,sGAsBC;AA4MD;;;;GAIG;AACH,8CAHW,MAAM,WACN,MAAM,EAAE,QAgBlB;AAED;;;;;GAKG;AACH,4CAJW,MAAM,EAAE,UACR,OAAO,YACP,MAAM,QAkBhB;AAED;;;;;GAKG;AACH,qDAJW,MAAM,WACN,MAAM,EAAE,GACP,MAAM,CA2EjB;mBA55BkB,gCAAgC;oBAG/B,uBAAuB"}
+{"version":3,"file":"CircleLayout.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/layout/CircleLayout.js"],"names":[],"mappings":"AA0HA;;;;;GAKG;AACH,yCAJW,MAAM,EAAE,yBAER,OAAO,QAyEjB;AAsBD;;;;GAIG;AACH,kDAHW,MAAM,EAAE,UACR,OAAO,QAcjB;AA2TD,sGAsBC;AA4MD;;;;GAIG;AACH,8CAHW,MAAM,WACN,MAAM,EAAE,QAgBlB;AAED;;;;;GAKG;AACH,4CAJW,MAAM,EAAE,UACR,OAAO,YACP,MAAM,QAkBhB;AAED;;;;;GAKG;AACH,qDAJW,MAAM,WACN,MAAM,EAAE,GACP,MAAM,CA2EjB;mBAp4BkB,gCAAgC;oBAI/B,uBAAuB"}

package/src/core/graph/layout/CircleLayout.js

@@ -1,8 +1,10 @@
+import { graph_peel_topological_layer } from "./graph_peel_topological_layer.js";
 import { assert } from "../../assert.js";
 import AABB2 from "../../geom/2d/aabb/AABB2.js";
 import Circle from "../../geom/2d/circle/Circle.js";
 import { segment2_intersects_segment2_2d } from "../../geom/2d/line/segment2_intersects_segment2_2d.js";
 import { v2_distance } from "../../geom/vec2/v2_distance.js";
+import { v2_length } from "../../geom/vec2/v2_length.js";
 import Vector2 from "../../geom/Vector2.js";
 import { max2 } from "../../math/max2.js";
 import { min2 } from "../../math/min2.js";
@@ -22,35 +24,10 @@ function doLayerLayout(circles) {
         return b.locked !== true;
     });
 
-    function buildLayer() {
-        const layer = [];
-
-        main_loop:for (let i = remaining.length - 1; i >= 0; i--) {
-            const box = remaining[i];
-            const connections = box.connections;
-
-            for (let j = 0; j < connections.length; j++) {
-                const connection = connections[j];
-
-                const source = connection.source;
-                if (source !== box && remaining.indexOf(source) !== -1) {
-                    //not closed yet
-                    continue main_loop;
-                }
-            }
-
-            remaining.splice(i, 1);
-
-            //all sources are already laid out
-            layer.push(box);
-        }
-
-        return layer;
-    }
 
     let offsetY = 0;
     while (remaining.length > 0) {
-        const layer = buildLayer();
+        const layer = graph_peel_topological_layer(remaining);
 
         if (layer.length === 0) {
             console.error("Layer is empty", remaining, circles, offsetY);
@@ -285,7 +262,7 @@ function applyPull(edges, strength) {
         const dX = x1 - x0;
         const dY = y1 - y0;
 
-        const length = Math.sqrt(dX * dX + dY * dY);
+        const length = v2_length(dX, dY);
 
         const r0 = c0.r;
         const r1 = c1.r;
@@ -742,7 +719,7 @@ function resolveCircleLineOverlap(circle, c0, c1) {
             const ndX = cX - nX;
             const ndY = cY - nY;
 
-            const ncD = Math.sqrt(ndX * ndX + ndY * ndY);
+            const ncD = v2_length(ndX, ndY);
 
             //compute penetration distance
             const penD = r - ncD;
@@ -877,7 +854,7 @@ export function resolveCircleOverlapStep(numCircles, circles) {
             const dx = x1 - x0;
             const dy = y1 - y0;
 
-            const distance = Math.sqrt(dx * dx + dy * dy);
+            const distance = v2_length(dx, dy);
 
             const minSeparation = r0 + r1;
 

package/src/core/graph/layout/box/BoxLayouter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BoxLayouter.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/layout/box/BoxLayouter.js"],"names":[],"mappings":"AAyaA;;;;GAIG;AACH,+CAHW,KAAK,EAAE,UACP,OAAO,QASjB;kBA/aiB,gCAAgC;oBAC9B,0BAA0B;AAub9C;;;;;GAKG;AACH,mCAJW,MAAO,KAAK,CAAC,yBAEb,OAAO,QA0FjB;AArGD,gDAKC"}
+{"version":3,"file":"BoxLayouter.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/layout/box/BoxLayouter.js"],"names":[],"mappings":"AAiZA;;;;GAIG;AACH,+CAHW,KAAK,EAAE,UACP,OAAO,QASjB;kBAtZiB,gCAAgC;oBAC9B,0BAA0B;AA8Z9C;;;;;GAKG;AACH,mCAJW,MAAO,KAAK,CAAC,yBAEb,OAAO,QA0FjB;AArGD,gDAKC"}

package/src/core/graph/layout/box/BoxLayouter.js

@@ -1,3 +1,4 @@
+import { graph_peel_topological_layer } from "../graph_peel_topological_layer.js";
 /**
  *
  * @param {Array.<AABB2>} boxes
@@ -358,35 +359,10 @@ function doLayerLayout(boxes) {
         return b.locked !== true;
     });
 
-    function buildLayer() {
-        const layer = [];
-
-        main_loop:for (let i = remaining.length - 1; i >= 0; i--) {
-            const box = remaining[i];
-            const connections = box.connections;
-
-            for (let j = 0; j < connections.length; j++) {
-                const connection = connections[j];
-
-                const source = connection.source;
-                if (source !== box && remaining.indexOf(source) !== -1) {
-                    //not closed yet
-                    continue main_loop;
-                }
-            }
-
-            remaining.splice(i, 1);
-
-            //all sources are already laid out
-            layer.push(box);
-        }
-
-        return layer;
-    }
 
     let offsetY = 0;
     while (remaining.length > 0) {
-        const layer = buildLayer();
+        const layer = graph_peel_topological_layer(remaining);
 
         if (layer.length === 0) {
             console.error("Layer is empty", remaining, boxes, offsetY);

package/src/core/graph/layout/box/position_box_next_to_box.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position_box_next_to_box.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/layout/box/position_box_next_to_box.js"],"names":[],"mappings":"AA8JA;;;;;;GAMG;AACH,8CALW,KAAK,UACL,KAAK,UACL,KAAK,GACH,KAAK,CAsCjB;kBAzMiB,gCAAgC"}
+{"version":3,"file":"position_box_next_to_box.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/layout/box/position_box_next_to_box.js"],"names":[],"mappings":"AA+JA;;;;;;GAMG;AACH,8CALW,KAAK,UACL,KAAK,UACL,KAAK,GACH,KAAK,CAsCjB;kBAzMiB,gCAAgC"}

package/src/core/graph/layout/box/position_box_next_to_box.js

@@ -1,3 +1,4 @@
+import { v2_length } from "../../../geom/vec2/v2_length.js";
 import AABB2 from "../../../geom/2d/aabb/AABB2.js";
 import Vector2 from "../../../geom/Vector2.js";
 import { EPSILON } from "../../../math/EPSILON.js";
@@ -34,7 +35,7 @@ function compute_initial_placement(
     const targetH = target.height;
     const targetW = target.width;
 
-    const targetDiagonal = Math.sqrt(targetH * targetH + targetW * targetW);
+    const targetDiagonal = v2_length(targetW, targetH);
 
     const boxWidth = box.width;
     const boxHeight = box.height;

package/src/core/graph/layout/computeDisconnectedSubGraphs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computeDisconnectedSubGraphs.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/layout/computeDisconnectedSubGraphs.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oDAHW;IAAC,WAAW,EAAC,YAAY,CAAA;CAAC,EAAE,SAuDtC"}
+{"version":3,"file":"computeDisconnectedSubGraphs.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/layout/computeDisconnectedSubGraphs.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oDAHW;IAAC,WAAW,EAAC,YAAY,CAAA;CAAC,EAAE,SAkEtC"}

package/src/core/graph/layout/computeDisconnectedSubGraphs.js

@@ -8,15 +8,20 @@ export function computeDisconnectedSubGraphs(nodes) {
     //find disconnected sub-graphs
     const unexplored = nodes.slice();
 
+    // Membership mirror. This used to be `unexplored.indexOf(node)` + `splice`, which made the whole
+    // traversal O(n^2). Claimed nodes are now skipped at pop time instead of being spliced out: since
+    // `splice` removed from the middle while `pop` reads from the end, the order of the remaining nodes --
+    // and therefore the sequence of cluster seeds -- is identical either way.
+    const claimed = new Set();
+
     let cursor, i;
 
 
     let currentCluster;
 
     function exploreNode(node) {
-        const i = unexplored.indexOf(node);
-        if (i !== -1) {
-            unexplored.splice(i, 1);
+        if (!claimed.has(node)) {
+            claimed.add(node);
 
             currentCluster.push(node);
         }
@@ -27,6 +32,12 @@ export function computeDisconnectedSubGraphs(nodes) {
     while (unexplored.length > 0) {
         const node = unexplored.pop();
 
+        if (claimed.has(node)) {
+            continue;
+        }
+
+        claimed.add(node);
+
         currentCluster = [node];
 
         cursor = 0;

package/src/core/graph/layout/graph_peel_topological_layer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Peel one topological layer off `remaining`: every node whose incoming connections all originate outside
+ * `remaining` (i.e. from nodes already laid out) is removed from it and returned.
+ *
+ * MUTATES `remaining` — peeled nodes are spliced out, so repeated calls walk the graph layer by layer and
+ * an empty result means the rest of the graph is cyclic.
+ *
+ * Self-connections are ignored, so a node pointing at itself does not block its own layer.
+ *
+ * Pure graph topology, no geometry: shared verbatim by the box and circle layouters, which each held an
+ * identical private copy closed over their own `remaining`.
+ *
+ * @template {{ connections: Array<{ source: * }> }} T
+ * @param {T[]} remaining nodes not yet laid out; mutated
+ * @returns {T[]} the peeled layer, empty when nothing can be peeled
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_peel_topological_layer<T extends {
+    connections: Array<{
+        source: any;
+    }>;
+}>(remaining: T[]): T[];
+//# sourceMappingURL=graph_peel_topological_layer.d.ts.map

package/src/core/graph/layout/graph_peel_topological_layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_peel_topological_layer.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/layout/graph_peel_topological_layer.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH;iBAP6B,MAAM;QAAE,MAAM,MAAG;KAAE,CAAC;wBAgChD"}

package/src/core/graph/layout/graph_peel_topological_layer.js

@@ -0,0 +1,45 @@
+/**
+ * Peel one topological layer off `remaining`: every node whose incoming connections all originate outside
+ * `remaining` (i.e. from nodes already laid out) is removed from it and returned.
+ *
+ * MUTATES `remaining` — peeled nodes are spliced out, so repeated calls walk the graph layer by layer and
+ * an empty result means the rest of the graph is cyclic.
+ *
+ * Self-connections are ignored, so a node pointing at itself does not block its own layer.
+ *
+ * Pure graph topology, no geometry: shared verbatim by the box and circle layouters, which each held an
+ * identical private copy closed over their own `remaining`.
+ *
+ * @template {{ connections: Array<{ source: * }> }} T
+ * @param {T[]} remaining nodes not yet laid out; mutated
+ * @returns {T[]} the peeled layer, empty when nothing can be peeled
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_peel_topological_layer(remaining) {
+    const layer = [];
+
+    main_loop: for (let i = remaining.length - 1; i >= 0; i--) {
+        const node = remaining[i];
+        const connections = node.connections;
+
+        for (let j = 0; j < connections.length; j++) {
+            const connection = connections[j];
+
+            const source = connection.source;
+
+            if (source !== node && remaining.indexOf(source) !== -1) {
+                // a source is still pending, so this node is not ready for this layer
+                continue main_loop;
+            }
+        }
+
+        remaining.splice(i, 1);
+
+        // all sources are already laid out
+        layer.push(node);
+    }
+
+    return layer;
+}

package/src/core/math/hash/hash_mix2.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Combine two integer hashes into one, using the classic `h * 31 + x` step truncated to int32.
+ *
+ * This is the canonical two-value mixer. Prefer it over {@link combine_hash} on any path that runs more
+ * than occasionally: `combine_hash` is varargs and therefore allocates a rest array per call, whereas this
+ * is allocation-free and monomorphic.
+ *
+ * Both `(a << 5) - a + b` and `a * 31 + b` spellings appear in the codebase and agree once truncated —
+ * `a * 31 + b` stays exact in a double for int32 inputs (31 * 2^31 is well under 2^53), so the trailing
+ * `| 0` reduces both mod 2^32 identically. The spelling is unified here so the truncation cannot be
+ * forgotten, which is how {@link Vector2#hash} came to return a non-int32.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} int32
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function hash_mix2(a: number, b: number): number;
+//# sourceMappingURL=hash_mix2.d.ts.map

package/src/core/math/hash/hash_mix2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash_mix2.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/hash_mix2.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,6BAPW,MAAM,KACN,MAAM,GACJ,MAAM,CAOlB"}

package/src/core/math/hash/hash_mix2.js

@@ -0,0 +1,22 @@
+/**
+ * Combine two integer hashes into one, using the classic `h * 31 + x` step truncated to int32.
+ *
+ * This is the canonical two-value mixer. Prefer it over {@link combine_hash} on any path that runs more
+ * than occasionally: `combine_hash` is varargs and therefore allocates a rest array per call, whereas this
+ * is allocation-free and monomorphic.
+ *
+ * Both `(a << 5) - a + b` and `a * 31 + b` spellings appear in the codebase and agree once truncated —
+ * `a * 31 + b` stays exact in a double for int32 inputs (31 * 2^31 is well under 2^53), so the trailing
+ * `| 0` reduces both mod 2^32 identically. The spelling is unified here so the truncation cannot be
+ * forgotten, which is how {@link Vector2#hash} came to return a non-int32.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} int32
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function hash_mix2(a, b) {
+    return (a * 31 + b) | 0;
+}

package/src/core/math/hash/hash_mix3.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Combine three integer hashes into one. Left-folded {@link hash_mix2}, so
+ * `hash_mix3(a, b, c) === hash_mix2(hash_mix2(a, b), c)`.
+ *
+ * Allocation-free, unlike the varargs {@link combine_hash}.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {number} int32
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function hash_mix3(a: number, b: number, c: number): number;
+//# sourceMappingURL=hash_mix3.d.ts.map

package/src/core/math/hash/hash_mix3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash_mix3.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/hash_mix3.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,6BARW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAOlB"}

package/src/core/math/hash/hash_mix3.js

@@ -0,0 +1,19 @@
+import { hash_mix2 } from "./hash_mix2.js";
+
+/**
+ * Combine three integer hashes into one. Left-folded {@link hash_mix2}, so
+ * `hash_mix3(a, b, c) === hash_mix2(hash_mix2(a, b), c)`.
+ *
+ * Allocation-free, unlike the varargs {@link combine_hash}.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {number} int32
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function hash_mix3(a, b, c) {
+    return hash_mix2(hash_mix2(a, b), c);
+}

package/src/core/math/lookup/LUT_HEATMAP.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canonical 6-stop "cold to hot" heatmap ramp, RGBA in 0..255, uniformly spaced across `[0,1]`:
+ * black → blue → teal → green → yellow → red.
+ *
+ * This exists so that every debug/diagnostic overlay in the engine reads the same colours; before
+ * it the identical six rows were declared independently by the terrain overlay painter and the
+ * forward+ froxel debug grid, and a palette tweak in one made the two disagree.
+ *
+ * Write mode is disabled, so the shared instance cannot be mutated by a consumer — build your own
+ * {@link ParameterLookupTable} if you need a different ramp.
+ *
+ * @readonly
+ * @type {ParameterLookupTable}
+ */
+export const LUT_HEATMAP: ParameterLookupTable;
+import { ParameterLookupTable } from "./ParameterLookupTable.js";
+//# sourceMappingURL=LUT_HEATMAP.d.ts.map

package/src/core/math/lookup/LUT_HEATMAP.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LUT_HEATMAP.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/lookup/LUT_HEATMAP.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,0BAFU,oBAAoB,CAEyB;qCAhBlB,2BAA2B"}

package/src/core/math/lookup/LUT_HEATMAP.js

@@ -0,0 +1,30 @@
+import { ParameterLookupTable } from "./ParameterLookupTable.js";
+
+/**
+ * Canonical 6-stop "cold to hot" heatmap ramp, RGBA in 0..255, uniformly spaced across `[0,1]`:
+ * black → blue → teal → green → yellow → red.
+ *
+ * This exists so that every debug/diagnostic overlay in the engine reads the same colours; before
+ * it the identical six rows were declared independently by the terrain overlay painter and the
+ * forward+ froxel debug grid, and a palette tweak in one made the two disagree.
+ *
+ * Write mode is disabled, so the shared instance cannot be mutated by a consumer — build your own
+ * {@link ParameterLookupTable} if you need a different ramp.
+ *
+ * @readonly
+ * @type {ParameterLookupTable}
+ */
+export const LUT_HEATMAP = new ParameterLookupTable(4);
+
+LUT_HEATMAP.write([
+    0, 0, 0, 255,
+    0, 0, 255, 255,
+    0, 179, 179, 255,
+    0, 255, 0, 255,
+    255, 255, 0, 255,
+    255, 5, 5, 255
+]);
+
+LUT_HEATMAP.computeUniformPositions();
+
+LUT_HEATMAP.disableWriteMode();

package/src/core/math/noise/curl_noise_3d.d.ts

@@ -1,4 +1,10 @@
 /**
+ * Divergence-free 3D curl noise.
+ *
+ * This is the time-independent face of {@link curl_noise_3dt}: sampling the animated field at `w = 0`.
+ * `0` is a real point on the time axis, not a sentinel. The three decorrelation offsets that separate the
+ * potential-field components live in `curl_noise_3dt` only — duplicating them here meant retuning one
+ * field silently decorrelated it from the other.
  *
  * @param {number[]} result
  * @param {number} x

package/src/core/math/noise/curl_noise_3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"curl_noise_3d.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/noise/curl_noise_3d.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,sCALW,MAAM,EAAE,KACR,MAAM,KACN,MAAM,KACN,MAAM,QAchB"}
+{"version":3,"file":"curl_noise_3d.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/noise/curl_noise_3d.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,sCALW,MAAM,EAAE,KACR,MAAM,KACN,MAAM,KACN,MAAM,QAIhB"}