feat: add hip-hinge primitive and fix torso flexion direction

- hips: hinge <deg> — closed-chain hip flexion (deadlift/forward fold):
  pelvis pitches forward, hips counter-rotate, legs stay vertical
- fix torso-chain flexion sign: spine/chest/neck/pelvis rest along +Y,
  so they bent backward (-Z) while limbs flexed forward (+Z)
- pelvis ROM entries (tilt); hinge clamped by hip-flexion ROM
- new examples: deadlift, true forward fold; roll-down keeps its own file
- teach hinge everywhere: SPEC, llm-authoring, language vocab, MCP guide,
  VS Code grammar (rebuilt bundle)
- repair broken typecheck script (root tsc -b had no tsconfig) + fix
  landing.ts narrowing error it uncovered

Author: a-baran-orhan

editors/vscode/syntaxes/movit.tmLanguage.json

@@ -37,7 +37,7 @@
     },
     "actions": {
       "name": "keyword.operator.movit",
-      "match": "\\b(flex|extend|abduct|adduct|rotate-in|rotate-out|supinate|pronate|dorsiflex|plantarflex)\\b"
+      "match": "\\b(flex|extend|abduct|adduct|rotate-in|rotate-out|supinate|pronate|dorsiflex|plantarflex|hinge)\\b"
     },
     "joints": {
       "name": "variable.other.movit",

package.json

@@ -15,7 +15,7 @@
     "coverage": "vitest run --coverage",
     "dev": "npm run dev -w playground",
     "build": "npm run build -w playground",
-    "typecheck": "tsc -b --pretty"
+    "typecheck": "tsc --noEmit -p packages/movit-parser && tsc --noEmit -p packages/movit-share && tsc --noEmit -p packages/movit-render && tsc --noEmit -p packages/movit-language && tsc --noEmit -p packages/movit-lsp && tsc --noEmit -p packages/movit-mcp && tsc --noEmit -p playground && tsc --noEmit -p editors/vscode"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.8",

packages/movit-language/src/vocab.ts

@@ -34,4 +34,7 @@ export const KEYWORD_DOCS: Record<string, string> = {
   "ground-lock": "Pins effectors (hands / feet) to the floor for this phase.",
   cue: "A short coaching cue shown while this phase plays.",
   hold: "Keep the joint at its neutral / rest angle.",
+  hinge:
+    "Hips only: closed-chain hip flexion — the torso tips over planted feet " +
+    "with a neutral spine (deadlift / forward fold).",
 };

packages/movit-mcp/src/guide.ts

@@ -44,5 +44,7 @@ movit <kind> "<Name>"          # kind = exercise | stretch | posture
 
 Joints: neck head spine chest pelvis, and (singular or plural) shoulders elbows
 wrists hips knees ankles. Actions (degrees are absolute targets): flex/extend,
-abduct/adduct, rotate-in/rotate-out, dorsiflex/plantarflex, hold neutral.
+abduct/adduct, rotate-in/rotate-out, dorsiflex/plantarflex, hold neutral, and
+hinge (hips only — closed-chain hip flexion: torso tips over planted feet with
+a neutral spine; use for deadlift / forward fold instead of hips: flex).
 Stay within healthy range of motion; the renderer hard-clamps anything beyond.`;

packages/movit-parser/src/clamp.ts

@@ -17,7 +17,14 @@ import type {
 } from "./types.js";
 import { MOVIT_VERSION } from "./types.js";
 import type { AstDoc, AstStep } from "./parser.js";
-import { actionAxis, boneType, expandJoint, flexionSign, isLeft } from "./joints.js";
+import {
+  HINGE_ACTION,
+  actionAxis,
+  boneType,
+  expandJoint,
+  flexionSign,
+  isLeft,
+} from "./joints.js";
 import { clampAngle, romFor } from "./rom.js";
 
 export interface ResolveResult {
@@ -70,6 +77,13 @@ function resolveStep(
       continue;
     }
 
+    // `hinge` is closed-chain and multi-bone (pelvis + both hips), so it
+    // can't go through the single-axis action table below.
+    if (target.action === HINGE_ACTION) {
+      resolveHinge(target, step.name, byBone, warnings, errors);
+      continue;
+    }
+
     const aa = actionAxis(target.action);
     if (!aa) {
       errors.push({ line: target.line, message: `unknown action: "${target.action}"` });
@@ -123,6 +137,55 @@ function resolveStep(
   };
 }
 
+/**
+ * Resolve `hips: hinge θ` — the closed-chain hip flexion of a deadlift or
+ * forward fold. Open-chain hip flexion swings the free leg forward; with the
+ * feet planted, the same joint motion instead tips the torso over the femurs.
+ * The rig expresses that as: rotate the pelvis forward by θ (the whole upper
+ * body pitches, spine staying neutral) and counter-rotate both hips by θ so
+ * the legs remain a vertical column. Clamped by hip-flexion ROM.
+ */
+function resolveHinge(
+  target: AstStep["targets"][number],
+  phaseName: string,
+  byBone: Map<string, EulerDeg>,
+  warnings: Warning[],
+  errors: ParseError[],
+): void {
+  if (target.joint !== "hips") {
+    errors.push({
+      line: target.line,
+      message: `action "hinge" only applies to "hips" (got "${target.joint}")`,
+    });
+    return;
+  }
+  if (target.degrees === null) {
+    errors.push({ line: target.line, message: `action "hinge" requires an angle` });
+    return;
+  }
+
+  const hipBones = expandJoint("hips");
+  let clamped = target.degrees;
+  for (const bone of hipBones) {
+    clamped = clampAngle(bone, HINGE_ACTION, target.degrees);
+    if (clamped !== target.degrees) {
+      warnings.push({
+        line: target.line,
+        phase: phaseName,
+        joint: bone,
+        action: HINGE_ACTION,
+        requested: target.degrees,
+        clamped,
+        limit: romFor(bone, HINGE_ACTION)!,
+      });
+    }
+  }
+
+  // Pelvis rests along +Y, so +x pitches the torso toward +Z (forward).
+  ensure(byBone, "pelvis").x = clamped;
+  for (const bone of hipBones) ensure(byBone, bone).x = -clamped;
+}
+
 function ensure(map: Map<string, EulerDeg>, bone: string): EulerDeg {
   let euler = map.get(bone);
   if (!euler) {

packages/movit-parser/src/joints.ts

@@ -83,22 +83,41 @@ const ACTIONS: Record<string, ActionAxis> = {
   plantarflex: { axis: "x", sign: -1 },
 };
 
+/**
+ * `hinge` is the closed-chain hip action (deadlift / forward fold): the torso
+ * tips over planted feet instead of the legs swinging forward. It maps to
+ * multiple bones (pelvis + both hips), so it lives outside the single-axis
+ * ACTIONS table and is resolved specially in clamp.ts.
+ */
+export const HINGE_ACTION = "hinge";
+
 /** Every semantic action name the DSL accepts (e.g. "flex", "abduct"). */
-export const ACTION_NAMES = Object.keys(ACTIONS);
+export const ACTION_NAMES = [...Object.keys(ACTIONS), HINGE_ACTION];
 
 /** Map a semantic action to its rotation axis and sign, or null if unknown. */
 export function actionAxis(action: string): ActionAxis | null {
   return ACTIONS[action] ?? 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
+ * (children hang below the joint), and for them a NEGATIVE x rotation flexes
+ * toward +Z — anatomically forward: hip, shoulder, elbow. Exceptions:
+ * - KNEE flexes toward -Z (heel toward the buttock) → +1.
+ * - TORSO chain (pelvis, spine, chest, neck) rests along +Y (children sit
+ *   ABOVE the joint), which mirrors the rotation: a POSITIVE x rotation is
+ *   what bends them toward +Z → +1. Without this the spine bent backward
+ *   while the limbs flexed forward.
+ * `extend` is the opposite of `flex`. Used by the resolver to sign
+ * flex/extend per joint so a squat folds correctly instead of inverting.
  */
-const FLEXION_SIGN: Record<string, number> = { knee: 1 };
+const FLEXION_SIGN: Record<string, number> = {
+  knee: 1,
+  pelvis: 1,
+  spine: 1,
+  chest: 1,
+  neck: 1,
+};
 
 export function flexionSign(boneType: string): number {
   return FLEXION_SIGN[boneType] ?? -1;

packages/movit-parser/src/rom.ts

@@ -41,6 +41,9 @@ const ROM: Record<string, ActionLimits> = {
   // --- Lower extremity (research Table 2) ---
   hip: {
     flex: { min: 0, max: 135 },
+    // Closed-chain hip flexion (torso over femur — deadlift / forward fold).
+    // Same anatomical joint and ceiling as open-chain flexion.
+    hinge: { min: 0, max: 135 },
     extend: { min: 0, max: 20 },
     abduct: { min: 0, max: 45 },
     adduct: { min: 0, max: 30 },
@@ -56,6 +59,14 @@ const ROM: Record<string, ActionLimits> = {
     plantarflex: { min: 0, max: 50 },
   },
   // --- Axial (conservative literature values) ---
+  pelvis: {
+    flex: { min: 0, max: 30 }, // anterior tilt
+    extend: { min: 0, max: 20 }, // posterior tilt
+    abduct: { min: 0, max: 15 }, // lateral tilt
+    adduct: { min: 0, max: 15 },
+    "rotate-in": { min: 0, max: 15 },
+    "rotate-out": { min: 0, max: 15 },
+  },
   spine: {
     flex: { min: 0, max: 90 },
     extend: { min: 0, max: 30 },

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

@@ -114,6 +114,83 @@ describe("parse", () => {
     expect(errors[0]!.message).toMatch(/header|must start/i);
   });
 
+  it("resolves torso flexion forward, matching the limbs (positive x)", () => {
+    // Torso bones' children sit at +Y offsets (limbs at -Y), so torso flexion
+    // needs the opposite euler sign to bend the same world direction (+Z).
+    const src = [
+      'movit stretch "Fold"',
+      "  rig humanoid",
+      '  step "Bend" 1s linear:',
+      "    spine: flex 45",
+      "    neck: flex 20",
+    ].join("\n");
+    const { ir, errors } = parse(src);
+    expect(errors).toEqual([]);
+    const targets = ir!.phases[0]!.targets;
+    expect(targets.find((t) => t.boneId === "spine")!.euler.x).toBe(45);
+    expect(targets.find((t) => t.boneId === "neck")!.euler.x).toBe(20);
+  });
+
+  it("resolves a hip hinge into pelvis rotation + hip counter-rotation", () => {
+    const src = [
+      'movit exercise "Deadlift"',
+      "  rig humanoid",
+      '  step "Hinge" 2s ease-in-out:',
+      "    hips: hinge 70",
+      "    knees: flex 20",
+      "    ground-lock: feet",
+    ].join("\n");
+    const { ir, errors, warnings } = parse(src);
+    expect(errors).toEqual([]);
+    expect(warnings).toEqual([]);
+    const targets = ir!.phases[0]!.targets;
+    // Pelvis tips the torso forward (+x); both hips counter-rotate so the
+    // legs stay vertical in world space.
+    expect(targets.find((t) => t.boneId === "pelvis")!.euler.x).toBe(70);
+    expect(targets.find((t) => t.boneId === "hip_left")!.euler.x).toBe(-70);
+    expect(targets.find((t) => t.boneId === "hip_right")!.euler.x).toBe(-70);
+    // Explicit knee targets are untouched by the hinge.
+    expect(targets.find((t) => t.boneId === "knee_left")!.euler.x).toBe(20);
+  });
+
+  it("clamps a hinge beyond hip flexion ROM and records warnings", () => {
+    const src = [
+      'movit exercise "Overfold"',
+      "  rig humanoid",
+      '  step "Hinge" 1s linear:',
+      "    hips: hinge 170",
+    ].join("\n");
+    const { ir, warnings } = parse(src);
+    expect(warnings).toHaveLength(2); // hip_left + hip_right
+    expect(warnings[0]!.action).toBe("hinge");
+    expect(warnings[0]!.clamped).toBe(135);
+    const targets = ir!.phases[0]!.targets;
+    expect(targets.find((t) => t.boneId === "pelvis")!.euler.x).toBe(135);
+    expect(targets.find((t) => t.boneId === "hip_left")!.euler.x).toBe(-135);
+  });
+
+  it("rejects hinge on joints other than hips", () => {
+    const src = [
+      'movit exercise "Bad hinge"',
+      "  rig humanoid",
+      '  step "Move" 1s linear:',
+      "    knees: hinge 30",
+    ].join("\n");
+    const { errors } = parse(src);
+    expect(errors.some((e) => /hinge.*hips/i.test(e.message))).toBe(true);
+  });
+
+  it("requires an angle for hinge", () => {
+    const src = [
+      'movit exercise "No angle"',
+      "  rig humanoid",
+      '  step "Move" 1s linear:',
+      "    hips: hinge",
+    ].join("\n");
+    const { errors } = parse(src);
+    expect(errors.some((e) => /angle/i.test(e.message))).toBe(true);
+  });
+
   it("rejects an unknown easing", () => {
     const src = [
       'movit exercise "Bad easing"',

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

@@ -55,6 +55,52 @@ describe("timeline", () => {
   });
 });
 
+describe("pose directions (world space)", () => {
+  function poseAtEnd(src: string) {
+    const { ir, errors } = parse(src);
+    expect(errors).toEqual([]);
+    const m = buildMannequin();
+    const tl = buildTimeline(ir!);
+    tl.sample(tl.segments[0]!.end - 1e-6, m.bones);
+    m.root.updateMatrixWorld(true);
+    return m;
+  }
+  const world = (m: ReturnType<typeof buildMannequin>, id: string) =>
+    m.bones.get(id)!.getWorldPosition(new THREE.Vector3());
+  const doc = (...lines: string[]) =>
+    ['movit exercise "t"', "  rig humanoid", '  step "go" 2s linear:', ...lines.map((l) => `    ${l}`)].join("\n");
+
+  it("spine flexion bends the head forward (+Z), the same side as the toes", () => {
+    const m = poseAtEnd(doc("spine: flex 45"));
+    expect(world(m, "head").z).toBeGreaterThan(0.15);
+  });
+
+  it("hip hinge tips the torso over the feet while the legs stay vertical", () => {
+    const m = poseAtEnd(doc("hips: hinge 70", "ground-lock: feet"));
+    // Torso pitched well forward…
+    expect(world(m, "head").z).toBeGreaterThan(0.35);
+    expect(world(m, "head").y).toBeLessThan(1.3);
+    // …while the legs stay a vertical column: knee directly below the hip.
+    const hip = world(m, "hip_left");
+    const knee = world(m, "knee_left");
+    const ankle = world(m, "ankle_left");
+    expect(Math.abs(knee.z - hip.z)).toBeLessThan(0.03);
+    expect(Math.abs(ankle.z - knee.z)).toBeLessThan(0.03);
+  });
+
+  it("hip hinge is a hinge, not a spinal roll: spine stays neutral", () => {
+    const m = poseAtEnd(doc("hips: hinge 70"));
+    // Neck→head direction should still align with the chest→neck direction
+    // (straight back), unlike a roll-down which curls the spine.
+    const chest = world(m, "chest");
+    const neck = world(m, "neck");
+    const head = world(m, "head");
+    const a = neck.clone().sub(chest).normalize();
+    const b = head.clone().sub(neck).normalize();
+    expect(a.dot(b)).toBeGreaterThan(0.99);
+  });
+});
+
 describe("ccd ik", () => {
   it("brings an effector close to its target", () => {
     const root = new THREE.Object3D();

playground/src/landing.ts

@@ -42,7 +42,7 @@ function initHero(): void {
 if ("requestIdleCallback" in window) {
   requestIdleCallback(initHero, { timeout: 1200 });
 } else {
-  window.setTimeout(initHero, 200);
+  setTimeout(initHero, 200);
 }
 
 // --- Examples gallery: each card opens the movement in the playground -------