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

Author: a-baran-orhan

packages/movit-parser/src/joints.ts

@@ -4,10 +4,12 @@
  * Coordinate convention (must match the renderer's rig — see spec/SPEC.md):
  *   Rest pose: standing, arms at sides, facing +Z. Each bone rotates in its
  *   own local frame where
- *     X = sagittal plane  (flexion +, extension -)
- *     Y = longitudinal    (internal rotation +, external -)
- *     Z = frontal plane   (abduction +, adduction -)
- *   Left-side bones mirror the Y and Z axes so symmetric cues look symmetric.
+ *     X = sagittal plane  (flexion / extension)
+ *     Y = longitudinal    (internal / external rotation)
+ *     Z = frontal plane   (abduction / adduction)
+ *   The unmirrored sign of each action is the RIGHT side's (the body's right
+ *   is -X); left-side bones mirror the Y and Z axes so symmetric cues look
+ *   symmetric — `shoulders: abduct 80` lifts both arms away from the midline.
  */
 
 import type { Axis } from "./types.js";
@@ -134,8 +136,14 @@ export interface ActionAxis {
 const ACTIONS: Record<string, ActionAxis> = {
   flex: { axis: "x", sign: 1 },
   extend: { axis: "x", sign: -1 },
-  abduct: { axis: "z", sign: 1 },
-  adduct: { axis: "z", sign: -1 },
+  // Frontal plane. The unmirrored sign is the RIGHT side's; with every bone
+  // resting along -Y and the right side of the body at -X, carrying a limb
+  // AWAY from the midline (abduction) is a -Z rotation. The left side mirrors
+  // to +Z. (Base sign +1 here was a bug that swung both arms and both legs
+  // through the torso.) For the unmirrored axial bones (spine/neck) abduct
+  // reads as lateral flexion toward the person's left.
+  abduct: { axis: "z", sign: -1 },
+  adduct: { axis: "z", sign: 1 },
   "rotate-in": { axis: "y", sign: 1 },
   "rotate-out": { axis: "y", sign: -1 },
   supinate: { axis: "y", sign: 1 },

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

@@ -458,3 +458,39 @@ describe("ROM-constrained reach-IK", () => {
     expect(Math.abs(e.z)).toBeLessThan(1e-6);
   });
 });
+
+describe("frontal plane direction", () => {
+  it("abduction carries arms and legs AWAY from the midline on both sides", () => {
+    const { ir, errors } = parse(
+      [
+        'movit exercise "Open"',
+        "  rig humanoid",
+        "  pose start = standing",
+        '  step "Open" 1s linear:',
+        "    shoulders: abduct 80",
+        "    hips: abduct 30",
+        "  repeat 1",
+      ].join("\n"),
+    );
+    expect(errors).toEqual([]);
+    const tl = buildTimeline(ir!);
+    const m = buildMannequin();
+    tl.sample(1, m.bones);
+    m.root.updateMatrixWorld(true);
+
+    // Each distal joint must sit FURTHER from the midline (|x|) than its
+    // proximal joint, on the SAME side — the inverted sign swung all four
+    // limbs across the body instead.
+    for (const [distal, proximal] of [
+      ["wrist_left", "shoulder_left"],
+      ["wrist_right", "shoulder_right"],
+      ["ankle_left", "hip_left"],
+      ["ankle_right", "hip_right"],
+    ] as const) {
+      const d = m.bones.get(distal)!.getWorldPosition(new THREE.Vector3());
+      const p = m.bones.get(proximal)!.getWorldPosition(new THREE.Vector3());
+      expect(Math.sign(d.x)).toBe(Math.sign(p.x));
+      expect(Math.abs(d.x)).toBeGreaterThan(Math.abs(p.x));
+    }
+  });
+});

spec/examples/neck-side-stretch.movit

@@ -3,17 +3,17 @@ movit stretch "Neck side stretch"
   pose start = standing
 
   step "Ear to right" 3s ease-in-out:
-    neck: abduct 40
+    neck: adduct 40
     ground-lock: feet
     cue "Gently take the right ear toward the right shoulder"
 
   step "Ear to left" 3.4s ease-in-out:
-    neck: adduct 40
+    neck: abduct 40
     ground-lock: feet
     cue "Pass through center and lengthen to the left"
 
   step "Center" 2s ease-out:
-    neck: adduct 0
+    neck: abduct 0
     ground-lock: feet
     cue "Float the head back to neutral"