@woosh/meep-engine 2.154.0 → 2.156.0

package/src/engine/control/first-person/math/jumpDynamics.js

@@ -0,0 +1,108 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Jump power as physics, not a magic velocity.
+ *
+ * A jump is the legs doing WORK: a push-off force `F` (newtons) applied over a
+ * leg-extension distance `d` (meters) while the body is still on the ground.
+ * That work becomes the body's kinetic energy at the instant it leaves the
+ * ground, which gravity then trades back for height:
+ *
+ *     F · d   =   ½ · m · v₀²          (leg work → launch kinetic energy)
+ *     ½ · m · v₀²   =   m · g · h      (launch KE → potential energy at apex)
+ *
+ * Eliminating v₀ collapses the two into a single, mass-honest relationship
+ * between the force the legs deliver and the apex the body reaches:
+ *
+ *     h   =   F · d / (m · g)
+ *     F   =   m · g · h / d
+ *     v₀  =   √(2 · F · d / m)   =   √(2 · g · h)
+ *
+ * Why express jump power as a FORCE (newtons) rather than a launch velocity?
+ *   - It is a property of the CHARACTER (the legs), not of the jump. A fixed
+ *     leg force makes a heavier body jump lower — `h ∝ 1/m` — for free, which a
+ *     raw launch-velocity number cannot express (the same v₀ ignores mass).
+ *   - It composes: momentum, fatigue, and surface bonuses all add/scale in the
+ *     same physical currency (newtons) before a single conversion to velocity.
+ *
+ * `d` (the push-off distance) is the one extra parameter a newtons model needs:
+ * force alone can't determine a launch without the distance (or time) it acts
+ * over. It is a body constant — roughly the crouch-to-full-extension travel of
+ * the legs (~0.4–0.5 m for a ~1.8 m human countermovement jump).
+ *
+ * All three functions are pure and frame-independent. The headline is
+ * {@link jumpForceForHeight}: the newtons a designer needs to reach a desired
+ * apex on a given character. {@link launchVelocityForForce} is the forward
+ * conversion an ability applies at launch.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The push-off force (newtons) the legs must deliver for the body to reach a
+ * given apex height — i.e. newtons BACK-CALCULATED from the desired maximum
+ * jump height on this character.
+ *
+ *     F = m · g · h / d
+ *
+ * Heavier body → more force for the same height; stronger gravity → more force;
+ * a longer push-off distance → less force (the work is spread over more travel).
+ *
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} gravity          gravitational acceleration, m/s² (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @param {number} height           desired apex height above launch, m (>= 0)
+ * @returns {number} push-off force in newtons
+ */
+export function jumpForceForHeight(mass, gravity, pushoffDistance, height) {
+    assert.greaterThan(mass, 0, "mass");
+    assert.greaterThan(gravity, 0, "gravity");
+    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
+    assert.greaterThanOrEqual(height, 0, "height");
+
+    return (mass * gravity * height) / pushoffDistance;
+}
+
+/**
+ * The apex height (meters) a given push-off force produces on this character —
+ * the inverse of {@link jumpForceForHeight}.
+ *
+ *     h = F · d / (m · g)
+ *
+ * @param {number} force            push-off force, newtons (>= 0)
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} gravity          gravitational acceleration, m/s² (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @returns {number} apex height above launch, meters
+ */
+export function jumpHeightForForce(force, mass, gravity, pushoffDistance) {
+    assert.greaterThanOrEqual(force, 0, "force");
+    assert.greaterThan(mass, 0, "mass");
+    assert.greaterThan(gravity, 0, "gravity");
+    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
+
+    return (force * pushoffDistance) / (mass * gravity);
+}
+
+/**
+ * The launch velocity (m/s) a given push-off force imparts to this character —
+ * the forward conversion an ability applies at the instant of launch.
+ *
+ *     v₀ = √(2 · F · d / m)
+ *
+ * Note this is independent of gravity: gravity only governs the apex the launch
+ * velocity then reaches, not the launch itself.
+ *
+ * @param {number} force            push-off force, newtons (>= 0)
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @returns {number} launch velocity, m/s
+ */
+export function launchVelocityForForce(force, mass, pushoffDistance) {
+    assert.greaterThanOrEqual(force, 0, "force");
+    assert.greaterThan(mass, 0, "mass");
+    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
+
+    return Math.sqrt((2 * force * pushoffDistance) / mass);
+}

package/src/engine/control/first-person/prototype_first_person_controller.js

@@ -30,6 +30,7 @@ import { RigidBody } from "../../physics/ecs/RigidBody.js";
 import { PhysicsSurfacePoint } from "../../physics/queries/PhysicsSurfacePoint.js";
 import { LedgeGrab } from "./abilities/LedgeGrab.js";
 import { Mantle } from "./abilities/Mantle.js";
+import { ScrambleUp } from "./abilities/ScrambleUp.js";
 import { Slide } from "./abilities/Slide.js";
 import { WallJump } from "./abilities/WallJump.js";
 import { WallRun } from "./abilities/WallRun.js";
@@ -84,6 +85,7 @@ const COLOR_SLIDE = 0x44ddee;
 const COLOR_GAP = 0xff66cc;
 const COLOR_STAIRS = 0xeedd44;
 const COLOR_RAMP = 0x3377dd;
+const COLOR_SCRAMBLE = 0x33ffaa;
 const COLOR_NEUTRAL = 0xaaaaaa;
 
 const eh = new EngineHarness();
@@ -234,6 +236,7 @@ function buildGym(ecd) {
     buildGapJumpStation(ecd);
     buildStairsStation(ecd);
     buildRampStation(ecd);
+    buildScrambleStation(ecd);
     buildMeshShapeShowcase(ecd);
 }
 
@@ -516,6 +519,34 @@ function buildLedgeGrabStation(ecd) {
     });
 }
 
