@woosh/meep-engine 3.0.2 → 3.2.0

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

@@ -1,117 +1,117 @@
-import { v3_distance_above_plane } from "../../vec3/v3_distance_above_plane.js";
-import Vector3 from "../../Vector3.js";
-import { plane3_compute_3_plane_intersection } from "../plane/plane3_compute_3_plane_intersection.js";
-import { plane3_compute_intersection } from "../plane/plane3_compute_intersection.js";
-import { plane3_project_point } from "../plane/plane3_project_point.js";
-import { ray3_compute_closest_point } from "../ray/ray3_compute_closest_point.js";
-
-/**
- * Indices into the caller's plane list, for the planes the target lies outside of.
- * @type {number[]}
- */
-const scratch_outer_planes = [];
-
-const scratch_v3_0 = new Vector3();
-
-const scratch_v3_1 = new Vector3();
-
-/**
- *
- * @type {number[]}
- */
-const scratch_v3_array = [];
-
-/**
- * The point inside a convex frustum nearest to a target point, and whether the target was already
- * inside it.
- *
- * **A plane is a `Vector4`**: `x, y, z` its normal and `w` its constant, inside where
- * `dot(normal, p) + w` is non-negative. That is the same four numbers every frustum query in the
- * tree reads and what `camera_active_frustum` publishes; it used to be a three `Plane`, whose
- * `normal`/`constant` pair is the same thing wearing an object (X15d).
- *
- * @param {Vector3} result
- * @param {Vector4[]} planes
- * @param {number} target_x
- * @param {number} target_y
- * @param {number} target_z
- * @returns {boolean} if point is inside the frustum - true, false otherwise
- */
-export function frustum3_compute_closest_point(result, planes, target_x, target_y, target_z) {
-    let j;
-
-    let outside_plane_count = 0;
-
-    const plane_count = planes.length;
-
-    for (j = 0; j < plane_count; j++) {
-
-        const plane = planes[j];
-
-        const distance = v3_distance_above_plane(
-            target_x, target_y, target_z,
-            plane.x, plane.y, plane.z, plane.w
-        );
-
-        if (distance < 0) {
-
-            scratch_outer_planes[outside_plane_count] = j;
-
-            outside_plane_count++;
-
-        }
-
-    }
-
-    if (outside_plane_count === 0) {
-        result.set(target_x, target_y, target_z);
-
-        return true;
-    }
-
-    // point is outside the frustum
-
-    if (outside_plane_count === 1) {
-        const plane_0 = planes[scratch_outer_planes[0]];
-
-        // point lies outside exactly one plane
-        plane3_project_point(result, target_x, target_y, target_z, plane_0.x, plane_0.y, plane_0.z, plane_0.w);
-    } else if (outside_plane_count === 2) {
-        // outside two planes, nearest point lies on the intersection line of two planes
-
-        const plane_0 = planes[scratch_outer_planes[0]];
-        const plane_1 = planes[scratch_outer_planes[1]];
-
-        const intersection_exists = plane3_compute_intersection(
-            scratch_v3_0, scratch_v3_1,
-            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
-            plane_1.x, plane_1.y, plane_1.z, plane_1.w
-        );
-
-        if (!intersection_exists) {
-            throw new Error('Planes are parallel and do not intersect, likely an invalid frustum');
-        }
-
-        ray3_compute_closest_point(result,
-            scratch_v3_0.x, scratch_v3_0.y, scratch_v3_0.z,
-            scratch_v3_1.x, scratch_v3_1.y, scratch_v3_1.z,
-            target_x, target_y, target_z
-        );
-    } else if (outside_plane_count === 3) {
-        // outside 3 planes, nearest point is intersect of 3 planes
-        const plane_0 = planes[scratch_outer_planes[0]];
-        const plane_1 = planes[scratch_outer_planes[1]];
-        const plane_2 = planes[scratch_outer_planes[2]];
-
-        plane3_compute_3_plane_intersection(
-            scratch_v3_array, 0,
-            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
-            plane_1.x, plane_1.y, plane_1.z, plane_1.w,
-            plane_2.x, plane_2.y, plane_2.z, plane_2.w
-        );
-
-        result.fromArray(scratch_v3_array, 0)
-    }
-
-    return false;
-}
+import { v3_distance_above_plane } from "../../vec3/v3_distance_above_plane.js";
+import Vector3 from "../../Vector3.js";
+import { plane3_compute_3_plane_intersection } from "../plane/plane3_compute_3_plane_intersection.js";
+import { plane3_compute_intersection } from "../plane/plane3_compute_intersection.js";
+import { plane3_project_point } from "../plane/plane3_project_point.js";
+import { ray3_compute_closest_point } from "../ray/ray3_compute_closest_point.js";
+
+/**
+ * Indices into the caller's plane list, for the planes the target lies outside of.
+ * @type {number[]}
+ */
+const scratch_outer_planes = [];
+
+const scratch_v3_0 = new Vector3();
+
+const scratch_v3_1 = new Vector3();
+
+/**
+ *
+ * @type {number[]}
+ */
+const scratch_v3_array = [];
+
+/**
+ * The point inside a convex frustum nearest to a target point, and whether the target was already
+ * inside it.
+ *
+ * **A plane is a `Vector4`**: `x, y, z` its normal and `w` its constant, inside where
+ * `dot(normal, p) + w` is non-negative. That is the same four numbers every frustum query in the
+ * tree reads and what `camera_active_frustum` publishes; it used to be a three `Plane`, whose
+ * `normal`/`constant` pair is the same thing wearing an object (X15d).
+ *
+ * @param {Vector3} result
+ * @param {Vector4[]} planes
+ * @param {number} target_x
+ * @param {number} target_y
+ * @param {number} target_z
+ * @returns {boolean} if point is inside the frustum - true, false otherwise
+ */
+export function frustum3_compute_closest_point(result, planes, target_x, target_y, target_z) {
+    let j;
+
+    let outside_plane_count = 0;
+
+    const plane_count = planes.length;
+
+    for (j = 0; j < plane_count; j++) {
+
+        const plane = planes[j];
+
+        const distance = v3_distance_above_plane(
+            target_x, target_y, target_z,
+            plane.x, plane.y, plane.z, plane.w
+        );
+
+        if (distance < 0) {
+
+            scratch_outer_planes[outside_plane_count] = j;
+
+            outside_plane_count++;
+
+        }
+
+    }
+
+    if (outside_plane_count === 0) {
+        result.set(target_x, target_y, target_z);
+
+        return true;
+    }
+
+    // point is outside the frustum
+
+    if (outside_plane_count === 1) {
+        const plane_0 = planes[scratch_outer_planes[0]];
+
+        // point lies outside exactly one plane
+        plane3_project_point(result, target_x, target_y, target_z, plane_0.x, plane_0.y, plane_0.z, plane_0.w);
+    } else if (outside_plane_count === 2) {
+        // outside two planes, nearest point lies on the intersection line of two planes
+
+        const plane_0 = planes[scratch_outer_planes[0]];
+        const plane_1 = planes[scratch_outer_planes[1]];
+
+        const intersection_exists = plane3_compute_intersection(
+            scratch_v3_0, scratch_v3_1,
+            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
+            plane_1.x, plane_1.y, plane_1.z, plane_1.w
+        );
+
+        if (!intersection_exists) {
+            throw new Error('Planes are parallel and do not intersect, likely an invalid frustum');
+        }
+
+        ray3_compute_closest_point(result,
+            scratch_v3_0.x, scratch_v3_0.y, scratch_v3_0.z,
+            scratch_v3_1.x, scratch_v3_1.y, scratch_v3_1.z,
+            target_x, target_y, target_z
+        );
+    } else if (outside_plane_count === 3) {
+        // outside 3 planes, nearest point is intersect of 3 planes
+        const plane_0 = planes[scratch_outer_planes[0]];
+        const plane_1 = planes[scratch_outer_planes[1]];
+        const plane_2 = planes[scratch_outer_planes[2]];
+
+        plane3_compute_3_plane_intersection(
+            scratch_v3_array, 0,
+            plane_0.x, plane_0.y, plane_0.z, plane_0.w,
+            plane_1.x, plane_1.y, plane_1.z, plane_1.w,
+            plane_2.x, plane_2.y, plane_2.z, plane_2.w
+        );
+
+        result.fromArray(scratch_v3_array, 0)
+    }
+
+    return false;
+}

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

