@woosh/meep-engine 3.43.0 → 3.45.0

package/src/core/geom/3d/quaternion/quat3_multiply_conjugate_left_array.js

@@ -0,0 +1,30 @@
+/**
+ * Hamilton product with the left operand conjugated, `out = a* ⊗ b`, both read from arrays.
+ *
+ * For unit quaternions the conjugate is the inverse, so this is `a⁻¹ ⊗ b`: the rotation `b` expressed
+ * in the frame `a` rotates into — a world orientation written in a parent's or a body's frame. Callers
+ * used to build `a*` in a scratch array and hand it to {@link quat3_multiply_array}; the conjugate's
+ * signs are folded into the product here instead, so there is no scratch and no extra pass.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and the rest of the
+ * `core/geom/3d/quaternion/` family.
+ *
+ * `out` may be `a` or `b`: all eight components are read before the first write.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number[]|Float32Array|Float64Array} a `[x, y, z, w]`, the operand that is conjugated
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b `[x, y, z, w]`
+ * @param {number} b_offset
+ */
+export function quat3_multiply_conjugate_left_array(out, out_offset, a, a_offset, b, b_offset) {
+    const ax = a[a_offset], ay = a[a_offset + 1], az = a[a_offset + 2], aw = a[a_offset + 3];
+    const bx = b[b_offset], by = b[b_offset + 1], bz = b[b_offset + 2], bw = b[b_offset + 3];
+
+    // quat3_multiply with (ax, ay, az) negated
+    out[out_offset]     = aw * bx - ax * bw - ay * bz + az * by;
+    out[out_offset + 1] = aw * by + ax * bz - ay * bw - az * bx;
+    out[out_offset + 2] = aw * bz - ax * by + ay * bx - az * bw;
+    out[out_offset + 3] = aw * bw + ax * bx + ay * by + az * bz;
+}

package/src/core/geom/3d/quaternion/quat3_multiply_conjugate_right_array.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Hamilton product with the right operand conjugated, `out = a ⊗ b*`, both read from arrays.
+ *
+ * For unit quaternions the conjugate is the inverse, so this is `a ⊗ b⁻¹`: the world-frame rotation
+ * that takes orientation `b` to orientation `a` — the turn a holder made since a hold began, the
+ * rotation a body must make to reach a target. Callers used to build `b*` in a scratch array, or pass
+ * its components negated, to {@link quat3_multiply_array}; the conjugate's signs are folded into the
+ * product here instead.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and the rest of the
+ * `core/geom/3d/quaternion/` family.
+ *
+ * `out` may be `a` or `b`: all eight components are read before the first write.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number[]|Float32Array|Float64Array} a `[x, y, z, w]`
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b `[x, y, z, w]`, the operand that is conjugated
+ * @param {number} b_offset
+ */
+export function quat3_multiply_conjugate_right_array(out: number[] | Float32Array | Float64Array, out_offset: number, a: number[] | Float32Array | Float64Array, a_offset: number, b: number[] | Float32Array | Float64Array, b_offset: number): void;
+//# sourceMappingURL=quat3_multiply_conjugate_right_array.d.ts.map

package/src/core/geom/3d/quaternion/quat3_multiply_conjugate_right_array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quat3_multiply_conjugate_right_array.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_multiply_conjugate_right_array.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,0DAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,QAWhB"}

package/src/core/geom/3d/quaternion/quat3_multiply_conjugate_right_array.js

