@woosh/meep-engine 3.40.0 → 3.42.0

package/src/core/geom/3d/gjk/gjk_epa_penetration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gjk_epa_penetration.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/gjk_epa_penetration.js"],"names":[],"mappings":"AAkkBA;;;;;;;;;;;;;;;;GAgBG;AACH,yCATW,YAAY,GAAC,MAAM,EAAE,KACrB,eAAe,KACf,eAAe,GACb,MAAM,CA0BlB;AA7DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4BAFU,MAAM,CAEgB;;;;;;;8BAzdnB;IAAE,OAAO,SAAW,YAAY,QAAE,MAAM,QAAE,CAAC,YAAY,GAAC,MAAM,EAAE,CAAC,QAAE,MAAM,KAAG,IAAI,CAAA;CAAE"}
+{"version":3,"file":"gjk_epa_penetration.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/gjk_epa_penetration.js"],"names":[],"mappings":"AAmkBA;;;;;;;;;;;;;;;;GAgBG;AACH,yCATW,YAAY,GAAC,MAAM,EAAE,KACrB,eAAe,KACf,eAAe,GACb,MAAM,CA0BlB;AA7DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4BAFU,MAAM,CAEgB;;;;;;;8BA1dnB;IAAE,OAAO,SAAW,YAAY,QAAE,MAAM,QAAE,CAAC,YAAY,GAAC,MAAM,EAAE,CAAC,QAAE,MAAM,KAAG,IAAI,CAAA;CAAE"}

package/src/core/geom/3d/gjk/gjk_epa_penetration.js

@@ -533,9 +533,6 @@ function epa(A, B, out) {
         // Degenerate: no face survived. Report no usable axis (the caller treats a
         // non-positive depth as a miss) rather than reading a stale face and
         // throwing out of the narrowphase step.
-        out[0] = 0;
-        out[1] = 0;
-        out[2] = 0;
         return 0;
     }
 
@@ -545,11 +542,15 @@ function epa(A, B, out) {
             best = f;
         }
     }
+    const depth = FACE_DIST[best];
+    if (!(depth > 0) || !Number.isFinite(depth)) {
+        return 0;
+    }
     const bn = best * 3;
     out[0] = FACE_N[bn];
     out[1] = FACE_N[bn + 1];
     out[2] = FACE_N[bn + 2];
-    return FACE_DIST[best];
+    return depth;
 }
 
 /**

package/src/core/geom/3d/line/line3_compute_segment_point_distance_eikonal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"line3_compute_segment_point_distance_eikonal.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/line/line3_compute_segment_point_distance_eikonal.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,iEAbW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAkFlB"}
+{"version":3,"file":"line3_compute_segment_point_distance_eikonal.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/line/line3_compute_segment_point_distance_eikonal.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,iEAbW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAwFlB"}

package/src/core/geom/3d/line/line3_compute_segment_point_distance_eikonal.js

@@ -26,7 +26,13 @@ export function line3_compute_segment_point_distance_eikonal(
     const ab_z = z1 - z0;
     const L = Math.hypot(ab_x, ab_y, ab_z);
 
-    if (L < 1e-9) return Math.min(d0, d1);
+    if (L < 1e-9) {
+        // A point-like edge still leaves the distance from its endpoints to the target.
+        return Math.min(
+            d0 + Math.hypot(px - x0, py - y0, pz - z0),
+            d1 + Math.hypot(px - x1, py - y1, pz - z1)
+        );
+    }
 
     // Vector AC
     const ac_x = px - x0;
@@ -93,4 +99,4 @@ export function line3_compute_segment_point_distance_eikonal(
         const dist_to_v1 = Math.hypot(px - x1, py - y1, pz - z1);
         return Math.min(d0 + dist_to_v0, d1 + dist_to_v1);
     }
-}
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Project a rotation into a box of swing-twist limits: the twist about X and the swing over Y and Z,
+ * as {@link swing_twist_error_array} measures them, each clamped to its own `[lower, upper]`.
+ *
+ * This is the box a physics `Joint` with `swingTwist` on allows: the joint solver limits each of
+ * the three positions separately, so Y and Z swing are a box and not a cone. A rotation already
+ * inside is written back unchanged, bit for bit; one outside is composed again from the clamped
+ * positions ({@link swing_twist_compose_array}).
+ *
+ * An axis that is not limited takes `-Infinity` / `Infinity`; a locked one takes `0` / `0`.
+ *
+ * `out` may be `q`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} q
+ * @param {number} q_offset `[x, y, z, w]`, unit
+ * @param {Float64Array} lower
+ * @param {Float64Array} upper
+ * @param {number} limit_offset `[twist, swing y, swing z]` in `lower` and `upper`, radians
+ * @returns {boolean} whether any position was outside its limits
+ */
+export function swing_twist_clamp_array(out: Float64Array, out_offset: number, q: Float64Array, q_offset: number, lower: Float64Array, upper: Float64Array, limit_offset: number): boolean;
+//# sourceMappingURL=swing_twist_clamp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"swing_twist_clamp.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/swing_twist_clamp.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,6CATW,YAAY,cACZ,MAAM,KACN,YAAY,YACZ,MAAM,SACN,YAAY,SACZ,YAAY,gBACZ,MAAM,GACJ,OAAO,CAgCnB"}

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

