Fix loop-wrap snaps, pin overshoot, and unreachable reach targets

Proactively audited all 65 movements by driving the real render pipeline
(Playwright + live bone-position diagnostics) across every phase and past
each loop's 100% mark, instead of waiting for individual bug reports.
Found and fixed four distinct classes of animation bugs:

- Loop-wrap snap: buildTimeline() always appends a wrap keyframe back to
  the start pose's joints, sized to the first phase's duration. Any
  movement whose last phase left a joint non-neutral produced a visible
  snap once per repeat cycle. Added an explicit reset phase to
  bent-over-row, step-up, and bicycle-crunch so every joint returns to
  its neutral/symmetric value before the loop wraps.

- Pin overshoot: applyPins() recomputes the whole-root translation every
  frame from the pinned effector's current position, so engaging a pin
  from a pose far from the anchor (e.g. arms at rest, bar overhead)
  caused a wild one-frame root spike. Restructured pull-up, dead-hang,
  and hanging-knee-raise so an FK-only lead-in phase reaches the bar
  before the pin engages, and an FK-only outro releases it, instead of
  engaging/releasing pins across a large pose gap.

- Unreachable reach-IK targets: solveCCD is a 2-joint chain hard-capped
  by physical arm/leg length (~0.54m for arms). touch-toes,
  cross-body-reach, and standing-quad-stretch asked for reaches beyond
  that envelope, leaving a visible gap between hand and target.
  Iteratively adjusted hinge/knee/rotation depth to bring each target
  within reach (touch-toes, standing-quad-stretch), and redesigned
  cross-body-reach to target the opposite shoulder instead of the knee,
  a standard reachable cross-body stretch.

- Floor clipping under a fixed-height pin: the frame-loop safety net only
  clamped the root above the floor when a phase had neither ground-lock
  nor a pin active, so triceps-dips (hands pinned to a low chair seat,
  legs held at a constant FK bend) let the feet sink 0.2m through the
  floor as the elbows folded and the root translated down to match the
  seat. Generalized the clamp to always run after ground-lock/pins,
  since it only ever moves the root up and never fights a legitimate
  pose — verified this doesn't affect the bar-hang movements, where feet
  are legitimately suspended above the floor.

seated-forward-fold's reach was blocked by a real engine gap: the
hip-hinge coupling in timeline.ts snapshot() assumes a zero hip-angle
baseline (true for standing) and breaks when combined with a pose that
pre-bends the hips, like seated (hip_left/right start at -90°). Rather
than change that coupling under time pressure, reworked the movement to
use FK-only torso flex instead of pelvis hinge + reach. This is a known
engine limitation, not a full fix.

Verified with a full sweep sampling all 65 movements at 9 points each
(including past 100% to exercise the loop-wrap transition) for both
floor-clipping and pelvis-height sanity — zero issues remain. All 139
existing tests still pass.

Author: claude

packages/movit-render/src/index.ts