@@ -0,0 +1,31 @@
+/**
+ * Hamilton product with the right operand conjugated, `out = a ⊗ b*`, both read from arrays.
+ *
+ * For unit quaternions the conjugate is the inverse, so this is `a ⊗ b⁻¹`: the world-frame rotation
+ * that takes orientation `b` to orientation `a` — the turn a holder made since a hold began, the
+ * rotation a body must make to reach a target. Callers used to build `b*` in a scratch array, or pass
+ * its components negated, to {@link quat3_multiply_array}; the conjugate's signs are folded into the
+ * product here instead.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and the rest of the
+ * `core/geom/3d/quaternion/` family.
+ *
+ * `out` may be `a` or `b`: all eight components are read before the first write.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number[]|Float32Array|Float64Array} a `[x, y, z, w]`
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b `[x, y, z, w]`, the operand that is conjugated
+ * @param {number} b_offset
+ */
+export function quat3_multiply_conjugate_right_array(out, out_offset, a, a_offset, b, b_offset) {
+    const ax = a[a_offset], ay = a[a_offset + 1], az = a[a_offset + 2], aw = a[a_offset + 3];
+    const bx = b[b_offset], by = b[b_offset + 1], bz = b[b_offset + 2], bw = b[b_offset + 3];
+
+    // quat3_multiply with (bx, by, bz) negated
+    out[out_offset]     = ax * bw - aw * bx - ay * bz + az * by;
+    out[out_offset + 1] = ay * bw - aw * by + ax * bz - az * bx;
+    out[out_offset + 2] = az * bw - aw * bz - ax * by + ay * bx;
+    out[out_offset + 3] = aw * bw + ax * bx + ay * by + az * bz;
+}

package/src/core/geom/3d/triangle/tri3_compute_normal_area_weighted_array.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The face normal of triangle `abc`, NOT normalised: the raw cross product `(c − b) × (a − b)`, whose
+ * magnitude is twice the triangle's area and whose direction follows the counter-clockwise winding
+ * `a → b → c`, the same winding {@link tri3_compute_normal} uses.
+ *
+ * The magnitude is the point. A pass that accumulates one normal per incident face and normalises at
+ * the end wants each face to pull in proportion to how much surface it is, so that a sliver beside a
+ * large face hardly moves the result and retriangulating the same surface does not change it. A
+ * triangle with no area contributes a zero vector, which is the right vote for nothing, where a
+ * normalising helper has to invent some unit vector.
+ *
+ * Each corner is its own array and offset, so corners may live in one shared position buffer
+ * (`positions, index * 3`) or anywhere else. `out` may alias any of them.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number[]|Float32Array|Float64Array} a
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b
+ * @param {number} b_offset
+ * @param {number[]|Float32Array|Float64Array} c
+ * @param {number} c_offset
+ * @returns {void}
+ */
+export function tri3_compute_normal_area_weighted_array(out: number[] | Float32Array | Float64Array, out_offset: number, a: number[] | Float32Array | Float64Array, a_offset: number, b: number[] | Float32Array | Float64Array, b_offset: number, c: number[] | Float32Array | Float64Array, c_offset: number): void;
+//# sourceMappingURL=tri3_compute_normal_area_weighted_array.d.ts.map

package/src/core/geom/3d/triangle/tri3_compute_normal_area_weighted_array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tri3_compute_normal_area_weighted_array.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/triangle/tri3_compute_normal_area_weighted_array.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6DAVW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,GACJ,IAAI,CAuBhB"}

package/src/core/geom/3d/triangle/tri3_compute_normal_area_weighted_array.js

@@ -0,0 +1,46 @@
+/**
+ * The face normal of triangle `abc`, NOT normalised: the raw cross product `(c − b) × (a − b)`, whose
+ * magnitude is twice the triangle's area and whose direction follows the counter-clockwise winding
+ * `a → b → c`, the same winding {@link tri3_compute_normal} uses.
+ *
+ * The magnitude is the point. A pass that accumulates one normal per incident face and normalises at
+ * the end wants each face to pull in proportion to how much surface it is, so that a sliver beside a
+ * large face hardly moves the result and retriangulating the same surface does not change it. A
+ * triangle with no area contributes a zero vector, which is the right vote for nothing, where a
+ * normalising helper has to invent some unit vector.
+ *
+ * Each corner is its own array and offset, so corners may live in one shared position buffer
+ * (`positions, index * 3`) or anywhere else. `out` may alias any of them.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number[]|Float32Array|Float64Array} a
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b
+ * @param {number} b_offset
+ * @param {number[]|Float32Array|Float64Array} c
+ * @param {number} c_offset
+ * @returns {void}
+ */
+export function tri3_compute_normal_area_weighted_array(
+    out, out_offset,
+    a, a_offset,
+    b, b_offset,
+    c, c_offset
+) {
+    const bx = b[b_offset];
+    const by = b[b_offset + 1];
+    const bz = b[b_offset + 2];
+
+    const cb_x = c[c_offset] - bx;
+    const cb_y = c[c_offset + 1] - by;
+    const cb_z = c[c_offset + 2] - bz;
+
+    const ab_x = a[a_offset] - bx;
+    const ab_y = a[a_offset + 1] - by;
+    const ab_z = a[a_offset + 2] - bz;
+
+    out[out_offset] = cb_y * ab_z - cb_z * ab_y;
+    out[out_offset + 1] = cb_z * ab_x - cb_x * ab_z;
+    out[out_offset + 2] = cb_x * ab_y - cb_y * ab_x;
+}

