Fix inverted axial/ankle/hinge sagittal directions, dead finger meshes, and chair dips

Three user reports (sign language a mess, cobra arching wrong, dips
clipping through the chair) traced back to two systemic rig bugs plus a
mis-fit prop:

1. Sagittal inversion across the axial chain. FLEXION_SIGN assumed every
   bone hangs downward like a limb, but the spine/chest/neck/head chain
   points UP — so spinal flexion leaned the torso BACKWARD, extension
   arched it forward, the pelvis hinge bowed deadlifts/bows backward,
   and dorsiflexion pointed the toes. Cobra pressed the head into the
   floor instead of arching up. An empirical direction matrix over every
   sagittal action confirmed all limb directions correct and all axial +
   ankle + hinge directions inverted; the sign table now distinguishes
   up-pointing bones (+X flexion) from down-pointing limbs (-X), and
   dorsiflex/plantarflex/hinge signs are corrected. The plank base pose
   carried the same inversion (it rendered belly-up) and is now face
   down. The whole example library was authored semantically, so every
   crunch, superman, chest-opener, forward fold, deadlift, and heel
   raise now renders as its cue describes.

2. Finger bones carried no meshes. Every digit capsule was parented to
   the WRIST, so curling a finger rotated an empty node — the hand never
   visibly moved, which is why finger-spelling looked broken. Finger
   bones now sit at the knuckle (the wrist-drawn segment becomes the
   rigid palm) and carry their own digit mesh, so curls fold visibly at
   the knuckle. The finger-spell demo also raises the hand to chest
   height instead of spelling at the hip.

3. Triceps dips on a chair seat clipped through the chair back. New
   `prop dip-bars` — parallel rails at support height with a `bars`
   grip anchor — and the example now presses up between the bars,
   lowers, and dismounts. Cobra is re-authored to plant the palms with
   ROM-constrained `reach: hands floor` while the back extends.

Tests: 169 passing (6 new: direction regressions for cobra and the
digit meshes, dip-bar anchor + dip-depth checks, plus updated hinge and
ankle ROM sign expectations).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0164eTtmmq6U8GQkAEmQsvV5

Author: claude

ROADMAP.md

@@ -19,7 +19,7 @@ domain needs — so contributions land where they unlock the most.
 | **Sports technique** | Golf swing, tennis serve, throwing, kicking | 🟡 Partial — needs trunk rotation fidelity, weight shift, and implements (club/racket/ball). |
 | **Dance / choreography** | Notating sequences, port de bras, phrases that turn & travel | ✅ Phrases, port de bras, pirouettes, and traveling combos (box-step, grapevine, chassé) work via `turn`/`travel`; partner work is future. |
 | **Martial arts** | Stances, strikes, basic forms | 🟡 Stances/strikes partly work; contact and weapons are future. |
-| **Sign language / gesture** | Finger-spelling, signs, expressive gesture | ⛔ Needs a hand/finger rig (the rig currently ends at the wrist). |
+| **Sign language / gesture** | Finger-spelling, signs, expressive gesture | 🟡 Partial — single-DOF finger curls render visibly (fist, pinch, wave, rough finger-spelling); exact sign language needs multi-joint fingers + wrist orientation. |
 
 ## Engine capabilities that widen the scope
 
@@ -72,14 +72,15 @@ Each prop is a small scene object + an anchor type; movements then reference it
 | **Resistance band** | Band pull-aparts, banded rehab, mobility with tension |
 | **Dumbbell / barbell / kettlebell** | Loaded strength patterns (needs grip + load cues) |
 | **Ball (stability / medicine)** | Core work, balance, throws |
-| **Parallettes / dip station** | Dips, L-sits, push-up variations at height |
+| **Parallettes / dip station** | ✅ Dip bars shipped (`prop dip-bars` — triceps dips). Still future: L-sits, push-up variations at height |
 | **Foam roller** | Self-myofascial release, mobility drills |
 
 ## Current limitations (honest)
 
 - One figure only; partner work and collision are still deferred.
