@woosh/meep-engine 2.140.0 → 2.141.0

package/package.json

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

package/src/core/geom/3d/quaternion/quat3_multiply.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hamilton product of two unit quaternions: `out = a ⊗ b`.
+ *
+ * Composition order is the usual rotation convention: the product `a ⊗ b`
+ * applies `b` first, then `a` (i.e. `(a⊗b)·v·(a⊗b)* == a·(b·v·b*)·a*`). So to
+ * rotate a vector by `q1` and then by `q2`, compose `q2 ⊗ q1`.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and
+ * the rest of the `core/geom/3d/quaternion/` family.
+ *
+ * `out` may alias neither `a` nor `b` component-wise (the result is computed
+ * from all eight inputs before any write, so passing the same backing array
+ * via different offsets is safe only if the ranges don't overlap).
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number} ax @param {number} ay @param {number} az @param {number} aw
+ * @param {number} bx @param {number} by @param {number} bz @param {number} bw
+ */
+export function quat3_multiply(out: number[] | Float32Array | Float64Array, out_offset: number, ax: number, ay: number, az: number, aw: number, bx: number, by: number, bz: number, bw: number): void;
+//# sourceMappingURL=quat3_multiply.d.ts.map

package/src/core/geom/3d/quaternion/quat3_multiply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quat3_multiply.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/quat3_multiply.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,oCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,MAC/D,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,QAOzE"}

package/src/core/geom/3d/quaternion/quat3_multiply.js

@@ -0,0 +1,25 @@
+/**
+ * Hamilton product of two unit quaternions: `out = a ⊗ b`.
+ *
+ * Composition order is the usual rotation convention: the product `a ⊗ b`
+ * applies `b` first, then `a` (i.e. `(a⊗b)·v·(a⊗b)* == a·(b·v·b*)·a*`). So to
+ * rotate a vector by `q1` and then by `q2`, compose `q2 ⊗ q1`.
+ *
+ * Sign convention: `(x, y, z, w)` — `w` last, matching {@link Quaternion} and
+ * the rest of the `core/geom/3d/quaternion/` family.
+ *
+ * `out` may alias neither `a` nor `b` component-wise (the result is computed
+ * from all eight inputs before any write, so passing the same backing array
+ * via different offsets is safe only if the ranges don't overlap).
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset offset into `out`; receives 4 floats (x, y, z, w)
+ * @param {number} ax @param {number} ay @param {number} az @param {number} aw
+ * @param {number} bx @param {number} by @param {number} bz @param {number} bw
+ */
+export function quat3_multiply(out, out_offset, ax, ay, az, aw, bx, by, bz, bw) {
+    out[out_offset]     = aw * bx + ax * bw + ay * bz - az * by;
+    out[out_offset + 1] = aw * by - ax * bz + ay * bw + az * bx;
+    out[out_offset + 2] = aw * bz + ax * by - ay * bx + az * bw;
+    out[out_offset + 3] = aw * bw - ax * bx - ay * by - az * bz;
+}

package/src/engine/physics/PLAN.md

@@ -257,21 +257,30 @@ Architectural references for design choices:
   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). The fix is
-  per-substep contact re-detection for pairs involving a concave body
-  (re-running narrowphase, or at least re-selecting the deepest triangle,
-  inside the substep loop) while convex pairs keep the cheap analytic
-  refresh — a hybrid the substep architecture already accommodates. Medium+
-  *perfectly* axis-aligned cube stacks can fail to fully settle (and so never
-  sleep), but *erratically* with height and exact placement — a 5-stack may
-  jitter while a 7-stack sleeps, and a sub-mm gap flips the outcome. That
-  chaotic, configuration-sensitive signature is box-box contact-point jitter
-  (Sutherland-Hodgman clipping selecting different points frame to frame),
-  NOT the solver — confirmed by running the same stacks through both the
-  single-step and TGS paths. It's the separate box-box-manifold robustness /
-  stable-feature-ID backlog item, independent of TGS. Realistic (slightly
-  perturbed, mixed-shape) stacks are unaffected; mass ratios up to ~100:1 and
-  4-/7-/8-cube aligned stacks settle and sleep cleanly under TGS.
+  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.
 
 ---
 
@@ -331,31 +340,121 @@ scaffolding is in place.
           for convex shapes (cheaper, no manifold-lifecycle churn) but is
           only as good as the frozen normal — see the concave caveat below.
 
