@woosh/meep-engine 2.169.6 → 2.170.0

package/src/engine/control/first-person/abilities/LedgeGrab.js

@@ -1,405 +1,404 @@
-import { assert } from "../../../../core/assert.js";
-import { clamp } from "../../../../core/math/clamp.js";
-import { DEG_TO_RAD } from "../../../../core/math/DEG_TO_RAD.js";
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
-import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
-import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
-import { Ability } from "./Ability.js";
-
-/**
- * Ledge-grab ability — catch a forward ledge while descending, then HANG
- * from it and traverse it: shimmy along the edge, pull up / vault over it,
- * or dismount.
- *
- * Activation (AUTO-CATCH):
- *   - `sensors.ledgeAhead.hit` — a forward+up obstacle probe found a
- *     grabbable edge (the same probe mantle uses). This already implies the
- *     body is facing a wall with a top, so even neutral input catches it.
- *   - `runtime.velocityY <= 0` — descending or static. We don't auto-catch
- *     on the way UP (that would feel like the world grabbed you mid-jump).
- *   - `state.airborneTime >= minAirborneTime` — a small post-takeoff window
- *     where ledge-grab can't fire even if instantly at apex.
- *   - NOT moving away — the move intent, taken to world space and projected
- *     onto the wall's outward normal, must not exceed `moveAwayThreshold`.
- *     You won't catch a ledge you're deliberately leaving (this also blocks
- *     a same-tick re-grab right after an away-dismount).
- *
- * The hanging input model (evaluated every tick): the move intent is taken
- * to WORLD space and decomposed against the wall frame captured at grab —
- * the outward normal `n` and the horizontal edge tangent `t = (-nz, nx)`.
- * This makes toward / away / lateral facing-INDEPENDENT, which is exactly
- * what makes "turn the camera to look away ≠ dismount" fall out for free.
- *
- *   - `away    = worldMove · n`   (>0 = off the wall, <0 = into it)
- *   - `lateral = worldMove · t`   (signed, along the edge)
- *   - `facing  = forward · (-n)`  (how squarely the camera faces the wall)
- *
- * Per-tick decision (mutually exclusive — opposite axes can't both be high):
- *   1. PULL-UP / VAULT — moving toward the wall, OR jump pressed while
- *      facing within `pullUpFacingConeDeg` of it. Hands off to Mantle
- *      (`runtime.ledgePullUpRequest`): onto a standable top, or a vault
- *      over a too-thin one.
- *   2. DISMOUNT (drop) — crouch, or an away-DOMINANT world-move past
- *      `moveAwayThreshold` (conservative: a strafe that merely bleeds into
- *      `away` shimmies instead — leaving the hang is more consequential).
- *   3. SHIMMY — lateral intent dominant: step along the edge if it stays
- *      clear and continuous; otherwise clamp (hold) — a shimmy NEVER drops.
- *   4. HOLD — snap to the hang pose, accrue fatigue.
- *   5. SLIP — exertion saturates (forced release).
- *   A jump pressed while facing AWAY is consumed (no back-hop in v1) and
- *   you keep hanging.
- *
- * Priority 40 — above mantle (30), below wall-run (50). Mantle CAN'T
- * preempt an active ledge-grab — that's the point of placing ledge higher.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class LedgeGrab extends Ability {
-    constructor() {
-        super();
-        this.name = "LedgeGrab";
-        this.priority = 40;
-
-        /** @private Wall-face anchor (x,z), the face's outward normal (x,z),
-         *  and the top-edge height (y) — captured at onActivate and advanced
-         *  while shimmying. The hang pose is built from the WALL, not the
-         *  (possibly oblique) body facing, so it stays just outside the wall
-         *  at any approach angle. */
-        this._anchorX = 0;
-        this._anchorZ = 0;
-        this._nx = 0;
-        this._nz = 0;
-        this._edgeY = 0;
-
-        /** @private Scratch query primitives for the shimmy probes — refilled
-         *  in place so a hanging player doesn't allocate each tick. */
-        this._ray = new Ray3();
-        this._hit = new PhysicsSurfacePoint();
-    }
-
-    canActivate(controller, runtime, sensors) {
-        const cfg = controller.config.ledgeGrab;
-        if (!cfg) return false;
-        if (sensors === undefined || sensors === null) return false;
-
-        // Refractory window after a release — don't immediately re-grab the
-        // lip we just dismounted from (the auto-catch is otherwise eager
-        // enough to snap us straight back onto it while we're still falling
-        // clear of it).
-        if (runtime.ledgeRegrabCooldown > 0) return false;
-
-        if (!sensors.ledgeAhead.hit) return false;
-        if (runtime.velocityY > 0) return false; // not on the way up
-        if (controller.state.grounded) return false;
-        if (controller.state.airborneTime < cfg.minAirborneTime) return false;
-        // Crouch or exhausted: don't re-grab. These are the same exit
-        // conditions that would IMMEDIATELY release after activation, so
-        // gating them here prevents a same-tick re-activation flicker.
-        if (controller.intent.crouch) return false;
-        if (controller.state.exertion >= 1.0) return false;
-
-        // Auto-catch, but not a ledge we're deliberately LEAVING: decompose
-        // the world move against the obstacle face normal (ledgeAhead.hit
-        // implies obstacleAhead.hit, so the face data is present). Moving away
-        // past the threshold refuses the grab — which also prevents a same-tick
-        // re-grab right after an away-dismount.
-        const face = sensors.obstacleAhead;
-        if (face.hit) {
-            const away = this._worldMoveDot(controller, runtime, face.normal.x, face.normal.z);
-            if (away > cfg.moveAwayThreshold) return false;
-        }
-
-        return true;
-    }
-
-    onActivate(controller, runtime) {
-        const sensors = runtime.sensors;
-
-        // Clear any stale pull-up request — a fresh grab starts neutral.
-        runtime.ledgePullUpRequest = false;
-
-        // Anchor on the wall face + its outward normal (ledgeAhead is only
-        // probed when obstacleAhead hits, so the face data is always present
-        // here). The top-edge height comes from the ledge probe.
-        this._anchorX = sensors.obstacleAhead.point.x;
-        this._anchorZ = sensors.obstacleAhead.point.z;
-        this._nx = sensors.obstacleAhead.normal.x;
-        this._nz = sensors.obstacleAhead.normal.z;
-        this._edgeY = sensors.ledgeAhead.point.y;
-
-        // -- Preconditions (dev-only; compiled out of prod). The hang frame is
-        //    built entirely from these — a bad capture here is the kind of
-        //    thing that silently produces a degenerate pose now and an
-        //    inexplicable camera jump later.
-        assert.ok(sensors.obstacleAhead.hit,
-            "LedgeGrab: activated without an obstacleAhead hit (no wall to anchor the hang)");
-        assert.ok(sensors.ledgeAhead.hit,
-            "LedgeGrab: activated without a ledgeAhead hit (no edge to grab)");
-        // The wall normal must be roughly horizontal + unit — the whole
-        // wall-frame model (toward/away/lateral, shimmy tangent, hang standoff)
-        // assumes it. A near-zero horizontal normal (e.g. a floor/slope hit)
-        // would collapse the frame.
-        assert.greaterThan(Math.hypot(this._nx, this._nz), 0.5,
-            "LedgeGrab: wall normal is not horizontal — degenerate hang/shimmy frame");
-        assert.ok(
-            Number.isFinite(this._anchorX) && Number.isFinite(this._anchorZ) && Number.isFinite(this._edgeY),
-            "LedgeGrab: captured a non-finite hang anchor/edge",
-        );
-
-        // Zero velocity — the body is now parked on the ledge.
-        runtime.velocityX = 0;
-        runtime.velocityY = 0;
-        runtime.velocityZ = 0;
-
-        // Clear any in-progress jump state — hanging supersedes them.
-        runtime.midJump = false;
-        runtime.apexFired = false;
-        controller.state.isVariableJumpCut = false;
-        controller.state.isAscending = false;
-
-        // The body is hanging — not on the ground.
-        controller.state.grounded = false;
-
-        // Body is suspended by the hands; L2 reads posture to gate gait and
-        // set eye height.
-        controller.state.posture = FirstPersonPosture.Hang;
-
-        controller.signals.onLedgeGrab.send1({
-            ledgeHeight: this._edgeY - controller.pose.rootPosition.y,
-        });
-    }
-
-    canInterrupt() {
-        // Wall-run / wall-jump can preempt if their conditions somehow hold
-        // (unusual mid-hang). Higher-priority abilities shouldn't be blocked.
-        return true;
-    }
-
-    onDeactivate(controller, runtime) {
-        // Open the re-grab refractory window on EVERY release (drop, slip,
-        // pull-up, shuffle-off). Covers the case where the dismount input
-        // returns to neutral while the body is still inside the grab window —
-        // without this the auto-catch re-fires next tick and snaps us back
-        // onto the lip.
-        runtime.ledgeRegrabCooldown = controller.config.ledgeGrab.regrabCooldown;
-    }
-
-    tick(controller, runtime, bodyTransform, dt, _system) {
-        const cfg = controller.config.ledgeGrab;
-        const intent = controller.intent;
-
-        // Re-assert posture each tick (defence against any layer resetting it
-        // before L2 reads). Body parked against the wall — no lean.
-        controller.state.posture = FirstPersonPosture.Hang;
-        runtime.leanTargetRad = 0;
-
-        // -- Exit: lost the ledge. Probe the CAPTURED anchor (not the
-        //    facing-relative sensor) so turning to look away from the wall
-        //    never reads as "ledge lost" — that's the whole point of the
-        //    wall-frame model. Releases only when the lip genuinely isn't
-        //    under us any more (e.g. the wall was removed).
-        if (!this._ledgeStillThere(runtime, cfg, _system)) {
-            controller.signals.onLedgeRelease.send1({ reason: "shuffle-off" });
-            return false;
-        }
-
-        // -- Decompose the move intent against the captured wall frame. These
-        //    are facing-INDEPENDENT (built from n/t, not the camera) — looking
-        //    away changes `facing` but not away/lateral, so it can't dismount.
-        const away = this._worldMoveDot(controller, runtime, this._nx, this._nz);
-        const lateral = this._worldMoveDot(controller, runtime, -this._nz, this._nx);
-        const { sinYaw, cosYaw } = runtime;
-        const facing = sinYaw * (-this._nx) + cosYaw * (-this._nz);
-        const jumpEdge = intent.jump && !runtime.prevJumpHeld;
-        const coneCos = Math.cos(cfg.pullUpFacingConeDeg * DEG_TO_RAD);
-
-        // -- (1) Pull-up / vault: moving toward the wall, OR a jump press while
-        //    facing into it. Request the climb; Mantle (next tick) resolves it
-        //    onto a standable top, or vaults over a too-thin one. The small
-        //    upward kick keeps mantle's ledgeAhead probe resolving correctly.
-        if (away < -cfg.moveTowardThreshold || (jumpEdge && facing > coneCos)) {
-            runtime.ledgePullUpRequest = true;
-            runtime.velocityY = runtime.jumpInitialVy * cfg.mantleUpUpFactor;
-            if (jumpEdge) runtime.prevJumpHeld = true;
-            runtime.midJump = true;
-            controller.state.isAscending = true;
-            controller.signals.onLedgeRelease.send1({ reason: "mantle-up" });
-            return false;
-        }
-        // Consume a jump press that DIDN'T pull up (facing away) so it doesn't
-        // fire later; stay hanging — looking away never auto-acts.
-        if (jumpEdge) runtime.prevJumpHeld = true;
-
-        // -- (2) Dismount. Crouch is an explicit, unconditional dismount.
-        //    Movement-away is CONSERVATIVE: leaving the hang (you fall) is more
-        //    consequential than shimmying, so a strafe taken while looking
-        //    somewhat off the wall — which bleeds a little into `away` — reads
-        //    as a SHIMMY (handled below), not an ejection. Only a stick that
-        //    clearly points OFF the edge (away-DOMINANT, past the threshold)
-        //    drops you.
-        if (intent.crouch) {
-            controller.signals.onLedgeRelease.send1({ reason: "drop" });
-            return false;
-        }
-        if (away > cfg.moveAwayThreshold && away > Math.abs(lateral)) {
-            controller.signals.onLedgeRelease.send1({ reason: "drop" });
-            return false;
-        }
-
-        // -- (5) Slip: exertion saturated → forced release.
-        if (controller.state.exertion >= 1.0) {
-            controller.signals.onLedgeRelease.send1({ reason: "slip" });
-            return false;
-        }
-
-        // -- (3) Shimmy: lateral intent dominant → try one step along the edge.
-        //    A blocked or discontinuous edge clamps (we stay hanging here),
-        //    never drops.
-        let shimmying = false;
-        if (Math.abs(lateral) > cfg.shimmyLateralMin && Math.abs(lateral) >= Math.abs(away)) {
-            shimmying = this._tryShimmy(controller, runtime, cfg, Math.sign(lateral), dt, _system);
-        }
-
-        // -- (4) Hold (or post-shimmy advance): snap to the hang pose just
-        //    OUTSIDE the wall face, gripping the top edge. The body centre sits
-        //    a capsule radius (+ a small gap) out from the face along its
-        //    outward normal — anchoring on the WALL keeps the body clear even
-        //    when the ledge was reached obliquely (a facing-relative offset
-        //    would sink it into a thin wall).
-        const standoff = controller.config.body.radius + cfg.hangOffsetForward;
-        bodyTransform.position.set(
-            this._anchorX + this._nx * standoff,
-            this._edgeY + cfg.hangOffsetY,
-            this._anchorZ + this._nz * standoff,
-        );
-        runtime.velocityX = 0;
-        runtime.velocityY = 0;
-        runtime.velocityZ = 0;
-        controller.state.grounded = false;
-
-        // Teleport-snap the camera on a parked (non-shimmying) hang: the body
-        // was just snapped onto the wall from wherever it was falling, so the
-        // render interpolation must JUMP to the hang pose, not glide into it.
-        // During a shimmy the body moves smoothly, so we let it interpolate.
-        if (!shimmying) runtime.renderSnap = true;
-
-        // Exertion rises while hanging — fatigue. Faster while actively
-        // shimmying. Mass-scaled like the rest of the exertion system.
-        const exertRate = cfg.exertionRiseRate * (shimmying ? cfg.shimmyExertionFactor : 1);
-        controller.state.exertion = clamp(
-            controller.state.exertion + exertRate * dt
-                * runtime.massRatios.exertionRiseScale,
-            0, 1,
-        );
-
-        return true;
-    }
-
-    /**
-     * World-space move intent (clamped to the unit disk) dotted with a
-     * horizontal axis (ax, az). Uses the controller's own move→world
-     * convention (screen_fwd = (sinYaw, cosYaw)). Facing-independent by
-     * construction — it's the intent in WORLD space, not camera space.
-     * @private
-     */
-    _worldMoveDot(controller, runtime, ax, az) {
-        const { sinYaw, cosYaw } = runtime;
-        let mx = controller.intent.move.x;
-        let my = controller.intent.move.y;
-        const len = Math.hypot(mx, my);
-        if (len > 1) { mx /= len; my /= len; }
-        const wmx = sinYaw * my - cosYaw * mx;
-        const wmz = cosYaw * my + sinYaw * mx;
-        return wmx * ax + wmz * az;
-    }
-
-    /**
-     * Is the grabbed lip still under us? Probes the CAPTURED anchor (a down-ray
-     * just past the face, into the wall along −n), independent of where the
-     * camera looks — so turning to look away never reads as "ledge lost". Falls
-     * back to the facing-relative sensor only when no physics backend is present
-     * (the flat-ground unit harness, which simulates loss via that sensor).
-     * @private
-     */
-    _ledgeStillThere(runtime, cfg, system) {
-        const physics = system && system.physicsSystem;
-        if (!physics) return runtime.sensors.ledgeAhead.hit;
-
-        const ray = this._ray;
-        const hit = this._hit;
-        ray.setOrigin(
-            this._anchorX - this._nx * cfg.shimmyEdgeProbeForward,
-            this._edgeY + cfg.shimmyContinuityProbeUp,
-            this._anchorZ - this._nz * cfg.shimmyEdgeProbeForward,
-        );
-        ray.setDirection(0, -1, 0);
-        ray.tMax = cfg.shimmyContinuityProbeUp + cfg.shimmyContinuityProbeDown;
-        const filter = (_e, c) => c !== runtime.collider;
-        if (!physics.raycast(ray, hit, filter)) return false;
-        return Math.abs(hit.position.y - this._edgeY) <= cfg.shimmyContinuityTol;
-    }
-
-    /**
-     * Attempt one shimmy step of `dir` (±1) along the edge tangent. Returns
-     * true if it stepped (clear AND continuous), false if it CLAMPED — a clamp
-     * holds in place, it never drops. On success it advances the anchor and
-     * re-captures the edge height so an undulating top is tracked.
-     *
-     * Two probes, both must pass:
-     *   (A) lateral CLEARANCE — a ray along the tangent from the body centre
-     *       must be free for the step (a perpendicular/concave wall blocks it).
-     *   (B) edge CONTINUITY — a down-ray just past the shifted edge must find
-     *       the lip still at ~edge height (else the edge ended).
-     * Needs the physics backend; without it (flat-ground unit harness) it
-     * can't verify geometry, so it clamps.
-     * @private
-     */
-    _tryShimmy(controller, runtime, cfg, dir, dt, system) {
-        const physics = system && system.physicsSystem;
-        if (!physics) return false; // no spatial backend → can't verify → clamp
-
-        const r = controller.config.body.radius;
-        const standoff = r + cfg.hangOffsetForward;
-        // Edge tangent (n is unit, so t is unit). dir picks the direction.
-        const tx = dir * (-this._nz);
-        const tz = dir * this._nx;
-        const step = cfg.shimmySpeed * dt;
-        const filter = (_e, c) => c !== runtime.collider; // exclude own body
-        const ray = this._ray;
-        const hit = this._hit;
-
-        // Body centre at the current hang pose.
-        const bx = this._anchorX + this._nx * standoff;
-        const bz = this._anchorZ + this._nz * standoff;
-
-        // (A) Lateral clearance along the tangent.
-        ray.setOrigin(bx, this._edgeY + cfg.shimmyClearanceProbeY, bz);
-        ray.setDirection(tx, 0, tz);
-        ray.tMax = step + r + cfg.shimmyClearanceGap;
-        if (physics.raycast(ray, hit, filter)) return false; // blocked → clamp
-
-        // (B) Edge continuity: down-probe just past the SHIFTED edge. The top
-        //     surface sits INTO the wall from the face (along -n), so offset the
-        //     probe that way before dropping it.
-        const nex = this._anchorX + tx * step;
-        const nez = this._anchorZ + tz * step;
-        ray.setOrigin(
-            nex - this._nx * cfg.shimmyEdgeProbeForward,
-            this._edgeY + cfg.shimmyContinuityProbeUp,
-            nez - this._nz * cfg.shimmyEdgeProbeForward,
-        );
-        ray.setDirection(0, -1, 0);
-        ray.tMax = cfg.shimmyContinuityProbeUp + cfg.shimmyContinuityProbeDown;
-        if (!physics.raycast(ray, hit, filter)) return false; // edge ended → clamp
-        if (Math.abs(hit.position.y - this._edgeY) > cfg.shimmyContinuityTol) return false;
-
-        // Commit: advance along the face and track the (possibly undulating)
-        // lip. The wall normal is kept constant — a straight face is the common
-        // case; wrapping a curving/convex wall is a v2 refinement.
-        this._anchorX = nex;
-        this._anchorZ = nez;
-        this._edgeY = hit.position.y;
-        return true;
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { DEG_TO_RAD } from "../../../../core/math/DEG_TO_RAD.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { PhysicsSurfacePoint } from "../../../physics/queries/PhysicsSurfacePoint.js";
+import { FirstPersonPosture } from "../pose/FirstPersonPosture.js";
+import { Ability } from "./Ability.js";
+
+/**
+ * Ledge-grab ability — catch a forward ledge while descending, then HANG
+ * from it and traverse it: shimmy along the edge, pull up / vault over it,
+ * or dismount.
+ *
+ * Activation (AUTO-CATCH):
+ *   - `sensors.ledgeAhead.hit` — a forward+up obstacle probe found a
+ *     grabbable edge (the same probe mantle uses). This already implies the
+ *     body is facing a wall with a top, so even neutral input catches it.
+ *   - `runtime.velocityY <= 0` — descending or static. We don't auto-catch
+ *     on the way UP (that would feel like the world grabbed you mid-jump).
+ *   - `state.airborneTime >= minAirborneTime` — a small post-takeoff window
+ *     where ledge-grab can't fire even if instantly at apex.
+ *   - NOT moving away — the move intent, taken to world space and projected
+ *     onto the wall's outward normal, must not exceed `moveAwayThreshold`.
+ *     You won't catch a ledge you're deliberately leaving (this also blocks
+ *     a same-tick re-grab right after an away-dismount).
+ *
+ * The hanging input model (evaluated every tick): the move intent is taken
+ * to WORLD space and decomposed against the wall frame captured at grab —
+ * the outward normal `n` and the horizontal edge tangent `t = (-nz, nx)`.
+ * This makes toward / away / lateral facing-INDEPENDENT, which is exactly
+ * what makes "turn the camera to look away ≠ dismount" fall out for free.
+ *
+ *   - `away    = worldMove · n`   (>0 = off the wall, <0 = into it)
+ *   - `lateral = worldMove · t`   (signed, along the edge)
+ *   - `facing  = forward · (-n)`  (how squarely the camera faces the wall)
+ *
+ * Per-tick decision (mutually exclusive — opposite axes can't both be high):
+ *   1. PULL-UP / VAULT — moving toward the wall, OR jump pressed while
+ *      facing within `pullUpFacingConeDeg` of it. Hands off to Mantle
+ *      (`runtime.ledgePullUpRequest`): onto a standable top, or a vault
+ *      over a too-thin one.
+ *   2. DISMOUNT (drop) — crouch, or an away-DOMINANT world-move past
+ *      `moveAwayThreshold` (conservative: a strafe that merely bleeds into
+ *      `away` shimmies instead — leaving the hang is more consequential).
+ *   3. SHIMMY — lateral intent dominant: step along the edge if it stays
+ *      clear and continuous; otherwise clamp (hold) — a shimmy NEVER drops.
+ *   4. HOLD — snap to the hang pose, accrue fatigue.
+ *   5. SLIP — exertion saturates (forced release).
+ *   A jump pressed while facing AWAY is consumed (no back-hop in v1) and
+ *   you keep hanging.
+ *
+ * Priority 40 — above mantle (30), below wall-run (50). Mantle CAN'T
+ * preempt an active ledge-grab — that's the point of placing ledge higher.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class LedgeGrab extends Ability {
+    name = "LedgeGrab";
+    priority = 40;
+
+    /** @private Wall-face anchor (x,z), the face's outward normal (x,z),
+     *  and the top-edge height (y) — captured at onActivate and advanced
+     *  while shimmying. The hang pose is built from the WALL, not the
+     *  (possibly oblique) body facing, so it stays just outside the wall
+     *  at any approach angle. */
+    _anchorX = 0;
+
+    _anchorZ = 0;
+    _nx = 0;
+    _nz = 0;
+    _edgeY = 0;
+
+    /** @private Scratch query primitives for the shimmy probes — refilled
+     *  in place so a hanging player doesn't allocate each tick. */
+    _ray = new Ray3();
+
+    _hit = new PhysicsSurfacePoint();
+
+    canActivate(controller, runtime, sensors) {
+        const cfg = controller.config.ledgeGrab;
+        if (!cfg) return false;
+        if (sensors === undefined || sensors === null) return false;
+
+        // Refractory window after a release — don't immediately re-grab the
+        // lip we just dismounted from (the auto-catch is otherwise eager
+        // enough to snap us straight back onto it while we're still falling
+        // clear of it).
+        if (runtime.ledgeRegrabCooldown > 0) return false;
+
+        if (!sensors.ledgeAhead.hit) return false;
+        if (runtime.velocityY > 0) return false; // not on the way up
+        if (controller.state.grounded) return false;
+        if (controller.state.airborneTime < cfg.minAirborneTime) return false;
+        // Crouch or exhausted: don't re-grab. These are the same exit
+        // conditions that would IMMEDIATELY release after activation, so
+        // gating them here prevents a same-tick re-activation flicker.
+        if (controller.intent.crouch) return false;
+        if (controller.state.exertion >= 1.0) return false;
+
+        // Auto-catch, but not a ledge we're deliberately LEAVING: decompose
+        // the world move against the obstacle face normal (ledgeAhead.hit
+        // implies obstacleAhead.hit, so the face data is present). Moving away
+        // past the threshold refuses the grab — which also prevents a same-tick
+        // re-grab right after an away-dismount.
+        const face = sensors.obstacleAhead;
+        if (face.hit) {
+            const away = this._worldMoveDot(controller, runtime, face.normal.x, face.normal.z);
+            if (away > cfg.moveAwayThreshold) return false;
+        }
+
+        return true;
+    }
+
+    onActivate(controller, runtime) {
+        const sensors = runtime.sensors;
+
+        // Clear any stale pull-up request — a fresh grab starts neutral.
+        runtime.ledgePullUpRequest = false;
+
+        // Anchor on the wall face + its outward normal (ledgeAhead is only
+        // probed when obstacleAhead hits, so the face data is always present
+        // here). The top-edge height comes from the ledge probe.
+        this._anchorX = sensors.obstacleAhead.point.x;
+        this._anchorZ = sensors.obstacleAhead.point.z;
+        this._nx = sensors.obstacleAhead.normal.x;
+        this._nz = sensors.obstacleAhead.normal.z;
+        this._edgeY = sensors.ledgeAhead.point.y;
+
+        // -- Preconditions (dev-only; compiled out of prod). The hang frame is
+        //    built entirely from these — a bad capture here is the kind of
+        //    thing that silently produces a degenerate pose now and an
+        //    inexplicable camera jump later.
+        assert.ok(sensors.obstacleAhead.hit,
+            "LedgeGrab: activated without an obstacleAhead hit (no wall to anchor the hang)");
+        assert.ok(sensors.ledgeAhead.hit,
+            "LedgeGrab: activated without a ledgeAhead hit (no edge to grab)");
+        // The wall normal must be roughly horizontal + unit — the whole
+        // wall-frame model (toward/away/lateral, shimmy tangent, hang standoff)
+        // assumes it. A near-zero horizontal normal (e.g. a floor/slope hit)
+        // would collapse the frame.
+        assert.greaterThan(Math.hypot(this._nx, this._nz), 0.5,
+            "LedgeGrab: wall normal is not horizontal — degenerate hang/shimmy frame");
+        assert.ok(
+            Number.isFinite(this._anchorX) && Number.isFinite(this._anchorZ) && Number.isFinite(this._edgeY),
+            "LedgeGrab: captured a non-finite hang anchor/edge",
+        );
+
+        // Zero velocity — the body is now parked on the ledge.
+        runtime.velocityX = 0;
+        runtime.velocityY = 0;
+        runtime.velocityZ = 0;
+
+        // Clear any in-progress jump state — hanging supersedes them.
+        runtime.midJump = false;
+        runtime.apexFired = false;
+        controller.state.isVariableJumpCut = false;
+        controller.state.isAscending = false;
+
+        // The body is hanging — not on the ground.
+        controller.state.grounded = false;
+
+        // Body is suspended by the hands; L2 reads posture to gate gait and
+        // set eye height.
+        controller.state.posture = FirstPersonPosture.Hang;
+
+        controller.signals.onLedgeGrab.send1({
+            ledgeHeight: this._edgeY - controller.pose.rootPosition.y,
+        });
+    }
+
+    canInterrupt() {
+        // Wall-run / wall-jump can preempt if their conditions somehow hold
+        // (unusual mid-hang). Higher-priority abilities shouldn't be blocked.
+        return true;
+    }
+
+    onDeactivate(controller, runtime) {
+        // Open the re-grab refractory window on EVERY release (drop, slip,
+        // pull-up, shuffle-off). Covers the case where the dismount input
+        // returns to neutral while the body is still inside the grab window —
+        // without this the auto-catch re-fires next tick and snaps us back
+        // onto the lip.
+        runtime.ledgeRegrabCooldown = controller.config.ledgeGrab.regrabCooldown;
+    }
+
+    tick(controller, runtime, bodyTransform, dt, _system) {
+        const cfg = controller.config.ledgeGrab;
+        const intent = controller.intent;
+
+        // Re-assert posture each tick (defence against any layer resetting it
+        // before L2 reads). Body parked against the wall — no lean.
+        controller.state.posture = FirstPersonPosture.Hang;
+        runtime.leanTargetRad = 0;
+
+        // -- Exit: lost the ledge. Probe the CAPTURED anchor (not the
+        //    facing-relative sensor) so turning to look away from the wall
+        //    never reads as "ledge lost" — that's the whole point of the
+        //    wall-frame model. Releases only when the lip genuinely isn't
+        //    under us any more (e.g. the wall was removed).
+        if (!this._ledgeStillThere(runtime, cfg, _system)) {
+            controller.signals.onLedgeRelease.send1({ reason: "shuffle-off" });
+            return false;
+        }
+
+        // -- Decompose the move intent against the captured wall frame. These
+        //    are facing-INDEPENDENT (built from n/t, not the camera) — looking
+        //    away changes `facing` but not away/lateral, so it can't dismount.
+        const away = this._worldMoveDot(controller, runtime, this._nx, this._nz);
+        const lateral = this._worldMoveDot(controller, runtime, -this._nz, this._nx);
+        const { sinYaw, cosYaw } = runtime;
+        const facing = sinYaw * (-this._nx) + cosYaw * (-this._nz);
+        const jumpEdge = intent.jump && !runtime.prevJumpHeld;
+        const coneCos = Math.cos(cfg.pullUpFacingConeDeg * DEG_TO_RAD);
+
+        // -- (1) Pull-up / vault: moving toward the wall, OR a jump press while
+        //    facing into it. Request the climb; Mantle (next tick) resolves it
+        //    onto a standable top, or vaults over a too-thin one. The small
+        //    upward kick keeps mantle's ledgeAhead probe resolving correctly.
+        if (away < -cfg.moveTowardThreshold || (jumpEdge && facing > coneCos)) {
+            runtime.ledgePullUpRequest = true;
+            runtime.velocityY = runtime.jumpInitialVy * cfg.mantleUpUpFactor;
+            if (jumpEdge) runtime.prevJumpHeld = true;
+            runtime.midJump = true;
+            controller.state.isAscending = true;
+            controller.signals.onLedgeRelease.send1({ reason: "mantle-up" });
+            return false;
+        }
+        // Consume a jump press that DIDN'T pull up (facing away) so it doesn't
+        // fire later; stay hanging — looking away never auto-acts.
+        if (jumpEdge) runtime.prevJumpHeld = true;
+
+        // -- (2) Dismount. Crouch is an explicit, unconditional dismount.
+        //    Movement-away is CONSERVATIVE: leaving the hang (you fall) is more
+        //    consequential than shimmying, so a strafe taken while looking
+        //    somewhat off the wall — which bleeds a little into `away` — reads
+        //    as a SHIMMY (handled below), not an ejection. Only a stick that
+        //    clearly points OFF the edge (away-DOMINANT, past the threshold)
+        //    drops you.
+        if (intent.crouch) {
+            controller.signals.onLedgeRelease.send1({ reason: "drop" });
+            return false;
+        }
+        if (away > cfg.moveAwayThreshold && away > Math.abs(lateral)) {
+            controller.signals.onLedgeRelease.send1({ reason: "drop" });
+            return false;
+        }
+
+        // -- (5) Slip: exertion saturated → forced release.
+        if (controller.state.exertion >= 1.0) {
+            controller.signals.onLedgeRelease.send1({ reason: "slip" });
+            return false;
+        }
+
+        // -- (3) Shimmy: lateral intent dominant → try one step along the edge.
+        //    A blocked or discontinuous edge clamps (we stay hanging here),
+        //    never drops.
+        let shimmying = false;
+        if (Math.abs(lateral) > cfg.shimmyLateralMin && Math.abs(lateral) >= Math.abs(away)) {
+            shimmying = this._tryShimmy(controller, runtime, cfg, Math.sign(lateral), dt, _system);
+        }
+
+        // -- (4) Hold (or post-shimmy advance): snap to the hang pose just
+        //    OUTSIDE the wall face, gripping the top edge. The body centre sits
+        //    a capsule radius (+ a small gap) out from the face along its
+        //    outward normal — anchoring on the WALL keeps the body clear even
+        //    when the ledge was reached obliquely (a facing-relative offset
+        //    would sink it into a thin wall).
+        const standoff = controller.config.body.radius + cfg.hangOffsetForward;
+        bodyTransform.position.set(
+            this._anchorX + this._nx * standoff,
+            this._edgeY + cfg.hangOffsetY,
+            this._anchorZ + this._nz * standoff,
+        );
+        runtime.velocityX = 0;
+        runtime.velocityY = 0;
+        runtime.velocityZ = 0;
+        controller.state.grounded = false;
+
+        // Teleport-snap the camera on a parked (non-shimmying) hang: the body
+        // was just snapped onto the wall from wherever it was falling, so the
+        // render interpolation must JUMP to the hang pose, not glide into it.
+        // During a shimmy the body moves smoothly, so we let it interpolate.
+        if (!shimmying) runtime.renderSnap = true;
+
+        // Exertion rises while hanging — fatigue. Faster while actively
+        // shimmying. Mass-scaled like the rest of the exertion system.
+        const exertRate = cfg.exertionRiseRate * (shimmying ? cfg.shimmyExertionFactor : 1);
+        controller.state.exertion = clamp(
+            controller.state.exertion + exertRate * dt
+                * runtime.massRatios.exertionRiseScale,
+            0, 1,
+        );
+
+        return true;
+    }
+
+    /**
+     * World-space move intent (clamped to the unit disk) dotted with a
+     * horizontal axis (ax, az). Uses the controller's own move→world
+     * convention (screen_fwd = (sinYaw, cosYaw)). Facing-independent by
+     * construction — it's the intent in WORLD space, not camera space.
+     * @private
+     */
+    _worldMoveDot(controller, runtime, ax, az) {
+        const { sinYaw, cosYaw } = runtime;
+        let mx = controller.intent.move.x;
+        let my = controller.intent.move.y;
+        const len = Math.hypot(mx, my);
+        if (len > 1) { mx /= len; my /= len; }
+        const wmx = sinYaw * my - cosYaw * mx;
+        const wmz = cosYaw * my + sinYaw * mx;
+        return wmx * ax + wmz * az;
+    }
+
+    /**
+     * Is the grabbed lip still under us? Probes the CAPTURED anchor (a down-ray
+     * just past the face, into the wall along −n), independent of where the
+     * camera looks — so turning to look away never reads as "ledge lost". Falls
+     * back to the facing-relative sensor only when no physics backend is present
+     * (the flat-ground unit harness, which simulates loss via that sensor).
+     * @private
+     */
+    _ledgeStillThere(runtime, cfg, system) {
+        const physics = system && system.physicsSystem;
+        if (!physics) return runtime.sensors.ledgeAhead.hit;
+
+        const ray = this._ray;
+        const hit = this._hit;
+        ray.setOrigin(
+            this._anchorX - this._nx * cfg.shimmyEdgeProbeForward,
+            this._edgeY + cfg.shimmyContinuityProbeUp,
+            this._anchorZ - this._nz * cfg.shimmyEdgeProbeForward,
+        );
+        ray.setDirection(0, -1, 0);
+        ray.tMax = cfg.shimmyContinuityProbeUp + cfg.shimmyContinuityProbeDown;
+        const filter = (_e, c) => c !== runtime.collider;
+        if (!physics.raycast(ray, hit, filter)) return false;
+        return Math.abs(hit.position.y - this._edgeY) <= cfg.shimmyContinuityTol;
+    }
+
+    /**
+     * Attempt one shimmy step of `dir` (±1) along the edge tangent. Returns
+     * true if it stepped (clear AND continuous), false if it CLAMPED — a clamp
+     * holds in place, it never drops. On success it advances the anchor and
+     * re-captures the edge height so an undulating top is tracked.
+     *
+     * Two probes, both must pass:
+     *   (A) lateral CLEARANCE — a ray along the tangent from the body centre
+     *       must be free for the step (a perpendicular/concave wall blocks it).
+     *   (B) edge CONTINUITY — a down-ray just past the shifted edge must find
+     *       the lip still at ~edge height (else the edge ended).
+     * Needs the physics backend; without it (flat-ground unit harness) it
+     * can't verify geometry, so it clamps.
+     * @private
+     */
+    _tryShimmy(controller, runtime, cfg, dir, dt, system) {
+        const physics = system && system.physicsSystem;
+        if (!physics) return false; // no spatial backend → can't verify → clamp
+
+        const r = controller.config.body.radius;
+        const standoff = r + cfg.hangOffsetForward;
+        // Edge tangent (n is unit, so t is unit). dir picks the direction.
+        const tx = dir * (-this._nz);
+        const tz = dir * this._nx;
+        const step = cfg.shimmySpeed * dt;
+        const filter = (_e, c) => c !== runtime.collider; // exclude own body
+        const ray = this._ray;
+        const hit = this._hit;
+
+        // Body centre at the current hang pose.
+        const bx = this._anchorX + this._nx * standoff;
+        const bz = this._anchorZ + this._nz * standoff;
+
+        // (A) Lateral clearance along the tangent.
+        ray.setOrigin(bx, this._edgeY + cfg.shimmyClearanceProbeY, bz);
+        ray.setDirection(tx, 0, tz);
+        ray.tMax = step + r + cfg.shimmyClearanceGap;
+        if (physics.raycast(ray, hit, filter)) return false; // blocked → clamp
+
+        // (B) Edge continuity: down-probe just past the SHIFTED edge. The top
+        //     surface sits INTO the wall from the face (along -n), so offset the
+        //     probe that way before dropping it.
+        const nex = this._anchorX + tx * step;
+        const nez = this._anchorZ + tz * step;
+        ray.setOrigin(
+            nex - this._nx * cfg.shimmyEdgeProbeForward,
+            this._edgeY + cfg.shimmyContinuityProbeUp,
+            nez - this._nz * cfg.shimmyEdgeProbeForward,
+        );
+        ray.setDirection(0, -1, 0);
+        ray.tMax = cfg.shimmyContinuityProbeUp + cfg.shimmyContinuityProbeDown;
+        if (!physics.raycast(ray, hit, filter)) return false; // edge ended → clamp
+        if (Math.abs(hit.position.y - this._edgeY) > cfg.shimmyContinuityTol) return false;
+
+        // Commit: advance along the face and track the (possibly undulating)
+        // lip. The wall normal is kept constant — a straight face is the common
+        // case; wrapping a curving/convex wall is a v2 refinement.
+        this._anchorX = nex;
+        this._anchorZ = nez;
+        this._edgeY = hit.position.y;
+        return true;
+    }
+}