ROM-constrain reach-IK and add hands/feet group effectors

Reach-IK previously ran unconstrained CCD, so a solved arm or leg could
exceed the healthy joint limits that authored angles are hard-clamped
to — a documented hole in the project's core safety promise, and the
roadmap's stated next unlock for reach.

- movit-parser: new `eulerRomFor(boneId)` expresses each bone's ROM as
  a signed per-axis Euler box in the renderer's local frame, derived
  from the clinical ROM table with the exact action→axis/sign/mirror
  mapping the clamp pass uses. Axes with no ROM entry lock to [0, 0],
  so a knee or elbow solves as a true hinge.
- movit-render: `solveCCD` accepts optional per-joint limits and clamps
  every chain joint back into its box each iteration; the viewer feeds
  reach chains their ROM boxes, widened to admit the authored FK start
  angle so IK never fights rig mechanics like the hip-hinge
  counter-rotation.
- reach/pin effectors now accept `hands` / `feet` groups (expand to
  both sides), and unknown effector names are line-anchored parse
  errors instead of being silently ignored by the renderer.
- language tooling: reach/pin effector completions, vocab sourced from
  the parser; spec, authoring guide, README, and roadmap updated.
- fix the root `typecheck` script (pointed at a nonexistent solution
  tsconfig) and a `window: never` narrowing error in the landing page.

Tests: 163 passing (11 new), including a sanity check that
unconstrained CCD does violate the shoulder ceiling on the same target
the constrained solve keeps safe.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0164eTtmmq6U8GQkAEmQsvV5

Author: claude

README.md

@@ -76,9 +76,10 @@ For where Movit spreads fastest and the per-domain go-to-market plan, see
 ## Scope (v0.1)
 
 ✅ Single-person movement across fitness, physio, desk, dance, education & rehab ·
-Mermaid-style DSL · ROM safety clamping · forward kinematics · ground-lock **and
-reach-to-target IK** · hip-hinge · lying/seated poses · scene props (chair/wall/
-bar) · a single-DOF hand rig · live playground.
+Mermaid-style DSL · ROM safety clamping (authored **and IK-solved** angles) ·
+forward kinematics · ground-lock **and ROM-constrained reach-to-target IK** ·
+hip-hinge · lying/seated poses · scene props (chair/wall/bar) · a single-DOF
+hand rig · live playground.
 
 ⏳ Deferred: two-person / partner movements + collision detection, deeper props
 (load, bands, rings), multi-joint fingers, FBX/GLB export, hosted SaaS editor and

ROADMAP.md

@@ -29,10 +29,13 @@ These are the unlocks, roughly in order of leverage:
    tips the torso forward over the hips while the legs stay planted (the renderer
    counter-rotates the hips). Powers `deadlift`, `bent-over-row`, `good-morning`,
    and `bow`. Next: hinge with a loaded-bar prop.
-2. ~~**Reach-IK (reach a world target)**~~ — ✅ **shipped.** `reach: <effector>
-   <target>` drives a hand/foot to a body landmark, the `floor`, or a prop anchor
-   via CCD. Powers `touch-toes`, `cross-body-reach`, `seated-forward-fold`, and
-   prop grips. Next: ROM-constrained reach + dual-hand targets.
+2. ~~**Reach-IK (reach a world target)**~~ — ✅ **shipped, now ROM-constrained.**
+   `reach: <effector> <target>` drives a hand/foot to a body landmark, the
+   `floor`, or a prop anchor via CCD. Powers `touch-toes`, `cross-body-reach`,
+   `seated-forward-fold`, and prop grips. The solve clamps every chain joint
+   into its Range-of-Motion box each iteration — solved angles obey the same
+   hard limits as authored ones — and `hands` / `feet` reach or pin both sides
+   in one line. Next: two-bone analytic solve for straighter elbows/knees.
 3. ~~**Scene props with contact anchors**~~ — ✅ **shipped (starter set).** `prop
    chair|wall|bar` adds a scene object with named anchors (`seat`, `wall`, `bar`).
    Powers `sit-to-stand`, `box-squat`, `wall-sit`, `dead-hang`, `hanging-knee-raise`.
@@ -77,8 +80,7 @@ Each prop is a small scene object + an anchor type; movements then reference it
 - 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.
-- Reach-IK is **unconstrained** (no ROM limits on the solved chain) and props are
-  visual + reach anchors (no physical sit/lean solve).
+- 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.
 

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": "for p in packages/*/tsconfig.json playground/tsconfig.json editors/*/tsconfig.json; do tsc --noEmit -p \"$p\" || exit 1; done"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.8",