-      Remaining (Phases 4–6, backlog):
-        - More regression coverage: heavy-on-light *pyramid*, a
-          ragdoll-stub once joints exist.
-        - **Per-substep contact re-detection for concave pairs** to lift the
-          dynamic-concave-body limitation (see Limitations) and un-skip the
-          torus-knot dynamic-settle test. The analytic refresh freezes *which*
-          triangle is the contact feature across substeps, which is wrong for
-          a body rocking on a mesh; convex pairs keep the cheap analytic path.
-        - REVIEW_002 retrospective.
+      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.
 
-- [ ] **Joints** (distance, hinge, ball-socket, prismatic — and beyond).
-      *To be refined when we get to it.* Joints want the TGS substep
-      iteration model in place first — joint-chain convergence is a TGS
-      sweet spot and a PGS pain point, and any constraint structures
-      written against PGS today become migration cost once TGS lands.
-      The solver loop is already set up to iterate
-      `contacts ∪ joints` and the manifold-style impulse persistence is
-      there; what's missing is the constraint structures themselves,
-      joint-limit handling, the motor / soft-constraint surface, and
-      the authoring API. Plan the phased breakdown once TGS lands —
-      until then this stays as a visible dependency placeholder.
+- [ ] **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**
@@ -391,6 +490,24 @@ scaffolding is in place.
       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.

package/src/engine/physics/REVIEW_002.md

