@woosh/meep-engine 2.139.0 → 2.141.0

package/src/engine/physics/PLAN.md

@@ -1,236 +1,578 @@
-# Physics engine — state of play
-
-Tracker for what's built, what's pending, and what's deferred.
-
----
-
-## Context
-
-Deterministic JS rigid-body physics engine for the meep ECS. Target: game
-scenarios with up to millions of mostly-sleeping bodies, deterministic replays
-for netcode and reproducible debugging, broad shape coverage for common game
-collisions. Pure JS — no WASM, no SIMD, no worker threads.
-
-Architectural references for design choices:
-- **Jolt** — pre-allocated body pool, active-list iteration, two-tree
-  broadphase (static + dynamic).
-- **Bullet** — `btPersistentManifold` cache layout with up to 4 points.
-- **Box2D / Catto** — sequential impulse with warm-starting, Sutherland-Hodgman
-  face clipping for box-box.
-
----
-
-## Done
-
-### Foundations
-- `RigidBody`, `Collider`, `BodyKind`, `RigidBodyFlags`, `ColliderFlags`,
-  `SleepState`, `PhysicsEvents`.
-- `BodyStorage`: SoA pool, generation-tracked stable IDs, dense awake list,
-  min-heap free for deterministic ID reuse.
-- `PhysicsSystem`: full public API surface (gravity, force/impulse with and
-  without application point, torque, velocity setter, wake/sleep, contact
-  filter callback).
-- Binary serialization adapters for `RigidBody` and `Collider` (transient
-  runtime state deliberately excluded).
-- `PairUint32Map`: open-addressed Robin Hood + Fibonacci hash for the
-  pair → manifold-slot index (the one new collection added to `core/collection/`).
-
-### Pipeline (`PhysicsSystem.fixedUpdate`)
-1. Velocity integration (semi-implicit Euler, linear + angular, gravity,
-   damping, world-frame inverse-inertia for torque)
-2. Per-collider broadphase refit with fat AABB (Box2D-style velocity-padded
-   slack)
-3. Pair generation: per-leaf query against both BVHs (static + dynamic),
-   canonical `(min, max)` pairs, dedup via manifold touched flag
-4. Wake propagation for sleeping bodies in the pair list
-5. Narrowphase cross-product over collider lists
-6. Sequential-impulse solver (Catto-style, warm-start, friction, Baumgarte)
-7. Position integration (linear + quaternion)
-8. Sleep test (per-body velocity² below threshold for ≥ 0.5 s)
-9. Manifold diff → `ContactBegin` / `Stay` / `End` event dispatch
-10. `manifolds.advance_frame()` — roll touched bits, evict grace-expired slots
-
-### Shape coverage
-| Pair | Path | Manifold |
-|---|---|---|
-| sphere-sphere | closed-form | 1 point |
-| sphere-box | closed-form (handles centre-inside-box) | 1 point |
-| capsule-sphere | point-on-segment closed-form | 1 point |
-| capsule-capsule | segment-segment closest pair | 1 point |
-| capsule-box | iterative segment-vs-OBB (primary) + cap-centre sphere-vs-OBB at each endpoint | up to 3 |
-| box-box face-face | SAT + Sutherland-Hodgman clipping | up to 4 |
-| box-box edge-edge | SAT + midpoint fallback | 1 point |
-| anything else | GJK + EPA | 1 point (may fail on smooth shapes) |
-
-### Solver
-- Sequential impulse with warm-starting (10 velocity iterations by default).
-- Coulomb friction with disk-clamped tangent impulses.
-- Baumgarte position correction folded into the velocity solve.
-- Full angular Jacobian (`I_w⁻¹ = R · diag · R^T`) and angular impulse
-  application.
-- Public force/impulse-at-point API (`applyForceAt`, `applyImpulseAt`,
-  `applyTorque`).
-
-### Sleep + events
-- Per-island **atomic sleep**: an island sleeps when `max(|v|² + |ω|²)`
-  across all members stays below the threshold long enough; the whole
-  island sleeps in the same frame. Replaces the per-body chatter on
-  weakly-connected piles.
-- **Atomic wake**: members of a sleeping island are threaded into a
-  circular doubly-linked list (`sleep_group_next` / `sleep_group_prev`);
-  waking any one member walks the chain and wakes the rest in the same
-  call. A 100-block stack hit at the base wakes top-down in one frame
-  rather than over 100 frames of broadphase propagation.
-- `DisableSleep` on any island member exempts the whole island.
-- ContactBegin / Stay / End buffer + dispatch through both
-  `PhysicsSystem.onContactBegin/Stay/End` Signals and the per-entity
-  `entity.sendEvent(PhysicsEvents.ContactBegin, ...)` channel (when a
-  dataset is attached).
-
-### Islands
-- **Union-find** with path halving + union by min-index over the awake-body
-  + touched-contact graph (`engine/physics/island/union_find.js`).
-- **`IslandBuilder`** produces deterministic CSR-style output: bodies and
-  manifold slots grouped by island, sorted ascending within and across
-  islands. Static / kinematic bodies are constraint anchors only — they
-  don't merge islands, so disjoint piles on the same floor are separate
-  islands.
-- **Solver iterates per island**: impulse convergence happens inside an
-  island without waiting on unrelated bodies' Gauss-Seidel updates, and
-  disconnected awake bodies don't pay each other's solver cost.
-
-### Compound bodies
-- A body has 0..N attached colliders. Each collider has its own world
-  transform and its own BVH leaf.
-- Same-entity colliders, child-entity colliders (via `ParentEntity`), or
-  hybrids all supported.
-- `ColliderObserverSystem` auto-attaches colliders via the dataset when
-  paired with `PhysicsSystem` in an EntityManager.
-- Narrowphase runs the cross-product over both bodies' collider lists per
-  body-pair, accumulates candidates, reduces to ≤4 contacts by
-  depth + spread.
-
-### Public queries
-- `raycast(origin, dir, max_dist, filter?)` — nearest broadphase AABB hit
-  across both trees.
-
-### Determinism
-- Direct typed-array writes on hot paths (bypassing `Vector3#set`'s observer
-  dispatch) — Transform writes still go through `set()` because external
-  systems subscribe (TransformAttachment, EntityNode, FogOfWarRevealer,
-  ViewportPosition).
-- Active body iteration sorted by body index.
-- Pair canonicalisation `(min, max)`.
-- Min-heap free list for slot reuse.
-- No `Math.random` anywhere in the simulation step.
-- Same-runtime bit-exact determinism by design; cross-runtime is a known
-  future seam.
-
-### Migration
-- `Motion` / `MotionSystem` / `MotionSerializationAdapter` relocated from
-  the meep core (`engine/ecs/`) to the game-domain layer
-  (`mir-engine/model/game/ecs/`). meep no longer ships the legacy shim.
-
-### Bonus utilities
-- `core/geom/3d/line/line3_closest_points_segment_segment.js` — generally
-  useful 3D segment-segment closest-pair via Ericson §5.1.9.
-- `core/collection/PairUint32Map.js` — non-allocating
-  `Map<(u32, u32) → u32>` with Robin Hood + Fibonacci hash.
-
----
-
-## Limitations / Known caveats
-
-- **Multi-collider material precision**: solver reads friction/restitution
-  from the first-attached collider of each body. Mixed-material compound
-  bodies lose accuracy here. The contact-filter callback's `colliderA/B`
-  arguments are similarly the body's primary collider, not the specific
-  collider in contact.
-- **EPA on smooth shapes**: degenerates (no flat face to converge on).
-  Mitigated by closed-form paths for sphere/cube/capsule pairs; exotic
-  convex shapes vs spheres can still fail.
-- **Box-box edge-edge contact**: single midpoint contact rather than
-  multi-point. Skewed-orientation cube collisions are stable-enough but
-  not as precise as face-face.
-- **CCD floor only**: speculative margin via the fattened AABB prevents
-  most tunnelling. No per-body swept shape-cast for very fast objects.
-- **Cross-runtime determinism is not guaranteed**: `Math.sin/cos/exp/log`
-  are ULP-correct but not bit-exact across V8 / SpiderMonkey / JSC.
-
----
-
-## Backlog (planned, in scope)
-
-### Stability
-- [ ] **Edge-edge multi-point manifold** for skewed box contacts.
-- [ ] **Per-contact source-collider tracking** so multi-material compound
-      bodies get accurate per-contact friction/restitution. Requires
-      stashing the collider identity in the manifold contact stride.
-
-### Performance / Scale
-- [ ] **TGS (Temporal Gauss-Seidel) substepping**: optional alternative
-      to PGS for high-quality stacking with large mass ratios.
-- [ ] **Per-body linear CCD shape-cast**: optional opt-in for fast-moving
-      bodies where speculative margin isn't enough.
-- [ ] **Per-island parallel solve**: today's island data layout would
-      allow worker-based solving once `SharedArrayBuffer` is available.
-      Out-of-scope unless / until SAB is universally usable.
-
-### Features
-- [ ] **Joints**: distance, hinge, ball-socket, prismatic. The solver loop
-      is already set up to iterate `contacts ∪ joints`; only constraint
-      pre-step + warm-start hook is missing.
-- [ ] **Convex hull shape** with eigen-based principal-axes inertia
-      derivation. Hooks `matrix_eigenvalues_in_place` from the existing
-      linalg layer.
-- [ ] **Cylinder / cone shapes** (closed-form pairs against the existing
-      family + GJK+EPA fallback for general convex).
-
-### API polish
-- [ ] **`overlapShape(shape, position, rotation, filter?)`** public query
-      (broadphase + narrowphase) for AOE and selection use cases.
-- [ ] **`castShape(shape, from, to, rotation, filter?)`** for character
-      controllers and kinematic shape sweeps.
-
----
-
-## Future / out-of-scope
-
-These are explicit architectural exclusions or post-v1 explorations.
-
-### Architecture
-- **Cross-runtime bit-exact determinism**: a soft-float library would
-  replace `Math.sin/cos/exp/log/pow` in the hot path. The codebase is
-  already structured to make this a swap-in at `quat_integrate.js` and
-  tangent-basis construction in `build_manifold.js`. Not pursued because
-  the same-runtime determinism we have covers the common cases (single-
-  device replay, networked lockstep where all clients run the same JS
-  engine).
-- **WASM / SIMD**: the engine targets pure-JS portability. SIMD would
-  invalidate the determinism story (V8 doesn't expose deterministic
-  Float64x2 ops).
-- **Multi-threaded solver**: workers don't share memory cheaply without
-  `SharedArrayBuffer` plus the COOP/COEP HTTP headers, which are not
-  always available. Single-threaded is good-enough for the awake-body
-  budget that matters.
-
-### Simulation extensions
-- **Soft body / cloth / fluids**: the SoA layout in `BodyStorage` and the
-  manifold cache are rigid-body shaped. A soft-body system would be a
-  parallel subsystem, not an extension.
-- **Reduced-coordinate articulations** (MuJoCo / Featherstone-style):
-  game-physics audience runs in maximal coordinates by convention. Not
-  on the roadmap.
-
-### Game-side
-- **Vehicle physics** (suspensions, drivetrains): a domain layer that
-  sits on top of the rigid-body primitives, not in `meep/`.
-- **Character controllers**: same — `engine/control/first-person/` is the
-  natural home.
-
----
-
-## Notable design files
-
-- Original design plan: `C:\Users\Alex\.claude\plans\let-s-plan-to-implement-transient-harp.md`
-- This file (state of play): `engine/physics/PLAN.md`
+# Physics engine — state of play
+
+Tracker for what's built, what's pending, and what's deferred.
+
+---
+
+## Context
+
+Deterministic JS rigid-body physics engine for the meep ECS. Target: game
+scenarios with up to millions of mostly-sleeping bodies, deterministic replays
+for netcode and reproducible debugging, broad shape coverage for common game
+collisions. Pure JS — no WASM, no SIMD, no worker threads.
+
+Architectural references for design choices:
+- **Jolt** — pre-allocated body pool, active-list iteration, two-tree
+  broadphase (static + dynamic).
+- **Bullet** — `btPersistentManifold` cache layout with up to 4 points.
+- **Box2D / Catto** — sequential impulse with warm-starting, Sutherland-Hodgman
+  face clipping for box-box.
+
+---
+
+## Done
+
+### Foundations
+- `RigidBody`, `Collider`, `BodyKind`, `RigidBodyFlags`, `ColliderFlags`,
+  `SleepState`, `PhysicsEvents`.
+- `BodyStorage`: SoA pool, generation-tracked stable IDs, dense awake list,
+  min-heap free for deterministic ID reuse.
+- `PhysicsSystem`: full public API surface (gravity, force/impulse with and
+  without application point, torque, velocity setter, wake/sleep, contact
+  filter callback).
+- Binary serialization adapters for `RigidBody` and `Collider` (transient
+  runtime state deliberately excluded).
+- `PairUint32Map`: open-addressed Robin Hood + Fibonacci hash for the
+  pair → manifold-slot index (the one new collection added to `core/collection/`).
+
+### Pipeline (`PhysicsSystem.fixedUpdate`)
+1. Velocity integration (semi-implicit Euler, linear + angular, gravity,
+   damping, world-frame inverse-inertia for torque)
+2. Per-collider broadphase refit with fat AABB (Box2D-style velocity-padded
+   slack)
+3. Pair generation: per-leaf query against both BVHs (static + dynamic),
+   canonical `(min, max)` pairs, dedup via manifold touched flag
+4. Wake propagation for sleeping bodies in the pair list
+5. Narrowphase cross-product over collider lists
+6. Sequential-impulse solver (Catto-style, warm-start, friction, Baumgarte)
+7. Position integration (linear + quaternion)
+8. Sleep test (per-body velocity² below threshold for ≥ 0.5 s)
+9. Manifold diff → `ContactBegin` / `Stay` / `End` event dispatch
+10. `manifolds.advance_frame()` — roll touched bits, evict grace-expired slots
+
+### Shape coverage
+| Pair | Path | Manifold |
+|---|---|---|
+| sphere-sphere | closed-form | 1 point |
+| sphere-box | closed-form (handles centre-inside-box) | 1 point |
+| capsule-sphere | point-on-segment closed-form | 1 point |
+| capsule-capsule | segment-segment closest pair | 1 point |
+| capsule-box | iterative segment-vs-OBB (primary) + cap-centre sphere-vs-OBB at each endpoint | up to 3 |
+| box-box face-face | SAT + Sutherland-Hodgman clipping | up to 4 |
+| box-box edge-edge | SAT + midpoint fallback | 1 point |
+| convex × concave (heightmap, mesh) | per-triangle GJK + EPA via decomposition dispatcher | 1 point per triangle (deepest wins) |
+| anything else | GJK + EPA | 1 point (may fail on smooth shapes) |
+
+### Non-convex shapes
+- **`is_convex` flag** on `AbstractShape3D.prototype` (default `true`).
+  Overridden to `false` on `HeightMapShape3D`, `MeshShape3D`, `UnionShape3D`.
+  `TransformedShape3D` inherits via getter that reads the wrapped subject.
+- **`HeightMapShape3D`** — orientation-vector + `Sampler2D`-backed terrain
+  shape. Heights sampled via `sampleChannelCatmullRomUV` (matching the
+  terrain system's geometry construction). Compute_bounding_box,
+  contains_point, signed_distance, nearest_point_on_surface all
+  implemented; `support` throws (non-convex by construction).
+- **`Triangle3D`** — buffer-flyweight convex shape. `bind(buffer, offset)`
+  repoints at 9 consecutive floats in an external Float64Array. Zero
+  allocation per emission; used by the decomposition path.
+- **Triangle decomposition machinery** under
+  `engine/physics/narrowphase/decomposition/`:
+    - `TRIANGLE_FLOAT_STRIDE = 10` per triangle (`vA.xyz`, `vB.xyz`,
+      `vC.xyz`, `feature_id`).
+    - `heightmap_enumerate_triangles(out, offset, shape, ...aabb)` —
+      Arvo-projects the convex's AABB into heightmap-local, intersects
+      with the footprint to derive a cell range, emits 2 triangles per
+      cell with stable feature_ids.
+    - `mesh_enumerate_triangles(out, offset, shape, ...aabb)` — linear
+      O(N) scan over `MeshShape3D.indices` with tight per-triangle AABB
+      filtering. feature_id = triangle index.
+    - `aabb_world_to_local(out, world_aabb, pos, rot)` — 8-corner
+      projection of a world AABB into a body's local frame.
+    - `decompose_to_triangles(...)` — dispatcher switching on shape
+      type marker.
+- **Narrowphase concave dispatch** in `narrowphase_step.js`: detects
+  `is_convex === false`, computes convex's world AABB, projects to
+  concave's local frame, decomposes, per-triangle GJK + EPA with
+  one-sided face-normal rejection and contact-normal dedup. Concave-vs-
+  concave dynamic pairs are explicitly refused.
+
+### Solver
+- Sequential impulse with warm-starting (10 velocity iterations by default).
+- Coulomb friction with disk-clamped tangent impulses.
+- Baumgarte position correction folded into the velocity solve.
+- Full angular Jacobian (`I_w⁻¹ = R · diag · R^T`) and angular impulse
+  application.
+- Public force/impulse-at-point API (`applyForceAt`, `applyImpulseAt`,
+  `applyTorque`).
+
+### Sleep + events
+- Per-island **atomic sleep**: an island sleeps when `max(|v|² + |ω|²)`
+  across all members stays below the threshold long enough; the whole
+  island sleeps in the same frame. Replaces the per-body chatter on
+  weakly-connected piles.
+- **Atomic wake**: members of a sleeping island are threaded into a
+  circular doubly-linked list (`sleep_group_next` / `sleep_group_prev`);
+  waking any one member walks the chain and wakes the rest in the same
+  call. A 100-block stack hit at the base wakes top-down in one frame
+  rather than over 100 frames of broadphase propagation.
+- `DisableSleep` on any island member exempts the whole island.
+- ContactBegin / Stay / End buffer + dispatch through both
+  `PhysicsSystem.onContactBegin/Stay/End` Signals and the per-entity
+  `entity.sendEvent(PhysicsEvents.ContactBegin, ...)` channel (when a
+  dataset is attached).
+
+### Islands
+- **Union-find** with path halving + union by min-index over the awake-body
+  + touched-contact graph (`engine/physics/island/union_find.js`).
+- **`IslandBuilder`** produces deterministic CSR-style output: bodies and
+  manifold slots grouped by island, sorted ascending within and across
+  islands. Static / kinematic bodies are constraint anchors only — they
+  don't merge islands, so disjoint piles on the same floor are separate
+  islands.
+- **Solver iterates per island**: impulse convergence happens inside an
+  island without waiting on unrelated bodies' Gauss-Seidel updates, and
+  disconnected awake bodies don't pay each other's solver cost.
+
+### Compound bodies
+- A body has 0..N attached colliders. Each collider has its own world
+  transform and its own BVH leaf.
+- Same-entity colliders, child-entity colliders (via `ParentEntity`), or
+  hybrids all supported.
+- `ColliderObserverSystem` auto-attaches colliders via the dataset when
+  paired with `PhysicsSystem` in an EntityManager.
+- Narrowphase runs the cross-product over both bodies' collider lists per
+  body-pair, accumulates candidates, reduces to ≤4 contacts by
+  depth + spread.
+
+### Public queries
+- `raycast(origin, dir, max_dist, filter?)` — nearest broadphase AABB hit
+  across both trees.
+- `shapeCast(ray, shape, rotation, result, filter?)` — broadphase swept
+  AABB against both BVHs; per-candidate AABB-slab interval narrowing,
+  coarse step over the narrowed window, GJK bisection to time-of-impact.
+  Output normal is the true contact-surface normal at the kiss point,
+  recovered by re-running GJK + EPA at `best_t` on the winning candidate.
+  Falls back to `-ray.direction` only on EPA degeneracies (NaN / zero
+  depth). Tests cover axis-aligned, off-axis, and oblique cube-vs-cube;
+  sphere-vs-smooth-shape near-tangent has documented angular tolerance
+  bands inherited from EPA on smooth supports.
+- `overlap(shape, position, rotation, output, output_offset, filter?)`
+  — broadphase + per-candidate GJK overlap detection. Writes body_ids
+  into a caller-sized buffer; returns count. Convex query shapes only
+  (concave throws). Concave candidates routed through the per-triangle
+  decomposition path. Designed for speculative kinematic queries on
+  kinematic bodies (character controllers, AOE selection).
+
+### Standalone narrowphase utilities
+- `compute_penetration(out_direction, shape_a, pos_a, rot_a, shape_b,
+  pos_b, rot_b)` — non-system geometry primitive: positive penetration
+  depth + outward direction (B → A convention) on overlap, 0 otherwise.
+  Convex × convex uses GJK + EPA. Convex × concave uses per-triangle
+  half-space test (`convex.support(-face_normal)` projected onto each
+  triangle's plane), aggregated deepest-wins. The half-space approach
+  sidesteps `Triangle3D`'s degenerate support along face-normal axes
+  (the same issue that makes per-triangle GJK return false positives
+  on clearly non-overlapping sphere-above-flat configurations).
+  Concave × concave throws (M×N triangle pairs is out of scope).
+  Naturally handles "body inside the concave solid" — reports the depth
+  needed to push back through the nearest face. Documented limitation:
+  closed meshes can over-report on side faces whose 2D extent the
+  convex shape's flank crosses; a future closed-form triangle-vs-X
+  solver fixes this.
+
+### Determinism
+- Direct typed-array writes on hot paths (bypassing `Vector3#set`'s observer
+  dispatch) — Transform writes still go through `set()` because external
+  systems subscribe (TransformAttachment, EntityNode, FogOfWarRevealer,
+  ViewportPosition).
+- Active body iteration sorted by body index.
+- Pair canonicalisation `(min, max)`.
+- Min-heap free list for slot reuse.
+- No `Math.random` anywhere in the simulation step.
+- Same-runtime bit-exact determinism by design; cross-runtime is a known
+  future seam.
+
+### Migration
+- `Motion` / `MotionSystem` / `MotionSerializationAdapter` relocated from
+  the meep core (`engine/ecs/`) to the game-domain layer
+  (`mir-engine/model/game/ecs/`). meep no longer ships the legacy shim.
+
+### Alternative narrowphase: MPR
+- `engine/physics/gjk/mpr.js` — Minkowski Portal Refinement (XenoCollide,
+  Snethen GDC 2009). Single-pass overlap test + MTV computation,
+  output convention matches EPA so it's drop-in compatible at any
+  narrowphase call site. Tends to converge in 5–15 iterations on
+  smooth shapes where EPA stalls (the polytope-on-curved-surface
+  failure mode the torus-knot reproducer exercised). Not yet wired
+  into `narrowphase_step` — available as a swap candidate / per-pair
+  preference once we want to fall back to it on EPA non-convergence,
+  or as the default for any shape pair that involves a mesh.
+
+### Bonus utilities
+- `core/geom/3d/line/line3_closest_points_segment_segment.js` — generally
+  useful 3D segment-segment closest-pair via Ericson §5.1.9.
+- `core/collection/PairUint32Map.js` — non-allocating
+  `Map<(u32, u32) → u32>` with Robin Hood + Fibonacci hash.
+
+---
+
+## Limitations / Known caveats
+
+- **Multi-collider material precision**: solver reads friction/restitution
+  from the first-attached collider of each body. Mixed-material compound
+  bodies lose accuracy here. The contact-filter callback's `colliderA/B`
+  arguments are similarly the body's primary collider, not the specific
+  collider in contact.
+- **EPA on smooth shapes**: degenerates (no flat face to converge on).
+  Mitigated by closed-form paths for sphere/cube/capsule pairs; exotic
+  convex shapes vs spheres can still fail.
+- **EPA on `Triangle3D`** (concave-shape narrowphase): the triangle's
+  support is degenerate along its face-normal axis (all 3 vertices
+  project to the same value), so per-triangle GJK + EPA in the
+  narrowphase concave dispatch produces imprecise depths near the
+  iteration cap. A sphere dropping onto a flat heightmap decelerates
+  ~70% on first contact but eventually sinks through over ~50 steps —
+  the `narrowphase_concave.spec.js` "drop and settle" cases are
+  `test.skip` for this reason. Workaround in `compute_penetration` is
+  the half-space pre-test that avoids running GJK on degenerate
+  triangle supports altogether; long-term fix is closed-form
+  triangle-vs-primitive solvers.
+- **Box-box edge-edge contact**: single midpoint contact rather than
+  multi-point. Skewed-orientation cube collisions are stable-enough but
+  not as precise as face-face.
+- **CCD floor only**: speculative margin via the fattened AABB prevents
+  most tunnelling. No per-body swept shape-cast for very fast objects.
+- **Cross-runtime determinism is not guaranteed**: `Math.sin/cos/exp/log`
+  are ULP-correct but not bit-exact across V8 / SpiderMonkey / JSC.
+- **Dynamic concave bodies settle poorly under TGS**: the substep loop
+  re-derives contact geometry analytically from the per-triangle contact
+  feature (witness anchors + normal) captured once by narrowphase and held
+  fixed for the whole outer step. For a convex body the contact feature is
+  stable under the small per-step motion, so this is exact; for a *dynamic
+  concave mesh body* (e.g. a torus knot rocking on its own lobes) the
+  supporting triangle itself changes as the body rocks, so freezing the
+  feature pumps a little energy in and the body rocks / slowly sinks instead
+  of settling (the `PhysicsSystem.spec.js` torus-knot dynamic-settle test is
+  `test.skip` for this reason). Note this is NOT a contact-precision issue —
+  the knot already uses the exact closed-form box-triangle solver (P1.1b);
+  the problem is purely that TGS freezes *which* feature is in contact across
+  substeps. The common concave case — a convex dynamic body on static concave
+  terrain — is unaffected (the convex side's feature is stable), and that is
+  the only concave case the engine targets.
+
+  **Interim fix (implemented): per-substep concave re-detection.** For
+  contact pairs involving a concave body, the substep loop re-runs the
+  concave narrowphase geometry at the current substep pose (instead of the
+  analytic refresh that freezes the feature) and re-prepares those contacts
+  from the fresh witness/normal/depth — so the contact normal tracks the
+  rocking body and no energy is pumped in. Convex pairs keep the cheap
+  analytic refresh. This is ~Nx narrowphase cost on concave-involved pairs
+  (acceptable — they're rare), gated by collider convexity. Un-skips the
+  torus-knot dynamic-settle test.
+
+  **Better long-term fix: convex collision proxies (not raw concave).** Every
+  major engine (Box2D, Jolt, PhysX, Rapier) requires dynamic bodies to be
+  convex or convex-decomposed; raw concave meshes are static-only. The right
+  granularity is a *few* convex pieces — NOT the thousands of tets a
+  volumetric mesher produces (tet count ≈ collider/BVH-leaf count, which
+  explodes the broadphase for an awake body; tet meshing is for a future
+  FEM/soft-body subsystem, not rigid collision). See the "Convex collision
+  proxies for dynamic concave bodies" backlog item — a 3D convex hull builder
+  (single-hull proxy covers most dynamic objects) plus an optional
+  few-hull (V-HACD-style) decomposition. Those supersede the interim
+  per-substep re-detection once built.
+
+---
+
+## Backlog (planned, in scope)
+
+### Solver quality (next major work)
+
+These items move the engine from "competent" to "great". TGS is the next
+significant solver-architecture change; joints come after, once the TGS
+scaffolding is in place.
+
+- **TGS (Temporal Gauss-Seidel) substepping with split-impulse** — Phases
+      1–3 **LANDED**. The solver is now a staged TGS pipeline
+      (`solver/solve_contacts.js`: `prepare_contacts` → per substep
+      [`refresh_contacts` → `warm_start_contacts` → `solve_velocity` →
+      `solve_position`] → `apply_restitution`), driven by the substep loop in
+      `PhysicsSystem.fixedUpdate`. Defaults: `substeps = 4`,
+      `velocityIterations = 4`, `positionIterations = 1` (all fields on
+      `PhysicsSystem`).
+        - **Phase 1 — split impulse.** Position correction runs on a per-body
+          pseudo-velocity (`__pseudo_velocity`) folded into the pose by
+          `integrate_position` and discarded; depth correction never
+          contaminates persistent velocity.
+        - **Phase 2 — one-shot restitution.** Velocity pass is pure
+          non-penetration; restitution is a single post-loop pass driving
+          `vn → -e·vn_approach`, gated on a running max normal impulse
+          (`maxNormalImpulse`) so transient collisions still bounce under
+          per-substep warm-start.
+        - **Phase 3 — substep loop.** `substeps` sub-iterations at `h = dt/N`.
+          Forces consumed once at full `dt` before the loop; gravity applied
+          per substep; **warm-start replayed per substep** (the crux — a
+          per-substep impulse balances one substep of gravity, so resting
+          stacks hold at zero velocity). Contact geometry is re-derived
+          **analytically** each substep from frozen local witness anchors +
+          the trusted prepare-time depth (a sign-robust delta), so narrowphase
+          runs **once** per outer step — cheaper than the originally-planned
+          per-substep match-and-merge refresh, and exact for convex
+          primitives whose contact feature is stable under small motion.
+
+      Results vs the single-step solver: a 100:1 mass ratio now stacks
+      instead of crushing through (regression test added); 8-cube stacks
+      settle to zero velocity and sleep (were impossible long-term under SI);
+      falling-tower bench cost unchanged (~48 ms/1000 active bodies);
+      `substeps = 1` reproduces the single-step result bit-for-bit-ish
+      (one-frame restitution delay aside).
+
+      **Hard-won lessons (for REVIEW_002):**
+        - Warm-start MUST be per-substep, not once. Replaying a full-frame
+          impulse once while gravity arrives per substep over-pushes resting
+          contacts and *explodes* deep stacks. Per-substep warm-start +
+          per-substep gravity cancel exactly at rest.
+        - Restitution must gate on the *running max* normal impulse, not the
+          end-of-loop value — per-substep warm-start relaxes a transient
+          contact's `j_n` back to ~0 by the end, which would suppress the
+          bounce.
+        - Analytic separation re-derivation beats per-substep narrowphase
+          for convex shapes (cheaper, no manifold-lifecycle churn) but is
+          only as good as the frozen normal — see the concave caveat below.
+
+      Follow-ups since the core landed:
+        - [x] **Box-box SAT reference tie-break deadband** — aligned cube
+          stacks (4–10 high) now settle to zero velocity and sleep; the
+          reference-face flip-flop that creeped/toppled them is gone.
+        - [x] **Per-substep contact re-detection for concave pairs** — lifts
+          the dynamic-concave-body limitation; the torus-knot dynamic-settle
+          test is un-skipped. Concave pairs re-run narrowphase geometry each
+          substep (`redetect_concave_contacts`); convex pairs keep the cheap
+          analytic refresh.
+
+      Remaining (Phases 4–6) — now complete:
+        - [x] Regression coverage: heavy-on-light pyramid (10× capstone on two
+          light cubes settles + sleeps) and a ragdoll-stub (shoulder
+          ball-socket + elbow hinge arm hangs, stays articulated, settles).
+        - [x] REVIEW_002 retrospective — `engine/physics/REVIEW_002.md`.
+
+      References: Catto 2018 ("Soft Constraints" GDC talk + the TGS
+      follow-up); Box2D v3 source (`b2ApplyRestitution`, the substep solver
+      stages); Rapier as the closest architectural sibling.
+
+- [ ] **Constraints / joints — the next major work.** Now unblocked: TGS is
+      in (joint-chain convergence is a TGS sweet spot), warm-start +
+      per-substep + island machinery is reusable, and the SPOOK compliance
+      dial already in the contact solver gives soft/spring constraints
+      essentially for free. Target use cases: chains/ropes, ragdolls,
+      vehicles (incl. suspension), plus the common mechanical set (doors,
+      pistons, welds, grab/drag, winches, drivetrains).
+
+      **Foundational work (do first): generalise the solver to constraint
+      rows.** Today `solver/solve_contacts.js` is hard-coded to the
+      contact-shape constraint (normal + 2 friction tangents, ≥0 clamp,
+      restitution, penetration bias). Joints are equality / inequality
+      constraints on relative velocity at anchors, generally bilateral
+      (impulse may be ±) with optional limits and motors. The clean shape —
+      and what Jolt / Box2D-v3 do — is a **generic constraint row**: a
+      Jacobian (linear + angular parts per body), an effective mass, a bias
+      (position error × SPOOK gain, or motor target), and impulse bounds
+      `[lo, hi]` (`[0,∞)` for a contact/limit, `(−∞,∞)` for an equality,
+      `[−maxForce·h, +maxForce·h]` for a motor). Each joint type just fills
+      in its rows; the existing per-body impulse-apply primitive
+      (`apply_impulse_to_body` + `world_inverse_inertia_apply`), the
+      per-substep warm-start, the islands, and the split-impulse / SPOOK
+      position handling are all reused. Contacts become *one* constraint
+      type among several rather than the hard-coded path.
+
+      The specific constraint set, its use-case mapping, and per-type
+      architecture-fit assessment are under review (see the constraints
+      sketch). High level: ball-socket / distance / spring / weld and the
+      grab constraint are near drop-ins on the row machinery; hinge /
+      prismatic / cone-twist / motors / limits add angular-row + bounded-row
+      mechanics (still within the impulse framework); raycast vehicles,
+      conveyor surface-velocity, and gear/pulley coupling are higher-level
+      systems or contact modifiers that sit *on top of* the primitives
+      rather than being generic rows.
+
+      **Decision: build ONE configurable 6-DOF constraint** (PhysX D6 / Jolt
+      SixDOF), implemented mode-by-mode. The `Joint` ECS component carries
+      `dofMode[6]` (3 linear, 3 angular) each `{locked|free|limited|spring|
+      motor}` + per-DOF limit/spring/motor config + warm-start accumulators.
+      Concrete joints are configs, not new code (ball-socket = lock 3 linear;
+      hinge = lock 3 linear + 2 angular; weld = lock 6; cone-twist = lock 3
+      linear + limit 3 angular; suspension = spring 1 linear + lock rest).
+
+      Phasing:
+        1. [x] Constraint-row solver as a **parallel row set** in the TGS
+           substep loop (contacts left untouched, not ported — lower risk).
+           `constraint/solve_constraints.js` reuses `world_inverse_inertia`,
+           per-substep warm-start, and the SPOOK position bias; `Joint`
+           component + `link_joint`/`unlink_joint` in PhysicsSystem;
+           `jointIterations` knob. Bodies need no collider.
+        2. [x] **LOCKED linear DOFs → ball-socket.** Pendulum (anchor pinned
+           to a world pivot, body swings) and a 2-link chain (body↔body,
+           joints stay connected, chain hangs) pass. → **chains, ropes,
+           pendulums working.**
+        3. [x] LOCKED angular + linear DOFs in the frame basis — **weld,
+           hinge, prismatic done**. Joint frame bases
+           (`localBasisA`/`localBasisB`); BOTH linear and angular rows now
+           resolve in frame A's axes (cleared the world-axis linear debt — the
+           solver is fully frame-relative). Angular: relative rotation
+           `qD = conj(qA)·qB` → small-angle error, ωB−ωA rows + SPOOK bias.
+           Linear: `C·axis` error, vA−vB rows. `asWeld()` / `asHinge(axis)` /
+           `asPrismatic(axis)` presets. Verified: weld holds pose + orientation
+           against an off-centre torque; hinge swings about its free axis only
+           (locked axes < 0.02); prismatic slides along its one free axis,
+           locked on the others; all LOCKED-mode tests still green after the
+           frame-basis rewrite.
+        4. [ ] LIMITED + MOTOR (bounded rows) → doors, pistons, wheel
+           spin/drive, joint ROM.
+        5. [ ] SPRING (SPOOK soft) → suspension, bungees, soft ragdolls.
+        6. [ ] Cone-twist / swing-twist angular limits → ragdolls.
+        7. [ ] Vehicle layer — recommend a **raycast-vehicle controller**
+           (raycast + suspension force + tire friction; what most games ship)
+           on top of the queries, with simulated wheels via the 6-DOF as an
+           option. → vehicles.
+        8. [ ] Extras: pulley, gear, conveyor (contact surface-velocity),
+           breakable-joint flag.
+
+      Foundation gaps — both now closed:
+        - [x] **Island integration.** Jointed dynamic-dynamic bodies are
+          unioned into one island (`IslandBuilder` Pass 1b), so a chain /
+          ragdoll sleeps and wakes as a unit; `__wake_joints` propagates wake
+          across a joint when one side is awake and the other asleep
+          (e.g. a kinematic/motor driver pulling a sleeping chain). Verified:
+          a damped chain settles and both links sleep in one sleep group.
+        - [x] **Generation-checked body references.** `solve_joints`,
+          `IslandBuilder` Pass 1b and `__wake_joints` all gate on
+          `storage.is_valid(packedId)`, so a joint to an unlinked / slot-reused
+          body goes inert instead of attaching to the wrong body or crashing.
+          Verified: unlinking a jointed body leaves the joint inert and the
+          survivor free.
+
+      References: Catto / Box2D-v3 joint solvers; Jolt's `Constraint` base
+      (`SetupVelocityConstraint` / `WarmStartVelocityConstraint` /
+      `SolveVelocityConstraint` / `SolvePositionConstraint`); PhysX D6 /
+      ODE joint taxonomy.
+
+### Stability
+- [ ] **Closed-form triangle-vs-primitive solvers**
+      (`triangle_sphere_contact`, `triangle_box_contact`,
+      `triangle_capsule_contact`). The decomposition machinery is in
+      place (`Triangle3D` flyweight, `heightmap_enumerate_triangles` /
+      `mesh_enumerate_triangles`, `decompose_to_triangles` dispatcher,
+      `aabb_world_to_local`, `narrowphase_step.js` concave branch), but
+      the per-triangle narrowphase uses GJK + EPA which hits the
+      smooth-shape iteration cap and `Triangle3D`'s degenerate-support
+      issue. Closed-form solvers per primitive bypass both. This is now
+      the single biggest accuracy gap in the engine — it would:
+        - Unblock the `narrowphase_concave.spec.js` skipped tests (ball
+          drops on heightmap / mesh-cube settle correctly).
+        - Unblock the `PhysicsSystem.spec.js` torus-knot test.
+        - Improve `compute_penetration`'s closed-mesh accuracy (currently
+          documented over-reports on side faces).
+      Existing primitive pair solvers (`sphere_box_contact`,
+      `capsule_box_multi_contacts`, `box_box_manifold`) are the
+      blueprint. Triangle is roughly a box with two half-extents = 0.
+- [ ] **Edge-edge multi-point manifold** for skewed box contacts.
+- [ ] **Per-contact source-collider tracking** so multi-material compound
+      bodies get accurate per-contact friction/restitution. Requires
+      stashing the collider identity in the manifold contact stride.
+
+### Performance / Scale
+- [ ] **Per-body linear CCD shape-cast**: optional opt-in for fast-moving
+      bodies where speculative margin isn't enough. The bench's falling
+      tower (1km drop onto a 1cm floor) is the concrete reproducer —
+      180 / 1000 bodies tunnel.
+- [ ] **Per-island parallel solve**: today's island data layout would
+      allow worker-based solving once `SharedArrayBuffer` is available.
+      Out-of-scope unless / until SAB is universally usable.
+
+### Features
+- [ ] **Convex collision proxies for dynamic concave bodies.** The long-term
+      replacement for the interim per-substep concave re-detection (see
+      Limitations) — and how every major engine handles dynamic non-convex
+      shapes: collide a *few* convex pieces, never the raw concave mesh.
+        1. **3D convex hull builder** (meep has only 2D hulls today —
+           `core/geom/2d/convex-hull/`). A single hull of a mesh is one
+           collider / one broadphase leaf and covers the overwhelming majority
+           of dynamic objects (thrown props, debris). Pairs with the existing
+           "Convex hull shape + eigen-inertia" item below.
+        2. **Few-hull (V-HACD-style) approximate convex decomposition** for
+           shapes whose concavity matters (a cup, a chair): ~8–64 fat convex
+           hulls = 8–64 colliders, two orders of magnitude below a tet mesh.
+      Each hull is convex → stable contact feature → the TGS analytic refresh
+      is exact → no per-substep re-detection, no rocking. Granularity is the
+      whole point: collider/BVH-leaf count must stay small for an *awake*
+      dynamic body (the volumetric tet-mesher under `core/geom/3d/tetrahedra/`
+      is the wrong tool here — thousands of pieces — and belongs to a future
+      FEM/soft-body subsystem, not rigid collision).
+- [ ] **Convex hull shape** with eigen-based principal-axes inertia
+      derivation. Hooks `matrix_eigenvalues_in_place` from the existing
+      linalg layer.
+- [ ] **Cylinder / cone shapes** (closed-form pairs against the existing
+      family + GJK+EPA fallback for general convex).
+
+### API polish
+- [x] **`overlap(shape, position, rotation, output, output_offset,
+      filter?)`** — broadphase + narrowphase overlap query for kinematic
+      / AOE / selection use cases. Body_ids written into a caller-sized
+      Uint32Array buffer. Convex query shape only; concave candidates
+      are routed through the per-triangle decomposition path.
+- [x] **`shapeCast(ray, shape, rotation, result, filter?)`** for
+      character controllers and kinematic shape sweeps. Broadphase
+      swept-AABB against both BVHs; per-candidate AABB-slab interval
+      narrowing + coarse step + GJK bisection for time-of-impact. The
+      output `result.normal` is the true contact-surface normal at the
+      kiss point, computed by re-running GJK + EPA at `best_t` on the
+      winning candidate (falls back to `-ray.direction` only on EPA
+      degeneracies).
+- [x] **`compute_penetration(out_direction, shape_a, pos_a, rot_a,
+      shape_b, pos_b, rot_b)`** — standalone geometry primitive (no
+      PhysicsSystem) for resolving overlap between two shapes at given
+      poses. Returns depth + outward direction. Convex × convex via
+      GJK + EPA; convex × concave via per-triangle half-space test.
+
+---
+
+## Future / out-of-scope
+
+These are explicit architectural exclusions or post-v1 explorations.
+
+### Architecture
+- **Cross-runtime bit-exact determinism**: a soft-float library would
+  replace `Math.sin/cos/exp/log/pow` in the hot path. The codebase is
+  already structured to make this a swap-in at `quat_integrate.js` and
+  tangent-basis construction in `build_manifold.js`. Not pursued because
+  the same-runtime determinism we have covers the common cases (single-
+  device replay, networked lockstep where all clients run the same JS
+  engine).
+- **WASM / SIMD**: the engine targets pure-JS portability. SIMD would
+  invalidate the determinism story (V8 doesn't expose deterministic
+  Float64x2 ops).
+- **Multi-threaded solver**: workers don't share memory cheaply without
+  `SharedArrayBuffer` plus the COOP/COEP HTTP headers, which are not
+  always available. Single-threaded is good-enough for the awake-body
+  budget that matters.
+
+### Simulation extensions
+- **Soft body / cloth / fluids**: the SoA layout in `BodyStorage` and the
+  manifold cache are rigid-body shaped. A soft-body system would be a
+  parallel subsystem, not an extension.
+- **Reduced-coordinate articulations** (MuJoCo / Featherstone-style):
+  game-physics audience runs in maximal coordinates by convention. Not
+  on the roadmap.
+
+### Game-side
+- **Vehicle physics** (suspensions, drivetrains): a domain layer that
+  sits on top of the rigid-body primitives, not in `meep/`.
+- **Character controllers**: same — `engine/control/first-person/` is the
+  natural home.
+
+---
+
+## Notable design files
+
+- Original design plan: `C:\Users\Alex\.claude\plans\let-s-plan-to-implement-transient-harp.md`
+- This file (state of play): `engine/physics/PLAN.md`