@@ -408,20 +408,20 @@ export function createViewer(
       mannequin.root.updateMatrixWorld(true);
       applyGroundLock(info.groundLock);
       applyPins(info.pins);
-      // Safety net: a phase with neither ground-lock nor a pin has no
-      // per-frame anchor at all, so the root stays frozen at the base pose's
-      // grounded height while the FK animates freely on top of it — bending
-      // joints (e.g. a prone "superman" lift, a supine crunch) can then swing
-      // part of the mesh below the floor with nothing to catch it. Clamp the
-      // root up so the lowest point never dips below y=0; a no-op whenever the
-      // pose is legitimately elevated (bbox min already ≥ 0).
-      if (info.groundLock.length === 0 && info.pins.length === 0) {
+      // Safety net: nothing above ever intentionally pushes part of the body
+      // below the floor, so clamp the root up whenever the lowest point dips
+      // below y=0 — a no-op whenever the pose is legitimately grounded or
+      // elevated (bbox min already ≥ 0). This also catches phases with
+      // neither ground-lock nor a pin (the root stays frozen at the base
+      // pose's grounded height while FK animates freely on top of it, e.g. a
+      // prone "superman" lift), and pinned phases where a fixed-height anchor
+      // (a low chair seat) combined with static leg FK can otherwise let the
+      // feet sink through the floor as the arms fold (e.g. a chair dip).
+      mannequin.root.updateMatrixWorld(true);
+      const box = new THREE.Box3().setFromObject(mannequin.root);
+      if (box.min.y < 0) {
+        mannequin.root.position.y -= box.min.y;
         mannequin.root.updateMatrixWorld(true);
-        const box = new THREE.Box3().setFromObject(mannequin.root);
-        if (box.min.y < 0) {
-          mannequin.root.position.y -= box.min.y;
-          mannequin.root.updateMatrixWorld(true);
-        }
       }
       applyReaches(info.reaches);
       if (info.phaseName !== lastPhaseName) {

spec/examples/bent-over-row.movit

@@ -23,4 +23,13 @@ movit exercise "Bent-over row"
     ground-lock: feet
     cue "Lower the bar under control, keep the back flat"
 
+  step "Stand" 1s ease-out:
+    pelvis: hinge 0
+    knees: flex 0
+    shoulders: extend 0
+    elbows: flex 0
+    neck: extend 0
+    ground-lock: feet
+    cue "Stand up tall between sets"
+
   repeat 8

spec/examples/bicycle-crunch.movit

@@ -27,4 +27,12 @@ movit exercise "Bicycle crunch"
     knee_left: flex 20
     cue "Switch — left elbow toward the right knee"
 
+  step "Center" 0.6s ease-out:
+    spine: rotate-in 0
+    hip_right: flex 90
+    knee_right: flex 90
+    hip_left: flex 90
+    knee_left: flex 90
+    cue "Return to center, knees stacked over the hips"
+
   repeat 5

spec/examples/cross-body-reach.movit

@@ -3,24 +3,24 @@ movit stretch "Cross-body reach"
   pose start = standing
 
   step "Reach across right" 2s ease-in-out:
-    spine: rotate-in 20
-    reach: hand_right knee_left
+    shoulder_right: flex 80
+    reach: hand_right shoulder_left
     ground-lock: feet
-    cue "Rotate gently and reach the right hand toward the left knee"
+    cue "Pull the right arm across the chest toward the left shoulder"
 
   step "Return" 1.4s ease-out:
-    spine: rotate-in 0
+    shoulder_right: flex 0
     ground-lock: feet
-    cue "Unwind back to standing tall"
+    cue "Release back to center"
 
   step "Reach across left" 2s ease-in-out:
-    spine: rotate-out 20
-    reach: hand_left knee_right
+    shoulder_left: flex 80
+    reach: hand_left shoulder_right
     ground-lock: feet
-    cue "Reach the left hand toward the right knee"
+    cue "Pull the left arm across the chest toward the right shoulder"
 
   step "Center" 1.4s ease-out:
-    spine: rotate-out 0
+    shoulder_left: flex 0
     ground-lock: feet
     cue "Return to center"
 

spec/examples/dead-hang.movit

@@ -3,16 +3,23 @@ movit exercise "Dead hang"
   prop bar
   pose start = standing
 
+  step "Reach" 0.8s ease-out:
+    shoulders: flex 175
+    elbows: flex 5
+    ground-lock: feet
+    cue "Reach up and grip the bar"
+
   step "Hang" 3s ease-in-out:
     shoulders: flex 175
     elbows: flex 5
     pin: hand_left bar
     pin: hand_right bar
-    cue "Reach up, grip the bar, and relax into a long, straight-arm hang"
+    cue "Relax into a long, straight-arm hang"
 
   step "Down" 1.5s ease-out:
     shoulders: flex 0
     elbows: flex 0
+    ground-lock: feet
     cue "Drop down off the bar and shake out the arms"
 
   repeat 3

spec/examples/hanging-knee-raise.movit

@@ -3,7 +3,13 @@ movit exercise "Hanging knee raise"
   prop bar
   pose start = standing
 
-  step "Grip" 1.5s ease-in-out:
+  step "Reach" 0.8s ease-out:
+    shoulders: flex 175
+    elbows: flex 5
+    ground-lock: feet
+    cue "Reach up and grip the bar"
+
+  step "Grip" 0.7s ease-in-out:
     shoulders: flex 175
     elbows: flex 5
     pin: hand_left bar
@@ -13,15 +19,25 @@ movit exercise "Hanging knee raise"
   step "Raise knees" 1.2s ease-out:
     hips: flex 90
     knees: flex 90
+    shoulders: flex 175
+    elbows: flex 5
     pin: hand_left bar
     pin: hand_right bar
     cue "Draw both knees up toward the chest"
 
   step "Lower" 1.4s ease-in:
     hips: flex 0
     knees: flex 0
+    shoulders: flex 175
+    elbows: flex 5
     pin: hand_left bar
     pin: hand_right bar
     cue "Lower the legs under control, staying in a steady hang"
 
+  step "Release" 0.8s ease-in:
+    shoulders: flex 0
+    elbows: flex 0
+    ground-lock: feet
+    cue "Drop off the bar and rest"
+
   repeat 8

spec/examples/pull-up.movit

@@ -3,7 +3,13 @@ movit exercise "Pull-up"
   prop bar
   pose start = standing
 
-  step "Hang" 1.5s ease-in-out:
+  step "Reach" 0.8s ease-out:
+    shoulders: flex 175
+    elbows: flex 5
+    ground-lock: feet
+    cue "Reach up and grip the bar"
+
+  step "Hang" 0.7s ease-in-out:
     shoulders: flex 175
     elbows: flex 5
     pin: hand_left bar
@@ -24,4 +30,10 @@ movit exercise "Pull-up"
     pin: hand_right bar
     cue "Lower under control back to a full hang"
 
+  step "Release" 0.8s ease-in:
+    shoulders: flex 0
+    elbows: flex 0
+    ground-lock: feet
+    cue "Drop off the bar and rest"
+
   repeat 6

spec/examples/seated-forward-fold.movit

@@ -3,15 +3,17 @@ movit stretch "Seated forward fold"
   pose start = seated
 
   step "Fold" 3s ease-in-out:
-    pelvis: hinge 70
-    neck: flex 10
-    reach: hand_left ankle_left
-    reach: hand_right ankle_right
-    cue "Hinge forward over the legs and reach toward the feet"
+    spine: flex 60
+    chest: flex 25
+    neck: flex 15
+    shoulders: flex 60
+    cue "Hinge forward from the hips over the legs, reaching toward the feet"
 
   step "Rise" 2.5s ease-in-out:
-    pelvis: hinge 0
+    spine: flex 0
+    chest: flex 0
     neck: flex 0
+    shoulders: flex 0
     cue "Roll back up to a tall seated spine"
 
   repeat 3

spec/examples/standing-quad-stretch.movit

@@ -3,8 +3,8 @@ movit stretch "Standing quad stretch"
   pose start = standing
 
   step "Catch the foot" 3s ease-in-out:
-    knee_right: flex 120
-    hip_right: extend 10
+    knee_right: flex 144
+    hip_right: extend 20
     reach: hand_right ankle_right
     cue "Bend the right knee back and reach the hand for the ankle"
 

spec/examples/step-up.movit

@@ -24,4 +24,10 @@ movit exercise "Step-up"
     pin: foot_right box
     cue "Lower the trailing foot back to the floor"
 
+  step "Off the box" 0.8s ease-out:
+    hip_right: flex 0
+    knee_right: flex 0
+    ground-lock: feet
+    cue "Step the lead foot down to meet it, standing tall on the floor"
+
   repeat 6