@@ -1,7 +1,7 @@
-import { frustum3_matrix4_project } from "./frustum3_matrix4_project.js";
-
-/**
- * @deprecated Renamed to {@link frustum3_matrix4_project}. This re-export is kept for backward
- * compatibility (meep is a library; old names are public surface).
- */
-export const frustum_matrix4_project = frustum3_matrix4_project;
+import { frustum3_matrix4_project } from "./frustum3_matrix4_project.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_matrix4_project}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const frustum_matrix4_project = frustum3_matrix4_project;

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

@@ -1,7 +1,7 @@
-import { frustum3_from_aabb } from "./frustum3_from_aabb.js";
-
-/**
- * @deprecated Renamed to {@link frustum3_from_aabb}. This re-export is kept for backward
- * compatibility (meep is a library; old names are public surface).
- */
-export const hexahedron_from_aabb = frustum3_from_aabb;
+import { frustum3_from_aabb } from "./frustum3_from_aabb.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_from_aabb}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const hexahedron_from_aabb = frustum3_from_aabb;

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

@@ -1,17 +1,17 @@
-import { v3_copy_array } from "../../vec3/v3_copy_array.js";
-
-/**
- * Read one corner out of a packed frustum-corner buffer.
- *
- * Index-flavoured wrapper over {@link v3_copy_array}: corners are stored as consecutive `(x, y, z)`
- * triples, so corner `i` starts at element `i * 3`. Overlapping source/destination ranges are safe —
- * `v3_copy_array` reads all three components before writing any.
- *
- * @param {number[]|Float32Array|Float64Array} source
- * @param {number} source_index
- * @param {number[]|Float32Array|Float64Array} destination
- * @param {number} destination_offset
- */
-export function read_frustum_corner(source, source_index, destination, destination_offset) {
-    v3_copy_array(destination, destination_offset, source, source_index * 3);
-}
+import { v3_copy_array } from "../../vec3/v3_copy_array.js";
+
+/**
+ * Read one corner out of a packed frustum-corner buffer.
+ *
+ * Index-flavoured wrapper over {@link v3_copy_array}: corners are stored as consecutive `(x, y, z)`
+ * triples, so corner `i` starts at element `i * 3`. Overlapping source/destination ranges are safe —
+ * `v3_copy_array` reads all three components before writing any.
+ *
+ * @param {number[]|Float32Array|Float64Array} source
+ * @param {number} source_index
+ * @param {number[]|Float32Array|Float64Array} destination
+ * @param {number} destination_offset
+ */
+export function read_frustum_corner(source, source_index, destination, destination_offset) {
+    v3_copy_array(destination, destination_offset, source, source_index * 3);
+}

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

