@woosh/meep-engine 2.163.10 → 2.163.11

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.163.10",
+  "version": "2.163.11",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_capsule.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Collect the user-data of every BVH leaf whose AABB overlaps a capsule.
+ *
+ * The capsule is packed into a single array as
+ * `[p0_x, p0_y, p0_z, p1_x, p1_y, p1_z, r]` — the two segment endpoints
+ * followed by the radius (the same component order as
+ * {@link capsule_intersects_aabb3_closed}).
+ *
+ * Modelled on {@link bvh_query_user_data_overlaps_aabb} /
+ * {@link bvh_query_user_data_overlaps_sphere}: the same stack traversal, with
+ * the per-node predicate swapped for the exact capsule-vs-AABB overlap. Every
+ * child AABB is contained in its parent's, so a node the capsule misses prunes
+ * its whole subtree.
+ *
+ * @param {number[]|Uint32Array} result destination for matched leaf user-data
+ * @param {number} result_offset first index in `result` to write to
+ * @param {BVH} bvh
+ * @param {Float32Array|number[]} capsule `[p0x, p0y, p0z, p1x, p1y, p1z, r]`
+ * @returns {number} number of leaves written
+ */
+export function bvh_query_user_data_overlaps_capsule(result: number[] | Uint32Array, result_offset: number, bvh: BVH, capsule: Float32Array | number[]): number;
+//# sourceMappingURL=bvh_query_user_data_overlaps_capsule.d.ts.map

package/src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_capsule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bvh_query_user_data_overlaps_capsule.d.ts","sourceRoot":"","sources":["../../../../../../src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_capsule.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6DANW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,qBAEN,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CAyElB"}

package/src/core/bvh2/bvh3/query/bvh_query_user_data_overlaps_capsule.js

@@ -0,0 +1,101 @@
+//
+import { SCRATCH_UINT32_TRAVERSAL_STACK } from "../../../collection/SCRATCH_UINT32_TRAVERSAL_STACK.js";
+import { capsule_intersects_aabb3_closed } from "../../../geom/3d/capsule/capsule_intersects_aabb3_closed.js";
+import { NULL_NODE } from "../BVH.js";
+
+const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
+
+const scratch_aabb = new Float32Array(6);
+
+/**
+ * Collect the user-data of every BVH leaf whose AABB overlaps a capsule.
+ *
+ * The capsule is packed into a single array as
+ * `[p0_x, p0_y, p0_z, p1_x, p1_y, p1_z, r]` — the two segment endpoints
+ * followed by the radius (the same component order as
+ * {@link capsule_intersects_aabb3_closed}).
+ *
+ * Modelled on {@link bvh_query_user_data_overlaps_aabb} /
+ * {@link bvh_query_user_data_overlaps_sphere}: the same stack traversal, with
+ * the per-node predicate swapped for the exact capsule-vs-AABB overlap. Every
+ * child AABB is contained in its parent's, so a node the capsule misses prunes
+ * its whole subtree.
+ *
+ * @param {number[]|Uint32Array} result destination for matched leaf user-data
+ * @param {number} result_offset first index in `result` to write to
+ * @param {BVH} bvh
+ * @param {Float32Array|number[]} capsule `[p0x, p0y, p0z, p1x, p1y, p1z, r]`
+ * @returns {number} number of leaves written
+ */
+export function bvh_query_user_data_overlaps_capsule(
+    result,
+    result_offset,
+    bvh,
+    capsule
+) {
+    const root = bvh.root;
+
+    if (root === NULL_NODE) {
+        return 0;
+    }
+
+    const p0_x = capsule[0], p0_y = capsule[1], p0_z = capsule[2];
+    const p1_x = capsule[3], p1_y = capsule[4], p1_z = capsule[5];
+    const r = capsule[6];
+
+    /**
+     *
+     * @type {number}
+     */
+    const stack_top = stack.pointer++;
+
+    stack[stack_top] = root;
+
+    let result_cursor = result_offset;
+
+    while (stack.pointer > stack_top) {
+        stack.pointer--;
+
+        /**
+         *
+         * @type {number}
+         */
+        const node = stack[stack.pointer];
+
+        // test node against the capsule
+        bvh.node_get_aabb(node, scratch_aabb);
+
+        const intersection_exists = capsule_intersects_aabb3_closed(
+            p0_x, p0_y, p0_z,
+            p1_x, p1_y, p1_z,
+            r,
+            scratch_aabb[0], scratch_aabb[1], scratch_aabb[2],
+            scratch_aabb[3], scratch_aabb[4], scratch_aabb[5]
+        );
+
+        if (!intersection_exists) {
+            // fully outside
+            continue;
+        }
+
+        const node_is_leaf = bvh.node_is_leaf(node);
+
+        if (node_is_leaf) {
+            // leaf node
+            result[result_cursor++] = bvh.node_get_user_data(node);
+
+        } else {
+            // read in-order
+            const child1 = bvh.node_get_child1(node);
+            const child2 = bvh.node_get_child2(node);
+
+            // write to stack in reverse order, so that fist child ends up being visited first
+            stack[stack.pointer++] = child1;
+            stack[stack.pointer++] = child2;
+        }
+    }
+
+    // drop stack frame
+
+    return result_cursor - result_offset;
+}

package/src/core/geom/3d/capsule/capsule_intersects_aabb3_closed.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Test whether an oriented capsule overlaps an axis-aligned box — exact,
+ * closed-form (no iteration count, no convergence tolerance).
+ *
+ * A capsule is the set of points within `r` of its central segment `p0 → p1`
+ * (the Minkowski sum of that segment with a sphere of radius `r`), so it
+ * overlaps the box exactly when the segment passes within `r` of the box:
+ *
+ *     overlap  ⟺  distanceSqr(segment, AABB) ≤ r²
+ *
+ * The closest point on the segment to the box is located in O(1) by
+ * {@link line3_compute_segment_nearest_point_to_aabb3_t} (convex
+ * piecewise-quadratic minimiser); this then compares that closest distance to
+ * `r²`. {@link capsule_intersects_aabb3_iterative} is the convex-bisection
+ * sibling (simpler, but ~50 refinement steps). A degenerate capsule
+ * (`p0 === p1`) collapses to the sphere-vs-box test with no special-casing.
+ *
+ * Box bounds are assumed ordered per axis (`box_*0 ≤ box_*1`), matching the
+ * `AABB3` storage convention.
+ *
+ * @param {number} p0_x capsule segment start x
+ * @param {number} p0_y capsule segment start y
+ * @param {number} p0_z capsule segment start z
+ * @param {number} p1_x capsule segment end x
+ * @param {number} p1_y capsule segment end y
+ * @param {number} p1_z capsule segment end z
+ * @param {number} r capsule radius
+ * @param {number} box_x0 box min x
+ * @param {number} box_y0 box min y
+ * @param {number} box_z0 box min z
+ * @param {number} box_x1 box max x
+ * @param {number} box_y1 box max y
+ * @param {number} box_z1 box max z
+ * @returns {boolean} true when the capsule overlaps the box
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function capsule_intersects_aabb3_closed(p0_x: number, p0_y: number, p0_z: number, p1_x: number, p1_y: number, p1_z: number, r: number, box_x0: number, box_y0: number, box_z0: number, box_x1: number, box_y1: number, box_z1: number): boolean;
+//# sourceMappingURL=capsule_intersects_aabb3_closed.d.ts.map

package/src/core/geom/3d/capsule/capsule_intersects_aabb3_closed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule_intersects_aabb3_closed.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/capsule/capsule_intersects_aabb3_closed.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,sDAlBW,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,OAAO,CA6BnB"}

package/src/core/geom/3d/capsule/capsule_intersects_aabb3_closed.js

