@woosh/meep-engine 3.30.0 → 3.31.0

package/src/core/geom/3d/cone/cone_compute_plane_side.js

@@ -48,18 +48,37 @@ export function cone_compute_plane_side(
     V1._crossVectors(plane_normal_x, plane_normal_y, plane_normal_z, directionX, directionY, directionZ);
     V2._crossVectors(V1.x, V1.y, V1.z, directionX, directionY, directionZ);
 
+    // `V2 = (n x f) x f = f(n·f) - n` has `V2·n = (n·f)^2 - 1 <= 0`, so `+V2` always points away
+    // from the plane normal and its length is `sin` of the angle between `n` and `f` rather than 1.
+    // Normalising makes the two extreme rim points land on the rim; a zero `V2` means the axis is
+    // parallel to the normal, where every rim point is the same distance from the plane and the
+    // cap centre stands for all of them.
+    const v2_length = Math.sqrt(V2.x * V2.x + V2.y * V2.y + V2.z * V2.z);
+
+    if (v2_length > 0) {
+        const inv = 1 / v2_length;
+
+        V2.set(V2.x * inv, V2.y * inv, V2.z * inv);
+    }
+
     const scaled_cos = length * Math.cos(angle);
     const scaled_sin = length * Math.sin(angle);
 
-    // compute cap rim point (closest point to the plane on the wide side of the cone)
-    V1.set(
-        originX + scaled_cos * directionX + scaled_sin * V2.x,
-        originY + scaled_cos * directionY + scaled_sin * V2.y,
-        originZ + scaled_cos * directionZ + scaled_sin * V2.z
+    const cap_x = originX + scaled_cos * directionX;
+    const cap_y = originY + scaled_cos * directionY;
+    const cap_z = originZ + scaled_cos * directionZ;
+
+    // The cone is the convex hull of its apex and its rim circle, so the two rim points along
+    // +/- V2 bracket the whole rim in the normal's direction. Sampling only `+V2` — the LOWEST rim
+    // point — said nothing about the highest, so a cone straddling the plane at a shallow axis
+    // angle reported -2, "entirely below", which for a frustum plane is a cull verdict.
+    const rim_low_side = v4_dot(
+        cap_x + scaled_sin * V2.x, cap_y + scaled_sin * V2.y, cap_z + scaled_sin * V2.z, 1,
+        plane_normal_x, plane_normal_y, plane_normal_z, plane_constant
     );
 
-    const rim_point_side = v4_dot(
-        V1.x, V1.y, V1.z, 1,
+    const rim_high_side = v4_dot(
+        cap_x - scaled_sin * V2.x, cap_y - scaled_sin * V2.y, cap_z - scaled_sin * V2.z, 1,
         plane_normal_x, plane_normal_y, plane_normal_z, plane_constant
     );
 
@@ -68,19 +87,12 @@ export function cone_compute_plane_side(
         plane_normal_x, plane_normal_y, plane_normal_z, plane_constant
     );
 
-    let result = 0;
-
-    if (rim_point_side >= 0) {
-        result += 1;
-    } else {
-        result -= 1;
-    }
+    const any_above = rim_low_side >= 0 || rim_high_side >= 0 || origin_point_side >= 0;
+    const any_below = rim_low_side < 0 || rim_high_side < 0 || origin_point_side < 0;
 
-    if (origin_point_side >= 0) {
-        result += 1;
-    } else {
-        result -= 1;
+    if (any_above && any_below) {
+        return 0;
     }
 
-    return result;
+    return any_above ? 2 : -2;
 }

package/src/core/geom/3d/equirectangular/equirectangular_direction_to_uv.d.ts

@@ -1,6 +1,16 @@
 /**
  * Convert a unit direction (+Y up) to an equirectangular UV, matching three.js'
- * `equirectUv`. Inverse of {@link equirectangular_uv_to_direction}.
+ * `equirectUv`. Inverse of {@link equirectangular_uv_to_direction}. *
+ * ## Not the only equirectangular convention in the tree
+ *
+ * The environment bake in `shade/renderer/light/environment` uses the other one —
+ * `equirectangular_zenith_first_direction_to_uv`, where v = 0 is the zenith and longitude runs from +Z —
+ * because that is what the HDRI path was built and measured against. This family matches three.js so a
+ * texture authored for `EquirectangularReflectionMapping` reads correctly through it.
+ *
+ * The two are self-consistent and not interchangeable: mixing them gives an environment flipped
+ * vertically and rotated ninety degrees in azimuth. `equirectangular_conventions.spec` pins that they
+ * differ, so neither is unified into the other by mistake.
  *
  * @param {number} x
  * @param {number} y

package/src/core/geom/3d/equirectangular/equirectangular_direction_to_uv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"equirectangular_direction_to_uv.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/equirectangular/equirectangular_direction_to_uv.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,mDANW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,eACrB,MAAM,QAKhB"}
+{"version":3,"file":"equirectangular_direction_to_uv.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/equirectangular/equirectangular_direction_to_uv.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,mDANW,MAAM,KACN,MAAM,KACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,eACrB,MAAM,QAKhB"}

package/src/core/geom/3d/equirectangular/equirectangular_direction_to_uv.js

@@ -4,7 +4,17 @@ const TWO_PI = Math.PI * 2;
 
 /**
  * Convert a unit direction (+Y up) to an equirectangular UV, matching three.js'
- * `equirectUv`. Inverse of {@link equirectangular_uv_to_direction}.
+ * `equirectUv`. Inverse of {@link equirectangular_uv_to_direction}. *
+ * ## Not the only equirectangular convention in the tree
+ *
+ * The environment bake in `shade/renderer/light/environment` uses the other one —
+ * `equirectangular_zenith_first_direction_to_uv`, where v = 0 is the zenith and longitude runs from +Z —
+ * because that is what the HDRI path was built and measured against. This family matches three.js so a
+ * texture authored for `EquirectangularReflectionMapping` reads correctly through it.
+ *
+ * The two are self-consistent and not interchangeable: mixing them gives an environment flipped
+ * vertically and rotated ninety degrees in azimuth. `equirectangular_conventions.spec` pins that they
+ * differ, so neither is unified into the other by mistake.
  *
  * @param {number} x
  * @param {number} y

package/src/core/geom/3d/equirectangular/equirectangular_uv_to_direction.d.ts

@@ -3,7 +3,17 @@
  * `equirectUv` so it can be used with EquirectangularReflectionMapping textures.
  *
  *   u = atan2(z, x) / (2pi) + 0.5
- *   v = asin(y) / pi + 0.5
+ *   v = asin(y) / pi + 0.5 *
+ * ## Not the only equirectangular convention in the tree
+ *
+ * The environment bake in `shade/renderer/light/environment` uses the other one —
+ * `equirectangular_zenith_first_direction_to_uv`, where v = 0 is the zenith and longitude runs from +Z —
+ * because that is what the HDRI path was built and measured against. This family matches three.js so a
+ * texture authored for `EquirectangularReflectionMapping` reads correctly through it.
+ *
+ * The two are self-consistent and not interchangeable: mixing them gives an environment flipped
+ * vertically and rotated ninety degrees in azimuth. `equirectangular_conventions.spec` pins that they
+ * differ, so neither is unified into the other by mistake.
  *
  * @param {number} u in [0, 1]
  * @param {number} v in [0, 1]

package/src/core/geom/3d/equirectangular/equirectangular_uv_to_direction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"equirectangular_uv_to_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/equirectangular/equirectangular_uv_to_direction.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,mDALW,MAAM,KACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,eACrB,MAAM,QAWhB"}
+{"version":3,"file":"equirectangular_uv_to_direction.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/equirectangular/equirectangular_uv_to_direction.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,mDALW,MAAM,KACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,eACrB,MAAM,QAWhB"}

package/src/core/geom/3d/equirectangular/equirectangular_uv_to_direction.js

@@ -5,7 +5,17 @@ const TWO_PI = Math.PI * 2;
  * `equirectUv` so it can be used with EquirectangularReflectionMapping textures.
  *
  *   u = atan2(z, x) / (2pi) + 0.5
- *   v = asin(y) / pi + 0.5
+ *   v = asin(y) / pi + 0.5 *
+ * ## Not the only equirectangular convention in the tree
+ *
+ * The environment bake in `shade/renderer/light/environment` uses the other one —
+ * `equirectangular_zenith_first_direction_to_uv`, where v = 0 is the zenith and longitude runs from +Z —
+ * because that is what the HDRI path was built and measured against. This family matches three.js so a
+ * texture authored for `EquirectangularReflectionMapping` reads correctly through it.
+ *
+ * The two are self-consistent and not interchangeable: mixing them gives an environment flipped
+ * vertically and rotated ninety degrees in azimuth. `equirectangular_conventions.spec` pins that they
+ * differ, so neither is unified into the other by mistake.
  *
  * @param {number} u in [0, 1]
  * @param {number} v in [0, 1]

package/src/core/geom/3d/frustum/frustum3_compute_closest_point.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frustum3_compute_closest_point.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum3_compute_closest_point.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;GAeG;AACH,uDAPW,OAAO,UACP,SAAS,YACT,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA+EnB;oBAnHmB,kBAAkB"}
+{"version":3,"file":"frustum3_compute_closest_point.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum3_compute_closest_point.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;GAeG;AACH,uDAPW,OAAO,UACP,SAAS,YACT,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA8HnB;oBA1KmB,kBAAkB"}

package/src/core/geom/3d/frustum/frustum3_compute_closest_point.js

@@ -21,6 +21,14 @@ const scratch_v3_1 = new Vector3();
  */
 const scratch_v3_array = [];
 
+/**
+ * How many projection rounds the four-or-more-planes fallback takes before it settles for where it
+ * has got to. Bounded rather than convergent: the loop must not be able to spin on a degenerate
+ * frustum.
+ * @type {number}
+ */
+const CLAMP_ITERATION_LIMIT = 32;
+
 /**
  * The point inside a convex frustum nearest to a target point, and whether the target was already
  * inside it.
@@ -111,6 +119,53 @@ export function frustum3_compute_closest_point(result, planes, target_x, target_
         );
 
         result.fromArray(scratch_v3_array, 0)
+    } else {
+        // Four or more violated planes has no closed form here, and a perspective frustum reaches
+        // that easily: its side planes all pass through the apex, so any point behind the camera is
+        // outside near, left, right, top and bottom at once. Falling out of the chain left `result`
+        // holding whatever the caller's vector had — with a reused scratch, the *previous* query's
+        // answer, which reads as a plausibly placed point rather than as a failure.
+        //
+        // Walk the point back in by repeatedly projecting it onto whichever plane it violates
+        // most. For a convex body that converges into the intersection; it is not guaranteed to be
+        // the exact nearest point, but it is inside, and it is written.
+        let px = target_x;
+        let py = target_y;
+        let pz = target_z;
+
+        for (let iteration = 0; iteration < CLAMP_ITERATION_LIMIT; iteration++) {
+            let worst_plane = -1;
+            let worst_distance = 0;
+
+            for (j = 0; j < plane_count; j++) {
+                const plane = planes[j];
+
+                const distance = v3_distance_above_plane(
+                    px, py, pz,
+                    plane.x, plane.y, plane.z, plane.w
+                );
+
+                if (distance < worst_distance) {
+                    worst_distance = distance;
+                    worst_plane = j;
+                }
+            }
+
+            if (worst_plane === -1) {
+                // inside every plane
+                break;
+            }
+
+            const plane = planes[worst_plane];
+
+            plane3_project_point(scratch_v3_0, px, py, pz, plane.x, plane.y, plane.z, plane.w);
+
+            px = scratch_v3_0.x;
+            py = scratch_v3_0.y;
+            pz = scratch_v3_0.z;
+        }
+
+        result.set(px, py, pz);
     }
 
     return false;

package/src/core/geom/3d/frustum/frustum_from_projection_matrix_array.d.ts

@@ -1,6 +1,20 @@
 /**
  *
  * Set frustum from projection matrix
+ *
+ * **Depth range 0..1**, which is what every projection in this engine produces — see the note on
+ * `m4_perspective`, which spells out that Shade's cameras are an infinite reverse-Z over 0..1.
+ * Gribb-Hartmann as published assumes OpenGL's -1..1, where the near plane is `row3 + row2`; that
+ * is what this used to extract, and for a 0..1 projection it is the plane at z_ndc = -1, which sits
+ * behind the camera and constrains nothing. Feeding the engine's own
+ * `m4_orthographic_off_center_z0(m, -1,1, -1,1, 0,1)` through it bounded the slab z in [-1, 1]
+ * instead of [0, 1], so a box behind the camera passed the clipping test. The engine's other
+ * extraction, `construct_frustum_planes` on the camera, carries the comment "Row 2 ONLY (Not Row 3
+ * + Row 2)" for exactly this reason.
+ *
+ * The four SIDE planes are the same under either convention, which is why the one production
+ * caller — DirectionalLightShadowmap, which takes `subarray(0, 16)` — is unaffected.
+ *
  * NOTE: uses Gribb/Hartmann method
  * @see "Fast Extraction of Viewing Frustum Planes from the WorldView-Projection Matrix", 2001 by Gribb & Hartmann
  * @param {number[]|Float32Array} frustum_planes tuples of 4, where each tuple is a plane normal (x,y,z) followed by a planar offset constant [normal_x, normal_y, normal_z, constant]

package/src/core/geom/3d/frustum/frustum_from_projection_matrix_array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frustum_from_projection_matrix_array.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum_from_projection_matrix_array.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qEAHW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,EAAE,QAuClB"}
+{"version":3,"file":"frustum_from_projection_matrix_array.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/frustum/frustum_from_projection_matrix_array.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qEAHW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,EAAE,QAyClB"}

package/src/core/geom/3d/frustum/frustum_from_projection_matrix_array.js

@@ -4,6 +4,20 @@ import { plane3_normalize } from "../plane/plane3_normalize.js";
 /**
  *
  * Set frustum from projection matrix
+ *
+ * **Depth range 0..1**, which is what every projection in this engine produces — see the note on
+ * `m4_perspective`, which spells out that Shade's cameras are an infinite reverse-Z over 0..1.
+ * Gribb-Hartmann as published assumes OpenGL's -1..1, where the near plane is `row3 + row2`; that
+ * is what this used to extract, and for a 0..1 projection it is the plane at z_ndc = -1, which sits
+ * behind the camera and constrains nothing. Feeding the engine's own
+ * `m4_orthographic_off_center_z0(m, -1,1, -1,1, 0,1)` through it bounded the slab z in [-1, 1]
+ * instead of [0, 1], so a box behind the camera passed the clipping test. The engine's other
+ * extraction, `construct_frustum_planes` on the camera, carries the comment "Row 2 ONLY (Not Row 3
+ * + Row 2)" for exactly this reason.
+ *
+ * The four SIDE planes are the same under either convention, which is why the one production
+ * caller — DirectionalLightShadowmap, which takes `subarray(0, 16)` — is unaffected.
+ *
  * NOTE: uses Gribb/Hartmann method
  * @see "Fast Extraction of Viewing Frustum Planes from the WorldView-Projection Matrix", 2001 by Gribb & Hartmann
  * @param {number[]|Float32Array} frustum_planes tuples of 4, where each tuple is a plane normal (x,y,z) followed by a planar offset constant [normal_x, normal_y, normal_z, constant]
@@ -44,6 +58,8 @@ export function frustum_from_projection_matrix_array(frustum_planes, m4) {
     const me10 = m4[10];
     const me14 = m4[14];
 
+    // z_ndc <= 1
     plane3_normalize(frustum_planes, 16, me3 - me2, me7 - me6, me11 - me10, me15 - me14);
-    plane3_normalize(frustum_planes, 20, me3 + me2, me7 + me6, me11 + me10, me15 + me14);
+    // z_ndc >= 0 — row 2 alone, not row 3 + row 2
+    plane3_normalize(frustum_planes, 20, me2, me6, me10, me14);
 }

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

@@ -5,6 +5,21 @@
  * in the Minkowski difference space. If the origin is enclosed by the simplex,
  * the shapes intersect.
  *
+ * ## The other GJK in this directory, and when to prefer it
+ *
+ * `gjk_epa_penetration.js` carries a second simplex solver over the same `minkowski_support` — the
+ * Muratori slot-0 convention against this file's C-slot one — and a tri-state verdict. Prefer it for
+ * anything that cares about a **touching** contact: this function returns `false` when the iteration cap
+ * is reached or the search direction collapses, and the direction collapses precisely when the origin
+ * lands exactly on a simplex feature, which is a touch (two spheres at exactly 2r). Reporting that as
+ * "not intersecting" is an overclaim, and the other file spends a paragraph on why.
+ *
+ * The two must keep agreeing on everything else. `gjk_solvers_agree.spec` holds them to it over 20,000
+ * random pairs; measured over 60,000 when it was written, they never contradicted each other. That
+ * matters because each has had the same class of bug fixed separately — the slot-management regression
+ * documented below produced false-positive sphere overlaps here, and the touching-verdict problem was
+ * fixed there.
+ *
  * Adapted from https://github.com/kevinmoran/GJK/blob/master/GJK.h
  *
  * @param {number[]|Float64Array} simplex Working buffer for simplex vertices (4 vec3s). Must have length >= 12.

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

@@ -1 +1 @@
-{"version":3,"file":"gjk.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/gjk.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;GAaG;AACH,6BALW,MAAM,EAAE,GAAC,YAAY,uDAGnB,OAAO,CAWnB"}
+{"version":3,"file":"gjk.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/gjk.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,6BALW,MAAM,EAAE,GAAC,YAAY,uDAGnB,OAAO,CAWnB"}

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

@@ -22,6 +22,21 @@ const scratch_dir = new Float64Array(3);
  * in the Minkowski difference space. If the origin is enclosed by the simplex,
  * the shapes intersect.
  *
+ * ## The other GJK in this directory, and when to prefer it
+ *
+ * `gjk_epa_penetration.js` carries a second simplex solver over the same `minkowski_support` — the
+ * Muratori slot-0 convention against this file's C-slot one — and a tri-state verdict. Prefer it for
+ * anything that cares about a **touching** contact: this function returns `false` when the iteration cap
+ * is reached or the search direction collapses, and the direction collapses precisely when the origin
+ * lands exactly on a simplex feature, which is a touch (two spheres at exactly 2r). Reporting that as
+ * "not intersecting" is an overclaim, and the other file spends a paragraph on why.
+ *
+ * The two must keep agreeing on everything else. `gjk_solvers_agree.spec` holds them to it over 20,000
+ * random pairs; measured over 60,000 when it was written, they never contradicted each other. That
+ * matters because each has had the same class of bug fixed separately — the slot-management regression
+ * documented below produced false-positive sphere overlaps here, and the touching-verdict problem was
+ * fixed there.
+ *
  * Adapted from https://github.com/kevinmoran/GJK/blob/master/GJK.h
  *
  * @param {number[]|Float64Array} simplex Working buffer for simplex vertices (4 vec3s). Must have length >= 12.

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":"AA2iBA;;;;;;;;;;;;;;;;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,MAAM,QAAE,MAAM,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":"AA6jBA;;;;;;;;;;;;;;;;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,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,IAAI,CAAA;CAAE"}

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

@@ -14,6 +14,24 @@ import { v3_triple_cross } from "../../vec3/v3_triple_cross.js";
  * returned a non-minimal axis for polytopes because its GJK handed EPA a
  * degenerate (origin-on-face) simplex (see memory: feedback_epa_unreliable_polytopes).
  *
+ * ## The other GJK in this directory
+ *
+ * That replacement was of the *penetration* pair, and it completed —
+ * `gjk_with_axis` and `expanding_polytope_algorithm.js` are both gone. What survives beside this file
+ * is a separate entry point, not the remains of a half-done migration: `gjk.js` exports a **boolean**
+ * `gjk`, live via `engine/physics/queries/overlap_shape` and `shape_cast`, and carries its own simplex
+ * solver — the C-slot convention, `update_simplex_triangle` / `update_simplex_tetrahedron` — where the
+ * private `gjk` below uses the Muratori slot-0 one.
+ *
+ * So there are two simplex solvers over one `minkowski_support`, and they must keep agreeing.
+ * `gjk_solvers_agree.spec` is what holds them to it: over 20,000 random box/sphere/capsule pairs neither
+ * may contradict the other. Measured over 60,000 when that spec was written, they never did.
+ *
+ * The one thing they are allowed to differ on is this file's {@link GJK_INCONCLUSIVE} exit — "no verdict"
+ * — which the boolean one has no way to express and answers `false` for. That is
+ * `gjk.js`'s documented overclaim, and it is the reason to prefer this entry point for anything that
+ * cares about a touching contact.
+ *
  * Structure follows Bullet's btGjkEpa2: GJK produces a rank-4 simplex that
  * strictly encloses the origin; EPA builds outward-oriented faces from it and
  * expands toward the closest face, rebuilding the horizon each step. Operates on

package/src/core/geom/3d/hash-grid/PointHashGrid3.d.ts

@@ -46,6 +46,29 @@
  * {@link forEachNear} skips a bucket it has already visited, which is a scan over
  * at most 27 numbers and removes the whole class.
  *
+ * ## Walking the buckets directly, and what that owes
+ *
+ * `offset` and `point` are public so a caller in a hot loop can walk the
+ * neighbourhood itself rather than pay a call per point. `cloth_self_find` does,
+ * in both of its passes, and this is the contract it is taking on rather than an
+ * oversight:
+ *
+ *  - **the neighbourhood is 27 cells**, the cell the query point falls in and its
+ *    26 face, edge and corner neighbours — `floor(x / cell_size)` and plus or minus
+ *    one on each axis. Fewer and a contact across a cell boundary is missed;
+ *  - **de-duplicate the buckets.** Two of the 27 cells can hash to one bucket, most
+ *    easily on a small table, and visiting it twice hands back every point in it
+ *    twice. A linear scan over the buckets already visited is the whole of it —
+ *    there are at most 27. This is the subtle part, and the one a direct walker is
+ *    most likely to leave out;
+ *  - **check the actual distance**, as every caller of this class must.
+ *
+ * {@link forEachNear} is the executable statement of all three, and its spec is
+ * where they are pinned. A direct walker is expected to match it, and to have a
+ * reason for not calling it — `cloth_self_find`'s is that its inner loops carry a
+ * per-candidate budget check that reads better as a loop condition than as a
+ * visitor returning `false`, and that it is the hottest loop in the solver.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -97,13 +120,19 @@ export class PointHashGrid3 {
      * Points from other cells may be handed back — see the class docblock on
      * hash collisions — and the visitor is expected to check the distance.
      *
+     * Returning `false` from the visitor stops the walk. Without that a search
+     * with a budget — the first k neighbours, the nearest one — could not be
+     * written through this method at all and had to walk the buckets itself,
+     * which is what `cloth_self_find` does. Any other return value, `undefined`
+     * included, continues.
+     *
      * @param {number} x
      * @param {number} y
      * @param {number} z
-     * @param {function(number): void} visit
-     * @returns {void}
+     * @param {function(number): (boolean|void)} visit
+     * @returns {boolean} `false` if the visitor stopped the walk
      */
-    forEachNear(x: number, y: number, z: number, visit: (arg0: number) => void): void;
+    forEachNear(x: number, y: number, z: number, visit: (arg0: number) => (boolean | void)): boolean;
     /**
      * The bucket a cell falls in. For a caller walking buckets itself.
      *

package/src/core/geom/3d/hash-grid/PointHashGrid3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PointHashGrid3.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/hash-grid/PointHashGrid3.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH;IAEI;;;;;OAKG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;OAQG;IACH,QAFU,UAAU,CAEO;IAE3B;;;OAGG;IACH,OAFU,UAAU,CAEM;IAQ1B;;;OAGG;IACH,0BAEC;IAED;;;;;;;OAOG;IACH,gBALW,YAAY,GAAC,YAAY,SACzB,MAAM,aACN,MAAM,GACJ,IAAI,CA0EhB;IAED;;;;;;;;;;;OAWG;IACH,eANW,MAAM,KACN,MAAM,KACN,MAAM,gBACG,MAAM,KAAG,IAAI,GACpB,IAAI,CAiDhB;IAED;;;;;;;OAOG;IACH,aALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;;CACJ"}
+{"version":3,"file":"PointHashGrid3.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/hash-grid/PointHashGrid3.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH;IAEI;;;;;OAKG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;OAQG;IACH,QAFU,UAAU,CAEO;IAE3B;;;OAGG;IACH,OAFU,UAAU,CAEM;IAQ1B;;;OAGG;IACH,0BAEC;IAED;;;;;;;OAOG;IACH,gBALW,YAAY,GAAC,YAAY,SACzB,MAAM,aACN,MAAM,GACJ,IAAI,CA0EhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,eANW,MAAM,KACN,MAAM,KACN,MAAM,gBACG,MAAM,KAAG,CAAC,OAAO,GAAC,IAAI,CAAC,GAC9B,OAAO,CAqDnB;IAED;;;;;;;OAOG;IACH,aALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;;CACJ"}

package/src/core/geom/3d/hash-grid/PointHashGrid3.js

@@ -48,6 +48,29 @@ import { assert } from "../../../assert.js";
  * {@link forEachNear} skips a bucket it has already visited, which is a scan over
  * at most 27 numbers and removes the whole class.
  *
+ * ## Walking the buckets directly, and what that owes
+ *
+ * `offset` and `point` are public so a caller in a hot loop can walk the
+ * neighbourhood itself rather than pay a call per point. `cloth_self_find` does,
+ * in both of its passes, and this is the contract it is taking on rather than an
+ * oversight:
+ *
+ *  - **the neighbourhood is 27 cells**, the cell the query point falls in and its
+ *    26 face, edge and corner neighbours — `floor(x / cell_size)` and plus or minus
+ *    one on each axis. Fewer and a contact across a cell boundary is missed;
+ *  - **de-duplicate the buckets.** Two of the 27 cells can hash to one bucket, most
+ *    easily on a small table, and visiting it twice hands back every point in it
+ *    twice. A linear scan over the buckets already visited is the whole of it —
+ *    there are at most 27. This is the subtle part, and the one a direct walker is
+ *    most likely to leave out;
+ *  - **check the actual distance**, as every caller of this class must.
+ *
+ * {@link forEachNear} is the executable statement of all three, and its spec is
+ * where they are pinned. A direct walker is expected to match it, and to have a
+ * reason for not calling it — `cloth_self_find`'s is that its inner loops carry a
+ * per-candidate budget check that reads better as a loop condition than as a
+ * visitor returning `false`, and that it is the hottest loop in the solver.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -186,11 +209,17 @@ export class PointHashGrid3 {
      * Points from other cells may be handed back — see the class docblock on
      * hash collisions — and the visitor is expected to check the distance.
      *
+     * Returning `false` from the visitor stops the walk. Without that a search
+     * with a budget — the first k neighbours, the nearest one — could not be
+     * written through this method at all and had to walk the buckets itself,
+     * which is what `cloth_self_find` does. Any other return value, `undefined`
+     * included, continues.
+     *
      * @param {number} x
      * @param {number} y
      * @param {number} z
-     * @param {function(number): void} visit
-     * @returns {void}
+     * @param {function(number): (boolean|void)} visit
+     * @returns {boolean} `false` if the visitor stopped the walk
      */
     forEachNear(x, y, z, visit) {
         const inverse = 1 / this.cell_size;
@@ -234,11 +263,15 @@ export class PointHashGrid3 {
                     const end = offset[bucket + 1];
 
                     for (let at = offset[bucket]; at < end; at++) {
-                        visit(point[at]);
+                        if (visit(point[at]) === false) {
+                            return false;
+                        }
                     }
                 }
             }
         }
+
+        return true;
     }
 
     /**

package/src/core/geom/3d/morton/v3_morton_encode_lut.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_morton_encode_lut.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/morton/v3_morton_encode_lut.js"],"names":[],"mappings":"AAkHA;;;;;;;;;GASG;AACH,wCALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAoBlB"}
+{"version":3,"file":"v3_morton_encode_lut.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/morton/v3_morton_encode_lut.js"],"names":[],"mappings":"AAkHA;;;;;;;;;GASG;AACH,wCALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA2BlB"}

package/src/core/geom/3d/morton/v3_morton_encode_lut.js

@@ -123,10 +123,17 @@ morton256_z.set([
  * @returns {number}
  */
 export function v3_morton_encode_lut(x, y, z) {
-    // convert to integers
-    const ix = x | 0;
-    const iy = y | 0;
-    const iz = z | 0;
+    // Ten bits per axis, the same window `split_by_3` gives {@link v3_morton_encode_magicbits},
+    // which the shared docblock says this mirrors.
+    //
+    // This is a transcription of libmorton's 64-bit C++ form, where the top byte reaches bit 45.
+    // JavaScript's `<<` is a 32-bit *signed* operation, so anything above the low 8 bits of
+    // `answer` was discarded and bit 31 became the sign: `(0, 1024, 0)` returned -2147483648 where
+    // magicbits returns 0, and `(0, 0, 1024)` returned 0 with bit 32 dropped. Masking to 10 bits
+    // keeps the whole computation inside 30 bits, where it is exact and agrees with the twin.
+    const ix = (x | 0) & 0x3FF;
+    const iy = (y | 0) & 0x3FF;
+    const iz = (z | 0) & 0x3FF;
 
     // shift top bytes
     let answer = morton256_z[(iz >> 8) & 0xFF] | // we start by shifting the third byte, since we only look at the first 21 bits

package/src/core/geom/3d/morton/v3_morton_encode_normalized.d.ts

@@ -1,8 +1,20 @@
 /**
- * Note: does not clamp, make sure that inputs are within 0..1 range.
- * @param {number} x value between 0 and 1
- * @param {number} y value between 0 and 1
- * @param {number} z value between 0 and 1
+ * A Morton code for a point in the unit cube.
+ *
+ * **Saturating.** A coordinate outside 0..1 is clamped to the nearest face, which is monotone and
+ * is what a spatial sort wants — an out-of-range point sorts to an end, where it is visible.
+ *
+ * It used to be documented as "does not clamp" and what it actually did was worse than not
+ * clamping: `split_by_3` masks to ten bits, so an input above 1 wrapped modulo 1024 and landed on
+ * a SPECIFIC in-range cell, usually the origin. `v3_morton_encode_normalized(1.0005, 0, 0)`
+ * returned 0, the same code as (0, 0, 0). Through `v3_morton_encode_bounded` that is a centroid
+ * 0.06% outside its bounds reported as sitting at the min corner: it does not sort to an end where
+ * a builder would notice, it sorts into the middle of the wrong subtree and silently degrades the
+ * hierarchy. Seven LBVH and partitioning builders sort on that key.
+ *
+ * @param {number} x clamped to 0..1
+ * @param {number} y clamped to 0..1
+ * @param {number} z clamped to 0..1
  * @returns {number} morton code
  */
 export function v3_morton_encode_normalized(x: number, y: number, z: number): number;

package/src/core/geom/3d/morton/v3_morton_encode_normalized.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_morton_encode_normalized.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/morton/v3_morton_encode_normalized.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,+CALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAiBlB"}
+{"version":3,"file":"v3_morton_encode_normalized.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/morton/v3_morton_encode_normalized.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AACH,+CALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAiBlB"}

package/src/core/geom/3d/morton/v3_morton_encode_normalized.js

@@ -1,11 +1,24 @@
 import { assert } from "../../../assert.js";
+import { clamp01 } from "../../../math/clamp01.js";
 import v3_morton_encode from "./v3_morton_encode.js";
 
 /**
- * Note: does not clamp, make sure that inputs are within 0..1 range.
- * @param {number} x value between 0 and 1
- * @param {number} y value between 0 and 1
- * @param {number} z value between 0 and 1
+ * A Morton code for a point in the unit cube.
+ *
+ * **Saturating.** A coordinate outside 0..1 is clamped to the nearest face, which is monotone and
+ * is what a spatial sort wants — an out-of-range point sorts to an end, where it is visible.
+ *
+ * It used to be documented as "does not clamp" and what it actually did was worse than not
+ * clamping: `split_by_3` masks to ten bits, so an input above 1 wrapped modulo 1024 and landed on
+ * a SPECIFIC in-range cell, usually the origin. `v3_morton_encode_normalized(1.0005, 0, 0)`
+ * returned 0, the same code as (0, 0, 0). Through `v3_morton_encode_bounded` that is a centroid
+ * 0.06% outside its bounds reported as sitting at the min corner: it does not sort to an end where
+ * a builder would notice, it sorts into the middle of the wrong subtree and silently degrades the
+ * hierarchy. Seven LBVH and partitioning builders sort on that key.
+ *
+ * @param {number} x clamped to 0..1
+ * @param {number} y clamped to 0..1
+ * @param {number} z clamped to 0..1
  * @returns {number} morton code
  */
 export function v3_morton_encode_normalized(x, y, z) {
@@ -13,10 +26,10 @@ export function v3_morton_encode_normalized(x, y, z) {
     assert.isNumber(y, 'y');
     assert.isNumber(z, 'z');
 
-    // scale to 10 bits
-    const ndc_x = 1023 * x;
-    const ndc_y = 1023 * y;
-    const ndc_z = 1023 * z;
+    // scale to 10 bits, saturating rather than wrapping
+    const ndc_x = 1023 * clamp01(x);
+    const ndc_y = 1023 * clamp01(y);
+    const ndc_z = 1023 * clamp01(z);
 
     return v3_morton_encode(
         Math.round(ndc_x),

package/src/core/geom/3d/normal/spherical/encode_unit_to_spheremap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encode_unit_to_spheremap.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/normal/spherical/encode_unit_to_spheremap.js"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,iDANW,MAAM,EAAE,iBACR,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAehB"}
+{"version":3,"file":"encode_unit_to_spheremap.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/normal/spherical/encode_unit_to_spheremap.js"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,iDANW,MAAM,EAAE,iBACR,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QA6BhB"}