@@ -1,7 +1,7 @@
-import { frustum3_planes_to_flat_from_three } from "./frustum3_planes_to_flat_from_three.js";
-
-/**
- * @deprecated Renamed to {@link frustum3_planes_to_flat_from_three}. This re-export is kept for backward
- * compatibility (meep is a library; old names are public surface).
- */
-export const read_three_planes_to_array = frustum3_planes_to_flat_from_three;
+import { frustum3_planes_to_flat_from_three } from "./frustum3_planes_to_flat_from_three.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_planes_to_flat_from_three}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const read_three_planes_to_array = frustum3_planes_to_flat_from_three;

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

@@ -1,7 +1,7 @@
-import { frustum3_slice_linear_to_points } from "./frustum3_slice_linear_to_points.js";
-
-/**
- * @deprecated Renamed to {@link frustum3_slice_linear_to_points}. This re-export is kept for backward
- * compatibility (meep is a library; old names are public surface).
- */
-export const slice_frustum_linear_to_points = frustum3_slice_linear_to_points;
+import { frustum3_slice_linear_to_points } from "./frustum3_slice_linear_to_points.js";
+
+/**
+ * @deprecated Renamed to {@link frustum3_slice_linear_to_points}. This re-export is kept for backward
+ * compatibility (meep is a library; old names are public surface).
+ */
+export const slice_frustum_linear_to_points = frustum3_slice_linear_to_points;

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

@@ -1,146 +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).
+# 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).