Merge pull request #7 from a-baran-orhan/claude/market-research-expansion-3xwm6w

Author: a-baran-orhan

ROADMAP.md

@@ -17,7 +17,7 @@ domain needs — so contributions land where they unlock the most.
 | **Fitness / strength** | Body-weight and free-form movement coaching | ✅ Core today (squat, curl, raise). Barbell/dumbbell/machine work needs props + grip. |
 | **Functional / elderly care** | Sit-to-stand, balance, gentle ROM, fall-prevention drills | 🟡 Partial — sit-to-stand works; reaching/balance need reach-IK + props. |
 | **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, simple phrases | 🟡 Simple gestures work; precise reach + partner work are future. |
+| **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). |
 
@@ -43,7 +43,14 @@ These are the unlocks, roughly in order of leverage:
 5. ~~**Hand / finger articulation**~~ — ✅ **shipped (single-DOF).** Per-finger
    curl bones + `fingers` group. Powers `make-a-fist`, `pinch-grip`, `hand-wave`,
    `finger-spell-demo`. Next: multi-joint fingers for accurate sign language.
-6. **Two-person + collision** — partner stretches, assisted rehab, contact sports
+6. ~~**Spatial choreography (turn & travel)**~~ — ✅ **shipped.** `turn: <deg>`
+   rotates the figure's facing and `travel: <x> <z>` moves it across the floor,
+   both absolute + carried across phases and returning home on the loop wrap.
+   Powers `pirouette`, `box-step`, `grapevine`, `waltz-box`, `chasse`,
+   `walk-cycle`, `quarter-turns` — pirouettes, traveling combos, and gait.
+   Standing poses only. Next: footstep-locked travel (true gait), motion
+   aliveness (velocity-continuous flow + weight shift).
+7. **Two-person + collision** — partner stretches, assisted rehab, contact sports
    (still deferred in the spec).
 
 ## Prop / equipment library (future)

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", "pin", "cue"];
+export const CHILD_KEYWORDS = ["ground-lock", "reach", "pin", "turn", "travel", "cue"];
 
 /** Short docs surfaced on hover and as completion detail. */
 export const KEYWORD_DOCS: Record<string, string> = {
@@ -39,6 +39,8 @@ export const KEYWORD_DOCS: Record<string, string> = {
   "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).",
+  turn: "Turns the figure to face a new direction — `turn: 360` (degrees, yaw about vertical). Absolute, carried across phases. Standing poses only.",
+  travel: "Moves the figure across the floor — `travel: 0.4 0` (world x z metres from the start spot). Absolute, carried across phases. Standing poses only.",
   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

@@ -114,6 +114,15 @@ function resolveStep(
     euler,
   }));
 
+  // Travel is clamped to a sane studio footprint (±TRAVEL_MAX m) so a stray
+  // large value can't fling the figure off the ground plane / out of frame.
+  const travel = step.travel
+    ? {
+        x: clampNum(step.travel.x, -TRAVEL_MAX, TRAVEL_MAX),
+        z: clampNum(step.travel.z, -TRAVEL_MAX, TRAVEL_MAX),
+      }
+    : undefined;
+
   return {
     name: step.name,
     durationSec: step.durationSec,
@@ -122,10 +131,19 @@ function resolveStep(
     groundLock: step.groundLock,
     reaches: step.reaches,
     pins: step.pins,
+    ...(step.turn !== undefined ? { turnDeg: step.turn } : {}),
+    ...(travel ? { travel } : {}),
     ...(step.cue ? { cue: step.cue } : {}),
   };
 }
 
