Add spatial choreography: turn & travel primitives

The figure could bend, reach, hinge, and grip but was bolted to one spot
facing one direction — so pirouettes, grapevines, box-steps, traveling
combos, and walk cycles were all impossible, the biggest ceiling for
dance and locomotion. This adds two per-phase primitives that let the
figure turn and move across the floor:

- `turn: <deg>` rotates the figure's facing (yaw about vertical).
- `travel: <x> <z>` moves it across the floor (world metres from the
  load spot).

Both are absolute targets carried forward across phases (like joint
angles) and both return home on the loop wrap, so a box-step traces a
square back to start and a pirouette spins a clean full turn.

Plumbing mirrors the existing reach/pin primitives end to end: parser
(parseStepChild + AstStep), schema, IR (Phase.turnDeg / Phase.travel,
travel clamped to a ±3m studio footprint), timeline (yaw/pos accumulate
alongside joints and interpolate with the same eased param), and the
renderer, which layers the sampled yaw and X/Z offset onto the base root
each frame before ground-lock. It composes cleanly because the feet
ground-lock only corrects the root's *vertical* height, never X/Z — so
the figure turns and steps while its feet still rest on the floor.

Loop seamlessness: the wrap keyframe returns facing to the NEAREST FULL
TURN to the final yaw rather than to 0, so a completed 360° pirouette
holds its facing through the reset (360°≡0° at the loop boundary) instead
of visibly un-spinning backward.

Scope: standing poses only — combining turn/travel with lying/seated
bases (whose root is already tilted) is documented as out of scope, like
the existing seated+hinge limit.

New movements (7): pirouette, box-step, grapevine, waltz-box, chasse
(Dance) and walk-cycle (a walk-out/about-face/walk-back) + quarter-turns
(Locomotion). Camera framing widens by the movement's travel extent so a
traveling figure stays in view.

Verified: 152/152 tests pass (13 new parser/render tests for turn/travel
sampling, clamping, and the home default); every example parses ROM-clean;
a full Playwright sweep of all 72 movements confirms the figures actually
turn and travel (live pelvis X/Z + root yaw telemetry) and that grounding
holds with zero floor-clipping — the additive change regressed none of
the existing 65 movements.

Author: claude

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,
       };
     },
   };