packages/movit-language/src/completion.ts

@@ -9,6 +9,7 @@ import {
   KINDS,
   POSES,
   EFFECTORS,
+  REACH_EFFECTORS,
   EASINGS,
   JOINT_NAMES,
   ACTION_NAMES,
@@ -37,6 +38,7 @@ type Context =
   | "pose"
   | "easing"
   | "effector"
+  | "reach-effector"
   | "action"
   | "joint"
   | "top"
@@ -49,6 +51,7 @@ function contextFor(prefix: string, line: number): Context {
   if (/^\s*pose\s+start\s*=\s*[\w-]*$/.test(prefix)) return "pose";
   if (/^\s*step\s+"[^"]*"\s+[0-9.]+s\s+[\w-]*$/.test(prefix)) return "easing";
   if (/^\s*ground-lock\s*:\s*[\w,\s-]*$/.test(prefix)) return "effector";
+  if (/^\s*(reach|pin)\s*:\s*[\w-]*$/.test(prefix)) return "reach-effector";
   if (/^\s*[\w-]+\s*:\s*[\w-]*$/.test(prefix)) return "action";
 
   if (/^\s*[\w-]*$/.test(prefix)) {
@@ -80,6 +83,8 @@ export function getCompletions(
       return EASINGS.map((e) => item(e, "easing"));
     case "effector":
       return EFFECTORS.map((e) => item(e, "effector"));
+    case "reach-effector":
+      return REACH_EFFECTORS.map((e) => item(e, "effector"));
     case "action":
       return [...ACTION_NAMES, "hold"].map((a) => item(a, "action"));
     case "joint":

packages/movit-language/src/vocab.ts

@@ -4,7 +4,7 @@
  * drift from what the language actually accepts.
  */
 
-import { JOINT_NAMES, ACTION_NAMES, EASINGS } from "movit-parser";
+import { JOINT_NAMES, ACTION_NAMES, EASINGS, EFFECTOR_NAMES } from "movit-parser";
 
 export { JOINT_NAMES, ACTION_NAMES, EASINGS };
 
@@ -17,8 +17,8 @@ export const POSES = ["neutral", "standing", "plank", "supine", "prone", "seated
 /** Effectors that can be ground-locked. */
 export const EFFECTORS = ["hands", "feet"];
 
-/** Reach effectors (friendly aliases) and the scene props that supply anchors. */
-export const REACH_EFFECTORS = ["hand_left", "hand_right", "foot_left", "foot_right"];
+/** Reach/pin effectors (groups + per-side aliases) — sourced from the parser. */
+export const REACH_EFFECTORS = EFFECTOR_NAMES;
 export const PROPS = ["chair", "wall", "bar", "box"];
 
 /** Top-level directives (excluding the `movit` header keyword). */
@@ -37,8 +37,9 @@ export const KEYWORD_DOCS: Record<string, string> = {
   step: 'A movement phase — `step "<name>" <Ns> <easing>:`.',
   repeat: "How many times the movement loops.",
   "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).",
+  reach:
+    "Drives an effector to a target via ROM-constrained IK — `reach: hand_left ankle_left`, `reach: hands floor`.",
+  pin: "Moves the body so an effector sits on an anchor — `pin: hands 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.",

packages/movit-language/test/language.test.ts

@@ -78,6 +78,13 @@ describe("getCompletions", () => {
       expect.arrayContaining(["hands", "feet"]),
     );
   });
+
+  it("suggests reach effectors (groups + sides) after `reach: ` and `pin: `", () => {
+    expect(onLine("    reach: ", 11)).toEqual(
+      expect.arrayContaining(["hands", "hand_left", "foot_right"]),
+    );
+    expect(onLine("    pin: ", 9)).toEqual(expect.arrayContaining(["feet"]));
+  });
 });
 
 describe("getHover", () => {

packages/movit-parser/src/clamp.ts

@@ -13,11 +13,20 @@ import type {
   MovitIR,
   ParseError,
   Phase,
+  PinTarget,
+  ReachTarget,
   Warning,
 } 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 {
+  actionAxis,
+  boneType,
+  expandEffector,
+  expandJoint,
+  flexionSign,
+  isLeft,
+} from "./joints.js";
 import { clampAngle, romFor } from "./rom.js";
 
 export interface ResolveResult {
@@ -114,6 +123,28 @@ function resolveStep(
     euler,
   }));
 
+  // Reach / pin effectors: expand symmetric groups (`hands` → both hands) and
+  // reject unknown names — a typo'd effector would otherwise be silently
+  // ignored by the renderer, invisible to the authoring LLM.
+  const reaches: ReachTarget[] = [];
+  for (const r of step.reaches) {
+    const sides = expandEffector(r.effector);
+    if (sides.length === 0) {
+      errors.push({ line: r.line, message: `unknown reach effector: "${r.effector}"` });
+      continue;
+    }
+    for (const effector of sides) reaches.push({ effector, target: r.target });
+  }
+  const pins: PinTarget[] = [];
+  for (const p of step.pins) {
+    const sides = expandEffector(p.effector);
+    if (sides.length === 0) {
+      errors.push({ line: p.line, message: `unknown pin effector: "${p.effector}"` });
+      continue;
+    }
+    for (const effector of sides) pins.push({ effector, anchor: p.anchor });
+  }
+
   // 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
@@ -129,8 +160,8 @@ function resolveStep(
     easing: step.easing as Phase["easing"],
     targets,
     groundLock: step.groundLock,
-    reaches: step.reaches,
-    pins: step.pins,
+    reaches,
+    pins,
     ...(step.turn !== undefined ? { turnDeg: step.turn } : {}),
     ...(travel ? { travel } : {}),
     ...(step.cue ? { cue: step.cue } : {}),

packages/movit-parser/src/index.ts

@@ -50,9 +50,11 @@ export {
   JOINT_GROUP_NAMES,
   JOINT_NAMES,
   ACTION_NAMES,
+  EFFECTOR_NAMES,
   expandJoint,
+  expandEffector,
   actionAxis,
   boneType,
 } from "./joints.js";
-export { romFor, clampAngle, type RomLimit } from "./rom.js";
+export { romFor, clampAngle, eulerRomFor, type RomLimit, type EulerRom } from "./rom.js";
 export { EASINGS } from "./schema.js";

packages/movit-parser/src/joints.ts

@@ -95,6 +95,36 @@ export function expandJoint(name: string): string[] {
   return [];
 }
 
+/** Per-side reach/pin effectors (friendly aliases the renderer maps to bones). */
+const EFFECTOR_SIDES = [
+  "hand_left",
+  "hand_right",
+  "foot_left",
+  "foot_right",
+] as const;
+
+/** Symmetric effector groups → the per-side effectors they expand to. */
+const EFFECTOR_GROUPS: Record<string, string[]> = {
+  hands: ["hand_left", "hand_right"],
+  feet: ["foot_left", "foot_right"],
+};
+
+/** Every effector name `reach:` / `pin:` accept: groups + per-side aliases. */
+export const EFFECTOR_NAMES = [...Object.keys(EFFECTOR_GROUPS), ...EFFECTOR_SIDES];
+
+const EFFECTOR_SIDE_SET = new Set<string>(EFFECTOR_SIDES);
+
+/**
+ * Resolve a reach/pin effector name into per-side effectors (`hands` →
+ * both hands). Returns an empty array if the name is unknown (caller errors).
+ */
+export function expandEffector(name: string): string[] {
+  const group = EFFECTOR_GROUPS[name];
+  if (group) return [...group];
+  if (EFFECTOR_SIDE_SET.has(name)) return [name];
+  return [];
+}
+
 export interface ActionAxis {
   axis: Axis;
   /** +1 or -1 in the bone's local frame (before left/right mirroring). */

packages/movit-parser/src/parser.ts

@@ -19,11 +19,13 @@ export interface AstJointTarget {
 export interface AstReach {
   effector: string;
   target: string;
+  line: number;
 }
 
 export interface AstPin {
   effector: string;
   anchor: string;
+  line: number;
 }
 
 export interface AstStep {
@@ -212,7 +214,7 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
     if (t[1]?.type !== "colon" || !effector || !target) {
       return { line: ln.line, message: "expected `reach: <effector> <target>`" };
     }
-    current.reaches.push({ effector, target });
+    current.reaches.push({ effector, target, line: ln.line });
     return null;
   }
 
@@ -224,7 +226,7 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
     if (t[1]?.type !== "colon" || !effector || !anchor) {
       return { line: ln.line, message: "expected `pin: <effector> <anchor>`" };
     }
-    current.pins.push({ effector, anchor });
+    current.pins.push({ effector, anchor, line: ln.line });
     return null;
   }