@@ -0,0 +1,67 @@
+import { clamp } from "../../../math/clamp.js";
+import { v3_distance_sqr } from "../../vec3/v3_distance_sqr.js";
+import { line3_compute_segment_nearest_point_to_aabb3_t } from "../line/line3_compute_segment_nearest_point_to_aabb3_t.js";
+
+/**
+ * Test whether an oriented capsule overlaps an axis-aligned box — exact,
+ * closed-form (no iteration count, no convergence tolerance).
+ *
+ * A capsule is the set of points within `r` of its central segment `p0 → p1`
+ * (the Minkowski sum of that segment with a sphere of radius `r`), so it
+ * overlaps the box exactly when the segment passes within `r` of the box:
+ *
+ *     overlap  ⟺  distanceSqr(segment, AABB) ≤ r²
+ *
+ * The closest point on the segment to the box is located in O(1) by
+ * {@link line3_compute_segment_nearest_point_to_aabb3_t} (convex
+ * piecewise-quadratic minimiser); this then compares that closest distance to
+ * `r²`. {@link capsule_intersects_aabb3_iterative} is the convex-bisection
+ * sibling (simpler, but ~50 refinement steps). A degenerate capsule
+ * (`p0 === p1`) collapses to the sphere-vs-box test with no special-casing.
+ *
+ * Box bounds are assumed ordered per axis (`box_*0 ≤ box_*1`), matching the
+ * `AABB3` storage convention.
+ *
+ * @param {number} p0_x capsule segment start x
+ * @param {number} p0_y capsule segment start y
+ * @param {number} p0_z capsule segment start z
+ * @param {number} p1_x capsule segment end x
+ * @param {number} p1_y capsule segment end y
+ * @param {number} p1_z capsule segment end z
+ * @param {number} r capsule radius
+ * @param {number} box_x0 box min x
+ * @param {number} box_y0 box min y
+ * @param {number} box_z0 box min z
+ * @param {number} box_x1 box max x
+ * @param {number} box_y1 box max y
+ * @param {number} box_z1 box max z
+ * @returns {boolean} true when the capsule overlaps the box
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function capsule_intersects_aabb3_closed(
+    p0_x, p0_y, p0_z,
+    p1_x, p1_y, p1_z,
+    r,
+    box_x0, box_y0, box_z0,
+    box_x1, box_y1, box_z1
+) {
+    const t = line3_compute_segment_nearest_point_to_aabb3_t(
+        p0_x, p0_y, p0_z,
+        p1_x, p1_y, p1_z,
+        box_x0, box_y0, box_z0,
+        box_x1, box_y1, box_z1
+    );
+
+    const p_x = p0_x + (p1_x - p0_x) * t;
+    const p_y = p0_y + (p1_y - p0_y) * t;
+    const p_z = p0_z + (p1_z - p0_z) * t;
+
+    return v3_distance_sqr(
+        p_x, p_y, p_z,
+        clamp(p_x, box_x0, box_x1),
+        clamp(p_y, box_y0, box_y1),
+        clamp(p_z, box_z0, box_z1)
+    ) <= r * r;
+}

package/src/core/geom/3d/capsule/capsule_intersects_aabb3_iterative.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Test whether an oriented capsule overlaps an axis-aligned box.
+ *
+ * A capsule is the set of points within `r` of its central segment `p0 → p1`
+ * (the Minkowski sum of that segment with a sphere of radius `r`). It therefore
+ * overlaps the box exactly when the segment passes within `r` of the box:
+ *
+ *     overlap  ⟺  distanceSqr(segment, AABB) ≤ r²
+ *
+ * so the whole test reduces to a segment-vs-box squared-distance compared
+ * against `r²` — no square root, no curved-surface math.
+ *
+ * The segment→box distance is `min_{t∈[0,1]} g(t)` with
+ * `g(t) = distanceSqr(P(t), box)`, `P(t) = p0 + t·d`. `g` is convex (a sum of
+ * per-axis convex "outside" terms composed with an affine `P`), so its
+ * minimiser is found from the monotone sign of
+ * `g'(t) ∝ (P(t) − clamp(P(t), box)) · d`: if `g'(0) ≥ 0` the minimum is the
+ * `p0` end, if `g'(1) ≤ 0` it is the `p1` end, otherwise it is the interior
+ * root, found by {@link BISECTION_ITERATIONS} bisection. A degenerate capsule
+ * (`p0 === p1`) has `d = 0 → g'(0) = 0 → t = 0`, i.e. the sphere-vs-box test,
+ * with no special-casing.
+ *
+ * Box bounds are assumed ordered per axis (`box_*0 ≤ box_*1`), matching the
+ * `AABB3` storage convention.
+ *
+ * @param {number} p0_x capsule segment start x
+ * @param {number} p0_y capsule segment start y
+ * @param {number} p0_z capsule segment start z
+ * @param {number} p1_x capsule segment end x
+ * @param {number} p1_y capsule segment end y
+ * @param {number} p1_z capsule segment end z
+ * @param {number} r capsule radius
+ * @param {number} box_x0 box min x
+ * @param {number} box_y0 box min y
+ * @param {number} box_z0 box min z
+ * @param {number} box_x1 box max x
+ * @param {number} box_y1 box max y
+ * @param {number} box_z1 box max z
+ * @returns {boolean} true when the capsule overlaps the box
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function capsule_intersects_aabb3_iterative(p0_x: number, p0_y: number, p0_z: number, p1_x: number, p1_y: number, p1_z: number, r: number, box_x0: number, box_y0: number, box_z0: number, box_x1: number, box_y1: number, box_z1: number): boolean;
+//# sourceMappingURL=capsule_intersects_aabb3_iterative.d.ts.map

package/src/core/geom/3d/capsule/capsule_intersects_aabb3_iterative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule_intersects_aabb3_iterative.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/capsule/capsule_intersects_aabb3_iterative.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,yDAlBW,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,KACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,OAAO,CA6EnB"}

package/src/core/geom/3d/capsule/capsule_intersects_aabb3_iterative.js

@@ -0,0 +1,137 @@
+import { clamp } from "../../../math/clamp.js";
+import { v3_dot } from "../../vec3/v3_dot.js";
+import { v3_distance_sqr } from "../../vec3/v3_distance_sqr.js";
+
+/**
+ * Bisection steps used to locate the closest point on the capsule's central
+ * segment to the box. `g(t) = distanceSqr(P(t), box)` is convex on `t ∈ [0,1]`,
+ * so bisecting the sign of `g'(t)` halves the bracket every step at a rate that
+ * does NOT depend on the segment's orientation. 50 steps drives `t` to the f64
+ * floor on `[0,1]` (`2⁻⁵⁰ ≈ 9e-16`), so the reported distance is exact to
+ * floating-point — there are no false negatives even for a hair-thin radius.
+ *
+ * (Alternating projection — project onto the segment, clamp into the box,
+ * repeat — was tried first and is what the narrowphase `capsule_box_contact`
+ * uses, but it crawls when the segment is near-parallel to a box face/edge and
+ * a short in-box chord can be missed entirely; a fuzz at `r = 1e-7` found such
+ * misses, hence the switch.)
+ * @type {number}
+ */
+const BISECTION_ITERATIONS = 50;
+
+/**
+ * Test whether an oriented capsule overlaps an axis-aligned box.
+ *
+ * A capsule is the set of points within `r` of its central segment `p0 → p1`
+ * (the Minkowski sum of that segment with a sphere of radius `r`). It therefore
+ * overlaps the box exactly when the segment passes within `r` of the box:
+ *
+ *     overlap  ⟺  distanceSqr(segment, AABB) ≤ r²
+ *
+ * so the whole test reduces to a segment-vs-box squared-distance compared
+ * against `r²` — no square root, no curved-surface math.
+ *
+ * The segment→box distance is `min_{t∈[0,1]} g(t)` with
+ * `g(t) = distanceSqr(P(t), box)`, `P(t) = p0 + t·d`. `g` is convex (a sum of
+ * per-axis convex "outside" terms composed with an affine `P`), so its
+ * minimiser is found from the monotone sign of
+ * `g'(t) ∝ (P(t) − clamp(P(t), box)) · d`: if `g'(0) ≥ 0` the minimum is the
+ * `p0` end, if `g'(1) ≤ 0` it is the `p1` end, otherwise it is the interior
+ * root, found by {@link BISECTION_ITERATIONS} bisection. A degenerate capsule
+ * (`p0 === p1`) has `d = 0 → g'(0) = 0 → t = 0`, i.e. the sphere-vs-box test,
+ * with no special-casing.
+ *
+ * Box bounds are assumed ordered per axis (`box_*0 ≤ box_*1`), matching the
+ * `AABB3` storage convention.
+ *
+ * @param {number} p0_x capsule segment start x
+ * @param {number} p0_y capsule segment start y
+ * @param {number} p0_z capsule segment start z
+ * @param {number} p1_x capsule segment end x
+ * @param {number} p1_y capsule segment end y
+ * @param {number} p1_z capsule segment end z
+ * @param {number} r capsule radius
+ * @param {number} box_x0 box min x
+ * @param {number} box_y0 box min y
+ * @param {number} box_z0 box min z
+ * @param {number} box_x1 box max x
+ * @param {number} box_y1 box max y
+ * @param {number} box_z1 box max z
+ * @returns {boolean} true when the capsule overlaps the box
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function capsule_intersects_aabb3_iterative(
+    p0_x, p0_y, p0_z,
+    p1_x, p1_y, p1_z,
+    r,
+    box_x0, box_y0, box_z0,
+    box_x1, box_y1, box_z1
+) {
+    const d_x = p1_x - p0_x;
+    const d_y = p1_y - p0_y;
+    const d_z = p1_z - p0_z;
+
+    // Parameter of the closest point on the segment to the box.
+    let t;
+
+    // g'(0) ≥ 0 ⇒ g is non-decreasing on [0,1] ⇒ minimum at the p0 end.
+    // (Also the degenerate-segment path: d = 0 makes this dot 0 ⇒ t = 0.)
+    if (v3_dot(
+        p0_x - clamp(p0_x, box_x0, box_x1),
+        p0_y - clamp(p0_y, box_y0, box_y1),
+        p0_z - clamp(p0_z, box_z0, box_z1),
+        d_x, d_y, d_z
+    ) >= 0) {
+        t = 0;
+    } else if (v3_dot(
+        // g'(1) ≤ 0 ⇒ g is non-increasing on [0,1] ⇒ minimum at the p1 end.
+        p1_x - clamp(p1_x, box_x0, box_x1),
+        p1_y - clamp(p1_y, box_y0, box_y1),
+        p1_z - clamp(p1_z, box_z0, box_z1),
+        d_x, d_y, d_z
+    ) <= 0) {
+        t = 1;
+    } else {
+        // Interior minimum: g'(0) < 0 < g'(1), so a sign change is bracketed —
+        // bisect for g'(t) = 0.
+        let lo = 0;
+        let hi = 1;
+
+        for (let i = 0; i < BISECTION_ITERATIONS; i++) {
+            const mid = (lo + hi) * 0.5;
+
+            const p_x = p0_x + d_x * mid;
+            const p_y = p0_y + d_y * mid;
+            const p_z = p0_z + d_z * mid;
+
+            const g_prime = v3_dot(
+                p_x - clamp(p_x, box_x0, box_x1),
+                p_y - clamp(p_y, box_y0, box_y1),
+                p_z - clamp(p_z, box_z0, box_z1),
+                d_x, d_y, d_z
+            );
+
+            if (g_prime > 0) {
+                hi = mid;
+            } else {
+                lo = mid;
+            }
+        }
+
+        t = (lo + hi) * 0.5;
+    }
+
+    // Closest segment point and the box point nearest it; overlap ⟺ within radius.
+    const p_x = p0_x + d_x * t;
+    const p_y = p0_y + d_y * t;
+    const p_z = p0_z + d_z * t;
+
+    return v3_distance_sqr(
+        p_x, p_y, p_z,
+        clamp(p_x, box_x0, box_x1),
+        clamp(p_y, box_y0, box_y1),
+        clamp(p_z, box_z0, box_z1)
+    ) <= r * r;
+}

package/src/core/geom/3d/gjk/GJK_REVIEW_NOTES.md

@@ -0,0 +1,146 @@
+# GJK review notes — Johnson distance subalgorithm & robustness
+
+Notes from a 2026-06-18 research pass (capsule-vs-AABB / segment-vs-box work) on
+how this engine's GJK family relates to the known GJK robustness literature —
+chiefly the **Johnson distance subalgorithm** and its 2017 **signed-volumes**
+replacement. See `NOTES.md` (same dir) for the raw reference links.
+
+**TL;DR:** the specific Johnson failure mode does **not** apply here, because this
+engine has **no distance-returning GJK** — nothing computes the Johnson
+sub-distance, so there is nothing to replace. The finding is *forward-looking*:
+it becomes relevant the day a closest-distance-between-separated-convexes query
+is added (speculative contacts, conservative-advancement CCD, proximity
+queries). The analogous simplex-degeneracy risk in our boolean/penetration GJK is
+real but already mitigated by explicit floating-point-dust guards.
+
+## What this engine actually has
+
+There are three Minkowski-difference routines here, and **none is a distance
+subalgorithm**:
+
+| File | Role | Simplex / sub-distance method |
+|---|---|---|
+| `gjk.js` | **Boolean** overlap test (used by `physics/queries/shape_cast.js`) | Voronoi-region simplex update via triple cross products (Kevin Moran adaptation). Returns a bool; never computes a closest point. |
+| `gjk_epa_penetration.js` | **Penetration** axis+depth (narrowphase convex / mesh / concave-per-triangle) | GJK builds a rank-4 origin-enclosing simplex (Voronoi-region updates), then EPA expands faces toward the closest one (Bullet `btGjkEpa2` structure). |
+| `mpr.js` | Penetration normal on **smooth** supports (sphere/capsule), where EPA stalls | Minkowski Portal Refinement — portal, not simplex sub-distance. |
+
+The thing the literature calls the *Johnson distance subalgorithm* — given a
+simplex of ≤4 points, find the closest point on it to the origin and the minimal
+sub-simplex (which Voronoi region the origin projects into), via recursively
+computed barycentric cofactors — is **absent**. Our GJK only ever asks "does the
+simplex enclose / has the support passed the origin?", never "what is the
+closest point on the simplex?". So there is no Johnson cofactor recursion and no
+Backup procedure in this codebase.
+
+## The Johnson subalgorithm and why it fails
+
+In a *distance* GJK (Gilbert–Johnson–Keerthi 1988), each iteration must solve the
+sub-distance problem: project the origin onto the current simplex and discard the
+vertices not contributing to the closest feature. Johnson's method expresses the
+barycentric weights as ratios of determinants (Δ cofactors) built from dot
+products of support-point *differences*.
+
+Failure mode (the part relevant to robustness reviews): for a **near-degenerate
+simplex** — points nearly coincident or nearly coplanar/collinear, which GJK
+*naturally drives toward* as it converges on a near-contact configuration — those
+determinants are differences of nearly-equal products and lose most of their
+significant digits to **subtractive cancellation**. The algorithm then either
+fails to find any valid sub-simplex (the historical "Backup procedure" brute-forces
+all subsets as a fallback) or, worse, selects the wrong Voronoi region and returns
+a **wrong closest point / distance**. Net effect in practice: the distance is
+*under-estimated just before contact* — i.e. under-detection, the same direction
+of error we found in the capsule-box alternating projection.
+
+## The 2017 fix — signed volumes (Montanari, Petrinic & Barbieri)
+
+*"Improving the GJK Algorithm for Faster and More Reliable Distance Queries
+Between Convex Objects"*, ACM TOG 36(3), 2017; reference impl **openGJK**
+(SoftwareX 2018). Both already cited in `NOTES.md`.
+
+It replaces Johnson's distance subalgorithm **and** the Backup procedure with a
+**signed-volumes** subalgorithm:
+
+- determines the Voronoi region by comparing **signed volumes** (determinants) of
+  the simplex and its sub-faces, projecting onto the lowest-dimensional one that
+  contains the origin's projection;
+- crucially **does not multiply together potentially small quantities**, so it is
+  *accurate to machine precision* and, per the paper, "cannot possibly generate
+  systems of linearly dependent equations" — **degenerate simplices are handled
+  naturally** (they collapse to a lower-dimensional projection instead of
+  triggering a fallback);
+- side benefit: ~10% faster on average, 15–30% in the contact-heavy regime.
+
+This is the single most relevant robustness upgrade for any GJK that returns a
+**distance**. It is *not* a drop-in change to a boolean or penetration GJK, which
+do not run a sub-distance step.
+
+## Applicability to this codebase
+
+1. **No live bug.** Nothing here runs the Johnson subalgorithm, so there is
+   nothing to "fix". Do not retrofit signed-volumes onto `gjk.js` /
+   `gjk_epa_penetration.js` — they have no sub-distance step to replace.
+
+2. **The analogous risk is the Voronoi-region update**, not Johnson cofactors.
+   `gjk.js` and the GJK phase of `gjk_epa_penetration.js` decide regions with
+   triple-cross-products and dot products, which suffer the *same class* of
+   cancellation on degenerate simplices. This is already mitigated deliberately:
+   - `gjk.js` `perpendicular_to_edge()` + the exact-zero direction checks are FP-dust
+     guards for exactly the collapsed-simplex case (see the comment block there —
+     a wedge dot rounding a hair above zero while the triple product rounds to
+     zero). Documented as off the hot path.
+   - `gjk_epa_penetration.js` carries `DIR_EPS`/`EPA_EPS` floors and pool-overflow
+     "use current best face" degradations.
+   These are spot mitigations, not a machine-precision guarantee — but they cover
+   the inputs the narrowphase actually feeds (the convex hulls / triangles), and
+   the penetration path is cross-checked by MPR on smooth shapes.
+
+3. **Signed-volumes becomes relevant when a distance query is added.** If/when the
+   engine grows speculative/“soft” contacts that need a *separation distance*, a
+   conservative-advancement CCD that needs closest-distance per step, or general
+   proximity queries, implement that as a **new** signed-volumes distance GJK
+   (port openGJK) rather than coaxing distance out of the boolean/penetration
+   routines. Capsule primitives should keep using the closed-form contacts
+   (`capsule_contacts.js`, now exact — see below), not GJK-with-margin.
+
+## Related robustness notes (same review)
+
+- **EPA precision wall on flat supports.** `Triangle3D`'s support is degenerate
+  along the face normal (all 3 vertices project equally), which stalls EPA and
+  yields noisy depths. The narrowphase already routes sphere/box/capsule-vs-
+  triangle through **closed-form** fast-paths in `narrowphase_step.js` for exactly
+  this reason, and `shape_cast.js` recovers the TOI normal with **MPR** rather
+  than EPA on smooth-vs-smooth. Good — keep new primitive pairs on closed forms.
+- **Capsule-as-segment-support-with-margin is intentionally NOT used here.** Jolt
+  and PhysX-PCM collide capsules as a segment support inflated by the radius
+  inside GJK/EPA (with bounded corner error from the shrink-margin model). This
+  engine instead uses exact closed-form capsule contacts. That is the more
+  accurate choice for these primitive pairs and should stay.
+- **Non-convergence policy.** Both `gjk.js` and `gjk_epa_penetration.js` cap at
+  `*_MAX_ITER = 64` and treat exhaustion as *no intersection*. For well-conditioned
+  convex inputs this is unreachable; it is a backstop against pathological input,
+  not a correctness lever.
+
+## Action items (low urgency — none is a known live defect)
+
+- [ ] If a separation-distance / proximity / conservative-advancement query is
+      ever needed, port **openGJK signed-volumes** as a dedicated distance GJK.
+      Do not extend the boolean/penetration routines for it.
+- [ ] (Optional, deeper) A focused robustness pass on
+      `gjk_epa_penetration.js`'s simplex phase — confirm the degenerate-simplex
+      guards hold under near-coplanar convex-hull inputs at scale. Out of scope
+      for this note; flagged only because it is the nearest analog to the Johnson
+      concern.
+
+## References
+
+- Gilbert, Johnson, Keerthi (1988), *A Fast Procedure for Computing the Distance
+  Between Complex Objects in Three-Dimensional Space*, IEEE J. Robotics &
+  Automation — the original GJK + Johnson distance subalgorithm.
+- Montanari, Petrinic, Barbieri (2017), *Improving the GJK Algorithm…*, ACM TOG
+  36(3), DOI 10.1145/3072959.3083724; openGJK reference impl
+  (github.com/MattiaMontanari/openGJK). Already in `NOTES.md`.
+- van den Bergen (1999), *A Fast and Robust GJK Implementation for Collision
+  Detection of Convex Objects* — the classic robustness treatment (error bounds,
+  the Backup procedure) that motivates the 2017 work.
+- Ericson, *Real-Time Collision Detection* (2005), §9.5 (GJK), Ch. 9 (EPA context).
+- `gjk.js` header — adapted from github.com/kevinmoran/GJK (boolean Voronoi GJK).

package/src/core/geom/3d/line/line3_compute_segment_nearest_point_to_aabb3_t.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Parameter `t ∈ [0,1]` of the point on the segment `p0 → p1` nearest to an
+ * axis-aligned box. The closest segment point is `p0 + t·(p1 − p0)`; the closest
+ * box point is that point clamped per-axis into the box. Sibling of
+ * {@link line3_compute_segment_nearest_point_to_point_t} (segment-vs-point).
+ *
+ * Exact and O(1). `g(t) = distanceSqr(P(t), box)` is convex and — for an AABB —
+ * piecewise-quadratic, with pieces meeting only where `P(t)` crosses one of the
+ * six box face planes (≤6 crossings). `g'(t) ∝ (P(t) − clamp(P(t), box)) · d` is
+ * therefore piecewise-linear and monotonically non-decreasing, so the minimiser
+ * is found in closed form by evaluating `g'` at the ≤8 candidates
+ * `{0, 1, face-plane crossings}`: the minimum is achieved on the interval where
+ * `g' = 0` (a single point when strictly convex), and this returns that
+ * interval's midpoint. No iteration, no tolerance, no Cramer's-Rule solve.
+ *
+ * When the minimum is non-unique (segment parallel to / inside the box) the
+ * midpoint is the *central* closest point — what the narrowphase
+ * `capsule_box_contact` needs for a stable resting manifold; a degenerate
+ * (`p0 === p1`) segment returns `0` (its parameter is arbitrary).
+ *
+ * The AABB specialisation of the Eberly/Ericson closest-point-segment-vs-box
+ * reduction. Backs {@link capsule_intersects_aabb3_closed} and the narrowphase
+ * `capsule_box_contact`; it replaced a 2-iteration alternating projection that
+ * under-detected and mis-placed contacts for segments near-parallel to a box
+ * face/edge (see `core/geom/3d/gjk/GJK_REVIEW_NOTES.md`).
+ *
+ * Box bounds are assumed ordered per axis (`box_*0 ≤ box_*1`).
+ *
+ * @param {number} p0_x segment start x
+ * @param {number} p0_y
+ * @param {number} p0_z
+ * @param {number} p1_x segment end x
+ * @param {number} p1_y
+ * @param {number} p1_z
+ * @param {number} box_x0 box min x
+ * @param {number} box_y0
+ * @param {number} box_z0
+ * @param {number} box_x1 box max x
+ * @param {number} box_y1
+ * @param {number} box_z1
+ * @returns {number} t in [0, 1]
+ */
+export function line3_compute_segment_nearest_point_to_aabb3_t(p0_x: number, p0_y: number, p0_z: number, p1_x: number, p1_y: number, p1_z: number, box_x0: number, box_y0: number, box_z0: number, box_x1: number, box_y1: number, box_z1: number): number;
+//# sourceMappingURL=line3_compute_segment_nearest_point_to_aabb3_t.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"line3_compute_segment_nearest_point_to_aabb3_t.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/line/line3_compute_segment_nearest_point_to_aabb3_t.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qEAdW,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAqFlB"}

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

