partforge 0.39.0 → 0.41.0

package/src/testing/bvh.js

@@ -5,12 +5,56 @@
 // (raycast), nearest surface point (closestPoint), and exact mesh-to-mesh distance
 // (distanceTo). AABB tree, median split on the widest centroid axis, slab ray–box
 // test with pruning.
+//
+// STORAGE — four flat typed arrays, no per-triangle and no per-node JS objects.
+// The nested-array representation this replaced ([[x,y,z],[x,y,z],[x,y,z]] per
+// triangle, wrapped in an object carrying min/max/centroid arrays, hung off object
+// nodes) cost ~950 bytes and ~7 heap objects per triangle: 350 MB for a 400k-triangle
+// mesh, which is what OOM-killed the inspect job in mobile Safari. This costs ~75
+// bytes/triangle for a Manifold soup, and every query allocates only its own stack.
+//
+//   vertices  9 coords per triangle (v0,v1,v2 interleaved), in MESH order — so the
+//             triangle ids in raycast's `tri`/`skipTri` are still mesh indices.
+//             Float32 in, Float32 out: a Manifold soup is already float32, and
+//             widening it would double the footprint without adding a bit of
+//             precision, while a mesh whose positions are plain JS numbers (OCCT,
+//             hand-written fixtures) is kept in a Float64Array. Either copy is
+//             exact, so no reading changes with the representation. Exposed
+//             READ-ONLY: every node bound was computed from these coords at build
+//             time, so writing into the array silently invalidates the whole tree
+//             (queries would prune against boxes that no longer contain their
+//             triangles). Read it through readTriangleInto() rather than
+//             open-coding the stride.
+//   order     Uint32 triangle ids, permuted by the build so each leaf owns a
+//             contiguous run. The vertices themselves never move.
+//   bounds    Float64, 6 per node: [minx,miny,minz, maxx,maxy,maxz]. Kept at double
+//             precision whatever the vertices are — a narrowed bound would have to
+//             be rounded outward to stay conservative, and node bounds are a small
+//             fraction of the total anyway (~0.6 nodes per triangle).
+//   meta      Uint32, 2 per node. A LEAF is [firstIndexIntoOrder, count + 1]; an
+//             INTERNAL node is [rightChildIndex, 0]. The +1 is what lets an empty
+//             mesh's root still read as a leaf instead of as an internal node
+//             pointing at itself. Nodes are laid out in pre-order, so an internal
+//             node's left child is always the next node.
 
 const LEAF = 4; // max triangles per leaf
 
+// Coords per triangle in a `vertices` store: v0,v1,v2 interleaved. The ONE place
+// this layout is decoded outside the queries below — copy triangle `t` of `V` into
+// `out` (9 numbers: x0,y0,z0, x1,y1,z1, x2,y2,z2) and hand callers a reusable
+// buffer, so nobody else has to know the stride and no per-triangle garbage is
+// made. min-wall casts one ray per triangle through this.
+export function readTriangleInto(V, t, out) {
+  const o = t * 9;
+  for (let i = 0; i < 9; i++) out[i] = V[o + i];
+  return out;
+}
+
 // Triangles as [v0,v1,v2] coord triples, from either a Manifold non-indexed soup
 // (positions = 9 floats/triangle, no indices) or an OCCT indexed mesh (positions =
