@woosh/meep-engine 2.163.9 → 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.9",
+  "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/collection/heap/IndexedFloatMaxHeap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexedFloatMaxHeap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/heap/IndexedFloatMaxHeap.js"],"names":[],"mappings":"AA6BA;IACI;;;OAGG;IACH,yBAHW,MAAM,0BACN,MAAM,EAsBhB;IAbG,wBAA4C;IAC5C,eAAe;IAEf,2BAA4E;IAC5E,2BAAwD;IACxD,6BAA0D;IAE1D;;;OAGG;IACH,cAFU,WAAW,CAE2B;IAIpD,mBAEC;IAED;;;OAGG;IACH,cAQC;IAED,2BAEC;IAED;;;OAGG;IACH,qBAkBC;IAED;;;;OAIG;IACH,oBAsBC;IAED;;;;OAIG;IACH,kBAYC;IAED,wBAUC;IAED;;;OAGG;IACH,WAHW,MAAM,SACN,MAAM,QAehB;IAED;;OAEG;IACH,WAFa,MAAM,CAuBlB;IAED;;;OAGG;IACH,WAHW,MAAM,aACN,MAAM,QAehB;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CA+BnB;CACJ"}

package/src/core/{graph/metis/native/refine → collection/heap}/IndexedFloatMaxHeap.js

@@ -1,4 +1,4 @@
-import { assert } from "../../../../assert.js";
+import { assert } from "../../assert.js";
 
 /**
  * Max-heap of (uint32 id, float32 score) entries with an external id→slot index

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"}