@woosh/meep-engine 3.30.0 → 3.31.0

package/src/core/geom/3d/normal/spherical/encode_unit_to_spheremap.js

@@ -17,10 +17,24 @@ import { v2_length } from "../../../vec2/v2_length.js";
 export function encode_unit_to_spheremap(output, output_offset, x, y, z) {
     const length_xy = v2_length(x, y);
 
-    const norm_xy_x = x / length_xy;
-    const norm_xy_y = y / length_xy;
+    let norm_xy_x;
+    let norm_xy_y;
 
-    const z_factor = Math.sqrt(-z * 0.5 - 0.5) * 0.5;
+    if (length_xy === 0) {
+        // Exactly on a pole, where `normalize(n.xy)` is 0/0. At +z the factor below is zero so the
+        // direction does not matter; at -z every direction on the unit circle decodes back to
+        // (0, 0, -1). Pick one.
+        norm_xy_x = 1;
+        norm_xy_y = 0;
+    } else {
+        norm_xy_x = x / length_xy;
+        norm_xy_y = y / length_xy;
+    }
+
+    // `+ 0.5`, not `- 0.5`: the reference is `sqrt(-n.z * 0.5 + 0.5)`. With the minus, the radicand
+    // is in [-1, 0] for every z in [-1, 1] and strictly negative for every z > -1, so `Math.sqrt`
+    // returned NaN for every unit normal there is.
+    const z_factor = Math.sqrt(-z * 0.5 + 0.5) * 0.5;
 
     const enc_x = norm_xy_x * z_factor + 0.5;
     const enc_y = norm_xy_y * z_factor + 0.5;

package/src/core/geom/3d/octahedra/octahedral_direction_to_uv.d.ts

@@ -1,4 +1,14 @@
 /**
+ * Octahedral encode of a unit direction, into `[0, 1]` UV.
+ *
+ * The projection is {@link encode_unit_to_octahedron}, which is the same function over `[-1, 1]`; this is
+ * the range adapter and the offset-taking argument shape. The two were written out separately — same
+ * projection, same `y < 0` diagonal fold, same `sign_not_zero` — and agreed to 2.2e-16, which is what
+ * they should: one of them is now the other.
+ *
+ * `y` is the pole. The WGSL chunk `uv_octahedral_unit_encode` and its CPU port in
+ * `shade/renderer/light/environment` fold on `z` instead and emit `(x, y)`, so they are a different
+ * convention and not interchangeable with this — see `octahedral_z_pole_uv_to_direction`.
  *
  * @param {number[]} out_uv
  * @param {number} out_offset

package/src/core/geom/3d/octahedra/octahedral_direction_to_uv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"octahedral_direction_to_uv.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/octahedra/octahedral_direction_to_uv.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,mDALW,MAAM,EAAE,cACR,MAAM,gBACN,MAAM,EAAE,aACR,MAAM,QAuChB"}
+{"version":3,"file":"octahedral_direction_to_uv.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/octahedra/octahedral_direction_to_uv.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;GAgBG;AACH,mDALW,MAAM,EAAE,cACR,MAAM,gBACN,MAAM,EAAE,aACR,MAAM,QAoBhB"}

package/src/core/geom/3d/octahedra/octahedral_direction_to_uv.js

@@ -1,49 +1,46 @@
-import { assert } from "../../../assert.js";
-import { sign_not_zero } from "../../../math/sign_not_zero.js";
-import { v3_dot } from "../../vec3/v3_dot.js";
-
-/**
- *
- * @param {number[]} out_uv
- * @param {number} out_offset
- * @param {number[]} in_direction
- * @param {number} in_offset
- */
-export function octahedral_direction_to_uv(
-    out_uv, out_offset,
-    in_direction, in_offset
-) {
-
-    assert.isNonNegativeInteger(out_offset, 'out_offset');
-    assert.isNonNegativeInteger(in_offset, 'in_offset');
-
-    const input_x = in_direction[in_offset + 0];
-    const input_y = in_direction[in_offset + 1];
-    const input_z = in_direction[in_offset + 2];
-
-    const octant_x = sign_not_zero(input_x);
-    const octant_y = sign_not_zero(input_y);
-    const octant_z = sign_not_zero(input_z);
-
-    // |x| + |y| + |z| = 1
-    const sum = v3_dot(
-        input_x, input_y, input_z,
-        octant_x, octant_y, octant_z
-    );
-
-    let octahedron_x = input_x / sum;
-    const octahedron_y = input_y / sum;
-    let octahedron_z = input_z / sum;
-
-    if (octahedron_y < 0) {
-        const absolute_x = Math.abs(octahedron_x);
-        const absolute_z = Math.abs(octahedron_z);
-
-        octahedron_x = octant_x * (1 - absolute_z);
-        octahedron_z = octant_z * (1 - absolute_x);
-    }
-
-    // map octahedron coordinates from [-1,1] into [0,1] UV space; this exactly inverts the decode's `*2 - 1`.
-    out_uv[out_offset + 0] = octahedron_x * 0.5 + 0.5;
-    out_uv[out_offset + 1] = octahedron_z * 0.5 + 0.5;
-}
+import { assert } from "../../../assert.js";
+import { encode_unit_to_octahedron } from "../normal/octahedron/encode_unit_to_octahedron.js";
+
+/**
+ * Scratch for the `[-1, 1]` result before it is remapped. Safe as a module-static: the callee does not
+ * re-enter, and JS here is single-threaded.
+ * @type {Float64Array}
+ */
+const scratch_octahedron = new Float64Array(2);
+
+/**
+ * Octahedral encode of a unit direction, into `[0, 1]` UV.
+ *
+ * The projection is {@link encode_unit_to_octahedron}, which is the same function over `[-1, 1]`; this is
+ * the range adapter and the offset-taking argument shape. The two were written out separately — same
+ * projection, same `y < 0` diagonal fold, same `sign_not_zero` — and agreed to 2.2e-16, which is what
+ * they should: one of them is now the other.
+ *
+ * `y` is the pole. The WGSL chunk `uv_octahedral_unit_encode` and its CPU port in
+ * `shade/renderer/light/environment` fold on `z` instead and emit `(x, y)`, so they are a different
+ * convention and not interchangeable with this — see `octahedral_z_pole_uv_to_direction`.
+ *
+ * @param {number[]} out_uv
+ * @param {number} out_offset
+ * @param {number[]} in_direction
+ * @param {number} in_offset
+ */
+export function octahedral_direction_to_uv(
+    out_uv, out_offset,
+    in_direction, in_offset
+) {
+
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.isNonNegativeInteger(in_offset, 'in_offset');
+
+    encode_unit_to_octahedron(
+        scratch_octahedron, 0,
+        in_direction[in_offset + 0],
+        in_direction[in_offset + 1],
+        in_direction[in_offset + 2]
+    );
+
+    // map octahedron coordinates from [-1,1] into [0,1] UV space; this exactly inverts the decode's `*2 - 1`.
+    out_uv[out_offset + 0] = scratch_octahedron[0] * 0.5 + 0.5;
+    out_uv[out_offset + 1] = scratch_octahedron[1] * 0.5 + 0.5;
+}

package/src/core/geom/3d/octahedra/octahedral_uv_to_direction.d.ts

@@ -1,9 +1,21 @@
 /**
+ * Octahedral decode of a `[0, 1]` UV into a unit direction.
+ *
+ * The fold and the normalisation are {@link decode_octahedron_to_unit}, which is the same function over
+ * `[-1, 1]`; this is the range adapter and the offset-taking argument shape. The two were written out
+ * separately and agreed to 5.6e-16, which is what they should: one of them is now the other. The
+ * octahedral length comes along with it — a useful distortion measure the `[0, 1]` form used to drop.
+ *
+ * `y` is the pole. The WGSL chunk `uv_octahedral_unit_decode` and its CPU port
+ * `octahedral_z_pole_uv_to_direction` in `shade/renderer/light/environment` fold on `z` and emit
+ * `(x, y)`, so they are a different convention and not interchangeable with this. That port used to carry
+ * this function's exact name.
  *
  * @param {number[]} out_direction This is where the normalized direction vector will be written to
  * @param {number} out_offset Where to start writing in the output
  * @param {number[]} in_uv in the 0..1 range
  * @param {number} in_offset where to start reading in the input
+ * @returns {number} length of the octahedral vector before normalisation; larger means more distortion
  */
-export function octahedral_uv_to_direction(out_direction: number[], out_offset: number, in_uv: number[], in_offset: number): void;
+export function octahedral_uv_to_direction(out_direction: number[], out_offset: number, in_uv: number[], in_offset: number): number;
 //# sourceMappingURL=octahedral_uv_to_direction.d.ts.map

package/src/core/geom/3d/octahedra/octahedral_uv_to_direction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"octahedral_uv_to_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/octahedra/octahedral_uv_to_direction.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,0DALW,MAAM,EAAE,cACR,MAAM,SACN,MAAM,EAAE,aACR,MAAM,QA4BhB"}
+{"version":3,"file":"octahedral_uv_to_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/octahedra/octahedral_uv_to_direction.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,0DANW,MAAM,EAAE,cACR,MAAM,SACN,MAAM,EAAE,aACR,MAAM,GACJ,MAAM,CAelB"}