+/**
+ * Scramble-up station — a tall wall the player runs vertically UP a short
+ * distance (à la Assassin's Creed) to reach a grabbable top, or to kick off.
+ * East of spawn.
+ *
+ *   1. sprint at the wall (hold forward into it)
+ *   2. ScrambleUp launches a short vertical climb up the face
+ *   3. near the apex the top comes into reach → LedgeGrab catches it on the
+ *      way down → press jump to Mantle up onto the platform
+ *   4. …or press jump DURING the climb for a wall-kick off the face
+ *
+ * The wall top (2.8 m) is just out of standing grab reach (~1.9 m), so a
+ * scramble is required — a shorter wall would just be a plain Mantle.
+ */
+function buildScrambleStation(ecd) {
+    const baseX = SPAWN_X + 15;
+    spawnPad(ecd, baseX - 6, SPAWN_Z, COLOR_SCRAMBLE);
+
+    // Tall solid block: top at 2.8 m, wide + deep enough to stand on after the
+    // climb (so scramble → grab → mantle-up lands somewhere).
+    spawnBox(ecd, {
+        center: new Vector3(baseX, 1.4, SPAWN_Z),
+        size: new Vector3(4, 2.8, 8),
+        color: COLOR_SCRAMBLE,
+        roughness: 0.6,
+    });
+}
+
 /**
  * Slide tunnel — a sprint run-up followed by a low ceiling that forces
  * the player to slide under. NE of spawn.
@@ -830,6 +861,7 @@ function buildPlayerEntity(ecd) {
     controller.abilities.add(new Slide());
     controller.abilities.add(new Mantle());
     controller.abilities.add(new LedgeGrab());
+    controller.abilities.add(new ScrambleUp());
     controller.abilities.add(new WallRun());
     controller.abilities.add(new WallJump());
 
@@ -971,8 +1003,20 @@ function setupPointerLock(engine) {
     const captureEl = engine.viewStack.el;
 
     captureEl.addEventListener("click", () => {
-        if (document.pointerLockElement !== el && el.requestPointerLock) {
+        if (document.pointerLockElement === el || !el.requestPointerLock) return;
+        // Request RAW mouse input (no OS pointer acceleration) where supported —
+        // acceleration on a high-res mouse amplifies micro-bursts into spurious
+        // `movementX` spikes (the camera-snap source). Browsers that don't
+        // support the option reject/throw; fall back to a plain lock.
+        let p;
+        try {
+            p = el.requestPointerLock({ unadjustedMovement: true });
+        } catch (e) {
             el.requestPointerLock();
+            return;
+        }
+        if (p && typeof p.catch === "function") {
+            p.catch(() => { el.requestPointerLock(); });
         }
     });
 

package/src/engine/graphics/camera/testClippingPlaneComputation.js

@@ -73,7 +73,7 @@ function makeConfig(engine) {
         new ScriptSystem(),
         new FacingDirectionSystem(),
         new PathFollowingSystem(),
-        new SoundEmitterSystem(assetManager, sound.destination, sound.context),
+        new SoundEmitterSystem(assetManager, sound),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),
         new TimerSystem(),

package/src/engine/graphics/ecs/decal/v2/FPDecalSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FPDecalSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/decal/v2/FPDecalSystem.js"],"names":[],"mappings":"AAoOA;;GAEG;AACH;IAGI;;;OAGG;IACH,4BA0CC;IAhDD,SAAgB;IASZ,kDAAsC;IAEtC;;;;OAIG;IACH,wBAUE;IAEF;;;;OAIG;IACH,iBAAmC;IAEnC;;;;OAIG;IACH,iBAAsB;IAEtB;;;;OAIG;IACH,oBAAiC;IAGrC,gCAEC;IAED,iCAEC;IAED;;;;;;OAMG;IACH,4BALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CA2DlB;IAED;;;;;;;;;;;OAWG;IACH,kBAVW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,uEAGJ;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,SAAS,EAAC,KAAK,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAC,EAAE,CAkGtE;CACJ;sCA1bqC,iDAAiD;oBArBnE,sCAAsC;0BAuBhC,wCAAwC;sBAM5C,YAAY;2BArBP,4CAA4C;8BASzC,8CAA8C"}
+{"version":3,"file":"FPDecalSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/decal/v2/FPDecalSystem.js"],"names":[],"mappings":"AAqOA;;GAEG;AACH;IAGI;;;OAGG;IACH,4BA0CC;IAhDD,SAAgB;IASZ,kDAAsC;IAEtC;;;;OAIG;IACH,wBAUE;IAEF;;;;OAIG;IACH,iBAAmC;IAEnC;;;;OAIG;IACH,iBAAsB;IAEtB;;;;OAIG;IACH,oBAAiC;IAGrC,gCASC;IAED,iCAEC;IAED;;;;;;OAMG;IACH,4BALW,MAAM,EAAE,iBACR,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CA2DlB;IAED;;;;;;;;;;;OAWG;IACH,kBAVW,MAAM,YACN,MAAM,YACN,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,uEAGJ;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,SAAS,EAAC,KAAK,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAC,EAAE,CAkGtE;CACJ;sCAjcqC,iDAAiD;oBAtBnE,sCAAsC;0BAwBhC,wCAAwC;sBAM5C,YAAY;2BAtBP,4CAA4C;8BASzC,8CAA8C"}

package/src/engine/graphics/ecs/decal/v2/FPDecalSystem.js

@@ -21,6 +21,7 @@ import { SurfacePoint3 } from "../../../../../core/geom/3d/SurfacePoint3.js";
 import { computeStringHash } from "../../../../../core/primitives/strings/computeStringHash.js";
 import { AssetManager } from "../../../../asset/AssetManager.js";
 import { GameAssetType } from "../../../../asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../../../../asset/loaders/image/ImageRGBADataLoader.js";
 import { AbstractContextSystem } from "../../../../ecs/system/AbstractContextSystem.js";
 import { SystemEntityContext } from "../../../../ecs/system/SystemEntityContext.js";
 import { Transform } from "../../../../ecs/transform/Transform.js";
@@ -282,6 +283,13 @@ export class FPDecalSystem extends AbstractContextSystem {
 
     async startup(em) {
         this.__fp_plugin = await this.__engine.plugins.acquire(ForwardPlusRenderingPlugin);
+
+        const am = this.__engine.assetManager;
+        if (!am.hasLoaderForType(GameAssetType.Image)) {
+            await am.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
+        }
+
+
     }
 
     async shutdown(em) {

package/src/engine/graphics/ecs/path/tube/prototypeAnimatedPathMask.js

@@ -91,7 +91,7 @@ function makeConfig(engine) {
         new FacingDirectionSystem(),
         new PathFollowingSystem(),
         new AttachmentSystem(),
-        new SoundEmitterSystem(assetManager, sound.destination, sound.context),
+        new SoundEmitterSystem(assetManager, sound),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),
         new TimerSystem(),

package/src/engine/graphics/particles/particular/engine/utils/volume/prototypeParticleVolume.js

@@ -99,7 +99,7 @@ function makeConfig(engine) {
 
     config.addManySystems(
         new AttachmentSystem(),
-        new SoundEmitterSystem(assetManager, sound.destination, sound.context),
+        new SoundEmitterSystem(assetManager, sound),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),
         guiSystem,

package/src/engine/graphics/render/buffer/buffers/prototypeNormalFrameBuffer.js

@@ -82,7 +82,7 @@ function makeConfig(engine) {
         new FacingDirectionSystem(),
         new PathFollowingSystem(),
         new AttachmentSystem(),
-        new SoundEmitterSystem(assetManager, sound.destination, sound.context),
+        new SoundEmitterSystem(assetManager, sound),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),
         new TimerSystem(),

package/src/engine/graphics/render/forward_plus/plugin/ptototypeFPPlugin.js

@@ -110,7 +110,7 @@ function makeConfig(engine) {
         new FacingDirectionSystem(),
         new PathFollowingSystem(),
         new AttachmentSystem(),
-        new SoundEmitterSystem(assetManager, sound.destination, sound.context),
+        new SoundEmitterSystem(assetManager, sound),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),
         new TimerSystem(),

package/src/engine/graphics/render/visibility/hiz/prototypeHiZ.js

@@ -88,7 +88,7 @@ function makeConfig(engine) {
         new FacingDirectionSystem(),
         new PathFollowingSystem(),
         new AttachmentSystem(),
-        new SoundEmitterSystem(assetManager, sound.destination, sound.context),
+        new SoundEmitterSystem(assetManager, sound),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),
         new TimerSystem(),

package/src/engine/graphics/sh3/path_tracer/texture/sample_material.js

@@ -6,7 +6,7 @@ import { decode_attribute_value } from "../../../geometry/decode_attribute_value
 import { geometry_construct_triangle_normal } from "../../../geometry/geometry_construct_triangle_normal.js";
 import { sample_triangle_attribute } from "../geometry/sample_triangle_attribute.js";
 
-import { v3_orthonormal_matrix_from_normal } from "../sampling/v3_orthonormal_matrix_from_normal.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
 
 const texture_uv = [0, 0];
 const color = new Float64Array(3);

package/src/engine/graphics/shadows/testShadowMapRendering.js

@@ -69,7 +69,7 @@ function makeConfig(engine) {
 
     config.addManySystems(
         new AttachmentSystem(),
-        new SoundEmitterSystem(assetManager, sound.destination, sound.context),
+        new SoundEmitterSystem(assetManager, sound),
         new SoundControllerSystem(),
         new SoundListenerSystem(sound.context),
         guiSystem,

package/src/engine/physics/CONSTRAINT_SOLVER_BENCH_LOG.md

@@ -0,0 +1,208 @@
+# Constraint-Solver Improvements — Benchmark Log
+
+Evidence log for `CONSTRAINT_SOLVER_IMPROVEMENTS_PLAN.md`. One section per phase:
+machine/Node, baseline vs after, delta, pass/fail, and any signed rationale for a
+regression that exceeds budget.
+
+**Environment:** Node v24.15.0 · Windows · single-thread JS · benches run via
+`npx jest --config jest.conf.json -t "<name>"` (flip `test.skip`→`test`).
+All numbers are a single in-process run unless noted (per the protocol, gate on
+same-process flag A/B; absolute ms vary by machine/thermal). Tick times in ms.
+
+---
+
+## Phase 0 — Baseline (current `master` + inert flags)
+
+Flags present but all at defaults (`contactBiasSmoothBand=0`, `jointBlockSolve=false`,
+`jointSweepSymmetric=false`, `jointRelaxation=1`, `jointComplianceLin=0`) → behaviour
+identical to pre-change master. Ragdoll spec: 3/3 pass, golden bands hold, determinism
+intact.
+
+### ragdoll MICRO (1 ragdoll, 10 joints, floor+sphere, 600 ticks)
+
+| metric | mean | median | p95 | p99 | max |
+|--------|------|--------|-----|-----|-----|
+| tick (all) | 0.4505 | 0.3802 | 0.7315 | 1.3891 | 4.2801 |
+| tick (last 1s) | 0.4325 | 0.3664 | 0.8504 | 1.0324 | 1.0324 |
+
+final awake **11 / 11** (never sleeps) · final max |v|+|ω| **0.1352**
+
+### ragdoll FIELD (N=64, 704 bodies, 640 joints, 600 ticks)
+
+| metric | mean | median | p95 | p99 | max |
+|--------|------|--------|-----|-----|-----|
+| tick (all) | 33.55 | 32.68 | 46.22 | 56.10 | 62.74 |
+| tick (first 1s, settle) | 27.31 | 24.99 | 37.62 | 62.57 | 62.57 |
+| tick (last 1s, settled) | 34.67 | 33.83 | 47.28 | 52.07 | 52.07 |
+
+avg awake 704.0 / 704 · final awake **704 / 704 (asleep 0)** · residual max |v|+|ω| **0.4997**
+asleep histogram: **0.0 every second** — the pile never sleeps; steady-state cost
+(34.7ms) is *higher* than settle (27ms). **This is the gap.** Target: A2/A3 drive
+asleep ↑ and settled-window tick ↓.
+
+### settling grid (1024 shapes, A4 / sleep canary)
+
+| metric | mean | median | p95 | p99 | max |
+|--------|------|--------|-----|-----|-----|
+| tick (all) | 4.155 | 1.732 | 29.74 | 33.31 | 79.96 |
+| tick (first 1s) | 22.88 | 29.74 | 35.28 | 79.96 | 79.96 |
+| tick (last 1s, settled) | 1.464 | 1.425 | 1.794 | 2.088 | 2.088 |
+
+final awake **77 / 1024** (stacks sleep) · fall-through **0** — A4 must preserve both.
+
+### Deferred (run at phase boundaries / final sweep)
+- KEVA tower (~15 min/run) — large-island contact; run pre/post per phase, not per-commit.
+- falling tower, MeshStack, Rain, raycast — control benches; full sweep in Phase 4.
+
+---
+## Phase 1 — A4: smooth contact position bias
+
+`position_correction_bias(depth, spook_a, band)` helper; both bias sites share it;
+`contactBiasSmoothBand` (default **0**). At band=0 the math is bit-identical to the
+old hard hinge → **140/141 physics tests pass unchanged** (ragdoll spec + PhysicsSystem
+spec), determinism intact. **PASS (refactor).**
+
+A/B on the settling-grid canary (band=0.005 vs baseline, same machine):
+
+| metric | baseline | A4 on (0.005) | Δ |
+|--------|----------|---------------|---|
+| settled tick (last 1s, mean) | 1.464 | 1.535 | +4.8%* |
+| settled tick (median) | 1.425 | 1.463 | +2.7% (within 3% noise) |
+| final awake | 77/1024 | 77/1024 | — (sleep preserved) |
+| fall-through | 0 | 0 | — |
+
+\* sub-ms absolute; within run-to-run noise for this scene (grid settles below slop
+fast, so A4's band barely engages here). **PASS** — quality gates green (fall-through 0,
+sleep intact), perf within the ≤+2% budget on the median.
+
+**Decision:** A4 implemented + validated-safe; **default stays off** (`band=0`). Whether
+to default-on (and whether it helps the ragdoll residual) is judged combined with A2/A3
+in Phase 4. Knob available for tuning.
+
+### Windowed-metric baselines (A4 off — used for A2/A3 A/B)
+Bench residual metric switched from single-tick (noisy) to worst over last 1s.
+
+| scene | tick mean | tick median | tick p99 | last-1s mean | residual | asleep |
+|-------|-----------|-------------|----------|--------------|----------|--------|
+| MICRO | 0.4250 | 0.3769 | 1.1478 | — | — | 0/11 |
+| FIELD (N=64) | 31.92 | 31.68 | 46.13 | 32.27 | **0.7515** | **0/704** |
+
+(Run-to-run variance vs Phase-0 ≈ 5% — gate on same-process A/B, not cross-run absolutes.)
+
+---
+## Phase 2 — A2: block 3×3 point-solve + symmetric sweep
+
+`jointBlockSolve` + `jointSweepSymmetric` (both default **false**). Inert at default
+→ 167 joint/system tests pass unchanged. Same-process A/B on the ragdoll benches:
+
+| scene | baseline | A2 on | Δ |
+|-------|----------|-------|---|
+| MICRO tick mean | 0.4250 | 0.3669 | **−13.7%** |
+| FIELD tick mean | 31.92 | 26.81 | **−16.0%** |
+| FIELD residual (max) | 0.7515 | 0.7445 | ~0 |
+
+**A2 is a perf win, not a cost** (the block does 1 solve + ≤2 impulse applies vs 3
+axes × 2 applies, and is better-conditioned). Well under the +10% budget — it's
+negative. Residual ~unchanged (expected: A2 sharpens convergence; killing the limit
+cycle is A3's job). **PASS.**
+
+**Finding (drives A3):** A2 *enabled* against the full instrumented spec fails
+`settledSpeedMean` (2.26 > 1.8). The under-converged per-axis solve was supplying
+*incidental numerical damping*; the exact block solve removes it, leaving the
+metastable on-sphere ragdoll livelier. A2 ⇒ must pair with A3 dissipation.
+
+## Phase 3 — A3: under-relaxation (ω) [+ compliance deferred]
+
+`jointRelaxation` (default **1** = off). Applied to all three solve paths.
+A2+A3 on the canonical seed (full instrumented spec):
+
+| metric | baseline | A2+A3 (ω=0.90) | Δ |
+|--------|----------|----------------|---|
+| settled lin accel (per-pt) | 55.07 | **3.79** m/s² | −93% |
+| settled ang accel (per-pt) | 36.9 | **4.21** rad/s² | −89% |
+| settled lin speed (per-pt) | 0.73 | **0.067** m/s | −91% |
+| settled ang speed (per-pt) | 0.75 | **0.189** rad/s | −75% |
+| MICRO tick mean | 0.425 | 0.365 | −14% |
+| transient pen (static) | 0.26 | 0.38 | **+46%** (cost) |
+
+The settled residual collapses ~10–14× — the gap the whole effort targeted. With
+defaults flipped on, **all 175 non-ragdoll joint/vehicle/IK/island tests still pass**;
+only the ragdoll golden *lower* bounds trip (we improved past them).
+
+### ⚠ Complication — ω is chaotic on the metastable scene (why we did NOT burn it in)
+
+Sweeping ω on the spec (single ragdoll draped on a convex sphere):
+
+| ω | settled lin speed | verdict |
+|---|-------------------|---------|
+| 1.00 | 0.981 | livelier |
+| 0.97 | **5.81** | slid off / unsettled |
+| 0.95 | 0.437 | good |
+| 0.92 | **4.50** | slid off / unsettled |
+| 0.90 | 0.067 | great |
+| 0.75 | 3.62 | unstable |
+
+Non-monotone and **bimodal**: the ragdoll either settles on the dome or slides off,
+and tiny ω changes flip the basin. So a good ω on one seed (0.90) is **not** a robust
+global default — a neighbouring scene could land in a bad basin. Also ω<~0.8 starves
+constraint convergence → energy injection. Plus the +46% transient-penetration cost.
+
+**Decision:** Do **not** burn in ω as a default off single-seed data — that is exactly
+the brittle-default risk this plan exists to avoid. A2/A3/A4 ship as **validated opt-in
+knobs, default off (zero regression)**. Full physics suite with defaults off: **865
+pass, 0 fail.**
+
+## Phase 4 — burn-in (no flags)
+
+Directive: **no flags/toggles on the engine** — converge to one baked behaviour.
+That required deciding each change on *robust* evidence, not the canonical seed.
+
+### Monte-Carlo settled-accel **median over 150 seeds** (the decider)
+
+| config | worst-point setA median | worst-point setV median |
+|--------|-------------------------|-------------------------|
+| baseline (no A2/A3) | ~68 | ~1.23 |
+| A2 only (ω=1) | ~71 | ~1.53 |
+| A2 + ω=0.90 | **~102** | ~2.04 |
+
+The single-seed ω=0.90 win (3.8 m/s²) was **basin luck** — across the seed space ω
+*raises* the median residual, and A2 raises settled velocity ~20%. **The settled
+jitter is basin/sleep-dominated, not solver-convergence-dominated** (per-seed variance
+≫ any config difference). No convergence/relaxation lever moves the median. So:
+
+### Burn-in decision
+
+| change | verdict | action |
+|--------|---------|--------|
+| **A2** (block 3×3 point-solve + symmetric sweep) | robust **−9–16%** joint-solve time, exact ball-socket, mass-ratio-robust; residual-neutral in median | **BAKED as the single code path** (no flag) |
+| **A3** (ω under-relaxation) | median-*worse*, chaotic/bimodal, +46% transient pen | **REMOVED** (disproven bandaid) |
+| **A4** (contact bias smoothing) | neutral, benefit unproven; baking would churn contact determinism for no measured gain | **REVERTED** to original hard hinge |
+
+All flags/config fields removed (`jointBlockSolve`, `jointSweepSymmetric`,
+`jointRelaxation`, `contactBiasSmoothBand`). Solver has one path. Final:
+
+| scene | pre (baseline) | post (A2 baked) | Δ |
+|-------|----------------|-----------------|---|
+| MICRO tick mean | 0.425 | 0.388 | −9% |
+| FIELD tick mean | 31.92 | 28.65 | −10% |
+| FIELD residual / asleep | 0.75 / 0 | 0.74 / 0 | neutral |
+
+Re-baselined one golden band: `settledSpeedMean` 1.8→2.9 hi (A2's honest liveliness;
+documented in the spec). Full physics suite: **865 pass / 0 fail.**
+
+### The jitter goal is NOT closed — and the data says why
+
+A2 is a perf+correctness win but does **not** reduce the settled jitter (it slightly
+raises it — removing the per-axis solve's incidental damping). The Monte-Carlo proves
+the residual is basin/sleep-dominated. **The real lever is island sleep, not the
+solver:** an *aggregate-energy + hysteresis* sleep criterion (plan item **B**) lets an
+over-constrained island deactivate once its *total* energy is low, instead of requiring
+every body under the per-body gate continuously (which the limit cycle never satisfies).
+Recommended next step. Beyond that, **A1** (reduced-coordinate articulation) removes the
+maximal-coordinate joint residual at the source.
+
+**Net of this effort:** a faster, more correct joint solver (shipped, no flags) + a
+rigorous, evidenced redirection of the jitter goal to the lever that can actually move
+it (sleep), instead of a brittle solver knob that looked good on one seed.
+
+