-// 3 floats/vertex + indices = 3 vertex-indices/triangle).
+// 3 floats/vertex + indices = 3 vertex-indices/triangle). A convenience for callers
+// that want plain arrays; the BVH itself reads triangleVertices() below, because
+// this shape costs four heap objects per triangle.
 export function meshTriangles(mesh) {
   const { positions, indices } = mesh;
   if (indices) {
@@ -33,48 +77,68 @@ export function meshTriangles(mesh) {
   return out;
 }
 
-function readTris(mesh) {
-  const triangles = meshTriangles(mesh);
-  return triangles.map(([v0, v1, v2], i) => {
-    const min = [Math.min(v0[0], v1[0], v2[0]), Math.min(v0[1], v1[1], v2[1]), Math.min(v0[2], v1[2], v2[2])];
-    const max = [Math.max(v0[0], v1[0], v2[0]), Math.max(v0[1], v1[1], v2[1]), Math.max(v0[2], v1[2], v2[2])];
-    return { i, v0, v1, v2, min, max, c: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2] };
-  });
-}
-
-function aabbOf(items) {
-  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
-  for (const it of items) for (let a = 0; a < 3; a++) { if (it.min[a] < min[a]) min[a] = it.min[a]; if (it.max[a] > max[a]) max[a] = it.max[a]; }
-  return { min, max };
+// The same triangles, flat: one typed array of 9 coords per triangle in mesh order.
+// Float32 source → Float32Array (lossless, and half the bytes); anything else →
+// Float64Array (plain JS numbers are doubles and must stay doubles).
+export function triangleVertices(mesh) {
+  const { positions, indices } = mesh;
+  const Store = positions instanceof Float32Array ? Float32Array : Float64Array;
+  if (indices) {
+    const n = indices.length / 3, verts = new Store(n * 9);
+    for (let t = 0; t < n; t++) {
+      const o = t * 9;
+      for (let k = 0; k < 3; k++) {
+        const s = indices[3 * t + k] * 3;
+        verts[o + 3 * k] = positions[s];
+        verts[o + 3 * k + 1] = positions[s + 1];
+        verts[o + 3 * k + 2] = positions[s + 2];
+      }
+    }
+    return verts;
+  }
+  const n = positions.length / 9;
+  if (positions instanceof Float32Array) return positions.slice(0, n * 9);
+  const verts = new Store(n * 9);
+  for (let i = 0; i < n * 9; i++) verts[i] = positions[i];
+  return verts;
 }
 
-function build(items) {
-  const box = aabbOf(items);
-  if (items.length <= LEAF) return { ...box, tris: items };
-  const ext = [box.max[0] - box.min[0], box.max[1] - box.min[1], box.max[2] - box.min[2]];
-  const axis = ext[0] >= ext[1] && ext[0] >= ext[2] ? 0 : ext[1] >= ext[2] ? 1 : 2;
-  const sorted = items.slice().sort((p, q) => p.c[axis] - q.c[axis]);
-  const mid = sorted.length >> 1;
-  const left = sorted.slice(0, mid), right = sorted.slice(mid);
-  if (left.length === 0 || right.length === 0) return { ...box, tris: items }; // degenerate split
-  return { ...box, left: build(left), right: build(right) };
+// Node count for a subtree of `len` triangles. The split is a pure function of the
+// length (median at len>>1, leaf at <= LEAF), so the tree's shape — and therefore
+// its exact size — is known before a single triangle is sorted. That is what lets
+// `bounds`/`meta` be allocated once at the right size rather than grown or trimmed.
+function countNodes(len, memo) {
+  if (len <= LEAF) return 1;
+  const hit = memo.get(len);
+  if (hit !== undefined) return hit;
+  const mid = len >> 1;
+  const n = 1 + countNodes(mid, memo) + countNodes(len - mid, memo);
+  memo.set(len, n);
+  return n;
 }
 
-// slab test: returns the entry distance if the ray meets [min,max] within (tMin,best], else Infinity
-function rayBox(o, invD, min, max, tMin, best) {
+// slab test: does the ray meet node `nb`'s box within (tMin, best]?
+function rayHitsBox(ox, oy, oz, ix, iy, iz, B, nb, tMin, best) {
   let t0 = tMin, t1 = best;
-  for (let a = 0; a < 3; a++) {
-    let lo = (min[a] - o[a]) * invD[a], hi = (max[a] - o[a]) * invD[a];
-    if (lo > hi) { const tmp = lo; lo = hi; hi = tmp; }
-    if (lo > t0) t0 = lo; if (hi < t1) t1 = hi;
-    if (t0 > t1) return Infinity;
-  }
-  return t0;
+  let lo = (B[nb] - ox) * ix, hi = (B[nb + 3] - ox) * ix;
+  if (lo > hi) { const s = lo; lo = hi; hi = s; }
+  if (lo > t0) t0 = lo; if (hi < t1) t1 = hi;
+  if (t0 > t1) return false;
+  lo = (B[nb + 1] - oy) * iy; hi = (B[nb + 4] - oy) * iy;
+  if (lo > hi) { const s = lo; lo = hi; hi = s; }
+  if (lo > t0) t0 = lo; if (hi < t1) t1 = hi;
+  if (t0 > t1) return false;
+  lo = (B[nb + 2] - oz) * iz; hi = (B[nb + 5] - oz) * iz;
+  if (lo > hi) { const s = lo; lo = hi; hi = s; }
+  if (lo > t0) t0 = lo; if (hi < t1) t1 = hi;
+  return t0 <= t1;
 }
 
-// nearest point on triangle to P (Ericson), returns { point, d2 }
-function closestOnTri(P, tri) {
-  const A = tri.v0, B = tri.v1, C = tri.v2;
+// nearest point on triangle `base` of `V` to P (Ericson), returns { point, d2 }
+function closestOnTri(P, V, base) {
+  const A = [V[base], V[base + 1], V[base + 2]];
+  const B = [V[base + 3], V[base + 4], V[base + 5]];
+  const C = [V[base + 6], V[base + 7], V[base + 8]];
   const sub = (p, q) => [p[0]-q[0], p[1]-q[1], p[2]-q[2]];
   const dot = (p, q) => p[0]*q[0] + p[1]*q[1] + p[2]*q[2];
   const add = (p, q) => [p[0]+q[0], p[1]+q[1], p[2]+q[2]];
@@ -98,21 +162,23 @@ function closestOnTri(P, tri) {
   return { point: Q, d2: dot(pq, pq) };
 }
 
-// squared distance from point to an AABB (0 inside)
-function distSqBox(p, min, max) {
-  let s = 0;
-  for (let a = 0; a < 3; a++) { const v = p[a] < min[a] ? min[a] - p[a] : p[a] > max[a] ? p[a] - max[a] : 0; s += v * v; }
-  return s;
+// squared distance from a point to node `nb`'s AABB (0 inside)
+function distSqBox(px, py, pz, B, nb) {
+  const x = px < B[nb] ? B[nb] - px : px > B[nb + 3] ? px - B[nb + 3] : 0;
+  const y = py < B[nb + 1] ? B[nb + 1] - py : py > B[nb + 4] ? py - B[nb + 4] : 0;
+  const z = pz < B[nb + 2] ? B[nb + 2] - pz : pz > B[nb + 5] ? pz - B[nb + 5] : 0;
+  return x * x + y * y + z * z;
 }
 
 // summed extent of a node's AABB — the "which node is larger" heuristic for dual traversal
-const nodeExtent = (n) => (n.max[0] - n.min[0]) + (n.max[1] - n.min[1]) + (n.max[2] - n.min[2]);
+const nodeExtent = (B, nb) => (B[nb + 3] - B[nb]) + (B[nb + 4] - B[nb + 1]) + (B[nb + 5] - B[nb + 2]);
 
-// squared distance between two AABBs (0 when they overlap)
-function boxBoxDistSq(a, b) {
+// squared distance between two nodes' AABBs (0 when they overlap)
+function boxBoxDistSq(A, na, B, nb) {
   let s = 0;
   for (let ax = 0; ax < 3; ax++) {
-    const v = a.min[ax] > b.max[ax] ? a.min[ax] - b.max[ax] : b.min[ax] > a.max[ax] ? b.min[ax] - a.max[ax] : 0;
+    const v = A[na + ax] > B[nb + 3 + ax] ? A[na + ax] - B[nb + 3 + ax]
+      : B[nb + ax] > A[na + 3 + ax] ? B[nb + ax] - A[na + 3 + ax] : 0;
     s += v * v;
   }
   return s;
@@ -146,32 +212,34 @@ function closestSegSeg(P1, Q1, P2, Q2) {
   return { a: A, b: B, d2: dot(pq, pq) };
 }
 
-// exact min distance between two triangles → { d2, a, b } (a on t1, b on t2).
-// Non-intersecting triangles realize their minimum at a vertex-face or edge-edge
-// feature pair; a piercing edge (interior×interior crossing) is caught first with
-// rayTri, since feature distances alone would miss it. rayTri's t is in units of
-// the unnormalized edge direction, so 0 < t <= 1 means the segment itself pierces;
-// parallel/grazing edges return Infinity and the coplanar cases fall to the
-// feature distances.
-function triTriDist(t1, t2) {
-  const edges = (t) => [[t.v0, t.v1], [t.v1, t.v2], [t.v2, t.v0]];
+// exact min distance between triangle `b1` of `V1` and triangle `b2` of `V2`
+// → { d2, a, b } (a on the first, b on the second). Non-intersecting triangles
+// realize their minimum at a vertex-face or edge-edge feature pair; a piercing
+// edge (interior×interior crossing) is caught first with rayTri, since feature
+// distances alone would miss it. rayTri's t is in units of the unnormalized edge
+// direction, so 0 < t <= 1 means the segment itself pierces; parallel/grazing
+// edges return Infinity and the coplanar cases fall to the feature distances.
+function triTriDist(V1, b1, V2, b2) {
+  const verts = (V, b) => [[V[b], V[b+1], V[b+2]], [V[b+3], V[b+4], V[b+5]], [V[b+6], V[b+7], V[b+8]]];
+  const t1 = verts(V1, b1), t2 = verts(V2, b2);
+  const edges = (t) => [[t[0], t[1]], [t[1], t[2]], [t[2], t[0]]];
   for (const [p, q] of edges(t1)) {
     const d = [q[0] - p[0], q[1] - p[1], q[2] - p[2]];
-    const t = rayTri(p, d, t2, 0);
+    const t = rayTri(p[0], p[1], p[2], d[0], d[1], d[2], V2, b2, 0);
     if (t <= 1) { const at = [p[0] + d[0] * t, p[1] + d[1] * t, p[2] + d[2] * t]; return { d2: 0, a: at, b: at }; }
   }
   for (const [p, q] of edges(t2)) {
     const d = [q[0] - p[0], q[1] - p[1], q[2] - p[2]];
-    const t = rayTri(p, d, t1, 0);
+    const t = rayTri(p[0], p[1], p[2], d[0], d[1], d[2], V1, b1, 0);
     if (t <= 1) { const at = [p[0] + d[0] * t, p[1] + d[1] * t, p[2] + d[2] * t]; return { d2: 0, a: at, b: at }; }
   }
   let best = { d2: Infinity, a: null, b: null };
-  for (const v of [t2.v0, t2.v1, t2.v2]) {
-    const r = closestOnTri(v, t1);
+  for (const v of t2) {
+    const r = closestOnTri(v, V1, b1);
     if (r.d2 < best.d2) best = { d2: r.d2, a: r.point, b: v };
   }
-  for (const v of [t1.v0, t1.v1, t1.v2]) {
-    const r = closestOnTri(v, t2);
+  for (const v of t1) {
+    const r = closestOnTri(v, V2, b2);
     if (r.d2 < best.d2) best = { d2: r.d2, a: v, b: r.point };
   }
   for (const [p1, q1] of edges(t1)) for (const [p2, q2] of edges(t2)) {
@@ -181,58 +249,154 @@ function triTriDist(t1, t2) {
   return best;
 }
 
-// Möller–Trumbore; returns t>tMin or Infinity
-function rayTri(o, d, tri, tMin) {
-  const e1 = [tri.v1[0] - tri.v0[0], tri.v1[1] - tri.v0[1], tri.v1[2] - tri.v0[2]];
-  const e2 = [tri.v2[0] - tri.v0[0], tri.v2[1] - tri.v0[1], tri.v2[2] - tri.v0[2]];
-  const p = [d[1] * e2[2] - d[2] * e2[1], d[2] * e2[0] - d[0] * e2[2], d[0] * e2[1] - d[1] * e2[0]];
-  const det = e1[0] * p[0] + e1[1] * p[1] + e1[2] * p[2];
+// Möller–Trumbore against triangle `base` of `V`; returns t>tMin or Infinity.
+// Scalars throughout — this is the inner loop of every raycast, and min-wall casts
+// one ray per sampled triangle.
+function rayTri(ox, oy, oz, dx, dy, dz, V, base, tMin) {
+  const ax = V[base], ay = V[base + 1], az = V[base + 2];
+  const e1x = V[base + 3] - ax, e1y = V[base + 4] - ay, e1z = V[base + 5] - az;
+  const e2x = V[base + 6] - ax, e2y = V[base + 7] - ay, e2z = V[base + 8] - az;
+  const px = dy * e2z - dz * e2y, py = dz * e2x - dx * e2z, pz = dx * e2y - dy * e2x;
+  const det = e1x * px + e1y * py + e1z * pz;
   if (det > -1e-12 && det < 1e-12) return Infinity;
   const inv = 1 / det;
-  const tv = [o[0] - tri.v0[0], o[1] - tri.v0[1], o[2] - tri.v0[2]];
-  const u = (tv[0] * p[0] + tv[1] * p[1] + tv[2] * p[2]) * inv;
+  const tx = ox - ax, ty = oy - ay, tz = oz - az;
+  const u = (tx * px + ty * py + tz * pz) * inv;
   if (u < 0 || u > 1) return Infinity;
-  const q = [tv[1] * e1[2] - tv[2] * e1[1], tv[2] * e1[0] - tv[0] * e1[2], tv[0] * e1[1] - tv[1] * e1[0]];
-  const v = (d[0] * q[0] + d[1] * q[1] + d[2] * q[2]) * inv;
+  const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x;
+  const v = (dx * qx + dy * qy + dz * qz) * inv;
   if (v < 0 || u + v > 1) return Infinity;
-  const t = (e2[0] * q[0] + e2[1] * q[1] + e2[2] * q[2]) * inv;
+  const t = (e2x * qx + e2y * qy + e2z * qz) * inv;
   return t > tMin ? t : Infinity;
 }
 
+// The BVH for `mesh`, memoized in a CALLER-OWNED Map keyed on the mesh object.
+// THE ONE HOME for the caller-owned-Map doctrine; the callers below just point here.
+//
+// Exists because two passes over the same posed meshes each want an index —
+// min-wall casts rays, meshGaps measures pair distances — and building both is a
+// second full index per sub-part at ~77 bytes/triangle. measure() owns the Map and
+// hands the same one (or, for min-wall, the resolved index) to both passes.
+//
+// `cache` is optional everywhere, and with none this is exactly buildBVH: the
+// direct callers that have no second pass to share with (assemblyGaps' bare
+// meshGaps, the tests) keep today's behaviour of building fresh. The Map is
+// deliberately the caller's, not a module-level WeakMap: a WeakMap keyed on
+// meshes would keep an index alive for as long as anything held its mesh, which
+// is the quiet retention this pass exists to remove. Here the index's lifetime is
+// visibly the caller's scope.
+export function cachedBVH(mesh, cache) {
+  if (!cache) return buildBVH(mesh);
+  let bvh = cache.get(mesh);
+  if (!bvh) cache.set(mesh, (bvh = buildBVH(mesh)));
+  return bvh;
+}
+
 export function buildBVH(mesh) {
-  const tris = readTris(mesh);
-  const root = build(tris);
+  const verts = triangleVertices(mesh);
+  const count = verts.length / 9;
+
+  const order = new Uint32Array(count);
+  // AABB-midpoint centroids, one Float64 triple per triangle. Transient: only the
+  // median split reads them, and they are released explicitly below.
+  let cent = new Float64Array(count * 3);
+  for (let t = 0; t < count; t++) {
+    order[t] = t;
+    const o = t * 9;
+    for (let a = 0; a < 3; a++) {
+      const p = verts[o + a], q = verts[o + 3 + a], r = verts[o + 6 + a];
+      const lo = p < q ? (p < r ? p : r) : (q < r ? q : r);
+      const hi = p > q ? (p > r ? p : r) : (q > r ? q : r);
+      cent[t * 3 + a] = (lo + hi) / 2;
+    }
+  }
+
+  const bounds = new Float64Array(countNodes(count, new Map()) * 6);
+  const meta = new Uint32Array(bounds.length / 3);
+  let next = 0;
+
+  // Pre-order emit: a node claims its slot, writes its own AABB, then either
+  // becomes a leaf over order[start, start+len) or sorts that range by the widest
+  // centroid axis and recurses. The left child lands at self+1 by construction, so
+  // only the right child's index needs storing.
+  function emit(start, len) {
+    const self = next++, nb = self * 6;
+    let x0 = Infinity, y0 = Infinity, z0 = Infinity, x1 = -Infinity, y1 = -Infinity, z1 = -Infinity;
+    for (let k = 0; k < len; k++) {
+      const o = order[start + k] * 9;
+      for (let j = 0; j < 9; j += 3) {
+        const x = verts[o + j], y = verts[o + j + 1], z = verts[o + j + 2];
+        if (x < x0) x0 = x; if (x > x1) x1 = x;
+        if (y < y0) y0 = y; if (y > y1) y1 = y;
+        if (z < z0) z0 = z; if (z > z1) z1 = z;
+      }
+    }
+    bounds[nb] = x0; bounds[nb + 1] = y0; bounds[nb + 2] = z0;
+    bounds[nb + 3] = x1; bounds[nb + 4] = y1; bounds[nb + 5] = z1;
+    if (len <= LEAF) { meta[self * 2] = start; meta[self * 2 + 1] = len + 1; return self; }
+    const ex = x1 - x0, ey = y1 - y0, ez = z1 - z0;
+    const axis = ex >= ey && ex >= ez ? 0 : ey >= ez ? 1 : 2;
+    order.subarray(start, start + len).sort((p, q) => cent[p * 3 + axis] - cent[q * 3 + axis]);
+    // No empty-half guard: len > LEAF here (LEAF >= 1), so mid = len>>1 >= 2 and
+    // len - mid >= 3 — both halves always non-empty. The nested-array build this
+    // replaced carried such a check; it was dead code there too, and countNodes()
+    // assumes this same split, so a guard that ever fired would mis-size `bounds`.
+    const mid = len >> 1;
+    emit(start, mid);
+    meta[self * 2] = emit(start + mid, len - mid);
+    meta[self * 2 + 1] = 0;
+    return self;
+  }
+  emit(0, count);
+  // Dropped explicitly, not left to scope: `emit` and the three query closures below
+  // share one function context, so a `cent` merely gone out of use would still be
+  // reachable from every returned BVH — 24 bytes/triangle of dead weight for the
+  // life of the index.
+  cent = null;
 
   function raycast(origin, dir, { tMin = 1e-6, tMax = Infinity, skipTri = -1 } = {}) {
-    const invD = [1 / dir[0], 1 / dir[1], 1 / dir[2]];
+    const ox = origin[0], oy = origin[1], oz = origin[2];
+    const dx = dir[0], dy = dir[1], dz = dir[2];
+    const ix = 1 / dx, iy = 1 / dy, iz = 1 / dz;
     let best = tMax, bestTri = -1;
-    const stack = [root];
+    const stack = [0];
     while (stack.length) {
-      const node = stack.pop();
-      if (rayBox(origin, invD, node.min, node.max, tMin, best) === Infinity) continue;
-      if (node.tris) {
-        for (const tri of node.tris) {
-          if (tri.i === skipTri) continue;
-          const t = rayTri(origin, dir, tri, tMin);
-          if (t < best) { best = t; bestTri = tri.i; }
+      const n = stack.pop();
+      if (!rayHitsBox(ox, oy, oz, ix, iy, iz, bounds, n * 6, tMin, best)) continue;
+      const packed = meta[n * 2 + 1];
+      if (packed) {
+        const start = meta[n * 2];
+        for (let k = 0; k < packed - 1; k++) {
+          const tri = order[start + k];
+          if (tri === skipTri) continue;
+          const t = rayTri(ox, oy, oz, dx, dy, dz, verts, tri * 9, tMin);
+          if (t < best) { best = t; bestTri = tri; }
         }
-      } else { stack.push(node.left, node.right); }
+      } else { stack.push(n + 1, meta[n * 2]); }
     }
     return bestTri === -1 ? null : { t: best, tri: bestTri };
   }
 
   function closestPoint(p) {
+    const px = p[0], py = p[1], pz = p[2];
     let best2 = Infinity, bestPt = null, bestTri = -1;
-    const stack = [root];
+    const stack = [0];
     while (stack.length) {
-      const node = stack.pop();
-      if (distSqBox(p, node.min, node.max) > best2) continue;
-      if (node.tris) {
-        for (const tri of node.tris) { const r = closestOnTri(p, tri); if (r.d2 < best2) { best2 = r.d2; bestPt = r.point; bestTri = tri.i; } }
+      const n = stack.pop();
+      if (distSqBox(px, py, pz, bounds, n * 6) > best2) continue;
+      const packed = meta[n * 2 + 1];
+      if (packed) {
+        const start = meta[n * 2];
+        for (let k = 0; k < packed - 1; k++) {
+          const tri = order[start + k];
+          const r = closestOnTri(p, verts, tri * 9);
+          if (r.d2 < best2) { best2 = r.d2; bestPt = r.point; bestTri = tri; }
+        }
       } else {
         // visit the nearer child first for better pruning
-        const dl = distSqBox(p, node.left.min, node.left.max), dr = distSqBox(p, node.right.min, node.right.max);
-        if (dl < dr) { stack.push(node.right, node.left); } else { stack.push(node.left, node.right); }
+        const l = n + 1, r = meta[n * 2];
+        const dl = distSqBox(px, py, pz, bounds, l * 6), dr = distSqBox(px, py, pz, bounds, r * 6);
+        if (dl < dr) { stack.push(r, l); } else { stack.push(l, r); }
       }
     }
     return { point: bestPt, dist: Math.sqrt(best2), tri: bestTri };
@@ -240,28 +404,31 @@ export function buildBVH(mesh) {
 
   // Exact minimum surface-to-surface distance to another buildBVH result.
   // Dual traversal pruned by AABB–AABB distance; exact triangle–triangle
-  // distance at leaf pairs; early-exits at 0 (touching/intersecting).
+  // distance at leaf pairs; early-exits at 0 (touching/intersecting). The stack
+  // holds node-index PAIRS, pushed and popped two entries at a time.
   function distanceTo(other) {
+    const oV = other.vertices, oB = other._bounds, oM = other._meta, oO = other._order;
     let best = { d2: Infinity, a: null, b: null };
-    const stack = [[root, other._root]];
+    const stack = [0, 0];
     while (stack.length && best.d2 > 0) {
-      const [na, nb] = stack.pop();
-      if (boxBoxDistSq(na, nb) >= best.d2) continue;
-      const aLeaf = !!na.tris, bLeaf = !!nb.tris;
-      if (aLeaf && bLeaf) {
-        for (const ta of na.tris) for (const tb of nb.tris) {
-          const r = triTriDist(ta, tb);
+      const nb = stack.pop(), na = stack.pop();
+      if (boxBoxDistSq(bounds, na * 6, oB, nb * 6) >= best.d2) continue;
+      const pa = meta[na * 2 + 1], pb = oM[nb * 2 + 1];
+      if (pa && pb) {
+        const sa = meta[na * 2], sb = oM[nb * 2];
+        for (let i = 0; i < pa - 1; i++) for (let j = 0; j < pb - 1; j++) {
+          const r = triTriDist(verts, order[sa + i] * 9, oV, oO[sb + j] * 9);
           if (r.d2 < best.d2) best = r;
         }
-      } else if (!aLeaf && (bLeaf || nodeExtent(na) >= nodeExtent(nb))) {
+      } else if (!pa && (pb || nodeExtent(bounds, na * 6) >= nodeExtent(oB, nb * 6))) {
         // descend the larger node; push the nearer child last so it pops first
-        const dl = boxBoxDistSq(na.left, nb), dr = boxBoxDistSq(na.right, nb);
-        if (dl < dr) stack.push([na.right, nb], [na.left, nb]);
-        else stack.push([na.left, nb], [na.right, nb]);
+        const l = na + 1, r = meta[na * 2];
+        const dl = boxBoxDistSq(bounds, l * 6, oB, nb * 6), dr = boxBoxDistSq(bounds, r * 6, oB, nb * 6);
+        if (dl < dr) stack.push(r, nb, l, nb); else stack.push(l, nb, r, nb);
       } else {
-        const dl = boxBoxDistSq(na, nb.left), dr = boxBoxDistSq(na, nb.right);
-        if (dl < dr) stack.push([na, nb.right], [na, nb.left]);
-        else stack.push([na, nb.left], [na, nb.right]);
+        const l = nb + 1, r = oM[nb * 2];
+        const dl = boxBoxDistSq(bounds, na * 6, oB, l * 6), dr = boxBoxDistSq(bounds, na * 6, oB, r * 6);
+        if (dl < dr) stack.push(na, r, na, l); else stack.push(na, l, na, r);
       }
     }
     if (best.a === null) return { distance: Infinity, at: null, pointA: null, pointB: null }; // empty mesh
@@ -269,5 +436,28 @@ export function buildBVH(mesh) {
     return { distance: Math.sqrt(best.d2), at, pointA: best.a, pointB: best.b };
   }
 
-  return { raycast, closestPoint, distanceTo, _root: root };
+  return {
+    raycast, closestPoint, distanceTo,
+    triangleCount: count,
+    // Flat, 9 per triangle, mesh order — min-wall casts from these. READ-ONLY (see
+    // the STORAGE note up top); decode a triangle with readTriangleInto().
+    vertices: verts,
+    // The root node's AABB, [minx,miny,minz, maxx,maxy,maxz] — a copy, so reading
+    // it cannot disturb the tree. It is the mesh's own bounding box over exactly
+    // the vertices the triangles reference, already computed by the build; min-wall
+    // uses it for its default ray cap instead of rescanning mesh.positions.
+    rootBounds: [bounds[0], bounds[1], bounds[2], bounds[3], bounds[4], bounds[5]],
+    // Diagnostic self-report: the four typed arrays' byte lengths, summed at build.
+    // NOT a measurement of retained memory — it counts only what this function
+    // knows it allocated, and cannot see a regression that reintroduces per-triangle
+    // JS objects (test/bvh.test.js weighs that in a child process). What it does
+    // pin, and the child-process bound is too loose to catch, is the index's
+    // COMPOSITION — widening `vertices` to Float64 would show up here.
+    bytesAllocated: verts.byteLength + order.byteLength + bounds.byteLength + meta.byteLength,
+    // Private to this module: only distanceTo reads them, off the OTHER BVH — a
+    // dual traversal walks two trees at once, and JS has no cross-instance private
+    // access to reach for. Nothing outside bvh.js touches them, and nothing should:
+    // they are raw node storage whose meaning is the packing rules in the header.
+    _bounds: bounds, _meta: meta, _order: order,
+  };
 }

package/src/testing/gaps.js

@@ -1,5 +1,5 @@
 import { buildView } from "./build.js";
-import { buildBVH } from "./bvh.js";
+import { cachedBVH } from "./bvh.js";
 
 // A measured pair distance at or below this (mm) counts as touching — absorbs
 // posing float error while staying far below any real print clearance.
@@ -17,12 +17,15 @@ export const pairKey = (a, b) => [a, b].sort().join("×");
 // meshes ([{ name, mesh }] — buildView output). Distance 0 = touching or
 // interpenetrating surfaces; callers filter. Pairs involving an empty mesh are
 // skipped (the watertight gate owns that failure). Pure mesh math — both backends.
+// `bvhCache` is an optional caller-owned Map — see cachedBVH for the doctrine;
+// measure() draws min-wall's index out of the same one, so each sub-part mesh is
+// indexed once, not twice.
 //   → [{ a, b, distance, at: [x,y,z] }]
-export function meshGaps(built) {
+export function meshGaps(built, { bvhCache } = {}) {
   const hasTris = (m) => (m.indices ? m.indices.length > 0 : m.positions.length > 0);
   const bvhs = built
     .filter(({ mesh }) => hasTris(mesh))
-    .map(({ name, mesh }) => ({ name, bvh: buildBVH(mesh) }));
+    .map(({ name, mesh }) => ({ name, bvh: cachedBVH(mesh, bvhCache) }));
   const out = [];
   for (let i = 0; i < bvhs.length; i++) {
     for (let j = i + 1; j < bvhs.length; j++) {

package/src/testing/measure.js

@@ -1,4 +1,5 @@
 import { buildView } from "./build.js";
+import { cachedBVH } from "./bvh.js";
 import { assemblyOverlaps } from "../framework/assembly.js";
 import { meshGaps, pairKey, CONTACT_EPS, GAP_THRESHOLD } from "./gaps.js";
 import { bounds, meshArea, meshCentroid } from "./mesh.js";
@@ -15,14 +16,29 @@ const unionBounds = (list) => list.reduce(
 // the assembly overlap check plus pair gap distances (near misses are reported,
 // never folded into `ok`). All solid facts are read BEFORE assemblyOverlaps,
 // which frees the shared kernel's objects at its end.
-//   → { part, view, subparts[], aggregate, overlaps[], gaps[], nearMisses[], ok }
+//   → { part, view, measuredMinWall, subparts[], aggregate, overlaps[], gaps[],
+//       nearMisses[], ok }
 export function measure(kernel, part, view = Object.keys(part.views)[0], params = {}, opts = {}) {
   const built = buildView(kernel, part, view, params);
+  // ONE BVH per sub-part mesh for this call, shared by the two passes that need
+  // one: min-wall (inward rays per triangle) and meshGaps (pair distances). They
+  // used to index the same mesh objects independently, so every sub-part of a
+  // multi-part view was built into a BVH twice — at ~77 bytes/triangle that is a
+  // whole second index's worth of build time and peak memory for nothing.
+  //
+  // This Map is the caller-owned cache cachedBVH documents — see there for why it
+  // is a Map of ours and not a module-level WeakMap. It dies with the call. Peak
+  // memory is unchanged (meshGaps already held every sub-part's index at once);
+  // the cache just fills it earlier. min-wall indexes exactly one mesh, so it is
+  // handed the resolved BVH rather than the Map.
+  const bvhCache = new Map();
   const subBounds = [];
   const subparts = built.map(({ name, solid, mesh }) => {
     const b = bounds(mesh.positions);
     subBounds.push(b);
-    const mw = opts.minWall ? minWall(mesh) : null;
+    // Resolved lazily and only when asked for: without min-wall, a single-sub-part
+    // view (no meshGaps) must still build no index at all.
+    const mw = opts.minWall ? minWall(mesh, { bvh: cachedBVH(mesh, bvhCache) }) : null;
     return {
       name,
       bbox: size(b),
@@ -35,6 +51,14 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
       holes: typeof solid.genus === "function" ? solid.genus() : null,
       minWall: mw?.value ?? null,
       minWallAt: mw?.location ?? null,
+      // Sampling accounting, so a report can tell a guaranteed minimum from an
+      // upper bound: on a dense mesh min-wall casts from a spread subset rather
+      // than every triangle (see min-wall.js). Exact readings say so explicitly,
+      // and a sampled run that found no wall still fills these in — `minWall`
+      // null with samples accounted for is "looked, found nothing"; null with
+      // `measuredMinWall` false is "never looked".
+      minWallSampled: mw?.sampled ?? false,
+      minWallSamples: mw ? { sampled: mw.sampledTriangles, total: mw.totalTriangles } : null,
     };
   });
 
@@ -42,7 +66,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // so this reads on OCCT too. nearMisses = the issue-#29 signal: pairs that
   // *almost* touch; overlapping pairs are excluded by name (a fully-contained
   // sub-part has surface distance > 0 but is the overlap gate's business).
-  const gaps = built.length > 1 ? meshGaps(built) : [];
+  const gaps = built.length > 1 ? meshGaps(built, { bvhCache }) : [];
 
   // Rebuilds with the same kernel and cleans up at its end — every solid fact
   // above is already read, so this is safe.
@@ -73,6 +97,12 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   return {
     part: part.meta?.title ?? view,
     view,
+    // Whether this measurement cast min-wall rays at all — stamped by the pass
+    // that did (or didn't) do the work, so a consumer never has to be told. A
+    // result with this false carries `minWall: null` on every sub-part because
+    // nothing measured it, which reads identically to "no reading available";
+    // verify's seeding rule turns on exactly this distinction (see verify.js).
+    measuredMinWall: !!opts.minWall,
     subparts,
     aggregate,
     overlaps,