@@ -0,0 +1,62 @@
+import { swing_twist_compose_array } from "./swing_twist_compose.js";
+import { swing_twist_error_array } from "./swing_twist_error.js";
+
+/**
+ * The three swing-twist positions, measured and then clamped.
+ * @type {Float64Array}
+ */
+const e = new Float64Array(3);
+
+/**
+ * Project a rotation into a box of swing-twist limits: the twist about X and the swing over Y and Z,
+ * as {@link swing_twist_error_array} measures them, each clamped to its own `[lower, upper]`.
+ *
+ * This is the box a physics `Joint` with `swingTwist` on allows: the joint solver limits each of
+ * the three positions separately, so Y and Z swing are a box and not a cone. A rotation already
+ * inside is written back unchanged, bit for bit; one outside is composed again from the clamped
+ * positions ({@link swing_twist_compose_array}).
+ *
+ * An axis that is not limited takes `-Infinity` / `Infinity`; a locked one takes `0` / `0`.
+ *
+ * `out` may be `q`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} q
+ * @param {number} q_offset `[x, y, z, w]`, unit
+ * @param {Float64Array} lower
+ * @param {Float64Array} upper
+ * @param {number} limit_offset `[twist, swing y, swing z]` in `lower` and `upper`, radians
+ * @returns {boolean} whether any position was outside its limits
+ */
+export function swing_twist_clamp_array(out, out_offset, q, q_offset, lower, upper, limit_offset) {
+    swing_twist_error_array(q, q_offset, e);
+
+    let clamped = false;
+
+    for (let k = 0; k < 3; k++) {
+        const lo = lower[limit_offset + k];
+        const hi = upper[limit_offset + k];
+
+        const value = e[k];
+
+        if (value < lo) {
+            e[k] = lo;
+            clamped = true;
+        } else if (value > hi) {
+            e[k] = hi;
+            clamped = true;
+        }
+    }
+
+    if (clamped) {
+        swing_twist_compose_array(out, out_offset, e, 0);
+    } else if (out !== q || out_offset !== q_offset) {
+        out[out_offset] = q[q_offset];
+        out[out_offset + 1] = q[q_offset + 1];
+        out[out_offset + 2] = q[q_offset + 2];
+        out[out_offset + 3] = q[q_offset + 3];
+    }
+
+    return clamped;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * The rotation whose swing-twist positions are `e[e_offset ..+2]`: the inverse of
+ * {@link swing_twist_error_array}.
+ *
+ * `e[0]` is the twist about X, `e[1]`, `e[2]` the swing as `φ·axis` over Y and Z, and the rotation is
+ * `swing ⊗ twist`. Composed back from what {@link swing_twist_error_array} measured, it is the
+ * measured rotation, on the hemisphere with `w ≥ 0`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} e
+ * @param {number} e_offset `[twist, swing y, swing z]`, radians
+ */
+export function swing_twist_compose_array(out: Float64Array, out_offset: number, e: Float64Array, e_offset: number): void;
+//# sourceMappingURL=swing_twist_compose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"swing_twist_compose.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/swing_twist_compose.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,+CALW,YAAY,cACZ,MAAM,KACN,YAAY,YACZ,MAAM,QAwBhB"}

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