@@ -0,0 +1,153 @@
+import { clamp } from "../../../math/clamp.js";
+import { v3_dot } from "../../vec3/v3_dot.js";
+
+/**
+ * The argmin of `g(t)=distanceSqr(P(t),box)` is an INTERVAL when the minimum is
+ * non-unique (segment parallel to a face, or lying inside the box — the closest
+ * distance is then constant along a sub-segment). We track that interval as the
+ * monotone sign-structure of `g'(t)` is scanned and return its MIDPOINT, so the
+ * reported closest point is the central one rather than an arbitrary endpoint.
+ * Module-level (single-threaded, non-reentrant — same convention as the
+ * narrowphase `g_ct_*` accumulators):
+ *   a = (max t, g) with g' ≤ 0,  b = (min t, g) with g' > 0   → t_hi (rightmost min)
+ *   c = (max t, g) with g' < 0,  d = (min t, g) with g' ≥ 0   → t_lo (leftmost min)
+ */
+let _a_t = -1, _a_g = 0;
+let _b_t = 2, _b_g = 0;
+let _c_t = -1, _c_g = 0;
+let _d_t = 2, _d_g = 0;
+
+/** Fold one candidate `(t, g'(t))` into the argmin-interval trackers. */
+function _consider(t, g) {
+    if (g <= 0 && t > _a_t) { _a_t = t; _a_g = g; }
+    if (g > 0 && t < _b_t) { _b_t = t; _b_g = g; }
+    if (g < 0 && t > _c_t) { _c_t = t; _c_g = g; }
+    if (g >= 0 && t < _d_t) { _d_t = t; _d_g = g; }
+}
+
+/**
+ * Parameter `t ∈ [0,1]` of the point on the segment `p0 → p1` nearest to an
+ * axis-aligned box. The closest segment point is `p0 + t·(p1 − p0)`; the closest
+ * box point is that point clamped per-axis into the box. Sibling of
+ * {@link line3_compute_segment_nearest_point_to_point_t} (segment-vs-point).
+ *
+ * Exact and O(1). `g(t) = distanceSqr(P(t), box)` is convex and — for an AABB —
+ * piecewise-quadratic, with pieces meeting only where `P(t)` crosses one of the
+ * six box face planes (≤6 crossings). `g'(t) ∝ (P(t) − clamp(P(t), box)) · d` is
+ * therefore piecewise-linear and monotonically non-decreasing, so the minimiser
+ * is found in closed form by evaluating `g'` at the ≤8 candidates
+ * `{0, 1, face-plane crossings}`: the minimum is achieved on the interval where
+ * `g' = 0` (a single point when strictly convex), and this returns that
+ * interval's midpoint. No iteration, no tolerance, no Cramer's-Rule solve.
+ *
+ * When the minimum is non-unique (segment parallel to / inside the box) the
+ * midpoint is the *central* closest point — what the narrowphase
+ * `capsule_box_contact` needs for a stable resting manifold; a degenerate
+ * (`p0 === p1`) segment returns `0` (its parameter is arbitrary).
+ *
+ * The AABB specialisation of the Eberly/Ericson closest-point-segment-vs-box
+ * reduction. Backs {@link capsule_intersects_aabb3_closed} and the narrowphase
+ * `capsule_box_contact`; it replaced a 2-iteration alternating projection that
+ * under-detected and mis-placed contacts for segments near-parallel to a box
+ * face/edge (see `core/geom/3d/gjk/GJK_REVIEW_NOTES.md`).
+ *
+ * Box bounds are assumed ordered per axis (`box_*0 ≤ box_*1`).
+ *
+ * @param {number} p0_x segment start x
+ * @param {number} p0_y
+ * @param {number} p0_z
+ * @param {number} p1_x segment end x
+ * @param {number} p1_y
+ * @param {number} p1_z
+ * @param {number} box_x0 box min x
+ * @param {number} box_y0
+ * @param {number} box_z0
+ * @param {number} box_x1 box max x
+ * @param {number} box_y1
+ * @param {number} box_z1
+ * @returns {number} t in [0, 1]
+ */
+export function line3_compute_segment_nearest_point_to_aabb3_t(
+    p0_x, p0_y, p0_z,
+    p1_x, p1_y, p1_z,
+    box_x0, box_y0, box_z0,
+    box_x1, box_y1, box_z1
+) {
+    const d_x = p1_x - p0_x;
+    const d_y = p1_y - p0_y;
+    const d_z = p1_z - p0_z;
+
+    if (d_x === 0 && d_y === 0 && d_z === 0) {
+        // Degenerate segment (a point) — its parameter is arbitrary.
+        return 0;
+    }
+
+    _a_t = -1; _a_g = 0;
+    _b_t = 2; _b_g = 0;
+    _c_t = -1; _c_g = 0;
+    _d_t = 2; _d_g = 0;
+
+    // Endpoint candidates.
+    _consider(0, v3_dot(
+        p0_x - clamp(p0_x, box_x0, box_x1),
+        p0_y - clamp(p0_y, box_y0, box_y1),
+        p0_z - clamp(p0_z, box_z0, box_z1),
+        d_x, d_y, d_z
+    ));
+    _consider(1, v3_dot(
+        p1_x - clamp(p1_x, box_x0, box_x1),
+        p1_y - clamp(p1_y, box_y0, box_y1),
+        p1_z - clamp(p1_z, box_z0, box_z1),
+        d_x, d_y, d_z
+    ));
+
+    // Face-plane crossing candidates (where an axis enters/leaves its slab).
+    for (let axis = 0; axis < 3; axis++) {
+        const d_a = axis === 0 ? d_x : (axis === 1 ? d_y : d_z);
+        if (d_a === 0) {
+            continue;
+        }
+        const p0_a = axis === 0 ? p0_x : (axis === 1 ? p0_y : p0_z);
+        const lo_a = axis === 0 ? box_x0 : (axis === 1 ? box_y0 : box_z0);
+        const hi_a = axis === 0 ? box_x1 : (axis === 1 ? box_y1 : box_z1);
+        const inv_d = 1 / d_a;
+
+        for (let side = 0; side < 2; side++) {
+            const tc = ((side === 0 ? lo_a : hi_a) - p0_a) * inv_d;
+            if (tc <= 0 || tc >= 1) {
+                continue;
+            }
+            const c_x = p0_x + d_x * tc;
+            const c_y = p0_y + d_y * tc;
+            const c_z = p0_z + d_z * tc;
+            _consider(tc, v3_dot(
+                c_x - clamp(c_x, box_x0, box_x1),
+                c_y - clamp(c_y, box_y0, box_y1),
+                c_z - clamp(c_z, box_z0, box_z1),
+                d_x, d_y, d_z
+            ));
+        }
+    }
+
+    // Rightmost minimiser: where g' last reaches 0 (g' linear between a and b).
+    let t_hi;
+    if (_a_t < 0) {
+        t_hi = 0;          // g' > 0 everywhere → minimum at the p0 end
+    } else if (_b_t > 1) {
+        t_hi = 1;          // g' ≤ 0 everywhere → minimum at the p1 end
+    } else {
+        t_hi = _a_t - _a_g * (_b_t - _a_t) / (_b_g - _a_g);
+    }
+
+    // Leftmost minimiser: where g' first reaches 0.
+    let t_lo;
+    if (_d_t > 1) {
+        t_lo = 1;          // g' < 0 everywhere → minimum at the p1 end
+    } else if (_c_t < 0) {
+        t_lo = 0;          // g' ≥ 0 everywhere → minimum at the p0 end
+    } else {
+        t_lo = _c_t - _c_g * (_d_t - _c_t) / (_d_g - _c_g);
+    }
+
+    return (t_lo + t_hi) * 0.5;
+}