package/src/core/geom/3d/octahedra/octahedral_uv_to_direction.js

@@ -1,39 +1,36 @@
-import { assert } from "../../../assert.js";
-import { sign_not_zero } from "../../../math/sign_not_zero.js";
-import { v3_normalize_array } from "../../vec3/v3_normalize_array.js";
-
-/**
- *
- * @param {number[]} out_direction This is where the normalized direction vector will be written to
- * @param {number} out_offset Where to start writing in the output
- * @param {number[]} in_uv in the 0..1 range
- * @param {number} in_offset where to start reading in the input
- */
-export function octahedral_uv_to_direction(
-    out_direction, out_offset,
-    in_uv, in_offset
-) {
-
-    assert.isNonNegativeInteger(out_offset, 'out_offset');
-    assert.isNonNegativeInteger(in_offset, 'in_offset');
-
-    let px = in_uv[in_offset + 0] * 2 - 1;
-    let pz = in_uv[in_offset + 1] * 2 - 1;
-
-    const abs_x = Math.abs(px);
-    const abs_z = Math.abs(pz);
-    const py = 1 - abs_x - abs_z;
-
-    if (py < 0) {
-        px = sign_not_zero(px) * (1 - abs_z);
-        pz = sign_not_zero(pz) * (1 - abs_x);
-    }
-
-    out_direction[out_offset + 0] = px;
-    out_direction[out_offset + 1] = py;
-    out_direction[out_offset + 2] = pz;
-
-    v3_normalize_array(out_direction, out_offset, out_direction, out_offset);
-
-}
-
+import { assert } from "../../../assert.js";
+import { decode_octahedron_to_unit } from "../normal/octahedron/decode_octahedron_to_unit.js";
+
+/**
+ * Octahedral decode of a `[0, 1]` UV into a unit direction.
+ *
+ * The fold and the normalisation are {@link decode_octahedron_to_unit}, which is the same function over
+ * `[-1, 1]`; this is the range adapter and the offset-taking argument shape. The two were written out
+ * separately and agreed to 5.6e-16, which is what they should: one of them is now the other. The
+ * octahedral length comes along with it — a useful distortion measure the `[0, 1]` form used to drop.
+ *
+ * `y` is the pole. The WGSL chunk `uv_octahedral_unit_decode` and its CPU port
+ * `octahedral_z_pole_uv_to_direction` in `shade/renderer/light/environment` fold on `z` and emit
+ * `(x, y)`, so they are a different convention and not interchangeable with this. That port used to carry
+ * this function's exact name.
+ *
+ * @param {number[]} out_direction This is where the normalized direction vector will be written to
+ * @param {number} out_offset Where to start writing in the output
+ * @param {number[]} in_uv in the 0..1 range
+ * @param {number} in_offset where to start reading in the input
+ * @returns {number} length of the octahedral vector before normalisation; larger means more distortion
+ */
+export function octahedral_uv_to_direction(
+    out_direction, out_offset,
+    in_uv, in_offset
+) {
+
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.isNonNegativeInteger(in_offset, 'in_offset');
+
+    return decode_octahedron_to_unit(
+        out_direction, out_offset,
+        in_uv[in_offset + 0] * 2 - 1,
+        in_uv[in_offset + 1] * 2 - 1
+    );
+}