@@ -0,0 +1,36 @@
+/**
+ * The rotation whose swing-twist positions are `e[e_offset ..+2]`: the inverse of
+ * {@link swing_twist_error_array}.
+ *
+ * `e[0]` is the twist about X, `e[1]`, `e[2]` the swing as `φ·axis` over Y and Z, and the rotation is
+ * `swing ⊗ twist`. Composed back from what {@link swing_twist_error_array} measured, it is the
+ * measured rotation, on the hemisphere with `w ≥ 0`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} e
+ * @param {number} e_offset `[twist, swing y, swing z]`, radians
+ */
+export function swing_twist_compose_array(out, out_offset, e, e_offset) {
+    const twist = e[e_offset];
+    const y = e[e_offset + 1];
+    const z = e[e_offset + 2];
+
+    const tx = Math.sin(twist * 0.5);
+    const tw = Math.cos(twist * 0.5);
+
+    const phi = Math.sqrt(y * y + z * z);
+
+    // sin(φ/2) / φ, which is 1/2 as φ goes to 0, as the measure's small-angle branch is
+    const s = phi < 1e-9 ? 0.5 : Math.sin(phi * 0.5) / phi;
+
+    const sy = y * s;
+    const sz = z * s;
+    const sw = Math.cos(phi * 0.5);
+
+    // (0, sy, sz, sw) ⊗ (tx, 0, 0, tw)
+    out[out_offset] = sw * tx;
+    out[out_offset + 1] = sy * tw + sz * tx;
+    out[out_offset + 2] = sz * tw - sy * tx;
+    out[out_offset + 3] = sw * tw;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Swing-twist decomposition of the relative rotation `qD = conj(qA)⊗qB`, giving
+ * the per-frame-axis angular positions used by wide-cone angular DOFs.
+ *
+ * Decomposes `qD = swing ⊗ twist`, with **twist** the rotation about frame
+ * axis X (the bone / twist axis) and **swing** the residual tilt (a rotation
+ * about an axis in the YZ plane that carries X to its new direction). Writes,
+ * into `out`:
+ *   - `out[0]` = signed twist angle about X, in `(−π, π]` — *exact*, so a twist
+ *     limit engages at the true angle, not the `2·sin(θ/2)` small-angle proxy;
+ *   - `out[1]`, `out[2]` = the swing angle distributed over Y and Z
+ *     (`φ·axis`, φ the true swing angle), so independent Y/Z swing limits form
+ *     an accurate (box-shaped) cone that holds at large tilt.
+ * Reduces continuously to the small-angle vector near identity. Pure scratch /
+ * locals — no allocation, suitable for the per-substep hot loop. (The Quaternion
+ * class has an object-based `computeSwingAndTwist`; this is the inlined,
+ * allocation-free form — see the bench that justifies it.)
+ *
+ * The physics joint solver measures a `Joint`'s angular DOFs with it, and IK clamps to the same
+ * measure ({@link swing_twist_clamp_array}), so the two agree on what a limit allows.
+ *
+ * @param {number} dx  qD x
+ * @param {number} dy  qD y
+ * @param {number} dz  qD z
+ * @param {number} dw  qD w
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error(dx: number, dy: number, dz: number, dw: number, out: Float64Array): void;
+/**
+ * {@link swing_twist_error} with `qD` read from `q[q_offset ..+3]`, `[x, y, z, w]`: the one place the
+ * arithmetic lives. For a caller whose inlining budget is spent, where a call taking the four numbers
+ * would box each into a new heap object.
+ *
+ * @param {Float64Array} q
+ * @param {number} q_offset
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error_array(q: Float64Array, q_offset: number, out: Float64Array): void;
+//# sourceMappingURL=swing_twist_error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"swing_twist_error.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/swing_twist_error.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,YAAY,QAWtB;AAKD;;;;;;;;GAQG;AACH,2CAJW,YAAY,YACZ,MAAM,OACN,YAAY,QAoCtB"}

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

@@ -0,0 +1,85 @@
+/**
+ * Swing-twist decomposition of the relative rotation `qD = conj(qA)⊗qB`, giving
+ * the per-frame-axis angular positions used by wide-cone angular DOFs.
+ *
+ * Decomposes `qD = swing ⊗ twist`, with **twist** the rotation about frame
+ * axis X (the bone / twist axis) and **swing** the residual tilt (a rotation
+ * about an axis in the YZ plane that carries X to its new direction). Writes,
+ * into `out`:
+ *   - `out[0]` = signed twist angle about X, in `(−π, π]` — *exact*, so a twist
+ *     limit engages at the true angle, not the `2·sin(θ/2)` small-angle proxy;
+ *   - `out[1]`, `out[2]` = the swing angle distributed over Y and Z
+ *     (`φ·axis`, φ the true swing angle), so independent Y/Z swing limits form
+ *     an accurate (box-shaped) cone that holds at large tilt.
+ * Reduces continuously to the small-angle vector near identity. Pure scratch /
+ * locals — no allocation, suitable for the per-substep hot loop. (The Quaternion
+ * class has an object-based `computeSwingAndTwist`; this is the inlined,
+ * allocation-free form — see the bench that justifies it.)
+ *
+ * The physics joint solver measures a `Joint`'s angular DOFs with it, and IK clamps to the same
+ * measure ({@link swing_twist_clamp_array}), so the two agree on what a limit allows.
+ *
+ * @param {number} dx  qD x
+ * @param {number} dy  qD y
+ * @param {number} dz  qD z
+ * @param {number} dw  qD w
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error(dx, dy, dz, dw, out) {
+    const q = swing_twist_inputs;
+
+    q[0] = dx;
+    q[1] = dy;
+    q[2] = dz;
+    q[3] = dw;
+
+    swing_twist_error_array(q, 0, out);
+}
+
+/** Where {@link swing_twist_error} packs its quaternion. */
+const swing_twist_inputs = new Float64Array(4);
+
+/**
+ * {@link swing_twist_error} with `qD` read from `q[q_offset ..+3]`, `[x, y, z, w]`: the one place the
+ * arithmetic lives. For a caller whose inlining budget is spent, where a call taking the four numbers
+ * would box each into a new heap object.
+ *
+ * @param {Float64Array} q
+ * @param {number} q_offset
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error_array(q, q_offset, out) {
+    let dx = q[q_offset], dy = q[q_offset + 1], dz = q[q_offset + 2], dw = q[q_offset + 3];
+
+    // Shortest arc: work with the hemisphere where dw ≥ 0.
+    if (dw < 0) { dx = -dx; dy = -dy; dz = -dz; dw = -dw; }
+
+    const nxt = Math.sqrt(dx * dx + dw * dw); // |twist| (before normalising)
+    let sy, sz, sw;
+    if (nxt < 1e-12) {
+        // dw ≈ 0 and dx ≈ 0: a ~180° pure swing — twist is undefined, take 0.
+        out[0] = 0;
+        // Swing is qD itself; distribute its angle over Y/Z below.
+        sy = dy; sz = dz; sw = dw;
+    } else {
+        out[0] = 2 * Math.atan2(dx, dw); // exact signed twist about X
+        const tx = dx / nxt, tw = dw / nxt; // normalised twist (tx,0,0,tw)
+        // swing = qD ⊗ conj(twist); its X component is identically 0.
+        sy = dy * tw - dz * tx;
+        sz = dy * tx + dz * tw;
+        sw = dw * tw + dx * tx;
+    }
+
+    if (sw < 0) { sy = -sy; sz = -sz; sw = -sw; }
+    const syz = Math.sqrt(sy * sy + sz * sz);
+    if (syz < 1e-9) {
+        // Near-zero swing: small-angle vector (continuous with φ·axis as φ→0).
+        out[1] = 2 * sy;
+        out[2] = 2 * sz;
+    } else {
+        const phi = 2 * Math.atan2(syz, sw); // exact swing angle in [0, π]
+        const s = phi / syz;
+        out[1] = sy * s;
+        out[2] = sz * s;
+    }
+}

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

@@ -20,4 +20,24 @@
  * @returns {boolean}
  */
 export function tri3_ray_intersection(result: SurfacePoint3, origin_x: number, origin_y: number, origin_z: number, direction_x: number, direction_y: number, direction_z: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number): boolean;
+/**
+ * Ray-triangle intersection with vertices read from a packed triangle,
+ * [ax, ay, az, bx, by, bz, cx, cy, cz] at triangle_offset.
+ *
+ * All nine coordinates are read before validation or output writes so output
+ * callbacks can mutate the source without changing this intersection.
+ * The arithmetic and output order match tri3_ray_intersection.
+ *
+ * @param {import("../SurfacePoint3.js").SurfacePoint3} result
+ * @param {number} origin_x
+ * @param {number} origin_y
+ * @param {number} origin_z
+ * @param {number} direction_x
+ * @param {number} direction_y
+ * @param {number} direction_z
+ * @param {ArrayLike<number>|number[]|Float32Array|Float64Array} triangle
+ * @param {number} [triangle_offset=0]
+ * @returns {boolean}
+ */
+export function tri3_ray_intersection_triangle_array(result: import("../SurfacePoint3.js").SurfacePoint3, origin_x: number, origin_y: number, origin_z: number, direction_x: number, direction_y: number, direction_z: number, triangle: ArrayLike<number> | number[] | Float32Array | Float64Array, triangle_offset?: number): boolean;
 //# sourceMappingURL=tri3_ray_intersection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tri3_ray_intersection.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/triangle/tri3_ray_intersection.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uEAjBW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAoJnB"}
+{"version":3,"file":"tri3_ray_intersection.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/triangle/tri3_ray_intersection.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uEAjBW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAoJnB;AAGD;;;;;;;;;;;;;;;;;;GAkBG;AACH,6DAXW,OAAO,qBAAqB,EAAE,aAAa,YAC3C,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,YACN,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,oBACpD,MAAM,GACJ,OAAO,CAmKnB"}

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

@@ -170,3 +170,185 @@ export function tri3_ray_intersection(
     return true;
 }
 
+
+/**
+ * Ray-triangle intersection with vertices read from a packed triangle,
+ * [ax, ay, az, bx, by, bz, cx, cy, cz] at triangle_offset.
+ *
+ * All nine coordinates are read before validation or output writes so output
+ * callbacks can mutate the source without changing this intersection.
+ * The arithmetic and output order match tri3_ray_intersection.
+ *
+ * @param {import("../SurfacePoint3.js").SurfacePoint3} result
+ * @param {number} origin_x
+ * @param {number} origin_y
+ * @param {number} origin_z
+ * @param {number} direction_x
+ * @param {number} direction_y
+ * @param {number} direction_z
+ * @param {ArrayLike<number>|number[]|Float32Array|Float64Array} triangle
+ * @param {number} [triangle_offset=0]
+ * @returns {boolean}
+ */
+export function tri3_ray_intersection_triangle_array(
+    result,
+    origin_x, origin_y, origin_z,
+    direction_x, direction_y, direction_z,
+    triangle, triangle_offset = 0
+) {
+    const ax = triangle[triangle_offset];
+    const ay = triangle[triangle_offset + 1];
+    const az = triangle[triangle_offset + 2];
+    const bx = triangle[triangle_offset + 3];
+    const by = triangle[triangle_offset + 4];
+    const bz = triangle[triangle_offset + 5];
+    const cx = triangle[triangle_offset + 6];
+    const cy = triangle[triangle_offset + 7];
+    const cz = triangle[triangle_offset + 8];
+
+    // Finite primitive numbers keep the valid path unboxed. The fallback
+    // preserves the scalar form's validation order and diagnostic messages.
+    if (!(Number.isFinite(ax) && Number.isFinite(ay) && Number.isFinite(az)
+        && Number.isFinite(bx) && Number.isFinite(by) && Number.isFinite(bz)
+        && Number.isFinite(cx) && Number.isFinite(cy) && Number.isFinite(cz))) {
+        assert.isNumber(ax, 'ax');
+        assert.isNumber(ay, 'ay');
+        assert.isNumber(az, 'az');
+
+        assert.isNumber(bx, 'bx');
+        assert.isNumber(by, 'by');
+        assert.isNumber(bz, 'bz');
+
+        assert.isNumber(cx, 'cx');
+        assert.isNumber(cy, 'cy');
+        assert.isNumber(cz, 'cz');
+
+        // nan checks
+        assert.notNaN(ax, 'ax');
+        assert.notNaN(ay, 'ay');
+        assert.notNaN(az, 'az');
+
+        assert.notNaN(bx, 'bx');
+        assert.notNaN(by, 'by');
+        assert.notNaN(bz, 'bz');
+
+        assert.notNaN(cx, 'cx');
+        assert.notNaN(cy, 'cy');
+        assert.notNaN(cz, 'cz');
+
+        // finate number check
+        assert.isFinite(ax, 'ax');
+        assert.isFinite(ay, 'ay');
+        assert.isFinite(az, 'az');
+
+        assert.isFinite(bx, 'bx');
+        assert.isFinite(by, 'by');
+        assert.isFinite(bz, 'bz');
+
+        assert.isFinite(cx, 'cx');
+        assert.isFinite(cy, 'cy');
+        assert.isFinite(cz, 'cz');
+
+
+    }
+
+    // edge1 = a - b
+    const edge1_x = bx - ax;
+    const edge1_y = by - ay;
+    const edge1_z = bz - az;
+
+    // edge2 = c - a
+    const edge2_x = cx - ax;
+    const edge2_y = cy - ay;
+    const edge2_z = cz - az;
+
+    // Compute triangle normal
+
+    // normal = edge1 x edge2
+    const normal_x = edge1_y * edge2_z - edge1_z * edge2_y;
+    const normal_y = edge1_z * edge2_x - edge1_x * edge2_z;
+    const normal_z = edge1_x * edge2_y - edge1_y * edge2_x
+
+    let DdN = v3_dot(direction_x, direction_y, direction_z, normal_x, normal_y, normal_z);
+    let sign = 1;
+
+    if (DdN === 0) {
+        // ray and the triangle normal are orthogonal, means that the ray can not pass penetrate triangle
+        return false;
+    } else if (DdN < 0) {
+        sign = -1;
+        DdN = -DdN;
+    }
+
+    // diff = origin - a
+    const diff_x = origin_x - ax;
+    const diff_y = origin_y - ay;
+    const diff_z = origin_z - az;
+
+    // edge3 = diff x edge2
+    const edge3_x = diff_y * edge2_z - diff_z * edge2_y;
+    const edge3_y = diff_z * edge2_x - diff_x * edge2_z;
+    const edge3_z = diff_x * edge2_y - diff_y * edge2_x;
+
+    // DdQxE2 = sign * ( direction . edge3)
+    const DdQxE2 = sign * v3_dot(direction_x, direction_y, direction_z, edge3_x, edge3_y, edge3_z);
+
+    if (DdQxE2 < 0) {
+        // b1 < 0, no intersection
+        return false;
+    }
+
+    const edge4_x = edge1_y * diff_z - edge1_z * diff_y;
+    const edge4_y = edge1_z * diff_x - edge1_x * diff_z;
+    const edge4_z = edge1_x * diff_y - edge1_y * diff_x;
+
+    const DdE1xQ = sign * v3_dot(direction_x, direction_y, direction_z, edge4_x, edge4_y, edge4_z);
+
+    if (DdE1xQ < 0) {
+        // b2 < 0, no intersection
+        return false;
+    }
+
+    if (DdQxE2 + DdE1xQ > DdN) {
+        // b1+b2 > 1, no intersection
+        return false;
+    }
+
+    // Line intersects triangle, check if ray does.
+    const QdN = -sign * v3_dot(diff_x, diff_y, diff_z, normal_x, normal_y, normal_z);
+
+    if (QdN < 0) {
+        // t < 0, no intersection
+        return false;
+
+    }
+
+    // Ray intersects triangle.
+    const t = QdN / DdN;
+
+    // `normal_x/y/z` is the raw `edge1 x edge2`, whose length is twice the triangle's area - it was
+    // written straight into `SurfacePoint3.normal`, which is documented as a surface normal and is
+    // a unit vector out of every other producer in the tree.
+    //
+    // NOTE: normalised but NOT turned to meet the ray, unlike `tri3_raycast`. This normal keeps the
+    // winding's facing on purpose: `StaticSceneBVH.raycast_nearest` derives `geometric_back_face`
+    // from `dot(normal, direction)`, and a normal pre-flipped toward the ray would report every hit
+    // as front-facing.
+    const normal_length = Math.sqrt(normal_x * normal_x + normal_y * normal_y + normal_z * normal_z);
+
+    const inv_normal_length = 1 / normal_length;
+
+    result.normal.set(
+        normal_x * inv_normal_length,
+        normal_y * inv_normal_length,
+        normal_z * inv_normal_length
+    );
+
+    result.position.set(
+        direction_x * t + origin_x,
+        direction_y * t + origin_y,
+        direction_z * t + origin_z,
+    );
+
+    return true;
+}

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

@@ -8,16 +8,21 @@
  *
  * The matrix N is built so that the eigenvector of its largest eigenvalue
  * IS the optimal rotation quaternion (in scalar-last form, matching meep's
- * `Quaternion`).
+ * `Quaternion`). Largest means signed, not by magnitude: for a coplanar set
+ * (every set of two) det S = 0, which makes N's spectrum symmetric about zero,
+ * so −λmax is an eigenvalue too (±count for a perfect fit). N is decomposed
+ * directly (Jacobi), which needs no gap between the top two eigenvalues, so a
+ * set whose twist is weakly determined (nearly parallel vectors) is solved as
+ * exactly as a well-spread one.
  *
  * Inputs are unit vectors so no centroid subtraction is needed — the rotation
  * is recovered from the cross-correlations alone.
  *
