Merge pull request #10 from a-baran-orhan/claude/project-core-features-ob0d4l

Fix axial/ankle/hinge sagittal inversion, dead finger meshes, dip bars, and a face marker

Author: a-baran-orhan

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,23 +96,37 @@ 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")!);
   addBall(bones.get("wrist_left")!, 0.05, mat);
   addBall(bones.get("wrist_right")!, 0.05, mat);
   addFoot(bones.get("ankle_left")!, mat);
@@ -139,6 +163,32 @@ function addBall(bone: THREE.Object3D, diameter: number, mat: THREE.Material): v
   bone.add(new THREE.Mesh(geo, mat));
 }
 
+/**
+ * A minimal face — nose wedge + two eye studs — on the head's front (+Z).
+ * The bare sphere hid which way the figure faces, making neck rotations and
+ * turns unreadable; darker studs poke just past the head surface so facing
+ * reads at a glance from any camera angle.
+ */
+function addFace(head: THREE.Object3D): void {
+  const mat = new THREE.MeshStandardMaterial({ color: 0x39424e, roughness: 0.6 });
+  const face = new THREE.Group();
+  face.name = "face";
+
+  // Head ball radius is 0.06 (see addBall(head, 0.12)).
+  const nose = new THREE.Mesh(new THREE.ConeGeometry(0.013, 0.035, 10), mat);
+  nose.rotation.x = Math.PI / 2; // cone +Y → +Z
+  nose.position.set(0, -0.004, 0.064);
+  face.add(nose);
+
+  for (const sx of [-1, 1]) {
+    const eye = new THREE.Mesh(new THREE.SphereGeometry(0.0095, 10, 8), mat);
+    eye.position.set(sx * 0.024, 0.016, 0.054);
+    face.add(eye);
+  }
+
+  head.add(face);
+}
+
 function addFoot(bone: THREE.Object3D, mat: THREE.Material): void {
   const geo = new THREE.BoxGeometry(0.07, 0.04, 0.16);
   const mesh = new THREE.Mesh(geo, mat);

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