-- A **starter** prop set (chair / wall / bar) — no bench, rings, bands, or loaded
-  implements yet, and props sit at fixed default placements.
+- A **starter** prop set (chair / wall / bar / box / dip bars) — no bench,
+  rings, bands, or loaded implements yet, and props sit at fixed default
+  placements.
 - Props are visual + reach anchors (no physical sit/lean solve).
 - Fingers are **single-DOF** curls — good for grip and rough gesture, not exact
   sign language. The head has no facial articulation.

packages/movit-language/src/vocab.ts

@@ -19,7 +19,7 @@ export const EFFECTORS = ["hands", "feet"];
 
 /** Reach/pin effectors (groups + per-side aliases) — sourced from the parser. */
 export const REACH_EFFECTORS = EFFECTOR_NAMES;
-export const PROPS = ["chair", "wall", "bar", "box"];
+export const PROPS = ["chair", "wall", "bar", "box", "dip-bars"];
 
 /** Top-level directives (excluding the `movit` header keyword). */
 export const TOP_KEYWORDS = ["rig", "prop", "pose", "step", "repeat"];
@@ -31,7 +31,7 @@ export const CHILD_KEYWORDS = ["ground-lock", "reach", "pin", "turn", "travel",
 export const KEYWORD_DOCS: Record<string, string> = {
   movit: 'Document header — `movit <kind> "<name>"`.',
   rig: "Selects the rig (currently `humanoid`).",
-  prop: "Adds a scene object — `prop chair | wall | bar | box`. Supplies reach anchors.",
+  prop: "Adds a scene object — `prop chair | wall | bar | box | dip-bars`. Supplies reach/pin anchors.",
   pose: "Sets the starting pose — `pose start = standing | neutral | plank | supine | prone | seated`.",
   start: "Used in `pose start = <pose>`.",
   step: 'A movement phase — `step "<name>" <Ns> <easing>:`.',

packages/movit-parser/src/joints.ts

@@ -148,13 +148,15 @@ const ACTIONS: Record<string, ActionAxis> = {
   "rotate-out": { axis: "y", sign: -1 },
   supinate: { axis: "y", sign: 1 },
   pronate: { axis: "y", sign: -1 },
-  dorsiflex: { axis: "x", sign: 1 },
-  plantarflex: { axis: "x", sign: -1 },
+  // The foot points FORWARD (+Z): lifting the toes toward the shin
+  // (dorsiflexion) is a -X rotation, pointing them is +X.
+  dorsiflex: { axis: "x", sign: -1 },
+  plantarflex: { axis: "x", sign: 1 },
   // Hip hinge: tip the torso forward over the hip line (deadlift, row, bow,
-  // good-morning). Applied to the `pelvis`; sign -1 tips the figure forward
-  // (same sagittal direction as spine flex). The renderer counter-rotates the
-  // hips so the legs stay planted — see movit-render/src/timeline.ts.
-  hinge: { axis: "x", sign: -1 },
+  // good-morning). Applied to the `pelvis`, whose torso child points UP, so
+  // forward is +X (like spine flexion). The renderer counter-rotates the hips
+  // so the legs stay planted — see movit-render/src/timeline.ts.
+  hinge: { axis: "x", sign: 1 },
 };
 
 /** Every semantic action name the DSL accepts (e.g. "flex", "abduct"). */
@@ -166,13 +168,22 @@ export function actionAxis(action: string): ActionAxis | null {
 }
 
 /**
- * Sagittal flexion direction differs by joint. With every bone resting along
- * -Y, most joints flex toward +Z (anatomically forward / up): hip, shoulder,
- * elbow, spine, neck. The KNEE is the exception — it flexes toward -Z (heel
- * toward the buttock). `extend` is the opposite of `flex`. Used by the resolver
- * to sign flex/extend per joint so a squat folds correctly instead of inverting.
+ * Sagittal flexion direction differs by joint. Limb bones rest along -Y
+ * (their child chain points DOWN), so flexing toward +Z (anatomically
+ * forward: hip, shoulder, elbow, wrist, fingers) is a -X rotation. The AXIAL
+ * chain (spine, chest, neck, head) points UP, so the same forward bend is +X.
+ * The KNEE is the odd limb out — it flexes backward (heel toward the buttock),
+ * +X. `extend` is the opposite of `flex`. Used by the resolver to sign
+ * flex/extend per joint so a squat folds and a crunch curls forward instead
+ * of inverting.
  */
-const FLEXION_SIGN: Record<string, number> = { knee: 1 };
+const FLEXION_SIGN: Record<string, number> = {
+  knee: 1,
+  spine: 1,
+  chest: 1,
+  neck: 1,
+  head: 1,
+};
 
 export function flexionSign(boneType: string): number {
   return FLEXION_SIGN[boneType] ?? -1;

packages/movit-parser/test/examples.test.ts

@@ -46,8 +46,9 @@ describe("hip-hinge action", () => {
     expect(errors).toEqual([]);
     expect(warnings).toEqual([]);
     const pelvis = ir!.phases[0]!.targets.find((t) => t.boneId === "pelvis")!;
-    // hinge tips the torso forward — same sagittal direction as spine flex (-X).
-    expect(pelvis.euler.x).toBe(-80);
+    // hinge tips the torso forward — same sagittal direction as spine flex (+X,
+    // the axial chain points up).
+    expect(pelvis.euler.x).toBe(80);
   });
 
   it("clamps an over-deep hinge to the pelvis ROM ceiling", () => {
@@ -56,6 +57,6 @@ describe("hip-hinge action", () => {
     expect(warnings).toHaveLength(1);
     expect(warnings[0]!.clamped).toBe(120);
     const pelvis = ir!.phases[0]!.targets.find((t) => t.boneId === "pelvis")!;
-    expect(pelvis.euler.x).toBe(-120);
+    expect(pelvis.euler.x).toBe(120);
   });
 });

packages/movit-parser/test/rom.test.ts

@@ -71,8 +71,10 @@ describe("euler ROM boxes (eulerRomFor)", () => {
   });
 
   it("covers the ankle via dorsiflex/plantarflex and the pelvis via hinge", () => {
-    expect(eulerRomFor("ankle_left")!.x).toEqual({ min: -50, max: 15 });
-    expect(eulerRomFor("pelvis")!.x).toEqual({ min: -120, max: 0 });
+    // Toes point +Z: dorsiflexion (toes up) is -X, plantarflexion +X.
+    expect(eulerRomFor("ankle_left")!.x).toEqual({ min: -15, max: 50 });
+    // The pelvis' torso child points up: the forward hinge is +X.
+    expect(eulerRomFor("pelvis")!.x).toEqual({ min: 0, max: 120 });
   });
 
   it("returns null for a bone without ROM data", () => {

packages/movit-render/src/mannequin.ts

@@ -52,8 +52,11 @@ const SKELETON: BoneSpec[] = [
   { id: "knee_right", parent: "hip_right", offset: [0, -0.45, 0], radius: 0.05 },
   { id: "ankle_right", parent: "knee_right", offset: [0, -0.43, 0], radius: 0.04 },
 
-  // Fingers — short single-segment digits off each wrist, splayed in X and
-  // angled slightly forward (+Z, palm-side). One curl DOF each (flex).
+  // Fingers — one curl DOF each (flex), splayed in X and angled slightly
+  // forward (+Z, palm-side). Offsets are the FINGERTIP position; the bone is
+  // placed partway along at the knuckle (KNUCKLE_T) so the wrist-drawn segment
+  // becomes the rigid palm/metacarpal and the bone carries its own digit mesh —
+  // otherwise curling a finger rotates an empty node and the hand never moves.
   { id: "thumb_left", parent: "wrist_left", offset: [0.035, -0.04, 0.025], radius: 0.014 },
   { id: "index_left", parent: "wrist_left", offset: [0.025, -0.085, 0.012], radius: 0.013 },
   { id: "middle_left", parent: "wrist_left", offset: [0.008, -0.092, 0.012], radius: 0.013 },
@@ -67,6 +70,13 @@ const SKELETON: BoneSpec[] = [
   { id: "pinky_right", parent: "wrist_right", offset: [0.028, -0.075, 0.012], radius: 0.012 },
 ];
 
+/** Fraction of the wrist→fingertip span where the knuckle (finger bone) sits. */
+const KNUCKLE_T = 0.55;
+
+function isFinger(id: string): boolean {
+  return /^(thumb|index|middle|ring|pinky)_/.test(id);
+}
+
 /** Build the mannequin. `material` lets the playground theme it. */
 export function buildMannequin(material?: THREE.Material): Mannequin {
   const mat =
@@ -86,21 +96,34 @@ export function buildMannequin(material?: THREE.Material): Mannequin {
   for (const spec of SKELETON) {
     const bone = new THREE.Object3D();
     bone.name = spec.id;
-    bone.position.set(...spec.offset);
+    // Finger bones sit at the knuckle; the offset names the fingertip.
+    const offset = new THREE.Vector3(...spec.offset);
+    if (isFinger(spec.id)) offset.multiplyScalar(KNUCKLE_T);
+    bone.position.copy(offset);
 
     const parent = spec.parent ? bones.get(spec.parent) : root;
     (parent ?? root).add(bone);
     bones.set(spec.id, bone);
 
     // Draw the segment from the parent joint to this joint, on the parent.
     if (spec.parent && spec.radius) {
-      const length = Math.hypot(...spec.offset);
-      const seg = makeSegment(length, spec.radius, mat);
-      orientSegment(seg, new THREE.Vector3(...spec.offset));
+      const seg = makeSegment(offset.length(), spec.radius, mat);
+      orientSegment(seg, offset);
       bones.get(spec.parent)!.add(seg);
     }
   }
 
+  // Digit meshes ON the finger bones, spanning knuckle → fingertip, so a
+  // finger curl visibly folds at the knuckle.
+  for (const spec of SKELETON) {
+    if (!isFinger(spec.id) || !spec.radius) continue;
+    const full = new THREE.Vector3(...spec.offset);
+    const span = full.clone().multiplyScalar(1 - KNUCKLE_T);
+    const digit = makeSegment(span.length(), spec.radius * 0.92, mat);
+    orientSegment(digit, span);
+    bones.get(spec.id)!.add(digit);
+  }
+
   // Head sphere + small hand/foot caps for readability.
   addBall(bones.get("head")!, 0.12, mat);
   addFace(bones.get("head")!);

packages/movit-render/src/poses.ts

@@ -22,17 +22,19 @@ const NEUTRAL: PoseSpec = {
 // Face-down support position: torso horizontal, arms reaching to the floor.
 // Ground-lock IK plants hands and feet; this just gets the gross posture right.
 const PLANK: PoseSpec = {
-  // Face-down diagonal: rotating the standing figure by -72° about X tips it so
-  // the head/shoulders stay HIGH and the legs point forward-and-down toward the
-  // floor (a value past -90 would kick the feet up instead). Arms drop straight
-  // down (shoulder flex 90); toes curl under (ankle). groundFigure() then drops
-  // the whole body so the lowest contact rests on the floor.
-  root: { position: [0, 0.6, 0], rotationDeg: [-72, 0, 0] },
+  // Face-down diagonal: rotating the standing figure by +72° about X (the same
+  // direction as prone's +90°) tips it chest-toward-the-floor with the
+  // head/shoulders HIGH and the feet trailing low behind (a value past 90
+  // would kick the feet up instead). Arms drop straight down toward the floor
+  // (shoulder flex 90 = local -X); toes curl under (ankle dorsiflex = local
+  // -X). groundFigure() then drops the body so the lowest contact rests on
+  // the floor.
+  root: { position: [0, 0.6, 0], rotationDeg: [72, 0, 0] },
   joints: {
-    shoulder_left: [90, 0, 0],
-    shoulder_right: [90, 0, 0],
-    ankle_left: [25, 0, 0],
-    ankle_right: [25, 0, 0],
+    shoulder_left: [-90, 0, 0],
+    shoulder_right: [-90, 0, 0],
+    ankle_left: [-25, 0, 0],
+    ankle_right: [-25, 0, 0],
   },
 };
 

packages/movit-render/src/props.ts

@@ -20,7 +20,7 @@ export interface PropScene {
   anchors: Map<string, THREE.Vector3>;
 }
 
-/** Build the declared props (`chair | wall | bar`). Unknown types are ignored. */
+/** Build the declared props (`chair | wall | bar | box | dip-bars`). Unknown types are ignored. */
 export function buildProps(types: string[], material?: THREE.Material): PropScene {
   const group = new THREE.Group();
   group.name = "movit-props";
@@ -60,6 +60,33 @@ export function buildProps(types: string[], material?: THREE.Material): PropScen
       wall.position.set(0, 1.3, -0.34);
       group.add(wall);
       anchors.set("wall", new THREE.Vector3(0, 0.9, -0.29));
+    } else if (type === "dip-bars") {
+      // Parallel dip bars either side of the figure, rails running along Z.
+      // Rail height is set so a straight-arm support holds the feet clear of
+      // the floor. The single `bars` grip anchor sits at the midpoint between
+      // the rails at grip height: pins translate the BODY so the average hand
+      // position meets the anchor, which leaves each authored hand over its
+      // own rail.
+      const railH = 1.1;
+      const halfSpan = 0.22;
+      for (const x of [-halfSpan, halfSpan]) {
+        const rail = new THREE.Mesh(
+          new THREE.CylinderGeometry(0.022, 0.022, 0.9, 12),
+          mat,
+        );
+        rail.rotation.x = Math.PI / 2; // horizontal, along Z
+        rail.position.set(x, railH, 0);
+        group.add(rail);
+        for (const z of [-0.35, 0.35]) {
+          const post = new THREE.Mesh(
+            new THREE.CylinderGeometry(0.026, 0.026, railH, 10),
+            mat,
+          );
+          post.position.set(x, railH / 2, z);
+          group.add(post);
+        }
+      }
+      anchors.set("bars", new THREE.Vector3(0, railH, 0));
     } else if (type === "box") {
       // A low step/plateau placed IN FRONT of the figure (+Z) — the lead foot
       // steps forward and up onto it. Top surface at ~0.30 m; `box` anchor sits

packages/movit-render/test/render.test.ts

@@ -507,3 +507,125 @@ describe("face marker", () => {
     }
   });
 });
+
+describe("hand rig articulation", () => {
+  it("finger bones carry their own digit meshes, so curls are visible", () => {
+    const m = buildMannequin();
+    m.root.updateMatrixWorld(true);
+    const index = m.bones.get("index_right")!;
+    expect(index.children.length).toBeGreaterThan(0); // the digit capsule
+
+    // Curl the finger 90° and check the digit's far end actually moves.
+    const digit = index.children[0]!;
+    const tipBefore = digit.getWorldPosition(new THREE.Vector3());
+    index.rotation.x = -90 * DEG;
+    m.root.updateMatrixWorld(true);
+    const tipAfter = digit.getWorldPosition(new THREE.Vector3());
+    expect(tipBefore.distanceTo(tipAfter)).toBeGreaterThan(0.015);
+  });
+});
+
+describe("dip bars prop", () => {
+  it("exposes a `bars` grip anchor at support height", () => {
+    const { anchors, group } = buildProps(["dip-bars"]);
+    expect(anchors.has("bars")).toBe(true);
+    const grip = anchors.get("bars")!;
+    expect(grip.y).toBeGreaterThan(0.9); // high enough that feet clear the floor
+    expect(grip.y).toBeLessThan(1.6); // but well below the pull-up bar
+    expect(group.children.length).toBeGreaterThan(0);
+  });
+
+  // Same root-translation logic as the viewer's applyPins (see contact pins).
+  function pelvisYAt(source: string, t: number, anchors: Map<string, THREE.Vector3>): number {
+    const BONE: Record<string, string> = {
+      hand_left: "wrist_left",
+      hand_right: "wrist_right",
+      foot_left: "ankle_left",
+      foot_right: "ankle_right",
+    };
+    const { ir } = parse(source);
+    const tl = buildTimeline(ir!);
+    const m = buildMannequin();
+    const info = tl.sample(t, m.bones);
+    m.root.updateMatrixWorld(true);
+    const delta = new THREE.Vector3();
+    let n = 0;
+    for (const pin of info.pins) {
+      const eff = m.bones.get(BONE[pin.effector] ?? pin.effector);
+      const a = anchors.get(pin.anchor);
+      if (!eff || !a) continue;
+      delta.add(a.clone().sub(eff.getWorldPosition(new THREE.Vector3())));
+      n++;
+    }
+    if (n > 0) {
+      m.root.position.add(delta.multiplyScalar(1 / n));
+      m.root.updateMatrixWorld(true);
+    }
+    return m.bones.get("pelvis")!.getWorldPosition(new THREE.Vector3()).y;
+  }
+
+  it("lowers the body between the bars as the elbows flex (dip bottom)", () => {
+    const dips = [
+      'movit exercise "Dips"',
+      "  rig humanoid",
+      "  prop dip-bars",
+      "  pose start = standing",
+      '  step "Support" 1s ease-out:',
+      "    elbows: flex 5",
+      "    knees: flex 70",
+      "    pin: hands bars",
+      '  step "Lower" 1s ease-in-out:',
+      "    shoulders: extend 30",
+      "    elbows: flex 90",
+      "    knees: flex 70",
+      "    pin: hands bars",
+      "  repeat 4",
+    ].join("\n");
+    const anchors = buildProps(["dip-bars"]).anchors;
+    const support = pelvisYAt(dips, 0.99, anchors);
+    const bottom = pelvisYAt(dips, 1.99, anchors);
+    expect(support).toBeGreaterThan(0.9); // hips held up at bar height
+    expect(bottom).toBeLessThan(support - 0.08); // body sinks into the dip
+  });
+});
+
+describe("cobra", () => {
+  it("arches the chest and head up off the floor during the Lift", () => {
+    const src = [
+      'movit stretch "Cobra"',
+      "  rig humanoid",
+      "  pose start = prone",
+      '  step "Lift" 2.5s ease-in-out:',
+      "    spine: extend 30",
+      "    chest: extend 15",
+      "    neck: extend 25",
+      "    shoulders: flex 50",
+      "    elbows: flex 25",
+      "    reach: hands floor",
+      "  repeat 1",
+    ].join("\n");
+    const { ir, errors, warnings } = parse(src);
+    expect(errors).toEqual([]);
+    expect(warnings).toEqual([]);
+    const tl = buildTimeline(ir!);
+    const m = buildMannequin();
+
+    // Apply the prone base root like the viewer does.
+    const base = tl.basePose.root!;
+    m.root.rotation.set(...(base.rotationDeg!.map((d) => d * DEG) as [number, number, number]));
+
+    tl.sample(0, m.bones);
+    m.root.updateMatrixWorld(true);
+    const headFlat = m.bones.get("head")!.getWorldPosition(new THREE.Vector3()).y;
+    const pelvisFlat = m.bones.get("pelvis")!.getWorldPosition(new THREE.Vector3()).y;
+
+    tl.sample(2.5, m.bones);
+    m.root.updateMatrixWorld(true);
+    const headUp = m.bones.get("head")!.getWorldPosition(new THREE.Vector3()).y;
+    const pelvisUp = m.bones.get("pelvis")!.getWorldPosition(new THREE.Vector3()).y;
+
+    // The head rises well above its flat height while the pelvis stays put.
+    expect(headUp - headFlat).toBeGreaterThan(0.2);
+    expect(Math.abs(pelvisUp - pelvisFlat)).toBeLessThan(0.05);
+  });
+});