+/** Max travel offset from the load spot, metres, in any single axis. */
+const TRAVEL_MAX = 3;
+
+function clampNum(v: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, v));
+}
+
 function ensure(map: Map<string, EulerDeg>, bone: string): EulerDeg {
   let euler = map.get(bone);
   if (!euler) {

packages/movit-parser/src/parser.ts

@@ -34,6 +34,10 @@ export interface AstStep {
   groundLock: string[];
   reaches: AstReach[];
   pins: AstPin[];
+  /** Root facing (yaw about world Y, degrees) at the end of this phase. */
+  turn?: number;
+  /** Root ground position (world X/Z metres) at the end of this phase. */
+  travel?: { x: number; z: number };
   cue?: string;
   line: number;
 }
@@ -224,6 +228,28 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
     return null;
   }
 
+  if (head === "turn") {
+    // `turn: <degrees>` — the figure's facing (root yaw about world Y) at the
+    // end of this phase. Absolute, accumulated forward like a joint target.
+    if (!current) return { line: ln.line, message: "`turn` outside of a step" };
+    if (t[1]?.type !== "colon" || t[2]?.type !== "num") {
+      return { line: ln.line, message: "expected `turn: <degrees>`" };
+    }
+    current.turn = Number(t[2].value);
+    return null;
+  }
+
+  if (head === "travel") {
+    // `travel: <x> <z>` — the figure's ground position (world X/Z metres) at the
+    // end of this phase. Absolute offset from the load spot, accumulated forward.
+    if (!current) return { line: ln.line, message: "`travel` outside of a step" };
+    if (t[1]?.type !== "colon" || t[2]?.type !== "num" || t[3]?.type !== "num") {
+      return { line: ln.line, message: "expected `travel: <x> <z>`" };
+    }
+    current.travel = { x: Number(t[2].value), z: Number(t[3].value) };
+    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

@@ -38,6 +38,8 @@ const stepSchema = z.object({
   groundLock: z.array(z.string()),
   reaches: z.array(reachSchema),
   pins: z.array(pinSchema),
+  turn: z.number().optional(),
+  travel: z.object({ x: z.number(), z: z.number() }).optional(),
   cue: z.string().optional(),
   line: z.number(),
 });

packages/movit-parser/src/types.ts

@@ -59,6 +59,16 @@ export interface Phase {
   reaches: ReachTarget[];
   /** Contact pins active during this phase (translate the body to the anchor). */
   pins: PinTarget[];
+  /**
+   * Root facing (yaw about world Y, degrees) at the end of this phase — an
+   * absolute target carried forward across phases. Powers turns / pirouettes.
+   */
+  turnDeg?: number;
+  /**
+   * Root ground position (world X/Z metres, offset from the load spot) at the
+   * end of this phase — absolute, carried forward. Powers travel / locomotion.
+   */
+  travel?: { x: number; z: number };
   cue?: string;
 }
 

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

@@ -124,4 +124,45 @@ describe("parse", () => {
     const { errors } = parse(src);
     expect(errors.some((e) => /easing/i.test(e.message))).toBe(true);
   });
+
+  it("parses turn and travel into the phase IR", () => {
+    const src = [
+      'movit exercise "Spin & step"',
+      "  rig humanoid",
+      "  pose start = standing",
+      '  step "Spin" 1s ease-in-out:',
+      "    turn: 360",
+      "    travel: -0.4 0.5",
+      "    ground-lock: feet",
+      "  repeat 2",
+    ].join("\n");
+    const { ir, errors, warnings } = parse(src);
+    expect(errors).toEqual([]);
+    expect(warnings).toEqual([]);
+    const phase = ir!.phases[0]!;
+    expect(phase.turnDeg).toBe(360);
+    expect(phase.travel).toEqual({ x: -0.4, z: 0.5 });
+  });
+
+  it("clamps travel to the studio footprint", () => {
+    const src = [
+      'movit exercise "Runaway"',
+      "  rig humanoid",
+      '  step "Go" 1s linear:',
+      "    travel: 99 -99",
+    ].join("\n");
+    const { ir } = parse(src);
+    expect(ir!.phases[0]!.travel).toEqual({ x: 3, z: -3 });
+  });
+
+  it("errors on malformed turn/travel", () => {
+    const src = [
+      'movit exercise "Bad"',
+      "  rig humanoid",
+      '  step "Go" 1s linear:',
+      "    travel: 0.4",
+    ].join("\n");
+    const { errors } = parse(src);
+    expect(errors.some((e) => /travel/i.test(e.message))).toBe(true);
+  });
 });

packages/movit-render/src/index.ts

@@ -217,6 +217,9 @@ export function createViewer(
   }
 
   const ROOT_X = new THREE.Vector3(1, 0, 0);
