@woosh/meep-engine 3.38.0 → 3.40.0

package/src/engine/physics/narrowphase/refine_ray_concave.js

@@ -1,8 +1,8 @@
+import { COLUMN_CHILD_1, COLUMN_CHILD_2, COLUMN_USER_DATA, ELEMENT_WORD_COUNT, NULL_NODE } from "../../../core/bvh2/bvh3/BVH.js";
 import { v3_length } from "../../../core/geom/vec3/v3_length.js";
 import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
 import { v3_quaternion_apply_inverse } from "../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
-import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
-import { mesh_enumerate_triangles } from "./decomposition/mesh_enumerate_triangles.js";
+import { TRIANGLE_FEATURE_ID_OFFSET, TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
 import { heightmap_enumerate_triangles } from "./decomposition/heightmap_enumerate_triangles.js";
 
 /**
@@ -13,15 +13,21 @@ import { heightmap_enumerate_triangles } from "./decomposition/heightmap_enumera
  * local frame:
  *   1. clip the ray to the shape's local bounding box (a quick reject, and a
  *      finite query segment even when `tMax` is unbounded);
- *   2. enumerate the triangles overlapping that segment's AABB
- *      (`mesh_enumerate_triangles` / `heightmap_enumerate_triangles`);
+ *   2. gather the triangles overlapping that segment's AABB — a heightmap's
+ *      through `heightmap_enumerate_triangles`, a mesh's by walking its
+ *      surface BVH (see {@link walk_mesh}; the same triangles the mesh
+ *      enumerator would give, without scanning the mesh);
  *   3. two-sided Möller–Trumbore each, keeping the nearest crossing;
  *   4. return its distance and the world surface normal (the triangle's
  *      geometric normal, oriented to face the ray).
  *
- * The triangle scratch grows on saturation and is bounded by {@link MAX_TRIS}
- * (a ray crossing more triangles than that in one mesh is not a realistic
- * raycast — it would mean skewering a 65k-triangle mesh lengthwise).
+ * The heightmap's triangle scratch grows on saturation and is bounded by {@link MAX_TRIS}.
+ * A segment's box is not bounded by anything that small: a long shallow ray
+ * over terrain boxes in the terrain's whole area (256 m at 1 m cells is
+ * 131,072 triangles). Past the bound the segment is tested a piece at a time
+ * — each sized so its box fits — instead of being cut off; the scratch
+ * used to stop at 65,536 and drop the rest, so the ray missed any surface it
+ * met beyond them.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -35,14 +41,73 @@ const INITIAL_TRIS = 1024;
 const MAX_TRIS = 1 << 16;
 let tri_buf = new Float64Array(INITIAL_TRIS * TRIANGLE_FLOAT_STRIDE);
 
+/**
+ * Shortest piece of the clipped segment worth splitting further, as a fraction
+ * of the segment. A piece this short whose box still overlaps more than
+ * {@link MAX_TRIS} triangles is not a long ray, it is a pile of triangles in one
+ * spot; it is tested against the first {@link MAX_TRIS} and reported once.
+ * @type {number}
+ */
+const MIN_PIECE_FRACTION = 1 / (1 << 20);
+
+/**
+ * Whether a piece too short to split has overflowed (once per process).
+ * @type {boolean}
+ */
+let overflow_reported = false;
+
 const EPS = 1e-12;
 const AABB_FATTEN = 1e-5; // guards triangles whose AABB just abuts the segment
 
+/**
+ * How far past its entry into the shape's box, along its fastest axis, a ray
+ * with an unbounded reach is walked when nothing in the shape's bounds ends it:
+ * far past any surface a body could carry, and far enough short of float64's
+ * 1.8e308 that the segment's box stays finite.
+ * @type {number}
+ */
+const UNBOUNDED_REACH = 1e300;
+
+/**
+ * One float32 ULP, relative: BVH node boxes are float32, rounded to nearest
+ * from the mesh's positions, so a node test widened by this much (and then
+ * the exact float64 test at the leaf) can only admit, never lose, a triangle.
+ * @type {number}
+ */
+const F32_RELATIVE_SLACK = 1 / (1 << 23);
+
+/** Float32's largest finite value; a float64 position past it has an infinite BVH box bound. */
+const F32_MAX = 3.4028234663852886e38;
+
+// Overflow to ±Infinity by multiplying (3.4e38 × 1e300), not with the
+// `Infinity` constant, which makes V8 box the bounds (see the enumerator's).
+
+/** @param {number} max a widened query maximum @returns {number} */
+function f32_reach_up(max) {
+    return max >= F32_MAX ? max * 1e300 : max;
+}
+
+/** @param {number} min a widened query minimum @returns {number} */
+function f32_reach_down(min) {
+    return min <= -F32_MAX ? min * 1e300 : min;
+}
+
+/**
+ * {@link walk_mesh}'s own node stack. It must not be
+ * SCRATCH_UINT32_TRAVERSAL_STACK: the physics raycast reaches this from inside
+ * its broadphase walk, which keeps that stack's pointer in a local — a nested
+ * walk there writes over the entries it has yet to pop (it looped forever).
+ * At most one pending sibling per level, so near the tree's height; grown on
+ * demand.
+ * @type {Uint32Array}
+ */
+let stack = new Uint32Array(64);
+
 /**
  * @param {AbstractShape3D} shape  a concave shape (`is_convex === false`)
  * @param {ArrayLike<number>} position  body world position, indexed as
  *   [x, y, z] — read by index like `rotation`, so an `{x, y, z}` object
- *   sends a NaN ray into the decomposition and returns NaN
+ *   makes a NaN ray, which misses (`Infinity`)
  * @param {ArrayLike<number>} rotation  body rotation quaternion (x,y,z,w)
  * @param {number} ox  ray origin x (world)
  * @param {number} oy  ray origin y (world)
@@ -50,7 +115,7 @@ const AABB_FATTEN = 1e-5; // guards triangles whose AABB just abuts the segment
  * @param {number} dx  ray dir x (world, unit)
  * @param {number} dy  ray dir y (world, unit)
  * @param {number} dz  ray dir z (world, unit)
- * @param {number} tMax
+ * @param {number} tMax  reach; NaN reaches nothing (a miss)
  * @param {Float64Array|Vector3} outNormal  world surface normal, written on hit
  * @returns {number} hit distance, or `Infinity` on miss
  */
@@ -62,33 +127,215 @@ export function refine_ray_concave(shape, position, rotation, ox, oy, oz, dx, dy
     const lox = lo[0], loy = lo[1], loz = lo[2];
     const ldx = ld[0], ldy = ld[1], ldz = ld[2];
 
+    // A NaN anywhere in the ray (or the pose it was taken through), or an
+    // infinite direction, makes a NaN query box, which overlaps everything: the
+    // walks below would test the whole shape — and the heightmap's piece walk,
+    // splitting a box that never shrinks, would take a million pieces to finish.
+    // Such a ray crosses nothing. (An infinite origin is the clip's business.)
+    if (lox !== lox || loy !== loy || loz !== loz || !Number.isFinite(ldx + ldy + ldz)) return Infinity;
+
     // Clip the local ray to the shape's local AABB → segment [tEnter, tExit].
+    // Only an axis the ray does not move along at all is held to the origin's
+    // slab, as in walk_mesh: a component however small still crosses a face,
+    // and a large surface is met far along it (1 nm above a 200 km floor at
+    // 1e-13 a metre is a hit 10 km on; Möller–Trumbore's det there is 4e-3).
+    // Divided, not multiplied by a reciprocal: a subnormal component's
+    // reciprocal is infinite, and 0 × Infinity, an origin on a face, is NaN.
     shape.compute_bounding_box(bounds);
     let tEnter = 0, tExit = tMax;
-    if (ldx > EPS || ldx < -EPS) {
-        const inv = 1 / ldx;
-        let t1 = (bounds[0] - lox) * inv, t2 = (bounds[3] - lox) * inv;
+    if (ldx !== 0) {
+        let t1 = (bounds[0] - lox) / ldx, t2 = (bounds[3] - lox) / ldx;
         if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
         if (t1 > tEnter) tEnter = t1;
         if (t2 < tExit) tExit = t2;
     } else if (lox < bounds[0] || lox > bounds[3]) return Infinity;
-    if (ldy > EPS || ldy < -EPS) {
-        const inv = 1 / ldy;
-        let t1 = (bounds[1] - loy) * inv, t2 = (bounds[4] - loy) * inv;
+    if (ldy !== 0) {
+        let t1 = (bounds[1] - loy) / ldy, t2 = (bounds[4] - loy) / ldy;
         if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
         if (t1 > tEnter) tEnter = t1;
         if (t2 < tExit) tExit = t2;
     } else if (loy < bounds[1] || loy > bounds[4]) return Infinity;
-    if (ldz > EPS || ldz < -EPS) {
-        const inv = 1 / ldz;
-        let t1 = (bounds[2] - loz) * inv, t2 = (bounds[5] - loz) * inv;
+    if (ldz !== 0) {
+        let t1 = (bounds[2] - loz) / ldz, t2 = (bounds[5] - loz) / ldz;
         if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
         if (t1 > tEnter) tEnter = t1;
         if (t2 < tExit) tExit = t2;
     } else if (loz < bounds[2] || loz > bounds[5]) return Infinity;
-    if (tExit < tEnter) return Infinity; // ray misses the shape's AABB entirely
+    // The ray misses the shape's AABB entirely — or its reach is NaN, which
+    // nothing passes: tEnter is never NaN (it only takes clip values greater
+    // than it), so `!(tExit >= tEnter)` catches a NaN tExit, which the piece
+    // walk would otherwise never reach the end of.
+    if (!(tExit >= tEnter)) return Infinity;
+
+    if (!(tExit < Infinity)) {
+        // An unbounded reach and no face to leave the box through: the shape's
+        // bounds are infinite or NaN on every axis the ray moves along — an
+        // infinite mesh vertex; an infinite height sample, which the filter
+        // makes NaN; an infinite heightmap size. The ray still meets what
+        // finite surface lies along it, but its box would hold 0 × Infinity =
+        // NaN on an axis it does not move along, which covers everything. End
+        // it UNBOUNDED_REACH past where it enters: its box stays finite.
+        tExit = tEnter + UNBOUNDED_REACH / Math.max(Math.abs(ldx), Math.abs(ldy), Math.abs(ldz));
+
+        // A zero direction goes nowhere (nor, in effect, does a subnormal one).
+        if (!(tExit < Infinity)) return Infinity;
+    }
+
+    ray[0] = lox; ray[1] = loy; ray[2] = loz;
+    ray[3] = ldx; ray[4] = ldy; ray[5] = ldz;
+
+    nearest[NEAREST_T] = tMax;
+    nearest[NEAREST_FID] = 0;
+    nearest[NEAREST_FOUND] = 0;
+
+    if (shape.isHeightMapShape3D === true) {
+        walk_heightmap(shape, tEnter, tExit);
+    } else {
+        walk_mesh(shape, tEnter, tExit);
+    }
+
+    if (nearest[NEAREST_FOUND] === 0) return Infinity;
+
+    hit_feature = nearest[NEAREST_FID];
+
+    // Normalise, orient to face the ray, then rotate the local normal to world.
+    let nx = nearest[NEAREST_NX], ny = nearest[NEAREST_NY], nz = nearest[NEAREST_NZ];
+    let nl = v3_length(nx, ny, nz);
+    if (nl === 0) nl = 1;
+    nx /= nl; ny /= nl; nz /= nl;
+    if (nx * ldx + ny * ldy + nz * ldz > 0) { nx = -nx; ny = -ny; nz = -nz; }
+    v3_quaternion_apply(outNormal, 0, nx, ny, nz, qx, qy, qz, qw);
+    return nearest[NEAREST_T];
+}
+
+// ── The query in progress (single-threaded; refine_ray_concave is not re-entered) ──
+//
+// Held in typed arrays rather than module-level `let`s: a module-level binding
+// holding a double is a boxed heap number, so every write to one — and every
+// read of one into a local that is then reassigned — allocates. As `let`s these
+// cost a mesh ray ~3 KB of garbage.
+
+/** The ray, shape-local: origin xyz, direction xyz. @type {Float64Array} */
+const ray = new Float64Array(6);
+
+/**
+ * The nearest crossing so far: its distance (starts at tMax, exclusive), its
+ * triangle's feature id, whether there is one (0/1), and its geometric normal
+ * e1 × e2, unnormalised.
+ * @type {Float64Array}
+ */
+const nearest = new Float64Array(6);
+const NEAREST_T = 0;
+const NEAREST_FID = 1;
+const NEAREST_FOUND = 2;
+const NEAREST_NX = 3;
+const NEAREST_NY = 4;
+const NEAREST_NZ = 5;
 
-    // Query AABB = bbox of the clipped local segment.
+/** The feature id of the triangle the last call to hit anything struck. */
+let hit_feature = 0;
+
+/**
+ * The feature id of the triangle the most recent {@link refine_ray_concave}
+ * that returned a hit struck — the enumerators' id, the triangle's index in
+ * its shape's triangulation plus one. Read straight after that call: a later
+ * hit overwrites it, a miss leaves it alone.
+ *
+ * @returns {number}
+ */
+export function refine_ray_concave_hit_feature() {
+    return hit_feature;
+}
+
+/**
+ * Two-sided Möller–Trumbore of the query ray against one triangle (shape-local
+ * vertices), keeping it if it is the nearest crossing so far. A tie at one
+ * distance goes to the lower feature id — the order both enumerators emit in,
+ * so the answer does not depend on the order triangles are tested in, and a
+ * single in-order pass keeps the first one it met.
+ *
+ * The vertices are read from where they are stored, by index: passed as nine
+ * doubles to a call V8 does not inline, each is boxed into a heap number — a
+ * mesh ray allocated 330 bytes that way, a heightmap ray 190 more than it needs.
+ *
+ * @param {ArrayLike<number>} p the array holding the vertices
+ * @param {number} ia index of vertex a's x in `p`; y and z follow
+ * @param {number} ib index of vertex b's x
+ * @param {number} ic index of vertex c's x
+ * @param {number} fid the triangle's feature id
+ */
+function test_triangle(p, ia, ib, ic, fid) {
+    const ax = p[ia], ay = p[ia + 1], az = p[ia + 2];
+    const bx = p[ib], by = p[ib + 1], bz = p[ib + 2];
+    const cx = p[ic], cy = p[ic + 1], cz = p[ic + 2];
+    const ldx = ray[3], ldy = ray[4], ldz = ray[5];
+
+    const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+    const e2x = cx - ax, e2y = cy - ay, e2z = cz - az;
+
+    const px = ldy * e2z - ldz * e2y, py = ldz * e2x - ldx * e2z, pz = ldx * e2y - ldy * e2x;
+    const det = e1x * px + e1y * py + e1z * pz;
+    if (det < EPS && det > -EPS) return; // ray parallel to the triangle
+    // det can overflow to ±Infinity on finite edges (1e154 and more); 1/det is
+    // then ±0 and u, v and t all come out 0 — a "crossing" at the ray's origin.
+    // No answer can be had from such a triangle here; it is not crossed.
+    if (!(det > -Infinity && det < Infinity)) return;
+    const invDet = 1 / det;
+
+    const tvx = ray[0] - ax, tvy = ray[1] - ay, tvz = ray[2] - az;
+    const u = (tvx * px + tvy * py + tvz * pz) * invDet;
+    if (u < 0 || u > 1) return;
+
+    const wx = tvy * e1z - tvz * e1y, wy = tvz * e1x - tvx * e1z, wz = tvx * e1y - tvy * e1x;
+    const v = (ldx * wx + ldy * wy + ldz * wz) * invDet;
+    if (v < 0 || u + v > 1) return;
+
+    const best = nearest[NEAREST_T];
+    const t = (e2x * wx + e2y * wy + e2z * wz) * invDet;
+    // A NaN or infinite vertex (a bad height sample, a NaN in a mesh) leaves t
+    // NaN — through det, or through w — and such a triangle is not there. The
+    // comparisons above are all false for NaN, so this is where it is turned
+    // away: taken, at a NaN distance, no later crossing could compare nearer.
+    if (!(t >= 0) || t > best) return;
+    if (t === best && !(nearest[NEAREST_FOUND] !== 0 && fid < nearest[NEAREST_FID])) return;
+
+    nearest[NEAREST_T] = t;
+    nearest[NEAREST_FID] = fid;
+    nearest[NEAREST_FOUND] = 1;
+    // Geometric normal e1 × e2 (local, unnormalised).
+    nearest[NEAREST_NX] = e1y * e2z - e1z * e2y;
+    nearest[NEAREST_NY] = e1z * e2x - e1x * e2z;
+    nearest[NEAREST_NZ] = e1x * e2y - e1y * e2x;
+}
+
+/**
+ * A mesh: walk its surface BVH ({@link MeshShape3D#get_surface_bvh}) for the
+ * triangles the clipped segment [tEnter, tExit] can cross, instead of
+ * enumerating every triangle under the segment's box — which for the mesh was
+ * a scan of every triangle in it (1.1 ms a ray on 200k triangles).
+ *
+ * The candidates are the ones enumeration filtered to — triangles whose box
+ * overlaps the segment's box (fattened by {@link AABB_FATTEN}) — less those
+ * whose BVH ancestor the ray provably does not enter before the nearest
+ * crossing so far. A crossing lies on its triangle, so inside every ancestor's
+ * box; the ancestors are tested fattened by {@link AABB_FATTEN} plus a float32
+ * ULP (node boxes are float32), far beyond Möller–Trumbore's rounding, so no
+ * crossing is culled. With the order-independent tie-break in
+ * {@link test_triangle}, the answer is the enumeration's, bit for bit.
+ *
+ * @param {MeshShape3D} shape
+ * @param {number} tEnter
+ * @param {number} tExit
+ */
+function walk_mesh(shape, tEnter, tExit) {
+    const indices = shape.indices;
+
+    if (indices.length < 3) return;
+
+    const lox = ray[0], loy = ray[1], loz = ray[2];
+    const ldx = ray[3], ldy = ray[4], ldz = ray[5];
+
+    // The segment's box, as enumeration filtered by.
     const sax = lox + ldx * tEnter, say = loy + ldy * tEnter, saz = loz + ldz * tEnter;
     const sbx = lox + ldx * tExit, sby = loy + ldy * tExit, sbz = loz + ldz * tExit;
     const qminx = (sax < sbx ? sax : sbx) - AABB_FATTEN;
@@ -98,63 +345,369 @@ export function refine_ray_concave(shape, position, rotation, ox, oy, oz, dx, dy
     const qmaxy = (say > sby ? say : sby) + AABB_FATTEN;
     const qmaxz = (saz > sbz ? saz : sbz) + AABB_FATTEN;
 
-    const enumerate = shape.isHeightMapShape3D === true ? heightmap_enumerate_triangles : mesh_enumerate_triangles;
-    let cap = (tri_buf.length / TRIANGLE_FLOAT_STRIDE) | 0;
-    // The enumerators return the TRUE overlap count, which can EXCEED the buffer
-    // capacity (writes past the end are silently dropped). So the grow trigger is
-    // `count > cap` (not `=== cap`): regrow whenever the true count overflowed.
-    let count = enumerate(tri_buf, 0, shape, qminx, qminy, qminz, qmaxx, qmaxy, qmaxz);
-    while (count > cap && cap < MAX_TRIS) {
-        cap = cap * 2 < MAX_TRIS ? cap * 2 : MAX_TRIS;
-        tri_buf = new Float64Array(cap * TRIANGLE_FLOAT_STRIDE);
-        count = enumerate(tri_buf, 0, shape, qminx, qminy, qminz, qmaxx, qmaxy, qmaxz);
+    // The same box widened by a float32 ULP, for the node test only. No floor
+    // at float32's subnormal step is needed here, unlike the enumerator's: these
+    // bounds carry ±AABB_FATTEN, so the nearest one to zero that is not zero is
+    // an ULP of 1e-5 (1.7e-21), a normal float32. A bound at or past float32's
+    // range reaches to infinity, as in the enumerator: a node wholly past it has
+    // a box of [+Infinity, +Infinity] (or the negative), beyond any finite bound.
+    const wminx = f32_reach_down(qminx - Math.abs(qminx) * F32_RELATIVE_SLACK);
+    const wminy = f32_reach_down(qminy - Math.abs(qminy) * F32_RELATIVE_SLACK);
+    const wminz = f32_reach_down(qminz - Math.abs(qminz) * F32_RELATIVE_SLACK);
+    const wmaxx = f32_reach_up(qmaxx + Math.abs(qmaxx) * F32_RELATIVE_SLACK);
+    const wmaxy = f32_reach_up(qmaxy + Math.abs(qmaxy) * F32_RELATIVE_SLACK);
+    const wmaxz = f32_reach_up(qmaxz + Math.abs(qmaxz) * F32_RELATIVE_SLACK);
+
+    // Only an axis the ray does not move along at all is held to the origin's
+    // slab. Treating a component under EPS as zero here, as the clip does, would
+    // cull nodes such a ray does reach at the 1e12-unit distances a direction
+    // that short crosses at; with an exact test the slab bounds stay exact.
+    const parallel_x = ldx === 0;
+    const parallel_y = ldy === 0;
+    const parallel_z = ldz === 0;
+    const inv_x = 1 / ldx, inv_y = 1 / ldy, inv_z = 1 / ldz;
+    const forward_x = ldx > 0, forward_y = ldy > 0, forward_z = ldz > 0;
+    // A component under 2^-1024 has an infinite reciprocal: a slab distance
+    // times it is ±Infinity (NaN at zero), where the true one, the gap over the
+    // component, is finite — 1e305 for a gap of 1e-5 at 1e-310 — and a node it
+    // reaches read as entered past any finite reach. Such an axis divides.
+    const divide_x = !(inv_x > -Infinity && inv_x < Infinity);
+    const divide_y = !(inv_y > -Infinity && inv_y < Infinity);
+    const divide_z = !(inv_z > -Infinity && inv_z < Infinity);
+
+    const positions = shape.positions;
+    const bvh = shape.get_surface_bvh();
+    const root = bvh.root;
+
+    if (root === NULL_NODE) return;
+
+    // Read the node columns directly, as ebvh_geometry_query_nearest_triangle_ray does.
+    const float32 = bvh.__data_float32;
+    const uint32 = bvh.__data_uint32;
+
+    let pointer = 0;
+    stack[pointer++] = root;
+
+    while (pointer > 0) {
+        const node = stack[--pointer];
+        const address = node * ELEMENT_WORD_COUNT;
+
+        const x0 = float32[address], y0 = float32[address + 1], z0 = float32[address + 2];
+        const x1 = float32[address + 3], y1 = float32[address + 4], z1 = float32[address + 5];
+
+        if (x0 > wmaxx || x1 < wminx || y0 > wmaxy || y1 < wminy || z0 > wmaxz || z1 < wminz) continue;
+
+        // Does the ray enter the (fattened) node box over [0, nearest so far]?
+        // Each axis's entry face is the one the ray's sign says it comes in
+        // through, not the nearer of the two distances: a node wholly past
+        // float32's range has a minimum of +Infinity (or a maximum of
+        // -Infinity), which fattened is Infinity - Infinity = NaN, and a NaN
+        // distance must bound nothing. Ordering by comparison, a ray coming
+        // back toward the origin took the other, infinite face's -Infinity
+        // for its exit and never entered such a node.
+        let t_near = 0;
+        let t_far = nearest[NEAREST_T];
+
+        {
+            const lo_x = x0 - AABB_FATTEN - Math.abs(x0) * F32_RELATIVE_SLACK;
+            const hi_x = x1 + AABB_FATTEN + Math.abs(x1) * F32_RELATIVE_SLACK;
+            if (parallel_x) {
+                if (lox < lo_x || lox > hi_x) continue;
+            } else {
+                const near = (forward_x ? lo_x : hi_x) - lox, far = (forward_x ? hi_x : lo_x) - lox;
+                const t_in = divide_x ? near / ldx : near * inv_x;
+                const t_out = divide_x ? far / ldx : far * inv_x;
+                if (t_in > t_near) t_near = t_in;
+                if (t_out < t_far) t_far = t_out;
+            }
+
+            const lo_y = y0 - AABB_FATTEN - Math.abs(y0) * F32_RELATIVE_SLACK;
+            const hi_y = y1 + AABB_FATTEN + Math.abs(y1) * F32_RELATIVE_SLACK;
+            if (parallel_y) {
+                if (loy < lo_y || loy > hi_y) continue;
+            } else {
+                const near = (forward_y ? lo_y : hi_y) - loy, far = (forward_y ? hi_y : lo_y) - loy;
+                const t_in = divide_y ? near / ldy : near * inv_y;
+                const t_out = divide_y ? far / ldy : far * inv_y;
+                if (t_in > t_near) t_near = t_in;
+                if (t_out < t_far) t_far = t_out;
+            }
+
+            const lo_z = z0 - AABB_FATTEN - Math.abs(z0) * F32_RELATIVE_SLACK;
+            const hi_z = z1 + AABB_FATTEN + Math.abs(z1) * F32_RELATIVE_SLACK;
+            if (parallel_z) {
+                if (loz < lo_z || loz > hi_z) continue;
+            } else {
+                const near = (forward_z ? lo_z : hi_z) - loz, far = (forward_z ? hi_z : lo_z) - loz;
+                const t_in = divide_z ? near / ldz : near * inv_z;
+                const t_out = divide_z ? far / ldz : far * inv_z;
+                if (t_in > t_near) t_near = t_in;
+                if (t_out < t_far) t_far = t_out;
+            }
+
+            if (t_near > t_far) continue;
+        }
+
+        const child_1 = uint32[address + COLUMN_CHILD_1];
+
+        if (child_1 !== NULL_NODE) {
+            if (pointer + 2 > stack.length) {
+                const grown = new Uint32Array(stack.length * 2);
+                grown.set(stack);
+                stack = grown;
+            }
+
+            stack[pointer++] = child_1;
+            stack[pointer++] = uint32[address + COLUMN_CHILD_2];
+            continue;
+        }
+
+        const tri = uint32[address + COLUMN_USER_DATA];
+
+        const i_a = indices[tri * 3] * 3;
+        const i_b = indices[tri * 3 + 1] * 3;
+        const i_c = indices[tri * 3 + 2] * 3;
+
+        const ax = positions[i_a], ay = positions[i_a + 1], az = positions[i_a + 2];
+        const bx = positions[i_b], by = positions[i_b + 1], bz = positions[i_b + 2];
+        const cx = positions[i_c], cy = positions[i_c + 1], cz = positions[i_c + 2];
+
+        // the exact filter enumeration applied: the triangle's box against the segment's
+        if ((ax < bx ? (ax < cx ? ax : cx) : (bx < cx ? bx : cx)) > qmaxx) continue;
+        if ((ax > bx ? (ax > cx ? ax : cx) : (bx > cx ? bx : cx)) < qminx) continue;
+        if ((ay < by ? (ay < cy ? ay : cy) : (by < cy ? by : cy)) > qmaxy) continue;
+        if ((ay > by ? (ay > cy ? ay : cy) : (by > cy ? by : cy)) < qminy) continue;
+        if ((az < bz ? (az < cz ? az : cz) : (bz < cz ? bz : cz)) > qmaxz) continue;
+        if ((az > bz ? (az > cz ? az : cz) : (bz > cz ? bz : cz)) < qminz) continue;
+
+        test_triangle(positions, i_a, i_b, i_c, tri + 1);
     }
-    // If the true count still exceeds MAX_TRIS, only `cap` triangles were written;
-    // clamp so the consume loop never reads undefined past the buffer (which would
-    // poison `best` with NaN). Dropping the overflow is the documented MAX_TRIS bound.
-    const n_tris = count < cap ? count : cap;
-
-    // Two-sided Möller–Trumbore over the candidates; keep the nearest.
-    let best = tMax;
-    let found = false;
-    let nx = 0, ny = 0, nz = 0;
-    for (let i = 0; i < n_tris; i++) {
-        const o = i * TRIANGLE_FLOAT_STRIDE;
-        const ax = tri_buf[o], ay = tri_buf[o + 1], az = tri_buf[o + 2];
-        const e1x = tri_buf[o + 3] - ax, e1y = tri_buf[o + 4] - ay, e1z = tri_buf[o + 5] - az;
-        const e2x = tri_buf[o + 6] - ax, e2y = tri_buf[o + 7] - ay, e2z = tri_buf[o + 8] - az;
-
-        const px = ldy * e2z - ldz * e2y, py = ldz * e2x - ldx * e2z, pz = ldx * e2y - ldy * e2x;
-        const det = e1x * px + e1y * py + e1z * pz;
-        if (det < EPS && det > -EPS) continue; // ray parallel to the triangle
-        const invDet = 1 / det;
-
-        const tvx = lox - ax, tvy = loy - ay, tvz = loz - az;
-        const u = (tvx * px + tvy * py + tvz * pz) * invDet;
-        if (u < 0 || u > 1) continue;
-
-        const wx = tvy * e1z - tvz * e1y, wy = tvz * e1x - tvx * e1z, wz = tvx * e1y - tvy * e1x;
-        const v = (ldx * wx + ldy * wy + ldz * wz) * invDet;
-        if (v < 0 || u + v > 1) continue;
-
-        const t = (e2x * wx + e2y * wy + e2z * wz) * invDet;
-        if (t < 0 || t >= best) continue;
-
-        best = t;
-        found = true;
-        // Geometric normal e1 × e2 (local, unnormalised).
-        nx = e1y * e2z - e1z * e2y;
-        ny = e1z * e2x - e1x * e2z;
-        nz = e1x * e2y - e1y * e2x;
+}
+
+/**
+ * A heightmap: enumerate the triangles under the clipped segment's box and
+ * test each. The segment [tEnter, tExit] is one piece unless its box overlaps
+ * more than MAX_TRIS triangles; then it is walked in ray order in pieces sized
+ * to fit. A crossing at distance t lies on the piece covering t,
+ * so its triangle overlaps that piece's box — every crossing is tested — and
+ * once the nearest so far lies before a piece's end, no later piece can come
+ * nearer.
+ *
+ * @param {HeightMapShape3D} shape
+ * @param {number} tEnter
+ * @param {number} tExit
+ */
+function walk_heightmap(shape, tEnter, tExit) {
+    const lox = ray[0], loy = ray[1], loz = ray[2];
+    const ldx = ray[3], ldy = ray[4], ldz = ray[5];
+
+    const segment = tExit - tEnter;
+    let piece = segment;
+    let t0 = tEnter;
+
+    // Set once a piece cannot be made to fit: shortening no longer shrinks its
+    // box below MAX_TRIS triangles (they all lie within the box's fattening,
+    // say), so walking on in short pieces would take a million of them, each
+    // enumerating the same box. The rest of the segment then goes as one piece,
+    // tested as far as the scratch holds, and the walk ends.
+    let saturated = false;
+
+    for (; ;) {
+        let t1 = saturated || !(piece < tExit - t0) ? tExit : t0 + piece;
+
+        // Size the piece before enumerating it: shrink it until its box holds
+        // at most MAX_TRIS triangles, counted in O(1) (heightmap_box_triangles),
+        // rather than enumerating an over-full box only to learn it was over
+        // full — that, once per halving, cost more than the whole old capped
+        // enumeration. A box's count grows at most with the square of its
+        // length, so scaling the length by sqrt(MAX_TRIS / count) shrinks a
+        // diagonal box to fit in one step and an axis-aligned one in a few. A
+        // segment that fits is still one piece, enumerated once, as before.
+        let in_box = saturated ? 0 : heightmap_piece_triangles(shape, lox, loy, loz, ldx, ldy, ldz, t0, t1);
+        while (in_box > MAX_TRIS) {
+            const shorter = (t1 - t0) * Math.sqrt(MAX_TRIS / in_box) * 0.9;
+            // `tExit - shorter < tExit`: it still moves `t` at the segment's
+            // magnitude, so the walk advances.
+            if (!(shorter > segment * MIN_PIECE_FRACTION && tExit - shorter < tExit)) {
+                saturated = true;
+                t1 = tExit;
+                break;
+            }
+            t1 = t0 + shorter;
+            in_box = heightmap_piece_triangles(shape, lox, loy, loz, ldx, ldy, ldz, t0, t1);
+        }
+
+        // Query AABB = bbox of this piece of the local segment.
+        const sax = lox + ldx * t0, say = loy + ldy * t0, saz = loz + ldz * t0;
+        const sbx = lox + ldx * t1, sby = loy + ldy * t1, sbz = loz + ldz * t1;
+        const qminx = (sax < sbx ? sax : sbx) - AABB_FATTEN;
+        const qminy = (say < sby ? say : sby) - AABB_FATTEN;
+        const qminz = (saz < sbz ? saz : sbz) - AABB_FATTEN;
+        const qmaxx = (sax > sbx ? sax : sbx) + AABB_FATTEN;
+        const qmaxy = (say > sby ? say : sby) + AABB_FATTEN;
+        const qmaxz = (saz > sbz ? saz : sbz) + AABB_FATTEN;
+
+        const cap = (tri_buf.length / TRIANGLE_FLOAT_STRIDE) | 0;
+        // The enumerator returns the TRUE overlap count, which can EXCEED the
+        // buffer capacity (writes past the end are silently dropped).
+        let n_tris = heightmap_enumerate_triangles(tri_buf, 0, shape, qminx, qminy, qminz, qmaxx, qmaxy, qmaxz);
+
+        if (n_tris > cap) {
+            if (cap < MAX_TRIS) {
+                // grow, and enumerate this piece again
+                tri_buf = new Float64Array(Math.min(MAX_TRIS, Math.max(n_tris, cap * 2)) * TRIANGLE_FLOAT_STRIDE);
+                continue;
+            }
+
+            if (!saturated) {
+                const half = (t1 - t0) * 0.5;
+                // `tExit - half < tExit`: the half still moves `t` at the segment's
+                // magnitude, so the walk advances.
+                if (half > segment * MIN_PIECE_FRACTION && tExit - half < tExit) {
+                    piece = half;
+                    continue;
+                }
+
+                // too short to split: the rest of the segment as one piece
+                saturated = true;
+                continue;
+            }
+
+            // The saturated last piece: test what fits, never read past it.
+            if (!overflow_reported) {
+                overflow_reported = true;
+                console.warn(
+                    `refine_ray_concave: ${n_tris} triangles of a ${shape.constructor.name} lie in a stretch of`
+                    + ` ray ${t1 - t0} long; ${cap} are tested and the rest are not.`
+                );
+            }
+            n_tris = cap;
+        }
+
+        for (let i = 0; i < n_tris; i++) {
+            const o = i * TRIANGLE_FLOAT_STRIDE;
+            test_triangle(tri_buf, o, o + 3, o + 6, tri_buf[o + TRIANGLE_FEATURE_ID_OFFSET]);
+        }
+
+        if (t1 >= tExit || (nearest[NEAREST_FOUND] !== 0 && nearest[NEAREST_T] < t1)) break;
+
+        // Offer the next piece twice this one's length; the sizing above takes
+        // it back down where the terrain is denser.
+        piece = 2 * (t1 - t0);
+        t0 = t1;
     }
+}
 
-    if (!found) return Infinity;
+/**
+ * How many triangles {@link heightmap_box_triangles} counts for the box of the
+ * ray piece [t0, t1], fattened by {@link AABB_FATTEN} as the walk queries it.
+ *
+ * @param {HeightMapShape3D} shape
+ * @param {number} lox
+ * @param {number} loy
+ * @param {number} loz
+ * @param {number} ldx
+ * @param {number} ldy
+ * @param {number} ldz
+ * @param {number} t0
+ * @param {number} t1
+ * @returns {number}
+ */
+function heightmap_piece_triangles(shape, lox, loy, loz, ldx, ldy, ldz, t0, t1) {
+    const sax = lox + ldx * t0, say = loy + ldy * t0, saz = loz + ldz * t0;
+    const sbx = lox + ldx * t1, sby = loy + ldy * t1, sbz = loz + ldz * t1;
 
-    // Normalise, orient to face the ray, then rotate the local normal to world.
-    let nl = v3_length(nx, ny, nz);
-    if (nl === 0) nl = 1;
-    nx /= nl; ny /= nl; nz /= nl;
-    if (nx * ldx + ny * ldy + nz * ldz > 0) { nx = -nx; ny = -ny; nz = -nz; }
-    v3_quaternion_apply(outNormal, 0, nx, ny, nz, qx, qy, qz, qw);
-    return best;
+    return heightmap_box_triangles(
+        shape,
+        (sax < sbx ? sax : sbx) - AABB_FATTEN,
+        (say < sby ? say : sby) - AABB_FATTEN,
+        (saz < sbz ? saz : sbz) - AABB_FATTEN,
+        (sax > sbx ? sax : sbx) + AABB_FATTEN,
+        (say > sby ? say : sby) + AABB_FATTEN,
+        (saz > sbz ? saz : sbz) + AABB_FATTEN
+    );
+}
+
+/**
+ * How many triangles {@link heightmap_enumerate_triangles} emits for a query box
+ * in the heightmap's own frame, in O(1): the enumerator's own cell-range
+ * arithmetic, expression for expression, without the emitting — so the same
+ * number for the same box. For sizing a walk's pieces before enumerating any
+ * (this one's, and `shape_cast`'s over a heightmap): enumerating an over-full
+ * box only to learn that it was samples every height in it.
+ *
+ * @param {HeightMapShape3D} shape
+ * @param {number} aabb_min_x query box in the heightmap's frame
+ * @param {number} aabb_min_y
+ * @param {number} aabb_min_z
+ * @param {number} aabb_max_x
+ * @param {number} aabb_max_y
+ * @param {number} aabb_max_z
+ * @returns {number}
+ */
+export function heightmap_box_triangles(shape, aabb_min_x, aabb_min_y, aabb_min_z, aabb_max_x, aabb_max_y, aabb_max_z) {
+    const sampler = shape.sampler;
+    if (sampler === null) return 0;
+
+    const W = sampler.width;
+    const H = sampler.height;
+    if (W < 2 || H < 2) return 0;
+
+    const size_x = shape.size[0];
+    const size_z = shape.size[2];
+    if (size_x <= 0 || size_z <= 0) return 0;
+
+    const N = shape.tessellation;
+    const seg_u = (W - 1) * N;
+    const seg_v = (H - 1) * N;
+
+    shape._ensure_basis();
+    const b = shape._basis;
+
+    const c_x = 0.5 * (aabb_min_x + aabb_max_x);
+    const c_y = 0.5 * (aabb_min_y + aabb_max_y);
+    const c_z = 0.5 * (aabb_min_z + aabb_max_z);
+
+    const h_x = 0.5 * (aabb_max_x - aabb_min_x);
+    const h_y = 0.5 * (aabb_max_y - aabb_min_y);
+    const h_z = 0.5 * (aabb_max_z - aabb_min_z);
+
+    const u_c = b[0] * c_x + b[1] * c_y + b[2] * c_z;
+    const v_c = b[3] * c_x + b[4] * c_y + b[5] * c_z;
+
+    const u_e = Math.abs(b[0]) * h_x + Math.abs(b[1]) * h_y + Math.abs(b[2]) * h_z;
+    const v_e = Math.abs(b[3]) * h_x + Math.abs(b[4]) * h_y + Math.abs(b[5]) * h_z;
+
+    const half_u = size_x * 0.5;
+    const half_v = size_z * 0.5;
+
+    const u_lo_q = u_c - u_e;
+    const u_hi_q = u_c + u_e;
+    const v_lo_q = v_c - v_e;
+    const v_hi_q = v_c + v_e;
+
+    if (u_lo_q > half_u || u_hi_q < -half_u) return 0;
+    if (v_lo_q > half_v || v_hi_q < -half_v) return 0;
+
+    const u_lo = u_lo_q > -half_u ? u_lo_q : -half_u;
+    const u_hi = u_hi_q < +half_u ? u_hi_q : +half_u;
+    const v_lo = v_lo_q > -half_v ? v_lo_q : -half_v;
+    const v_hi = v_hi_q < +half_v ? v_hi_q : +half_v;
+
+    const inv_cell_u = seg_u / size_x;
+    const inv_cell_v = seg_v / size_z;
+
+    let i_first = Math.floor((u_lo + half_u) * inv_cell_u);
+    let i_last = Math.ceil((u_hi + half_u) * inv_cell_u) - 1;
+    let j_first = Math.floor((v_lo + half_v) * inv_cell_v);
+    let j_last = Math.ceil((v_hi + half_v) * inv_cell_v) - 1;
+
+    if (i_first < 0) i_first = 0;
+    if (j_first < 0) j_first = 0;
+    if (i_last > seg_u - 1) i_last = seg_u - 1;
+    if (j_last > seg_v - 1) j_last = seg_v - 1;
+
+    if (i_first > i_last || j_first > j_last) return 0;
+
+    return (i_last - i_first + 1) * (j_last - j_first + 1) * 2;
 }