package/src/core/geom/3d/quadric/quadric3_to_tensor_m3_inverse.d.ts

@@ -10,7 +10,10 @@
  * @param {number} m3_offset
  * @param {ArrayLike<number>} q 11 elements from `q_offset`
  * @param {number} q_offset
- * @param {number} epsilon determinant magnitude below which the tensor counts as singular
+ * @param {number} epsilon *relative* singularity threshold: the tensor counts as singular when
+ *     `|det|` falls to or below `epsilon` times the cube of the tensor's largest absolute entry.
+ *     Relative, so the verdict does not move when the quadric is rescaled — which area weighting
+ *     and {@link quadric3_sub} both do without changing the geometry.
  * @returns {boolean} whether the tensor was invertible
  *
  * @author Alex Goldring

package/src/core/geom/3d/quadric/quadric3_to_tensor_m3_inverse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"quadric3_to_tensor_m3_inverse.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric3_to_tensor_m3_inverse.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAXW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,aAElC,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,WACN,MAAM,GACJ,OAAO,CA0CnB"}
+{"version":3,"file":"quadric3_to_tensor_m3_inverse.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quadric/quadric3_to_tensor_m3_inverse.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kDAdW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,aAElC,MAAM,KACN,UAAU,MAAM,CAAC,YACjB,MAAM,WACN,MAAM,GAIJ,OAAO,CAyDnB"}