@@ -0,0 +1,151 @@
+# REVIEW_002 — TGS solver, contact robustness, and constraints
+
+Retrospective on the "competent → great" push: promoting the solver from
+single-step PGS to substepped TGS, fixing the contact-robustness issues that
+surfaced, and standing up the 6-DOF constraint subsystem. Companion to the
+engine-comparison docs (`CANNON_REVIEW`, `RAPIER_REVIEW`, `JOLT_REVIEW`,
+`BULLET_REVIEW`); this one is a build retrospective, not a comparison.
+
+Scope: the work tracked in `PLAN.md` under "Solver quality" + "Constraints /
+joints". What landed, the hard-won lessons, where the implementation
+deviated from the original plan and why, and what's deferred.
+
+---
+
+## What landed
+
+**TGS (Temporal Gauss-Seidel), Phases 1–3.** The solver is now a staged
+pipeline driven by a substep loop:
+`prepare → per substep [redetect-concave / refresh-convex → warm-start →
+solve-velocity → solve-position] → restitution`. Defaults: 4 substeps, 4
+velocity + 1 position iteration per substep. Split-impulse position
+correction (pseudo-velocity folded into the pose, never into real velocity);
+one-shot restitution; SPOOK compliance as the soft-constraint dial.
+
+**Contact robustness.**
+- Box-box SAT reference tie-break deadband → aligned cube stacks 4–10 high
+  settle to zero velocity and sleep.
+- Per-substep concave re-detection → a dynamic concave mesh body (torus knot)
+  settles instead of rocking.
+
+**Constraints — 6-DOF configurable joint** (PhysX D6 / Jolt SixDOF model):
+one constraint type, each of 3 linear + 3 angular DOFs independently
+locked/free/limited/spring/motor. Landed modes: LOCKED linear (ball-socket)
+and LOCKED angular (hinge, weld). Solved as a parallel row set inside the
+same substep loop; island-integrated; generation-checked against stale body
+references.
+
+Coverage went ~698 → 720+ physics tests, all green. Falling-tower bench
+unchanged (~48 ms / 1000 active bodies).
+
+---
+
+## Hard-won lessons
+
+These cost real debugging and are the reason the code looks the way it does.
+
+1. **Per-substep warm-start is mandatory under substepping.** The first
+   substep attempt warm-started once per outer step and applied gravity per
+   substep. That mismatch — replaying a *full-frame* impulse against a
+   *single substep* of gravity — over-pushes resting contacts and **explodes**
+   deep stacks (a 10-cube stack hit 9 m of drift / 13 m/s). The fix: gravity
+   per substep **and** warm-start per substep, so each substep's gravity and
+   each substep's replayed impulse cancel exactly at rest. A resting body
+   holds at `v = 0`, `j_n ≈ m·g·h`.
+
+2. **Restitution must gate on the running-max normal impulse, not the
+   end-of-loop value.** With per-substep warm-start, a transient collision's
+   accumulated `j_n` relaxes back to ~0 by the end of the loop (no sustained
+   load to hold it), so gating restitution on the final `j_n` silently killed
+   every bounce. Tracking `maxNormalImpulse` over the whole step (Box2D-v3's
+   trick) is what makes restitution fire.
+
+3. **Analytic separation re-derivation is great for convex, wrong for
+   dynamic concave.** Re-deriving each substep's penetration from frozen
+   witness anchors + current pose (no narrowphase re-run) is cheap and exact
+   *while the contact feature is stable* — true for a convex primitive under
+   the small per-step motion. For a concave body rocking on a mesh, the
+   supporting triangle (and its normal) genuinely changes mid-step, so
+   freezing it pumps energy in. Resolution: convex pairs use the cheap
+   analytic refresh; concave-involved pairs re-run narrowphase geometry each
+   substep (`redetect_concave_contacts`). Hybrid, gated by collider convexity.
+
+4. **The aligned-stack instability was not the solver.** Cube stacks crept
+   and toppled; the instinct was "solver convergence". Dumping
+   `box_box_manifold` across a settling pair showed the normal and contact
+   *count* were stable, but the *reference face* flip-flopped between A and B
+   each frame (their SAT overlaps are exactly equal for aligned boxes, so
+   float noise from a sub-degree wobble decided the winner). That reordered
+   the contacts → flipped the Gauss-Seidel sweep order → alternating bias →
+   creep. A 6-line relative+absolute tie-break deadband (bias ties toward the
+   earlier-tested axis) fixed stacks 4–10. **Lesson: diagnose the manifold
+   before blaming the solver.**
+
+5. **Granularity is everything for dynamic concave.** The first instinct
+   ("decompose the mesh into the exact Delaunay tets we already have") is
+   wrong: a Suzanne is ~8000 tets → ~8000 colliders → ~8000 dynamic-BVH
+   leaves refit every frame. Tet meshing is a *volumetric* (FEM/soft-body)
+   tool. Rigid collision wants the *fewest* convex pieces — a single convex
+   hull for most dynamic objects, or a few-hull (V-HACD-style) decomposition.
+   Recorded as the long-term path; the per-substep re-detection is the
+   interim.
+
+6. **One configurable 6-DOF constraint beats N joint types.** The row math is
+   contact-shaped (Jacobian + effective mass + bias + bounds), so it slots
+   into the existing solver. Concrete joints become *config*: ball-socket =
+   lock 3 linear; hinge = lock 3 linear + 2 angular; weld = lock 6. This
+   minimises distinct code paths — the whole point.
+
+7. **Sign conventions: linear A−B, angular B−A.** The linear rows use
+   "A minus B" (impulse +to A); the angular rows use "B minus A" (impulse
+   +to B). Each is internally consistent — the body-order difference just
+   folds the sign in. Derived carefully against the SPOOK Baumgarte target
+   (`dC/dt = vrel`); both worked first try once written down.
+
+---
+
+## Deviations from the original plan (and why)
+
+- **Joints run as a parallel row set, not by porting contacts onto a shared
+  constraint base.** The plan floated either. Porting the working,
+  well-tuned contact path carried regression risk for no immediate benefit;
+  running joints as a second row family in the same substep loop gets the
+  coupling (shared warm-start / islands / substep cadence) at far lower risk.
+  Unifying remains optional.
+
+- **Convex contacts use analytic refresh, not per-substep match-and-merge.**
+  The plan said "substeps refresh contacts via match-and-merge". Analytic
+  re-derivation is cheaper and avoids manifold-lifecycle churn for the convex
+  majority; match-and-merge-style re-detection is reserved for the concave
+  minority (lesson 3).
+
+- **Dynamic concave: per-substep re-detection now, convex proxies later** —
+  not the tet-compound idea first sketched (lesson 5).
+
+---
+
+## Deferred (with rationale)
+
+- **Constraints**: prismatic (needs frame-basis linear rows — today's linear
+  locks use world axes, exact only when all 3 are locked), limits, motors,
+  springs (SPOOK soft), swing-twist (ragdoll cone), the raycast-vehicle
+  layer, and extras (pulley/gear/conveyor/breakable). Sequenced in `PLAN.md`.
+- **Trajectory accuracy**: gravity is substepped, so ballistic integration is
+  at the substep rate — good. No higher-order integrator pursued.
+- **Per-island parallel solve / CCD shape-cast / closed-form
+  triangle-vs-primitive remainder**: unchanged backlog items.
+- **Convex hull builder + few-hull decomposition**: the production answer for
+  dynamic concave (lesson 5), not yet built.
+
+---
+
+## Bottom line
+
+The engine moved from "competent PGS" to a substepped TGS solver with stable
+stacks, accurate restitution, robust mass ratios, settling dynamic concave
+bodies, and a working 6-DOF constraint (ball-socket / hinge / weld) — i.e.
+chains, ropes, and the structural joints for ragdolls and mechanisms. The
+costliest mistakes were all about *substepping invariants* (warm-start and
+restitution-gating cadence) and *not trusting assumptions* (the stack bug was
+narrowphase, not the solver). The remaining constraint work is incremental
+on a validated framework.