package/src/core/geom/vec3/v3_distance_array.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Euclidean distance between two 3-vectors stored in arrays.
+ *
+ * @param {number[]|Float32Array|Float64Array} a
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b
+ * @param {number} b_offset
+ * @returns {number}
+ */
+export function v3_distance_array(a: number[] | Float32Array | Float64Array, a_offset: number, b: number[] | Float32Array | Float64Array, b_offset: number): number;
+//# sourceMappingURL=v3_distance_array.d.ts.map

package/src/core/geom/vec3/v3_distance_array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_distance_array.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_distance_array.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qCANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,KACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,YAClC,MAAM,GACJ,MAAM,CAWlB"}

package/src/core/geom/vec3/v3_distance_array.js

@@ -0,0 +1,19 @@
+/**
+ * Euclidean distance between two 3-vectors stored in arrays.
+ *
+ * @param {number[]|Float32Array|Float64Array} a
+ * @param {number} a_offset
+ * @param {number[]|Float32Array|Float64Array} b
+ * @param {number} b_offset
+ * @returns {number}
+ */
+export function v3_distance_array(
+    a, a_offset,
+    b, b_offset
+) {
+    const dx = b[b_offset] - a[a_offset];
+    const dy = b[b_offset + 1] - a[a_offset + 1];
+    const dz = b[b_offset + 2] - a[a_offset + 2];
+
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}

package/src/core/geom/vec3/v3_normalize_array_checked.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalise a vector, reporting whether it had a direction to normalise.
+ *
+ * Unlike {@link v3_normalize_array}, which passes a zero vector through and scales anything else, a
+ * vector whose squared length is below `epsilon_sqr` is refused: `false` is returned and `output` is
+ * not written at all, so with `output === input` the vector is left as it was. A vector that short
+ * has a direction made of rounding, and a caller that builds a rotation from it wants to know.
+ *
+ * So is a vector with no finite squared length — a NaN component, an infinite one, or one so long
+ * its square overflows — since none of those leaves a unit vector to write.
+ *
+ * `output` may alias `input`.
+ *
+ * @param {number[]|Float32Array|Float64Array} output
+ * @param {number} output_offset
+ * @param {number[]|Float32Array|Float64Array} input
+ * @param {number} input_offset
+ * @param {number} epsilon_sqr squared length below which the vector has no direction; positive, since at
+ * zero a zero vector would pass and normalise to NaN
+ * @returns {boolean} true when `output` received the unit vector, false when it was not written
+ */
+export function v3_normalize_array_checked(output: number[] | Float32Array | Float64Array, output_offset: number, input: number[] | Float32Array | Float64Array, input_offset: number, epsilon_sqr: number): boolean;
+//# sourceMappingURL=v3_normalize_array_checked.d.ts.map

package/src/core/geom/vec3/v3_normalize_array_checked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_normalize_array_checked.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_normalize_array_checked.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,mDARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gBAClC,MAAM,eACN,MAAM,GAEJ,OAAO,CA2BnB"}

package/src/core/geom/vec3/v3_normalize_array_checked.js