package/src/core/geom/3d/quadric/quadric3_to_tensor_m3_inverse.js

@@ -10,7 +10,10 @@
  * @param {number} m3_offset
  * @param {ArrayLike<number>} q 11 elements from `q_offset`
  * @param {number} q_offset
- * @param {number} epsilon determinant magnitude below which the tensor counts as singular
+ * @param {number} epsilon *relative* singularity threshold: the tensor counts as singular when
+ *     `|det|` falls to or below `epsilon` times the cube of the tensor's largest absolute entry.
+ *     Relative, so the verdict does not move when the quadric is rescaled — which area weighting
+ *     and {@link quadric3_sub} both do without changing the geometry.
  * @returns {boolean} whether the tensor was invertible
  *
  * @author Alex Goldring
@@ -28,9 +31,24 @@ export function quadric3_to_tensor_m3_inverse(m3, m3_offset, q, q_offset, epsilo
         ab * (ab * c2 - ac * bc) +
         ac * (ab * bc - ac * b2);
 
-    // Written as `> epsilon` rather than an early `<= epsilon` bail so that a NaN determinant — a
-    // quadric that has already accumulated a NaN — is refused rather than written out as NaNs.
-    if (Math.abs(det) > epsilon) {
+    // The determinant is homogeneous of degree three in the quadric's scale, so an absolute
+    // threshold would measure how much has been folded into the quadric rather than whether the
+    // system is solvable: three mutually orthogonal planes — condition number exactly 1 — are
+    // refused once their weight drops far enough, and three near-parallel ones are accepted once it
+    // rises far enough. The area weighting the module documents, and `quadric3_sub`, both move that
+    // scale around without touching the geometry.
+    //
+    // Compare against the cube of the tensor's max-norm instead, which cancels the scale and leaves
+    // the conditioning.
+    const scale = Math.max(
+        Math.abs(a2), Math.abs(ab), Math.abs(ac),
+        Math.abs(b2), Math.abs(bc), Math.abs(c2)
+    );
+
+    // Written as `> threshold` rather than an early `<= threshold` bail so that a NaN determinant —
+    // a quadric that has already accumulated a NaN — is refused rather than written out as NaNs.
+    // A NaN anywhere in the tensor makes `scale` NaN, and the comparison false, for the same reason.
+    if (Math.abs(det) > epsilon * scale * scale * scale) {
         // avoid division by zero
 
         const invdet = 1.0 / det;

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

@@ -0,0 +1,38 @@
+/**
+ * Negate quaternions in a keyframe run so consecutive keys lie in the same hemisphere.
+ *
+ * A quaternion and its negation are the same rotation, so this changes no pose. It changes what happens
+ * *between* keys: an animation track is interpolated as four independent per-component curves, and a pair
+ * of adjacent keys whose dot product is negative then interpolates the long way — spinning nearly a full
+ * turn and dipping through a near-degenerate quaternion at the midpoint. Aligning first makes the
+ * component nlerp take the short arc, which is what `Quaternion.slerpFlat`'s sign flip does at
+ * interpolation time.
+ *
+ * **Whole blocks are negated, not just the value.** `stride` and `val_offset` are what make this work for
+ * a CUBICSPLINE track, where each key is `[in_tangent, value, out_tangent]` — 12 floats with the value at
+ * offset 4. Flipping the value and leaving its tangents behind is worse than not flipping at all. For a
+ * STEP or LINEAR track the stride is 4 and the offset 0.
+ *
+ * `rest_rotation` anchors the leading sign: without it the run is internally consistent but its overall
+ * sign is whatever the author happened to write, so two clips on one node can land in opposite hemispheres
+ * and a blend between them takes the long way. With it, every clip on a node starts on the same side.
+ *
+ * Mutates `values` in place.
+ *
+ * @param {Float32Array|Float64Array|number[]} values flat keyframe blocks
+ * @param {number} key_count
+ * @param {number} stride floats per keyframe block
+ * @param {number} val_offset offset of the quaternion within a block
+ * @param {{x:number, y:number, z:number, w:number}} [rest_rotation] the target's authored rest rotation;
+ * omitted leaves the leading sign as authored
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quat3_canonicalize_sign_run(values: Float32Array | Float64Array | number[], key_count: number, stride: number, val_offset: number, rest_rotation?: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}): void;
+//# sourceMappingURL=quat3_canonicalize_sign_run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quat3_canonicalize_sign_run.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_canonicalize_sign_run.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,oDAVW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,aAClC,MAAM,UACN,MAAM,cACN,MAAM,kBACN;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,QAgDlD"}

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

@@ -0,0 +1,76 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Negate quaternions in a keyframe run so consecutive keys lie in the same hemisphere.
+ *
+ * A quaternion and its negation are the same rotation, so this changes no pose. It changes what happens
+ * *between* keys: an animation track is interpolated as four independent per-component curves, and a pair
+ * of adjacent keys whose dot product is negative then interpolates the long way — spinning nearly a full
+ * turn and dipping through a near-degenerate quaternion at the midpoint. Aligning first makes the
+ * component nlerp take the short arc, which is what `Quaternion.slerpFlat`'s sign flip does at
+ * interpolation time.
+ *
+ * **Whole blocks are negated, not just the value.** `stride` and `val_offset` are what make this work for
+ * a CUBICSPLINE track, where each key is `[in_tangent, value, out_tangent]` — 12 floats with the value at
+ * offset 4. Flipping the value and leaving its tangents behind is worse than not flipping at all. For a
+ * STEP or LINEAR track the stride is 4 and the offset 0.
+ *
+ * `rest_rotation` anchors the leading sign: without it the run is internally consistent but its overall
+ * sign is whatever the author happened to write, so two clips on one node can land in opposite hemispheres
+ * and a blend between them takes the long way. With it, every clip on a node starts on the same side.
+ *
+ * Mutates `values` in place.
+ *
+ * @param {Float32Array|Float64Array|number[]} values flat keyframe blocks
+ * @param {number} key_count
+ * @param {number} stride floats per keyframe block
+ * @param {number} val_offset offset of the quaternion within a block
+ * @param {{x:number, y:number, z:number, w:number}} [rest_rotation] the target's authored rest rotation;
+ * omitted leaves the leading sign as authored
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function quat3_canonicalize_sign_run(values, key_count, stride, val_offset, rest_rotation) {
+    assert.isNonNegativeInteger(key_count, 'key_count');
+    assert.isNonNegativeInteger(stride, 'stride');
+    assert.isNonNegativeInteger(val_offset, 'val_offset');
+    assert.lessThanOrEqual(val_offset + 4, stride, 'a quaternion must fit inside the block');
+
+    if (key_count >= 1 && rest_rotation !== undefined) {
+        const rest_dot =
+            values[val_offset + 0] * rest_rotation.x +
+            values[val_offset + 1] * rest_rotation.y +
+            values[val_offset + 2] * rest_rotation.z +
+            values[val_offset + 3] * rest_rotation.w;
+
+        if (rest_dot < 0) {
+            // Negate the whole first keyframe block (value + tangents); the loop below carries the flip
+            // through the remaining keyframes.
+            for (let i = 0; i < stride; i++) {
+                values[i] = -values[i];
+            }
+        }
+    }
+
+    for (let k = 1; k < key_count; k++) {
+        const prev_base = (k - 1) * stride + val_offset;
+        const cur_base = k * stride + val_offset;
+
+        const dot =
+            values[prev_base + 0] * values[cur_base + 0] +
+            values[prev_base + 1] * values[cur_base + 1] +
+            values[prev_base + 2] * values[cur_base + 2] +
+            values[prev_base + 3] * values[cur_base + 3];
+
+        if (dot < 0) {
+            // Flip the whole keyframe block (value + tangents).
+            const start = k * stride;
+            const end = start + stride;
+
+            for (let i = start; i < end; i++) {
+                values[i] = -values[i];
+            }
+        }
+    }
+}

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

@@ -1,6 +1,17 @@
 /**
  * Based on GDC talk from Bungie on destiny, compressing quaternions for animation
  *
+ * The WGSL mirror is `chunk_quat_encode_u32`, whose docblock points back here. Both choose the component
+ * to drop through {@link v4_max_axis} / `v4_max_axis` so that they agree on a tie; this function used to
+ * inline its own comparison chain, which broke ties the other way, so for `|x| = |y| = 0.6`,
+ * `|z| = |w| = 0.1` the CPU dropped x and the GPU dropped y and the same quaternion encoded to two
+ * different words. Both decode correctly either way, so nothing broke until something compared a
+ * CPU-encoded row with a GPU-encoded one.
+ *
+ * The three 10-bit payloads still differ by up to one step between the two, and cannot not: the
+ * normalisation runs in f64 here and f32 in the shader. `quat_encode_u32_parity.spec` holds the pair to
+ * the same dropped component exactly, and to one step on the payload.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  *

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

@@ -1 +1 @@
-{"version":3,"file":"quat3_encode_to_uint32.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_encode_to_uint32.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,0CANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAgGlB"}
+{"version":3,"file":"quat3_encode_to_uint32.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_encode_to_uint32.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0CANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAgElB"}

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

@@ -1,9 +1,21 @@
 import { assert } from "../../../assert.js";
 import { v4_length } from "../../vec4/v4_length.js";
+import { v4_max_axis } from "../../vec4/v4_max_axis.js";
 
 /**
  * Based on GDC talk from Bungie on destiny, compressing quaternions for animation
  *
+ * The WGSL mirror is `chunk_quat_encode_u32`, whose docblock points back here. Both choose the component
+ * to drop through {@link v4_max_axis} / `v4_max_axis` so that they agree on a tie; this function used to
+ * inline its own comparison chain, which broke ties the other way, so for `|x| = |y| = 0.6`,
+ * `|z| = |w| = 0.1` the CPU dropped x and the GPU dropped y and the same quaternion encoded to two
+ * different words. Both decode correctly either way, so nothing broke until something compared a
+ * CPU-encoded row with a GPU-encoded one.
+ *
+ * The three 10-bit payloads still differ by up to one step between the two, and cannot not: the
+ * normalisation runs in f64 here and f32 in the shader. `quat_encode_u32_parity.spec` holds the pair to
+ * the same dropped component exactly, and to one step on the payload.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  *
@@ -15,42 +27,10 @@ import { v4_length } from "../../vec4/v4_length.js";
  */
 export function quat3_encode_to_uint32(x, y, z, w) {
 
-    const absX = Math.abs(x);
-    const absY = Math.abs(y);
-    const absZ = Math.abs(z);
-    const absW = Math.abs(w);
-
-    let v0, v1, v2, dropped, max;
+    let v0, v1, v2, dropped;
 
     //pick max component
-    if (absY > absX) {
-        if (absY > absZ) {
-            if (absY > absW) {
-                //absY is max
-                max = 1;
-            } else {
-                //absW is max
-                max = 3;
-            }
-        } else if (absZ > absW) {
-            //absZ is max
-            max = 2;
-        } else {
-            //absW is max
-            max = 3;
-        }
-    } else if (absX > absZ) {
-        if (absX > absW) {
-            max = 0;
-        } else {
-            max = 3;
-        }
-    } else if (absZ > absW) {
-        max = 2;
-    } else {
-        max = 3;
-    }
-
+    const max = v4_max_axis(Math.abs(x), Math.abs(y), Math.abs(z), Math.abs(w));
 
     //max will be dropped
     if (max === 0) {

package/src/core/geom/3d/shape/PosedShape3D.d.ts

@@ -80,6 +80,15 @@ export class PosedShape3D extends AbstractShape3D {
      * @returns {boolean}
      */
     contains_point(point: number[] | Float32Array | Float64Array): boolean;
+    /**
+     * The base class's `equals` is a constructor check and its `hash` is a constant 0 - a template
+     * every concrete shape narrows. Without this, two posed shapes holding different subjects at
+     * different poses compare equal and land in one bucket.
+     *
+     * @param {PosedShape3D} other
+     * @returns {boolean}
+     */
+    equals(other: PosedShape3D): boolean;
     /**
      * Fast type-check marker, mirroring `SphereShape3D.prototype.isSphereShape3D` and friends.
      * @readonly

package/src/core/geom/3d/shape/PosedShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACH,wBATW,eAAe,MACf,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAMhB;IA+HD,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCA5Q+B,sBAAsB"}
+{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACH,wBATW,eAAe,MACf,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAMhB;IA+HD,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAED;;;;;;;OAOG;IACH,cAHW,YAAY,GACV,OAAO,CAoBnB;IAiBL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCAtT+B,sBAAsB"}

package/src/core/geom/3d/shape/PosedShape3D.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../assert.js";
+import { computeHashFloatArray } from "../../../math/hash/computeHashFloatArray.js";
 import { v3_quaternion_apply } from "../../vec3/v3_quaternion_apply.js";
 import { v3_quaternion_apply_inverse } from "../../vec3/v3_quaternion_apply_inverse.js";
 import { aabb3_transform_oriented } from "../aabb/aabb3_transform_oriented.js";
@@ -271,6 +272,48 @@ export class PosedShape3D extends AbstractShape3D {
         this.#world_point_to_local(point);
         return this.shape.contains_point(scratch_local);
     }
+
+    /**
+     * The base class's `equals` is a constructor check and its `hash` is a constant 0 - a template
+     * every concrete shape narrows. Without this, two posed shapes holding different subjects at
+     * different poses compare equal and land in one bucket.
+     *
+     * @param {PosedShape3D} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (!super.equals(other)) {
+            return false;
+        }
+
+        if (this.shape === null || other.shape === null) {
+            return this.shape === other.shape;
+        }
+
+        return this.shape.equals(other.shape)
+            && this.px === other.px
+            && this.py === other.py
+            && this.pz === other.pz
+            && this.qx === other.qx
+            && this.qy === other.qy
+            && this.qz === other.qz
+            && this.qw === other.qw
+            ;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        const pose_hash = computeHashFloatArray([
+            this.px, this.py, this.pz,
+            this.qx, this.qy, this.qz, this.qw
+        ]);
+
+        const subject_hash = this.shape === null ? 0 : this.shape.hash();
+
+        return ((pose_hash << 5) - pose_hash) + subject_hash;
+    }
 }
 
 /**

package/src/core/geom/3d/shape/UnionShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA4BA;IAkII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGAyBC;IAiED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCApZ+B,sBAAsB"}
+{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA4BA;IAkII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGA0CC;IAiED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCAra+B,sBAAsB"}