package/src/engine/physics/constraint/DofMode.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-degree-of-freedom mode for a 6-DOF constraint ({@link Joint }).
+ *
+ * A 6-DOF constraint has 3 linear DOFs (translation of body B's anchor frame
+ * relative to body A's, along A's frame axes) and 3 angular DOFs (relative
+ * rotation, swing-twist decomposed). Each DOF independently takes one of these
+ * modes — which is how a single configurable constraint expresses the whole
+ * joint taxonomy (PhysX D6 / Jolt SixDOF / Bullet Generic6DOF):
+ *
+ *   - ball-socket  = lock 3 linear
+ *   - hinge        = lock 3 linear + 2 angular
+ *   - prismatic    = lock 2 linear + 3 angular
+ *   - weld         = lock all 6
+ *   - cone-twist   = lock 3 linear + limit 3 angular
+ *   - suspension   = spring 1 linear + lock the rest
+ *
+ * Implementation lands mode-by-mode: LOCKED first (covers ball-socket / hinge
+ * / prismatic / weld), then LIMITED, SPRING, MOTOR.
+ */
+export type DofMode = number;
+export namespace DofMode {
+    let LOCKED: number;
+    let FREE: number;
+    let LIMITED: number;
+    let SPRING: number;
+    let MOTOR: number;
+}
+//# sourceMappingURL=DofMode.d.ts.map

package/src/engine/physics/constraint/DofMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DofMode.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/DofMode.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;sBAqBU,MAAM"}

package/src/engine/physics/constraint/DofMode.js

@@ -0,0 +1,35 @@
+/**
+ * Per-degree-of-freedom mode for a 6-DOF constraint ({@link Joint}).
+ *
+ * A 6-DOF constraint has 3 linear DOFs (translation of body B's anchor frame
+ * relative to body A's, along A's frame axes) and 3 angular DOFs (relative
+ * rotation, swing-twist decomposed). Each DOF independently takes one of these
+ * modes — which is how a single configurable constraint expresses the whole
+ * joint taxonomy (PhysX D6 / Jolt SixDOF / Bullet Generic6DOF):
+ *
+ *   - ball-socket  = lock 3 linear
+ *   - hinge        = lock 3 linear + 2 angular
+ *   - prismatic    = lock 2 linear + 3 angular
+ *   - weld         = lock all 6
+ *   - cone-twist   = lock 3 linear + limit 3 angular
+ *   - suspension   = spring 1 linear + lock the rest
+ *
+ * Implementation lands mode-by-mode: LOCKED first (covers ball-socket / hinge
+ * / prismatic / weld), then LIMITED, SPRING, MOTOR.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @enum {number}
+ */
+export const DofMode = {
+    /** Constrained to zero (relative position/angle held at the rest value). */
+    LOCKED: 0,
+    /** Unconstrained — the DOF moves freely. */
+    FREE: 1,
+    /** Free within `[lower, upper]`, constrained (one-sided) at the limits. */
+    LIMITED: 2,
+    /** A soft spring (stiffness + damping) pulling toward a rest target. */
+    SPRING: 3,
+    /** Driven toward a target velocity, bounded by a maximum force. */
+    MOTOR: 4,
+};

package/src/engine/physics/constraint/solve_constraints.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Solve every joint for one substep: recompute geometry at the current poses,
+ * replay the per-substep warm-start, and run `iters` velocity iterations of
+ * the locked linear DOFs.
+ *
+ * Called once per substep from `PhysicsSystem.fixedUpdate`, after the contact
+ * solve so the two share the substep / warm-start cadence.
+ *
+ * @param {Joint[]} joints  live joints (sparse array; holes skipped)
+ * @param {PhysicsSystem} system  reads `__bodies` / `__transforms` / index map
+ * @param {number} dt_sub  substep size in seconds (the SPOOK gain is derived
+ *   from it, matching the contact solver's per-substep position stiffness)
+ * @param {number} iters  velocity iterations
+ */
+export function solve_joints(joints: Joint[], system: PhysicsSystem, dt_sub: number, iters: number): void;
+//# sourceMappingURL=solve_constraints.d.ts.map

package/src/engine/physics/constraint/solve_constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AAyJA;;;;;;;;;;;;;GAaG;AACH,qCANW,OAAO,iCAEP,MAAM,SAEN,MAAM,QA8QhB"}