Add contact-pin primitive: pull-ups, step-ups, dips, true hangs (#3)

The root-translation capability that step-ups / dips / pull-ups needed. A plain
"lift the body" scalar wouldn't do them — those need a CONTACT to stay pinned
(foot on box, hands on bar) while the body moves relative to it. So this adds a
`pin: <effector> <anchor>` directive: the renderer translates the whole figure so
the pinned effector sits on its anchor, letting the body hang, climb, or lower as
the joints work.

Engine:
- IR: Phase.pins threaded through types/parser/schema/clamp/timeline (mirrors
  reaches). New `pin: <effector> <anchor>` step-child.
- Renderer: applyPins() translates the root so pinned effectors meet anchors;
  runs after ground-lock, before reach-IK. Also fixed a latent root-state issue —
  the frame loop now resets the root to its grounded base each frame so
  ground-lock/pin/reach never accumulate (and the body returns to base when a pin
  ends).
- props: raised the pull-up bar to 2.3 m (above standing reach) with support
  posts, so a pinned grip genuinely hangs the body below it.

Movements (all verified against the real rig): pull-up (pelvis climbs ~0.34 m,
feet leave the floor), step-up (body rises ~0.32 m onto the box), triceps-dips
(hips lower), and dead-hang / hanging-knee-raise now truly suspended.

Docs + vocab: `pin` registered in SPEC, llm-authoring, vocab; coverage-gap updated.
Tests: pin parsing + a pull-up rise assertion; 140 passing, build green.


Claude-Session: https://claude.ai/code/session_018WCktDrKYZpJjCb2apbqWp

Co-authored-by: Claude <noreply@anthropic.com>

Author: a-baran-orhan

docs/coverage-gap.md

@@ -51,15 +51,24 @@ Ordered by gap size × how cleanly the engine renders it:
 These ~10 movements roughly **double our chest/core/back coverage** — all on
 today's engine, no new primitives required.
 
-**Front box prop (added):** a `prop box` placed in front of the figure now powers
+**Front box prop (added):** a `prop box` placed in front of the figure powers
 `box-step-taps` (the lead foot taps the box top — verified landing on the anchor).
 
-**Still deferred:** a true `step-up` and `triceps-dips`. Beyond prop placement,
-both need the figure's whole body to **translate vertically** (rise onto the box /
-lower into the dip), and the rig has no authorable root-height channel yet — the
-pelvis is fixed and only ground-lock nudges it. So a step-up reads as a step-*tap*
-and a dip can't lower. These return with a root-translation primitive (a `lift` /
-body-height channel) — a clean roadmap item, not a forced low-fidelity render.
+**Contact pins (added) — the root-translation primitive.** `pin: <effector>
+<anchor>` translates the whole body so a pinned hand/foot stays on its anchor
+while the limbs work, which is exactly the vertical body motion that was missing.
+This unlocked, all verified through the real rig:
+
+- `pull-up` — hang from the bar (feet ~0.38 m off the floor), elbows flex → pelvis
+  climbs ~0.34 m toward the bar.
+- `step-up` — lead foot pinned to the box top; the leg straightens → the body
+  rises ~0.32 m onto the box, trailing foot lifting off.
+- `triceps-dips` — hands pinned to the chair seat; elbows bend → hips lower.
+- `dead-hang` / `hanging-knee-raise` — now genuinely suspended from the bar.
+
+**Still deferred:** free-flight moves (jumps, burpees) where the body leaves *all*
+contacts — those want an authored whole-body `lift` channel (no anchor), a small
+follow-on to the pin work.
 
 ## Metadata gap (drives the catalogue work)
 

packages/movit-language/src/vocab.ts

@@ -25,7 +25,7 @@ export const PROPS = ["chair", "wall", "bar", "box"];
 export const TOP_KEYWORDS = ["rig", "prop", "pose", "step", "repeat"];
 
 /** Keywords valid as step children. */
-export const CHILD_KEYWORDS = ["ground-lock", "reach", "cue"];
+export const CHILD_KEYWORDS = ["ground-lock", "reach", "pin", "cue"];
 
 /** Short docs surfaced on hover and as completion detail. */
 export const KEYWORD_DOCS: Record<string, string> = {
@@ -38,6 +38,7 @@ export const KEYWORD_DOCS: Record<string, string> = {
   repeat: "How many times the movement loops.",
   "ground-lock": "Pins effectors (hands / feet) to the floor for this phase.",
   reach: "Drives an effector to a target via IK — `reach: hand_left ankle_left`.",
+  pin: "Moves the body so an effector sits on an anchor — `pin: hand_left bar` (hang, pull up, step up, dip).",
   cue: "A short coaching cue shown while this phase plays.",
   hold: "Keep the joint at its neutral / rest angle.",
 };

packages/movit-parser/src/clamp.ts

@@ -121,6 +121,7 @@ function resolveStep(
     targets,
     groundLock: step.groundLock,
     reaches: step.reaches,
+    pins: step.pins,
     ...(step.cue ? { cue: step.cue } : {}),
   };
 }

packages/movit-parser/src/index.ts