package/src/core/geom/3d/topology/struct/binary/BinaryTopology.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinaryTopology.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryTopology.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"BinaryTopology.d.ts","sourceRoot":"","sources":["../../../../../../../../src/core/geom/3d/topology/struct/binary/BinaryTopology.js"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,2BAFU,MAAM,CAEuB;AAQvC;;;GAGG;AACH;IACI;;;;;;;;OAQG;IACH,sBAA4F;IAE5F;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAAsD;IAEtD;;;;;;;;;;;;OAYG;IACH,oBAAsD;IAEtD;;;;;;OAMG;IACH,oBAAsE;IAEtE;;;;;OAKG;IACH,2BAA0B;IAE1B;;;;OAIG;IACH,yBAAwB;IAExB;;;;OAIG;IACH,yBAAwB;IAExB;;;;OAIG;IACH,yBAAwB;IAGxB;;;OAGG;IACH,uBAYC;IAED;;;OAGG;IACH,aAUC;IAED;;;OAGG;IACH,kCAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;;;;OAMG;IACH,qCAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;;;;;;;;OAUG;IACH,oCAFW,MAAM,QAKhB;IAED;;;OAGG;IACH,kCAFW,MAAM,QAKhB;IAED;;;OAGG;IACH,kCAFW,MAAM,QAKhB;IAED;;;OAGG;IACH,kCAFW,MAAM,QAKhB;IAED;;OAEG;IACH,sBAFa,OAAO,CAQnB;IAED;;OAEG;IACH,oBAFa,OAAO,CAQnB;IAED;;OAEG;IACH,oBAFa,OAAO,CAQnB;IAED;;OAEG;IACH,oBAFa,OAAO,CAQnB;IAED;;;;;OAKG;IACH,2BAWC;IAGD;;OAEG;IACH,cAUC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,iBACvC,MAAM,MACN,MAAM,QAUhB;IAED;;;;;OAKG;IACH,4BAJW,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,QAUhB;IAED;;;;;OAKG;IACH,2BAJW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,iBACvC,MAAM,MACN,MAAM,QAUhB;IAED;;;;;OAKG;IACH,wBAJW,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,QAUhB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,sBAFW,MAAM,WADN,MAAM,QAQhB;IAED;;;OAGG;IACH,sBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,uBAFW,MAAM,SADN,MAAM,QAQhB;IAED;;;OAGG;IACH,sBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,uBAFW,MAAM,SADN,MAAM,QAQhB;IAGD;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,WADN,MAAM,QAQhB;IAED;;;OAGG;IACH,2BAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;OAIG;IACH,4BAFW,MAAM,SADN,MAAM,QAUhB;IAED;;;OAGG;IACH,2BAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;OAIG;IACH,4BAFW,MAAM,SADN,MAAM,QAUhB;IAED;;;OAGG;IACH,2BAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;OAIG;IACH,4BAFW,MAAM,SADN,MAAM,QAUhB;IAED;;;OAGG;IACH,2BAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;OAIG;IACH,4BAFW,MAAM,SADN,MAAM,QAUhB;IAED;;;;;OAKG;IACH,iBAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,eAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,eAFa,MAAM,CAQlB;IAED;;;;OAIG;IACH,eAFa,MAAM,CAUlB;IAED;;;OAGG;IACH,oBAFW,MAAM,QAOhB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,sBAFW,MAAM,SADN,MAAM,QAQhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,SADN,MAAM,QAQhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,SADN,MAAM,QAUhB;IAED;;;;OAIG;IACH,0BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,2BAFW,MAAM,SADN,MAAM,QAShB;IAED;;;;OAIG;IACH,0BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,2BAFW,MAAM,SADN,MAAM,QAShB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,SADN,MAAM,QAQhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,SADN,MAAM,QAQhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,SADN,MAAM,QAQhB;IAED;;;;OAIG;IACH,yBAJW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC,YAAY,iBACvC,MAAM,MACN,MAAM,QAUhB;IAED;;;;OAIG;IACH,sBAJW,MAAM,SACN,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,QAShB;IAED;;;OAGG;IACH,YAFW,cAAc,QA4CxB;IAED;;;OAGG;IACH,SAFa,cAAc,CAM1B;IAIL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;CAPxC;kCAh9BiC,wBAAwB"}

package/src/core/geom/3d/topology/struct/binary/BinaryTopology.js

@@ -1,5 +1,4 @@
 import { assert } from "../../../../../assert.js";
-import { array_copy } from "../../../../../collection/array/array_copy.js";
 import { BinaryElementPool } from "./BinaryElementPool.js";
 
 /**
@@ -358,7 +357,9 @@ export class BinaryTopology {
 
         const v_address = pool.element_address(id);
         const v_offset = v_address >> 2; // get 4-byte boundary
-        array_copy(pool.data_float32, v_offset, result, result_offset, 3);
+        result[result_offset] = pool.data_float32[v_offset];
+        result[result_offset + 1] = pool.data_float32[v_offset + 1];
+        result[result_offset + 2] = pool.data_float32[v_offset + 2];
     }
 
     /**
@@ -372,7 +373,9 @@ export class BinaryTopology {
 
         const v_address = pool.element_address(id);
         const v_offset = v_address >> 2; // get 4-byte boundary
-        array_copy(value, value_offset, pool.data_float32, v_offset, 3);
+        pool.data_float32[v_offset] = value[value_offset];
+        pool.data_float32[v_offset + 1] = value[value_offset + 1];
+        pool.data_float32[v_offset + 2] = value[value_offset + 2];
     }
 
     /**
@@ -386,7 +389,9 @@ export class BinaryTopology {
 
         const v_address = pool.element_address(id) + 3 * FLOAT_32_SIZE;
         const v_offset = v_address >> 2; // get 4-byte boundary
-        array_copy(pool.data_float32, v_offset, result, result_offset, 3);
+        result[result_offset] = pool.data_float32[v_offset];
+        result[result_offset + 1] = pool.data_float32[v_offset + 1];
+        result[result_offset + 2] = pool.data_float32[v_offset + 2];
     }
 
     /**
@@ -400,7 +405,9 @@ export class BinaryTopology {
 
         const v_address = pool.element_address(id) + 3 * FLOAT_32_SIZE;
         const v_offset = v_address >> 2; // get 4-byte boundary
-        array_copy(value, value_offset, pool.data_float32, v_offset, 3);
+        pool.data_float32[v_offset] = value[value_offset];
+        pool.data_float32[v_offset + 1] = value[value_offset + 1];
+        pool.data_float32[v_offset + 2] = value[value_offset + 2];
     }
 
     /**
@@ -891,7 +898,9 @@ export class BinaryTopology {
         // Offset by the first loop pointer (UINT_32_SIZE)
         const f_address = pool.element_address(id) + UINT_32_SIZE;
         const f_offset = f_address >> 2;
-        array_copy(pool.data_float32, f_offset, result, result_offset, 3);
+        result[result_offset] = pool.data_float32[f_offset];
+        result[result_offset + 1] = pool.data_float32[f_offset + 1];
+        result[result_offset + 2] = pool.data_float32[f_offset + 2];
     }
 
     /**
@@ -903,7 +912,9 @@ export class BinaryTopology {
         const pool = this.__face_pool;
         const f_address = pool.element_address(id) + UINT_32_SIZE;
         const f_offset = f_address >> 2;
-        array_copy(value, value_offset, pool.data_float32, f_offset, 3);
+        pool.data_float32[f_offset] = value[value_offset];
+        pool.data_float32[f_offset + 1] = value[value_offset + 1];
+        pool.data_float32[f_offset + 2] = value[value_offset + 2];
     }
 
     /**

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.d.ts

@@ -11,6 +11,12 @@
  * Call AFTER an initial vertex-merge/edge-fuse, then merge + fuse again so the new split vertices weld
  * onto the T-junction vertices and the resulting duplicate edges fuse.
  *
+ * A BVH over the vertices replaces the naive all-vertices-per-edge scan: for each boundary edge we
+ * query only the vertices within the tolerance of the edge segment (a capsule), which IS the on-edge
+ * region, so no separate per-candidate distance test is needed. The BVH is built ONCE -- every split
+ * adds a vertex snapped exactly onto an existing one's position, so no candidate position is ever
+ * missing from the original leaf set, and the tree never needs rebuilding as edges split.
+ *
  * @param {BinaryTopology} mesh
  * @param {number} [tolerance] max distance from a vertex to an edge for it to count as "on" the edge
  * @returns {number} number of splits performed

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_resolve_t_junctions.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH,8EAHW,MAAM,GACJ,MAAM,CAuElB"}
+{"version":3,"file":"bt_mesh_resolve_t_junctions.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8EAHW,MAAM,GACJ,MAAM,CAwGlB"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_resolve_t_junctions.js

@@ -1,95 +1,139 @@
-import { NULL_POINTER } from "../BinaryTopology.js";
-import { bt_edge_split } from "./edge/bt_edge_split.js";
-
-const _a = new Float32Array(3);
-const _b = new Float32Array(3);
-const _p = new Float32Array(3);
-const _hit = new Float32Array(3);
-
-/**
- * Resolve T-junctions: where a vertex lies on the interior of a boundary edge (rather than at one of
- * its endpoints), split that edge at the vertex so the two pieces can later be welded/fused into a
- * shared edge.
- *
- * This is required for meshes assembled from independently-authored faces of differing sizes - e.g. an
- * L-shaped or ring floor built from rectangles, where one rectangle's corner falls in the middle of a
- * neighbour's edge. Without it those faces touch only at a single vertex, so edge-based neighbour
- * queries (island detection, erosion, path-finding) treat them as DISCONNECTED.
- *
- * Call AFTER an initial vertex-merge/edge-fuse, then merge + fuse again so the new split vertices weld
- * onto the T-junction vertices and the resulting duplicate edges fuse.
- *
- * @param {BinaryTopology} mesh
- * @param {number} [tolerance] max distance from a vertex to an edge for it to count as "on" the edge
- * @returns {number} number of splits performed
- */
-export function bt_mesh_resolve_t_junctions(mesh, tolerance = 1e-4) {
-    const tol_sq = tolerance * tolerance;
-
-    let total = 0;
-    let rounds = 0;
-    let changed = true;
-
-    while (changed && rounds < 256) {
-        changed = false;
-        rounds++;
-
-        const edge_count = mesh.edges.size;
-
-        for (let e = 0; e < edge_count; e++) {
-            if (!mesh.edges.is_allocated(e)) continue;
-
-            // only boundary edges (a single radial loop) can carry a T-junction
-            const l = mesh.edge_read_loop(e);
-            if (l === NULL_POINTER) continue;
-            if (mesh.loop_read_radial_next(l) !== l) continue;
-
-            const v1 = mesh.edge_read_vertex1(e);
-            const v2 = mesh.edge_read_vertex2(e);
-
-            mesh.vertex_read_coordinate(_a, 0, v1);
-            mesh.vertex_read_coordinate(_b, 0, v2);
-
-            const abx = _b[0] - _a[0], aby = _b[1] - _a[1], abz = _b[2] - _a[2];
-            const ab_sq = abx * abx + aby * aby + abz * abz;
-            if (ab_sq <= tol_sq) continue;
-
-            const t_margin = tolerance / Math.sqrt(ab_sq);
-
-            let split_t = -1;
-            let split_v = -1;
-
-            const vertex_count = mesh.vertices.size;
-            for (let v = 0; v < vertex_count; v++) {
-                if (v === v1 || v === v2) continue;
-                if (!mesh.vertices.is_allocated(v)) continue;
-
-                mesh.vertex_read_coordinate(_p, 0, v);
-
-                const t = ((_p[0] - _a[0]) * abx + (_p[1] - _a[1]) * aby + (_p[2] - _a[2]) * abz) / ab_sq;
-                if (t <= t_margin || t >= 1 - t_margin) continue;
-
-                const cx = _a[0] + t * abx - _p[0];
-                const cy = _a[1] + t * aby - _p[1];
-                const cz = _a[2] + t * abz - _p[2];
-                if (cx * cx + cy * cy + cz * cz > tol_sq) continue;
-
-                split_t = t;
-                split_v = v;
-                break;
-            }
-
-            if (split_t >= 0) {
-                // snapshot the on-edge vertex coordinate, split, then snap the new vertex exactly onto it
-                mesh.vertex_read_coordinate(_hit, 0, split_v);
-                const nv = bt_edge_split(mesh, e, split_t);
-                mesh.vertex_write_coordinate(nv, _hit, 0);
-
-                total++;
-                changed = true;
-            }
-        }
-    }
-
-    return total;
-}
+import { BVH } from "../../../../../../bvh2/bvh3/BVH.js";
+import {
+    bvh_query_user_data_overlaps_capsule
+} from "../../../../../../bvh2/bvh3/query/bvh_query_user_data_overlaps_capsule.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
+import { bt_edge_split } from "./edge/bt_edge_split.js";
+
+const _a = new Float32Array(3);
+const _b = new Float32Array(3);
+const _p = new Float32Array(3);
+const _hit = new Float32Array(3);
+const _capsule = new Float32Array(7);
+
+/**
+ * Resolve T-junctions: where a vertex lies on the interior of a boundary edge (rather than at one of
+ * its endpoints), split that edge at the vertex so the two pieces can later be welded/fused into a
+ * shared edge.
+ *
+ * This is required for meshes assembled from independently-authored faces of differing sizes - e.g. an
+ * L-shaped or ring floor built from rectangles, where one rectangle's corner falls in the middle of a
+ * neighbour's edge. Without it those faces touch only at a single vertex, so edge-based neighbour
+ * queries (island detection, erosion, path-finding) treat them as DISCONNECTED.
+ *
+ * Call AFTER an initial vertex-merge/edge-fuse, then merge + fuse again so the new split vertices weld
+ * onto the T-junction vertices and the resulting duplicate edges fuse.
+ *
+ * A BVH over the vertices replaces the naive all-vertices-per-edge scan: for each boundary edge we
+ * query only the vertices within the tolerance of the edge segment (a capsule), which IS the on-edge
+ * region, so no separate per-candidate distance test is needed. The BVH is built ONCE -- every split
+ * adds a vertex snapped exactly onto an existing one's position, so no candidate position is ever
+ * missing from the original leaf set, and the tree never needs rebuilding as edges split.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} [tolerance] max distance from a vertex to an edge for it to count as "on" the edge
+ * @returns {number} number of splits performed
+ */
+export function bt_mesh_resolve_t_junctions(mesh, tolerance = 1e-4) {
+    const tol_sq = tolerance * tolerance;
+
+    // --- Build a vertex BVH over the original vertices (point leaves; user data = vertex id) ---
+    const vertices = mesh.vertices;
+    const vertex_count = vertices.size;
+
+    const bvh = new BVH();
+
+    let leaf_count = 0;
+    for (let v = 0; v < vertex_count; v++) {
+        if (!vertices.is_allocated(v)) continue;
+
+        mesh.vertex_read_coordinate(_p, 0, v);
+
+        const node = bvh.allocate_node();
+        bvh.node_set_user_data(node, v);
+        bvh.node_set_aabb_primitive(node, _p[0], _p[1], _p[2], _p[0], _p[1], _p[2]);
+        bvh.insert_leaf(node);
+
+        leaf_count++;
+    }
+
+    if (leaf_count === 0) {
+        return 0;
+    }
+
+    // The query writes one vertex id per overlapping leaf; it can never exceed the leaf count.
+    const candidates = new Uint32Array(leaf_count);
+
+    let total = 0;
+    let rounds = 0;
+    let changed = true;
+
+    while (changed && rounds < 256) {
+        changed = false;
+        rounds++;
+
+        const edge_count = mesh.edges.size;
+
+        for (let e = 0; e < edge_count; e++) {
+            if (!mesh.edges.is_allocated(e)) continue;
+
+            // only boundary edges (a single radial loop) can carry a T-junction
+            const l = mesh.edge_read_loop(e);
+            if (l === NULL_POINTER) continue;
+            if (mesh.loop_read_radial_next(l) !== l) continue;
+
+            const v1 = mesh.edge_read_vertex1(e);
+            const v2 = mesh.edge_read_vertex2(e);
+
+            mesh.vertex_read_coordinate(_a, 0, v1);
+            mesh.vertex_read_coordinate(_b, 0, v2);
+
+            const abx = _b[0] - _a[0], aby = _b[1] - _a[1], abz = _b[2] - _a[2];
+            const ab_sq = abx * abx + aby * aby + abz * abz;
+            if (ab_sq <= tol_sq) continue;
+
+            const t_margin = tolerance / Math.sqrt(ab_sq);
+
+            // candidate vertices: those within `tolerance` of the edge segment (a capsule)
+            _capsule[0] = _a[0]; _capsule[1] = _a[1]; _capsule[2] = _a[2];
+            _capsule[3] = _b[0]; _capsule[4] = _b[1]; _capsule[5] = _b[2];
+            _capsule[6] = tolerance;
+
+            const candidate_count = bvh_query_user_data_overlaps_capsule(candidates, 0, bvh, _capsule);
+
+            let split_t = -1;
+            let split_v = -1;
+
+            for (let i = 0; i < candidate_count; i++) {
+                const v = candidates[i];
+
+                // Candidates are original vertices, which are never removed during resolution (splits
+                // only add), so they are always allocated -- no is_allocated check needed.
+                if (v === v1 || v === v2) continue;
+
+                mesh.vertex_read_coordinate(_p, 0, v);
+
+                // the capsule query already guarantees distance-to-segment <= tolerance; all that is
+                // left is to exclude the segment's endpoints (its hemispherical end caps)
+                const t = ((_p[0] - _a[0]) * abx + (_p[1] - _a[1]) * aby + (_p[2] - _a[2]) * abz) / ab_sq;
+                if (t <= t_margin || t >= 1 - t_margin) continue;
+
+                split_t = t;
+                split_v = v;
+                break;
+            }
+
+            if (split_t >= 0) {
+                // snapshot the on-edge vertex coordinate, split, then snap the new vertex exactly onto it
+                mesh.vertex_read_coordinate(_hit, 0, split_v);
+                const nv = bt_edge_split(mesh, e, split_t);
+                mesh.vertex_write_coordinate(nv, _hit, 0);
+
+                total++;
+                changed = true;
+            }
+        }
+    }
+
+    return total;
+}

package/src/engine/physics/narrowphase/capsule_contacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capsule_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/capsule_contacts.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;GAeG;AACH,2CAVW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,eACN,MAAM,QAOhB;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,4CAhBW,MAAM,EAAE,GAAC,YAAY,QACrB,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,GACJ,OAAO,CA6CnB;AAMD;;;;;GAKG;AACH,6CAHW,MAAM,EAAE,GAAC,YAAY,yNACnB,OAAO,CAuEnB;AA8BD;;;;;;;;;GASG;AACH,oDAHW,MAAM,EAAE,GAAC,YAAY,yNACnB,MAAM,CAoHlB;AASD;;;;;;;;;;;;;GAaG;AACH,yCAHW,MAAM,EAAE,GAAC,YAAY,4NACnB,OAAO,CAqGnB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,gDAtBW,YAAY,QACZ,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,GACJ,MAAM,CAsElB;AAzaD;;;;;;;;GAQG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;;GAIG;AACH,2CAFU,MAAM,CAE8B;AAsQ9C;;;;;;;;;;GAUG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;;GAKG;AACH,uCAFU,MAAM,CAE0B"}
+{"version":3,"file":"capsule_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/capsule_contacts.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;GAeG;AACH,2CAVW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,eACN,MAAM,QAOhB;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,4CAhBW,MAAM,EAAE,GAAC,YAAY,QACrB,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,GACJ,OAAO,CA6CnB;AAMD;;;;;GAKG;AACH,6CAHW,MAAM,EAAE,GAAC,YAAY,yNACnB,OAAO,CAuEnB;AA8BD;;;;;;;;;GASG;AACH,oDAHW,MAAM,EAAE,GAAC,YAAY,yNACnB,MAAM,CAoHlB;AASD;;;;;;;;;;;;;GAaG;AACH,yCAHW,MAAM,EAAE,GAAC,YAAY,4NACnB,OAAO,CA6FnB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,gDAtBW,YAAY,QACZ,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,GACJ,MAAM,CAsElB;AAjaD;;;;;;;;GAQG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;;GAIG;AACH,2CAFU,MAAM,CAE8B;AA8P9C;;;;;;;;;;GAUG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;;GAKG;AACH,uCAFU,MAAM,CAE0B"}

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

@@ -1,5 +1,6 @@
 import { line3_closest_points_segment_segment } from "../../../core/geom/3d/line/line3_closest_points_segment_segment.js";
 import { line3_compute_segment_nearest_point_to_point_t } from "../../../core/geom/3d/line/line3_compute_segment_nearest_point_to_point_t.js";
+import { line3_compute_segment_nearest_point_to_aabb3_t } from "../../../core/geom/3d/line/line3_compute_segment_nearest_point_to_aabb3_t.js";
 import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
 import { v3_quat3_apply_inverse } from "../../../core/geom/vec3/v3_quat3_apply_inverse.js";
 import { sphere_box_contact } from "./sphere_box_contact.js";
@@ -389,27 +390,19 @@ export function capsule_box_contact(
     const a0lx = scratch_a0_local[0], a0ly = scratch_a0_local[1], a0lz = scratch_a0_local[2];
     const a1lx = scratch_a1_local[0], a1ly = scratch_a1_local[1], a1lz = scratch_a1_local[2];
 
-    // Fixed-point iteration: start with t at the closest point to the box centre.
-    let t = line3_compute_segment_nearest_point_to_point_t(a0lx, a0ly, a0lz, a1lx, a1ly, a1lz, 0, 0, 0);
-    let plx = a0lx + (a1lx - a0lx) * t;
-    let ply = a0ly + (a1ly - a0ly) * t;
-    let plz = a0lz + (a1lz - a0lz) * t;
-
-    for (let iter = 0; iter < 2; iter++) {
-        // Clamp current segment point to the box → closest box-surface point.
-        const qlx = plx < -b_hx ? -b_hx : (plx > b_hx ? b_hx : plx);
-        const qly = ply < -b_hy ? -b_hy : (ply > b_hy ? b_hy : ply);
-        const qlz = plz < -b_hz ? -b_hz : (plz > b_hz ? b_hz : plz);
-
-        // Re-find closest segment point to that box point.
-        t = line3_compute_segment_nearest_point_to_point_t(
-            a0lx, a0ly, a0lz, a1lx, a1ly, a1lz,
-            qlx, qly, qlz
-        );
-        plx = a0lx + (a1lx - a0lx) * t;
-        ply = a0ly + (a1ly - a0ly) * t;
-        plz = a0lz + (a1lz - a0lz) * t;
-    }
+    // Exact closest point on the capsule segment to the box-local AABB [−h, h].
+    // Replaces a 2-iteration alternating projection (project onto segment, clamp
+    // into box, repeat) that converged too slowly for capsules near-parallel to
+    // a box face/edge — overestimating the segment-vs-box distance, which
+    // under-detected contacts (~0.85% of random configs missed) and mis-placed
+    // depth/normal on many more. See core/geom/3d/gjk/GJK_REVIEW_NOTES.md.
+    const t = line3_compute_segment_nearest_point_to_aabb3_t(
+        a0lx, a0ly, a0lz, a1lx, a1ly, a1lz,
+        -b_hx, -b_hy, -b_hz, b_hx, b_hy, b_hz
+    );
+    const plx = a0lx + (a1lx - a0lx) * t;
+    const ply = a0ly + (a1ly - a0ly) * t;
+    const plz = a0lz + (a1lz - a0lz) * t;
 
     // Final box-side point. `let` because the interior branch snaps it onto
     // the chosen face — for an inside segment point the clamp is an identity.