@@ -0,0 +1,49 @@
+import { assert } from "../../assert.js";
+
+/**
+ * Normalise a vector, reporting whether it had a direction to normalise.
+ *
+ * Unlike {@link v3_normalize_array}, which passes a zero vector through and scales anything else, a
+ * vector whose squared length is below `epsilon_sqr` is refused: `false` is returned and `output` is
+ * not written at all, so with `output === input` the vector is left as it was. A vector that short
+ * has a direction made of rounding, and a caller that builds a rotation from it wants to know.
+ *
+ * So is a vector with no finite squared length — a NaN component, an infinite one, or one so long
+ * its square overflows — since none of those leaves a unit vector to write.
+ *
+ * `output` may alias `input`.
+ *
+ * @param {number[]|Float32Array|Float64Array} output
+ * @param {number} output_offset
+ * @param {number[]|Float32Array|Float64Array} input
+ * @param {number} input_offset
+ * @param {number} epsilon_sqr squared length below which the vector has no direction; positive, since at
+ * zero a zero vector would pass and normalise to NaN
+ * @returns {boolean} true when `output` received the unit vector, false when it was not written
+ */
+export function v3_normalize_array_checked(
+    output, output_offset,
+    input, input_offset,
+    epsilon_sqr
+) {
+    assert.greaterThan(epsilon_sqr, 0, 'epsilon_sqr');
+
+    const x = input[input_offset];
+    const y = input[input_offset + 1];
+    const z = input[input_offset + 2];
+
+    const length_sqr = x * x + y * y + z * z;
+
+    // Written so that NaN, which fails every comparison, lands on the refusing side.
+    if (!(length_sqr >= epsilon_sqr && length_sqr < Infinity)) {
+        return false;
+    }
+
+    const inverse = 1 / Math.sqrt(length_sqr);
+
+    output[output_offset] = x * inverse;
+    output[output_offset + 1] = y * inverse;
+    output[output_offset + 2] = z * inverse;
+
+    return true;
+}

package/src/core/geom/vec3/v3_reject_array.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Vector rejection: the part of `v` square to the unit vector `n`, `v − (v·n) n`. Equivalently, `v`
+ * projected onto the plane through the origin whose normal is `n`.
+ *
+ * `n` must be of unit length; nothing here normalises it. `output` may alias `input` or `normal`.
+ *
+ * @param {number[]|Float32Array|Float64Array} output
+ * @param {number} output_offset
+ * @param {number[]|Float32Array|Float64Array} input `v`
+ * @param {number} input_offset
+ * @param {number[]|Float32Array|Float64Array} normal `n`, unit length
+ * @param {number} normal_offset
+ */
+export function v3_reject_array(output: number[] | Float32Array | Float64Array, output_offset: number, input: number[] | Float32Array | Float64Array, input_offset: number, normal: number[] | Float32Array | Float64Array, normal_offset: number): void;
+//# sourceMappingURL=v3_reject_array.d.ts.map

package/src/core/geom/vec3/v3_reject_array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3_reject_array.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_reject_array.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wCAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gBAClC,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,QAoBhB"}

package/src/core/geom/vec3/v3_reject_array.js