@@ -37,6 +37,7 @@ export type {
   EulerDeg,
   JointTarget,
   ReachTarget,
+  PinTarget,
   Phase,
   MovitIR,
   Warning,

packages/movit-parser/src/parser.ts

@@ -21,13 +21,19 @@ export interface AstReach {
   target: string;
 }
 
+export interface AstPin {
+  effector: string;
+  anchor: string;
+}
+
 export interface AstStep {
   name: string;
   durationSec: number;
   easing: string;
   targets: AstJointTarget[];
   groundLock: string[];
   reaches: AstReach[];
+  pins: AstPin[];
   cue?: string;
   line: number;
 }
@@ -152,6 +158,7 @@ export function parseToAst(source: string): ParseAstResult {
           targets: [],
           groundLock: [],
           reaches: [],
+          pins: [],
           line: ln.line,
         };
         doc.steps.push(current);
@@ -205,6 +212,18 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
     return null;
   }
 
+  if (head === "pin") {
+    // `pin: <effector> <anchor>` — translate the body so the effector sits there.
+    if (!current) return { line: ln.line, message: "`pin` outside of a step" };
+    const effector = t[2]?.type === "word" ? t[2].value : null;
+    const anchor = t[3]?.type === "word" ? t[3].value : null;
+    if (t[1]?.type !== "colon" || !effector || !anchor) {
+      return { line: ln.line, message: "expected `pin: <effector> <anchor>`" };
+    }
+    current.pins.push({ effector, anchor });
+    return null;
+  }
+
   // Joint target: `<joint>: <action> [<degrees>]`
   if (!current) {
     return { line: ln.line, message: "joint target outside of a step" };

packages/movit-parser/src/schema.ts

@@ -25,13 +25,19 @@ const reachSchema = z.object({
   target: z.string().min(1),
 });
 
+const pinSchema = z.object({
+  effector: z.string().min(1),
+  anchor: z.string().min(1),
+});
+
 const stepSchema = z.object({
   name: z.string(),
   durationSec: z.number().positive(),
   easing: z.enum(EASINGS),
   targets: z.array(jointTargetSchema),
   groundLock: z.array(z.string()),
   reaches: z.array(reachSchema),
+  pins: z.array(pinSchema),
   cue: z.string().optional(),
   line: z.number(),
 });

packages/movit-parser/src/types.ts

@@ -36,6 +36,17 @@ export interface ReachTarget {
   target: string;
 }
 
+/**
+ * A contact pin: translate the whole figure so `effector` sits on a fixed
+ * `anchor` (a prop anchor, a landmark, or `floor`). Unlike a reach (which moves
+ * the limb to a target) a pin moves the BODY, so the figure can hang from a bar,
+ * rise onto a box, or lower into a dip while the contact stays put.
+ */
+export interface PinTarget {
+  effector: string;
+  anchor: string;
+}
+
 /** One concurrent phase of a movement (e.g. "Lower" in a push-up). */
 export interface Phase {
   name: string;
@@ -46,6 +57,8 @@ export interface Phase {
   groundLock: string[];
   /** Reach-IK goals active during this phase. */
   reaches: ReachTarget[];
+  /** Contact pins active during this phase (translate the body to the anchor). */
+  pins: PinTarget[];
   cue?: string;
 }
 

packages/movit-render/src/index.ts

@@ -10,7 +10,7 @@
 
 import * as THREE from "three";
 import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
-import type { MovitIR, ReachTarget } from "movit-parser";
+import type { MovitIR, ReachTarget, PinTarget } from "movit-parser";
 import { buildMannequin, type Mannequin } from "./mannequin.js";
 import { buildTimeline, type BuiltTimeline, type PhaseSegment } from "./timeline.js";
 import { solveCCD } from "./ik.js";
@@ -132,6 +132,11 @@ export function createViewer(
   // wall surface). Populated when a doc declares props; empty otherwise.
   let propAnchors = new Map<string, THREE.Vector3>();
   let propScene: PropScene | null = null;
+  // The grounded base transform captured at load. Each frame resets the root to
+  // this before ground-lock / pins / reach recompute, so those root adjustments
+  // never accumulate across frames (and the body returns to base when a pin ends).
+  const baseRootPos = new THREE.Vector3();
+  const baseRootQuat = new THREE.Quaternion();
   let time = 0;
   let speed = 1;
   let playing = false;
@@ -325,6 +330,33 @@ export function createViewer(
     }
   }
 
+  /**
+   * Contact pins: translate the WHOLE figure so each pinned effector sits on its
+   * anchor. Where ground-lock keeps a planted foot on the floor, a pin keeps a
+   * hand on the bar or a foot on the box while the body moves relative to it —
+   * so the figure hangs from a bar, pulls up toward it, rises onto a box, or
+   * lowers into a dip as the limb joints work. Applied after ground-lock (which
+   * pinned movements normally omit) and before reach-IK.
+   */
+  function applyPins(pins: PinTarget[]): void {
+    if (pins.length === 0) return;
+    const delta = new THREE.Vector3();
+    let n = 0;
+    for (const p of pins) {
+      const effectorBone = EFFECTOR_BONE[p.effector] ?? p.effector;
+      const effector = mannequin.bones.get(effectorBone);
+      if (!effector) continue;
+      const anchor = resolveReachTarget(p.anchor, effector);
+      if (!anchor) continue;
+      delta.add(anchor.sub(effector.getWorldPosition(new THREE.Vector3())));
+      n++;
+    }
+    if (n > 0) {
+      mannequin.root.position.add(delta.multiplyScalar(1 / n));
+      mannequin.root.updateMatrixWorld(true);
+    }
+  }
+
   function frameCamera(): void {
     // Auto-frame the figure: fit its bounding box, keep a pleasant angle.
     const box = new THREE.Box3().setFromObject(mannequin.root);
@@ -349,8 +381,12 @@ export function createViewer(
   function frame(): void {
     if (timeline) {
       const info = timeline.sample(time, mannequin.bones);
+      // Recompute root contact from the grounded base each frame (no drift).
+      mannequin.root.position.copy(baseRootPos);
+      mannequin.root.quaternion.copy(baseRootQuat);
       mannequin.root.updateMatrixWorld(true);
       applyGroundLock(info.groundLock);
+      applyPins(info.pins);
       applyReaches(info.reaches);
       if (info.phaseName !== lastPhaseName) {
         lastPhaseName = info.phaseName;
@@ -416,6 +452,8 @@ export function createViewer(
       mannequin.root.updateMatrixWorld(true);
       groundFigure();
       captureGroundTargets();
+      baseRootPos.copy(mannequin.root.position);
+      baseRootQuat.copy(mannequin.root.quaternion);
       frameCamera();
     },
     play() {

packages/movit-render/src/props.ts

@@ -39,14 +39,21 @@ export function buildProps(types: string[], material?: THREE.Material): PropScen
       group.add(seat, back, leg(mat, 0.18, -0.0), leg(mat, -0.18, -0.0), leg(mat, 0.18, -0.32), leg(mat, -0.18, -0.32));
       anchors.set("seat", new THREE.Vector3(0, seatH + 0.03, -0.12));
     } else if (type === "bar") {
-      const barH = 1.95;
+      // Above standing reach, so a pinned grip genuinely hangs the body below it.
+      const barH = 2.3;
       const bar = new THREE.Mesh(
         new THREE.CylinderGeometry(0.025, 0.025, 1.2, 12),
         mat,
       );
       bar.rotation.z = Math.PI / 2; // horizontal, along X
       bar.position.set(0, barH, 0);
       group.add(bar);
+      // Posts down to the floor so the bar reads as a pull-up frame.
+      for (const x of [-0.55, 0.55]) {
+        const post = new THREE.Mesh(new THREE.CylinderGeometry(0.03, 0.03, barH, 10), mat);
+        post.position.set(x, barH / 2, 0);
+        group.add(post);
+      }
       anchors.set("bar", new THREE.Vector3(0, barH, 0));
     } else if (type === "wall") {
       const wall = box(2.2, 2.6, 0.1, mat);

packages/movit-render/src/timeline.ts

@@ -8,7 +8,7 @@
  */
 
 import * as THREE from "three";
-import type { MovitIR, ReachTarget } from "movit-parser";
+import type { MovitIR, ReachTarget, PinTarget } from "movit-parser";
 import { poseFor, type PoseSpec } from "./poses.js";
 
 const DEG = Math.PI / 180;
@@ -24,6 +24,7 @@ interface Keyframe {
   quats: Map<string, THREE.Quaternion>;
   groundLock: string[];
   reaches: ReachTarget[];
+  pins: PinTarget[];
 }
 
 /** A phase as a time span on the timeline, for scrubber markers / ribbon. */
@@ -45,7 +46,13 @@ export interface BuiltTimeline {
   sample(
     t: number,
     bones: Map<string, THREE.Object3D>,
-  ): { phaseName: string; cue?: string; groundLock: string[]; reaches: ReachTarget[] };
+  ): {
+    phaseName: string;
+    cue?: string;
+    groundLock: string[];
+    reaches: ReachTarget[];
+    pins: PinTarget[];
+  };
 }
 
 function eulerToQuat([x, y, z]: EulerDegTuple): THREE.Quaternion {
@@ -78,6 +85,7 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
     quats: snapshot(curr),
     groundLock: [],
     reaches: [],
+    pins: [],
   });
 
   let t = 0;
@@ -94,6 +102,7 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
       quats: snapshot(curr),
       groundLock: phase.groundLock,
       reaches: phase.reaches,
+      pins: phase.pins,
     });
   }
 
@@ -107,6 +116,7 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
     quats: snapshot(new Map(baseJoints)),
     groundLock: [],
     reaches: [],
+    pins: [],
   });
 
   // Fill every keyframe with the full bone set (missing → identity).
@@ -162,6 +172,7 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
         ...(b.cue ? { cue: b.cue } : {}),
         groundLock: b.groundLock,
         reaches: b.reaches,
+        pins: b.pins,
       };
     },
   };