- * @param {Float32Array|number[]} a_xyz Source vectors — Length: count*3, unit length per triple
- * @param {Float32Array|number[]} b_xyz Target vectors — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} a_xyz Target vectors, which R·b_i is fitted onto — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} b_xyz Source vectors, which R rotates — Length: count*3, unit length per triple
  * @param {number} count
- * @param {Float32Array|number[]} out_quaternion Length 4 (x, y, z, w)
- * @returns {number} The maximum eigenvalue ≈ Σ a_i · R·b_i. For a perfect alignment this equals `count`.
+ * @param {Float32Array|Float64Array|number[]} out_quaternion Length 4 (x, y, z, w)
+ * @returns {number} The maximum eigenvalue = Σ a_i · R·b_i at the optimum. For a perfect alignment this equals `count`.
  */
-export function v3_rigid_align_paired_unit_vectors(a_xyz: Float32Array | number[], b_xyz: Float32Array | number[], count: number, out_quaternion: Float32Array | number[]): number;
+export function v3_rigid_align_paired_unit_vectors(a_xyz: Float32Array | Float64Array | number[], b_xyz: Float32Array | Float64Array | number[], count: number, out_quaternion: Float32Array | Float64Array | number[]): number;
 //# sourceMappingURL=v3_rigid_align_paired_unit_vectors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"v3_rigid_align_paired_unit_vectors.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_rigid_align_paired_unit_vectors.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,0DANW,YAAY,GAAC,MAAM,EAAE,SACrB,YAAY,GAAC,MAAM,EAAE,SACrB,MAAM,kBACN,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CAsElB"}