@@ -0,0 +1,32 @@
+/**
+ * Vector rejection: the part of `v` square to the unit vector `n`, `v − (v·n) n`. Equivalently, `v`
+ * projected onto the plane through the origin whose normal is `n`.
+ *
+ * `n` must be of unit length; nothing here normalises it. `output` may alias `input` or `normal`.
+ *
+ * @param {number[]|Float32Array|Float64Array} output
+ * @param {number} output_offset
+ * @param {number[]|Float32Array|Float64Array} input `v`
+ * @param {number} input_offset
+ * @param {number[]|Float32Array|Float64Array} normal `n`, unit length
+ * @param {number} normal_offset
+ */
+export function v3_reject_array(
+    output, output_offset,
+    input, input_offset,
+    normal, normal_offset
+) {
+    const x = input[input_offset];
+    const y = input[input_offset + 1];
+    const z = input[input_offset + 2];
+
+    const nx = normal[normal_offset];
+    const ny = normal[normal_offset + 1];
+    const nz = normal[normal_offset + 2];
+
+    const d = x * nx + y * ny + z * nz;
+
+    output[output_offset] = x - d * nx;
+    output[output_offset + 1] = y - d * ny;
+    output[output_offset + 2] = z - d * nz;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Group the indices of a key array by key, as CSR: for every bucket `k`, the items
+ * `out_items[out_offset[k] .. out_offset[k + 1])` are the indices `i` with `keys[i] === k`, in ascending order.
+ *
+ * This is the counting sort behind every "which rows touch this vertex" table — count each key into
+ * `out_offset[k + 1]`, prefix-sum, then scatter each index through a per-bucket cursor. A key array with a
+ * fixed arity (two vertices per edge, three per triangle) is passed flat, and an item is then the flat index
+ * `element · arity + slot`; a caller that wants the element divides by the arity. Ascending order within a
+ * bucket is what makes the result a function of the keys alone, and what lets a consumer walking a bucket
+ * read its elements' tables forwards.
+ *
+ * A negative key is skipped: it is in no bucket and its index appears nowhere — the form a parent array takes
+ * at its roots.
+ *
+ * Allocation-free: `out_offset` itself is the scatter cursor. After the scatter every `out_offset[k]` has
+ * advanced to the start of bucket `k + 1`, so one shift down by a slot restores the starts.
+ *
+ * @param {Int32Array|Uint32Array|number[]} out_offset written whole, `bucket_count + 1` entries; the last is the
+ *   number of items written
+ * @param {Int32Array|Uint32Array|number[]} out_items at least as long as the number of non-negative keys
+ * @param {ArrayLike<number>} keys bucket of each index, in `[0, bucket_count)`, or negative for none
+ * @param {number} key_count how many leading entries of `keys` to group
+ * @param {number} bucket_count
+ */
+export function csr_build_incidence(out_offset: Int32Array | Uint32Array | number[], out_items: Int32Array | Uint32Array | number[], keys: ArrayLike<number>, key_count: number, bucket_count: number): void;
+//# sourceMappingURL=csr_build_incidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csr_build_incidence.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/csr/csr_build_incidence.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,gDAPW,UAAU,GAAC,WAAW,GAAC,MAAM,EAAE,aAE/B,UAAU,GAAC,WAAW,GAAC,MAAM,EAAE,QAC/B,UAAU,MAAM,CAAC,aACjB,MAAM,gBACN,MAAM,QA8ChB"}

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

@@ -0,0 +1,71 @@
+import { assert } from "../../assert.js";
+
+/**
+ * Group the indices of a key array by key, as CSR: for every bucket `k`, the items
+ * `out_items[out_offset[k] .. out_offset[k + 1])` are the indices `i` with `keys[i] === k`, in ascending order.
+ *
+ * This is the counting sort behind every "which rows touch this vertex" table — count each key into
+ * `out_offset[k + 1]`, prefix-sum, then scatter each index through a per-bucket cursor. A key array with a
+ * fixed arity (two vertices per edge, three per triangle) is passed flat, and an item is then the flat index
+ * `element · arity + slot`; a caller that wants the element divides by the arity. Ascending order within a
+ * bucket is what makes the result a function of the keys alone, and what lets a consumer walking a bucket
+ * read its elements' tables forwards.
+ *
+ * A negative key is skipped: it is in no bucket and its index appears nowhere — the form a parent array takes
+ * at its roots.
+ *
+ * Allocation-free: `out_offset` itself is the scatter cursor. After the scatter every `out_offset[k]` has
+ * advanced to the start of bucket `k + 1`, so one shift down by a slot restores the starts.
+ *
+ * @param {Int32Array|Uint32Array|number[]} out_offset written whole, `bucket_count + 1` entries; the last is the
+ *   number of items written
+ * @param {Int32Array|Uint32Array|number[]} out_items at least as long as the number of non-negative keys
+ * @param {ArrayLike<number>} keys bucket of each index, in `[0, bucket_count)`, or negative for none
+ * @param {number} key_count how many leading entries of `keys` to group
+ * @param {number} bucket_count
+ */
+export function csr_build_incidence(out_offset, out_items, keys, key_count, bucket_count) {
+    assert.isNonNegativeInteger(key_count, 'key_count');
+    assert.isNonNegativeInteger(bucket_count, 'bucket_count');
+    assert.greaterThanOrEqual(out_offset.length, bucket_count + 1, 'out_offset shorter than bucket_count + 1');
+    assert.greaterThanOrEqual(keys.length, key_count, 'keys shorter than key_count');
+
+    for (let k = 0; k <= bucket_count; k++) {
+        out_offset[k] = 0;
+    }
+
+    for (let i = 0; i < key_count; i++) {
+        const key = keys[i];
+
+        if (key < 0) {
+            continue;
+        }
+
+        assert.lessThan(key, bucket_count, 'key out of range');
+
+        out_offset[key + 1]++;
+    }
+
+    for (let k = 0; k < bucket_count; k++) {
+        out_offset[k + 1] += out_offset[k];
+    }
+
+    assert.greaterThanOrEqual(out_items.length, out_offset[bucket_count], 'out_items shorter than the item count');
+
+    // `out_offset[k]` is bucket `k`'s write cursor; it ends at the start of bucket `k + 1`
+    for (let i = 0; i < key_count; i++) {
+        const key = keys[i];
+
+        if (key < 0) {
+            continue;
+        }
+
+        out_items[out_offset[key]++] = i;
+    }
+
+    for (let k = bucket_count; k > 0; k--) {
+        out_offset[k] = out_offset[k - 1];
+    }
+
+    out_offset[0] = 0;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Greedy graph colouring over a CSR adjacency: visit the vertices in `order`, and give each the lowest colour
+ * none of its already-coloured neighbours holds.
+ *
+ * Greedy colouring is order-sensitive, and the order is the caller's — Welsh–Powell's largest-degree-first
+ * is the usual choice, and the reason it is a parameter rather than a policy. For a given order the result
+ * is fully determined: the order of neighbours within a row, and duplicate entries in a row, do not change
+ * it. A vertex's colour is at most its degree, so the colour count is at most the largest degree plus one.
+ *
+ * Works on the raw CSR arrays rather than a {@link CSRGraph}, so any row-pointer/column-index pair can be
+ * coloured without being copied into one; for a `CSRGraph` pass `graph.edge_addresses, graph.adjacency`.
+ * A self-loop is ignored, since a vertex is uncoloured while its own colour is being chosen.
+ *
+ * Allocation-free per call, beyond growing the module scratch to `vertex_count + 1`; not reentrant.
+ *
+ * @param {Uint32Array|Int32Array|number[]} out_colors colour of every vertex, written for `[0, vertex_count)`
+ * @param {Uint32Array|Int32Array|ArrayLike<number>} edge_addresses row offsets, `vertex_count + 1` entries
+ * @param {Uint32Array|Int32Array|ArrayLike<number>} adjacency neighbour ids, rows
+ *   `adjacency[edge_addresses[v] .. edge_addresses[v + 1])`
+ * @param {ArrayLike<number>} order a permutation of `[0, vertex_count)`, the visit order
+ * @param {number} vertex_count
+ * @returns {number} number of colours used; colours are `[0, count)`
+ */
+export function csr_graph_color_greedy(out_colors: Uint32Array | Int32Array | number[], edge_addresses: Uint32Array | Int32Array | ArrayLike<number>, adjacency: Uint32Array | Int32Array | ArrayLike<number>, order: ArrayLike<number>, vertex_count: number): number;
+//# sourceMappingURL=csr_graph_color_greedy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csr_graph_color_greedy.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/csr/csr_graph_color_greedy.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,mDARW,WAAW,GAAC,UAAU,GAAC,MAAM,EAAE,kBAC/B,WAAW,GAAC,UAAU,GAAC,UAAU,MAAM,CAAC,aACxC,WAAW,GAAC,UAAU,GAAC,UAAU,MAAM,CAAC,SAExC,UAAU,MAAM,CAAC,gBACjB,MAAM,GACJ,MAAM,CAmDlB"}

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

@@ -0,0 +1,83 @@
+import { assert } from "../../assert.js";
+
+/**
+ * Per-colour stamp: `MARK[c] === i + 1` while visiting the `i`-th vertex of the order means a neighbour
+ * already holds colour `c`. Module-static and grown on demand; the colouring runs synchronously start to
+ * finish, so reuse is safe.
+ * @type {Uint32Array}
+ */
+let MARK = new Uint32Array(0);
+
+/**
+ * Greedy graph colouring over a CSR adjacency: visit the vertices in `order`, and give each the lowest colour
+ * none of its already-coloured neighbours holds.
+ *
+ * Greedy colouring is order-sensitive, and the order is the caller's — Welsh–Powell's largest-degree-first
+ * is the usual choice, and the reason it is a parameter rather than a policy. For a given order the result
+ * is fully determined: the order of neighbours within a row, and duplicate entries in a row, do not change
+ * it. A vertex's colour is at most its degree, so the colour count is at most the largest degree plus one.
+ *
+ * Works on the raw CSR arrays rather than a {@link CSRGraph}, so any row-pointer/column-index pair can be
+ * coloured without being copied into one; for a `CSRGraph` pass `graph.edge_addresses, graph.adjacency`.
+ * A self-loop is ignored, since a vertex is uncoloured while its own colour is being chosen.
+ *
+ * Allocation-free per call, beyond growing the module scratch to `vertex_count + 1`; not reentrant.
+ *
+ * @param {Uint32Array|Int32Array|number[]} out_colors colour of every vertex, written for `[0, vertex_count)`
+ * @param {Uint32Array|Int32Array|ArrayLike<number>} edge_addresses row offsets, `vertex_count + 1` entries
+ * @param {Uint32Array|Int32Array|ArrayLike<number>} adjacency neighbour ids, rows
+ *   `adjacency[edge_addresses[v] .. edge_addresses[v + 1])`
+ * @param {ArrayLike<number>} order a permutation of `[0, vertex_count)`, the visit order
+ * @param {number} vertex_count
+ * @returns {number} number of colours used; colours are `[0, count)`
+ */
+export function csr_graph_color_greedy(out_colors, edge_addresses, adjacency, order, vertex_count) {
+    assert.isNonNegativeInteger(vertex_count, 'vertex_count');
+    assert.greaterThanOrEqual(order.length, vertex_count, 'order shorter than vertex_count');
+    assert.greaterThanOrEqual(out_colors.length, vertex_count, 'out_colors shorter than vertex_count');
+
+    if (MARK.length < vertex_count + 1) {
+        MARK = new Uint32Array(vertex_count + 1);
+    } else {
+        MARK.fill(0, 0, vertex_count + 1);
+    }
+
+    const mark = MARK;
+
+    // No colour reaches `vertex_count`, so it stands for "not coloured yet" in whatever type the caller's
+    // array is.
+    for (let v = 0; v < vertex_count; v++) {
+        out_colors[v] = vertex_count;
+    }
+
+    let colour_count = 0;
+
+    for (let i = 0; i < vertex_count; i++) {
+        const v = order[i];
+        const stamp = i + 1;
+
+        const end = edge_addresses[v + 1];
+
+        for (let k = edge_addresses[v]; k < end; k++) {
+            const neighbour_colour = out_colors[adjacency[k]];
+
+            if (neighbour_colour < vertex_count) {
+                mark[neighbour_colour] = stamp;
+            }
+        }
+
+        let colour = 0;
+
+        while (mark[colour] === stamp) {
+            colour++;
+        }
+
+        out_colors[v] = colour;
+
+        if (colour >= colour_count) {
+            colour_count = colour + 1;
+        }
+    }
+
+    return colour_count;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Whether a colouring is proper over a CSR adjacency: no vertex shares its colour with any of its neighbours.
+ * A self-loop is not a conflict.
+ *
+ * A debug check, meant to sit behind `assert.*` after a colouring is built; it reads every adjacency entry
+ * once. Works on the raw CSR arrays, like {@link csr_graph_color_greedy}.
+ *
+ * @param {ArrayLike<number>} colors colour of every vertex
+ * @param {ArrayLike<number>} edge_addresses row offsets, `vertex_count + 1` entries
+ * @param {ArrayLike<number>} adjacency neighbour ids
+ * @param {number} vertex_count
+ * @returns {boolean} true when no edge joins two vertices of one colour
+ */
+export function csr_graph_validate_coloring(colors: ArrayLike<number>, edge_addresses: ArrayLike<number>, adjacency: ArrayLike<number>, vertex_count: number): boolean;
+//# sourceMappingURL=csr_graph_validate_coloring.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csr_graph_validate_coloring.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/csr/csr_graph_validate_coloring.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oDANW,UAAU,MAAM,CAAC,kBACjB,UAAU,MAAM,CAAC,aACjB,UAAU,MAAM,CAAC,gBACjB,MAAM,GACJ,OAAO,CAqBnB"}

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

@@ -0,0 +1,33 @@
+/**
+ * Whether a colouring is proper over a CSR adjacency: no vertex shares its colour with any of its neighbours.
+ * A self-loop is not a conflict.
+ *
+ * A debug check, meant to sit behind `assert.*` after a colouring is built; it reads every adjacency entry
+ * once. Works on the raw CSR arrays, like {@link csr_graph_color_greedy}.
+ *
+ * @param {ArrayLike<number>} colors colour of every vertex
+ * @param {ArrayLike<number>} edge_addresses row offsets, `vertex_count + 1` entries
+ * @param {ArrayLike<number>} adjacency neighbour ids
+ * @param {number} vertex_count
+ * @returns {boolean} true when no edge joins two vertices of one colour
+ */
+export function csr_graph_validate_coloring(colors, edge_addresses, adjacency, vertex_count) {
+    if (colors.length < vertex_count) {
+        return false;
+    }
+
+    for (let v = 0; v < vertex_count; v++) {
+        const colour = colors[v];
+        const end = edge_addresses[v + 1];
+
+        for (let k = edge_addresses[v]; k < end; k++) {
+            const neighbour = adjacency[k];
+
+            if (neighbour !== v && colors[neighbour] === colour) {
+                return false;
+            }
+        }
+    }
+
+    return true;
+}

package/src/core/math/linalg/matrix_symmetric_3x3_solve_ldlt.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Solve `M·x = b` for a symmetric positive definite 3×3 `M`, by LDLᵀ factorisation.
+ *
+ * `M` is read as its six distinct entries, diagonal first: `[m00, m11, m22, m01, m02, m12]`.
+ *
+ * LDLᵀ rather than a cofactor inverse. The two agree in exact arithmetic and do not agree in Float64: an SPD
+ * matrix with a condition number in the billions has a cofactor determinant — a sum of triple products that
+ * has to cancel down by that ratio squared — that can come out *negative* although every eigenvalue is
+ * positive. The factorisation never forms those products, so its pivots stay positive where the determinant
+ * does not, and their product is the determinant to full precision.
+ *
+ * The pivots of an SPD matrix are `M` restricted to nested subspaces, so all three positive *is* positive
+ * definiteness: the function checks exactly that, and returns `false` without writing `out` when a pivot is
+ * not positive and finite — an indefinite, singular or non-finite `M`. An infinite pivot needs refusing
+ * explicitly: it is positive, and dividing by it reads as a finite solution, zero along that axis.
+ *
+ * @param {Float64Array|Float32Array|number[]} out solution `x`, 3 entries at `out_offset`
+ * @param {number} out_offset
+ * @param {Float64Array|Float32Array|number[]} m `[m00, m11, m22, m01, m02, m12]` at `m_offset`
+ * @param {number} m_offset
+ * @param {Float64Array|Float32Array|number[]} b right-hand side, 3 entries at `b_offset`
+ * @param {number} b_offset
+ * @returns {boolean} true when `M` was positive definite and `out` holds the solution
+ */
+export function matrix_symmetric_3x3_solve_ldlt(out: Float64Array | Float32Array | number[], out_offset: number, m: Float64Array | Float32Array | number[], m_offset: number, b: Float64Array | Float32Array | number[], b_offset: number): boolean;
+//# sourceMappingURL=matrix_symmetric_3x3_solve_ldlt.d.ts.map

package/src/core/math/linalg/matrix_symmetric_3x3_solve_ldlt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix_symmetric_3x3_solve_ldlt.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/linalg/matrix_symmetric_3x3_solve_ldlt.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qDARW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,cAClC,MAAM,KACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,YAClC,MAAM,KACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,YAClC,MAAM,GACJ,OAAO,CAgDnB"}