+  // Reused scratch for the per-frame facing rotation (yaw about world Y).
+  const WORLD_Y = new THREE.Vector3(0, 1, 0);
+  const YAW_Q = new THREE.Quaternion();
 
   /** Rotate the whole figure about a world-space pivot (axis through pivot). */
   function rotateRootAboutPivot(pivot: THREE.Vector3, angle: number): void {
@@ -385,8 +388,11 @@ export function createViewer(
     const center = box.getCenter(new THREE.Vector3());
     const size = box.getSize(new THREE.Vector3());
     // Frame against a ~1.8m standing height floor so short poses (squat,
-    // plank) don't zoom in awkwardly; fill most of the viewport.
-    const radius = Math.max(size.x, size.y, size.z, 1.8) * 0.5;
+    // plank) don't zoom in awkwardly; fill most of the viewport. Traveling
+    // movements (turn/travel) roam across the floor, so widen the frame by the
+    // movement's travel extent to keep the figure in view the whole loop.
+    const travel = timeline?.travelExtent ?? 0;
+    const radius = Math.max(size.x, size.y, size.z, 1.8) * 0.5 + travel;
     const dist = (radius / Math.sin((camera.fov * DEG) / 2)) * 1.15 + 0.3;
 
     desiredTarget.copy(center);
@@ -405,6 +411,17 @@ export function createViewer(
       // Recompute root contact from the grounded base each frame (no drift).
       mannequin.root.position.copy(baseRootPos);
       mannequin.root.quaternion.copy(baseRootQuat);
+      // Spatial choreography: layer the phase's facing (yaw about world Y) and
+      // ground travel (world X/Z) onto the base root BEFORE ground-lock. The
+      // feet-only ground-lock only corrects the root's Y, so it composes with
+      // travel (X/Z) and yaw without fighting them; the figure turns and steps
+      // across the floor while its feet still rest on it.
+      if (info.rootYaw !== 0) {
+        YAW_Q.setFromAxisAngle(WORLD_Y, info.rootYaw);
+        mannequin.root.quaternion.premultiply(YAW_Q);
+      }
+      mannequin.root.position.x += info.rootOffset.x;
+      mannequin.root.position.z += info.rootOffset.z;
       mannequin.root.updateMatrixWorld(true);
       applyGroundLock(info.groundLock);
       applyPins(info.pins);

packages/movit-render/src/timeline.ts

@@ -25,6 +25,10 @@ interface Keyframe {
   groundLock: string[];
   reaches: ReachTarget[];
   pins: PinTarget[];
+  /** Root facing (yaw about world Y, radians) at this keyframe. */
+  yaw: number;
+  /** Root ground offset (world X/Z metres) from the load spot at this keyframe. */
+  pos: { x: number; z: number };
 }
 
 /** A phase as a time span on the timeline, for scrubber markers / ribbon. */
@@ -52,7 +56,13 @@ export interface BuiltTimeline {
     groundLock: string[];
     reaches: ReachTarget[];
     pins: PinTarget[];
+    /** Interpolated root facing (yaw about world Y, radians). */
+    rootYaw: number;
+    /** Interpolated root ground offset (world X/Z metres) from the load spot. */
+    rootOffset: { x: number; z: number };
   };
+  /** Largest travel offset magnitude reached (metres) — for camera framing. */
+  travelExtent: number;
 }
 
 function eulerToQuat([x, y, z]: EulerDegTuple): THREE.Quaternion {
@@ -76,6 +86,11 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
 
   // Accumulating current joint angles (degrees).
   const curr = new Map<string, EulerDegTuple>(baseJoints);
+  // Accumulating root facing (yaw, degrees) and ground offset (metres), both
+  // carried forward across phases like joints and seeded at home (0).
+  let currYaw = 0;
+  let currPos = { x: 0, z: 0 };
+  let travelExtent = 0;
 
   const keyframes: Keyframe[] = [];
   keyframes.push({
@@ -86,13 +101,18 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
     groundLock: [],
     reaches: [],
     pins: [],
+    yaw: 0,
+    pos: { x: 0, z: 0 },
   });
 
   let t = 0;
   for (const phase of ir.phases) {
     for (const target of phase.targets) {
       curr.set(target.boneId, [target.euler.x, target.euler.y, target.euler.z]);
     }
+    if (phase.turnDeg !== undefined) currYaw = phase.turnDeg;
+    if (phase.travel) currPos = { x: phase.travel.x, z: phase.travel.z };
+    travelExtent = Math.max(travelExtent, Math.hypot(currPos.x, currPos.z));
     t += phase.durationSec;
     keyframes.push({
       time: t,
@@ -103,11 +123,18 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
       groundLock: phase.groundLock,
       reaches: phase.reaches,
       pins: phase.pins,
+      yaw: currYaw * DEG,
+      pos: { ...currPos },
     });
   }
 
-  // Wrap back to the base pose for a seamless loop.
+  // Wrap back to the base pose (and home position) for a seamless loop. Facing
+  // wraps to the NEAREST FULL TURN to the final yaw, not to 0: a completed 360°
+  // pirouette then holds its facing through the reset and the loop boundary
+  // (360°≡0°) is seamless, instead of visibly un-spinning backward. A partial
+  // turn (e.g. 90°) rounds to 0 and rotates back to front during the reset.
   const wrap = ir.phases[0]?.durationSec ?? 1;
+  const wrapYaw = Math.round(currYaw / 360) * 360 * DEG;
   t += wrap;
   keyframes.push({
     time: t,
@@ -117,6 +144,8 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
     groundLock: [],
     reaches: [],
     pins: [],
+    yaw: wrapYaw,
+    pos: { x: 0, z: 0 },
   });
 
   // Fill every keyframe with the full bone set (missing → identity).
@@ -147,6 +176,7 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
     basePose,
     bonesUsed,
     segments,
+    travelExtent,
     sample(time, bones) {
       const tt = duration > 0 ? ((time % duration) + duration) % duration : 0;
       let a = keyframes[0]!;
@@ -167,12 +197,22 @@ export function buildTimeline(ir: MovitIR): BuiltTimeline {
         if (!node) continue;
         node.quaternion.slerpQuaternions(a.quats.get(bone)!, b.quats.get(bone)!, eased);
       }
+      // Root facing/position: linear interpolation of the raw values so a large
+      // turn (e.g. 360°) sweeps the whole way round rather than taking a short
+      // arc. Uses the same eased param as the joints so everything moves as one.
+      const rootYaw = a.yaw + (b.yaw - a.yaw) * eased;
+      const rootOffset = {
+        x: a.pos.x + (b.pos.x - a.pos.x) * eased,
+        z: a.pos.z + (b.pos.z - a.pos.z) * eased,
+      };
       return {
         phaseName: b.name,
         ...(b.cue ? { cue: b.cue } : {}),
         groundLock: b.groundLock,
         reaches: b.reaches,
         pins: b.pins,
+        rootYaw,
+        rootOffset,
       };
     },
   };