+{"version":3,"file":"v3_rigid_align_paired_unit_vectors.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_rigid_align_paired_unit_vectors.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,0DANW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,SAClC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,SAClC,MAAM,kBACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,GAChC,MAAM,CA+ElB"}

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

@@ -1,8 +1,8 @@
-import { BinaryDataType } from "../../binary/type/BinaryDataType.js";
-import { matrix_top_eigenvector_power_iteration } from "../../math/linalg/eigen/matrix_top_eigenvector_power_iteration.js";
-import { SquareMatrix } from "../../math/matrix/SquareMatrix.js"
+import { matrix_symmetric_4x4_eigen } from "../../math/linalg/eigen/matrix_symmetric_4x4_eigen.js";
 
-const scratch_horn_n = new SquareMatrix(4, BinaryDataType.Float64);
+const scratch_horn_n = new Float64Array(16);
+const scratch_eigen_values = new Float64Array(4);
+const scratch_eigen_vectors = new Float64Array(16);
 
 /**
  * Closed-form solution for the rotation that best aligns two sets of unit
@@ -14,16 +14,21 @@ const scratch_horn_n = new SquareMatrix(4, BinaryDataType.Float64);
  *
  * The matrix N is built so that the eigenvector of its largest eigenvalue
  * IS the optimal rotation quaternion (in scalar-last form, matching meep's
- * `Quaternion`).
+ * `Quaternion`). Largest means signed, not by magnitude: for a coplanar set
+ * (every set of two) det S = 0, which makes N's spectrum symmetric about zero,
+ * so −λmax is an eigenvalue too (±count for a perfect fit). N is decomposed
+ * directly (Jacobi), which needs no gap between the top two eigenvalues, so a
+ * set whose twist is weakly determined (nearly parallel vectors) is solved as
+ * exactly as a well-spread one.
  *
  * Inputs are unit vectors so no centroid subtraction is needed — the rotation
  * is recovered from the cross-correlations alone.
  *
- * @param {Float32Array|number[]} a_xyz Source vectors — Length: count*3, unit length per triple
- * @param {Float32Array|number[]} b_xyz Target vectors — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} a_xyz Target vectors, which R·b_i is fitted onto — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} b_xyz Source vectors, which R rotates — Length: count*3, unit length per triple
  * @param {number} count
- * @param {Float32Array|number[]} out_quaternion Length 4 (x, y, z, w)
- * @returns {number} The maximum eigenvalue ≈ Σ a_i · R·b_i. For a perfect alignment this equals `count`.
+ * @param {Float32Array|Float64Array|number[]} out_quaternion Length 4 (x, y, z, w)
+ * @returns {number} The maximum eigenvalue = Σ a_i · R·b_i at the optimum. For a perfect alignment this equals `count`.
  */
 export function v3_rigid_align_paired_unit_vectors(a_xyz, b_xyz, count, out_quaternion) {
 
@@ -72,9 +77,8 @@ export function v3_rigid_align_paired_unit_vectors(a_xyz, b_xyz, count, out_quat
     const Nyw = Szx - Sxz;
     const Nzw = Sxy - Syx;
 
-    const N = scratch_horn_n;
-    const d = N.data;
-    // SquareMatrix is column-major: d[col * 4 + row]
+    // Symmetric, so the index is row*4 + col and col*4 + row alike.
+    const d = scratch_horn_n;
     d[0] = Nxx;
     d[5] = Nyy;
     d[10] = Nzz;
@@ -92,5 +96,15 @@ export function v3_rigid_align_paired_unit_vectors(a_xyz, b_xyz, count, out_quat
     d[11] = Nzw;
     d[14] = Nzw;
 
-    return matrix_top_eigenvector_power_iteration(N, out_quaternion);
+    const values = scratch_eigen_values;
+    const vectors = scratch_eigen_vectors;
+    matrix_symmetric_4x4_eigen(values, vectors, d);
+
+    // Eigenpairs come back ascending; the last is the largest.
+    out_quaternion[0] = vectors[12];
+    out_quaternion[1] = vectors[13];
+    out_quaternion[2] = vectors[14];
+    out_quaternion[3] = vectors[15];
+
+    return values[3];
 }