Merge pull request #64 from posecode-dev/agent/support-back-ground-lock

Support back ground lock

Author: a-baran-orhan

packages/posecode-eval/test/eval.test.ts

@@ -74,6 +74,15 @@ describe("metrics", () => {
 
     const pullUp = movement("pull-up");
     expect(Math.min(...pullUp.phases.map((p) => headPropClearance(pullUp, p)))).toBeGreaterThan(-0.01);
+
+    // A dead bug moves opposite limbs while the torso remains planted. This
+    // catches the old silent `ground-lock: back` no-op, where whole-figure
+    // floor reconciliation could move the torso with whichever limb was lowest.
+    const deadBug = movement("dead-bug");
+    for (const id of ["pelvis", "chest"]) {
+      const heights = deadBug.phases.map((p) => p.bones.get(id)![1]);
+      expect(Math.max(...heights) - Math.min(...heights)).toBeLessThan(0.01);
+    }
   });
 });
 

packages/posecode-language/src/vocab.ts

@@ -22,7 +22,7 @@ export const KINDS = ["exercise", "stretch", "posture"];
 /** Recognised start poses (`pose start = ...`). */
 export const POSES = ["neutral", "standing", "plank", "supine", "prone", "seated"];
 
-/** Effectors that can be ground-locked. */
+/** Floor contacts that can be ground-locked. */
 export const EFFECTORS = [...GROUND_LOCK_EFFECTOR_NAMES];
 
 /** Reach/pin effectors (groups + per-side aliases), sourced from the parser. */
@@ -50,7 +50,7 @@ export const KEYWORD_DOCS: Record<string, string> = {
   snap: "Timing mode: fast, near-immediate arrival — an accent.",
   linear: "Timing mode: constant velocity — intentionally mechanical.",
   repeat: "How many times the movement loops.",
-  "ground-lock": "Pins grouped or per-side effectors to the floor: `feet`, `foot_left` (also written `left foot`), `hands`, or `forearms`. Planted feet auto-level unless the ankle is intentionally plantarflexed.",
+  "ground-lock": "Keeps grouped, per-side, or axial contacts on the floor: `feet`, `foot_left` (also `left foot`), `hands`, `forearms`, or `back` for supine work. Planted feet auto-level unless intentionally plantarflexed.",
   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).",

packages/posecode-language/test/language.test.ts

@@ -75,7 +75,15 @@ describe("getCompletions", () => {
 
   it("suggests effectors after `ground-lock: `", () => {
     expect(onLine("    ground-lock: ", 17)).toEqual(
-      expect.arrayContaining(["hands", "feet", "hand_left", "hand_right", "foot_left", "foot_right"]),
+      expect.arrayContaining([
+        "hands",
+        "feet",
+        "hand_left",
+        "hand_right",
+        "foot_left",
+        "foot_right",
+        "back",
+      ]),
     );
   });
 

packages/posecode-mcp/src/guide.ts

@@ -37,7 +37,7 @@ posecode <kind> "<Name>"          # kind = exercise | stretch | posture
   pose start = <pose>          # neutral | standing | plank
   step "<Phase>" <Ns> <mode>:  # mode = flow | settle | drive | snap | linear
     <joint>: <action> <degrees>
-    ground-lock: <effectors>   # feet/hands/forearms, or one side: foot_left / left foot
+    ground-lock: <contacts>    # feet/hands/forearms/back, or foot_left / left foot
     cue "<short coaching cue>"
   repeat <count>
 \`\`\`
@@ -47,4 +47,7 @@ wrists hips knees ankles. Actions (degrees are absolute targets): flex/extend,
 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.`;
+Stay within healthy range of motion; the renderer hard-clamps anything beyond.
+Use ground-lock: feet when standing, hands and feet in a high plank, forearms
+and feet in a forearm plank, and back for supine floor work such as a dead bug.
+Do not invent other contact names.`;

packages/posecode-parser/src/joints.ts

@@ -121,9 +121,10 @@ const EFFECTOR_GROUPS: Record<string, string[]> = {
 export const EFFECTOR_NAMES = [...Object.keys(EFFECTOR_GROUPS), ...EFFECTOR_SIDES];
 
 /**
- * Effectors accepted by `ground-lock:`. Ground locking has historically
+ * Contacts accepted by `ground-lock:`. Ground locking has historically
  * supported the symmetric hand/forearm/foot groups; per-side aliases let a
  * movement keep one support planted while the opposite limb moves freely.
+ * `back` is an axial surface contact for supine floor work.
  */
 export const GROUND_LOCK_EFFECTOR_NAMES = [
   "hands",
@@ -135,6 +136,7 @@ export const GROUND_LOCK_EFFECTOR_NAMES = [
   "feet",
   "foot_left",
   "foot_right",
+  "back",
 ] as const;
 
 const GROUND_LOCK_EFFECTOR_SET = new Set<string>(GROUND_LOCK_EFFECTOR_NAMES);

packages/posecode-parser/src/parser.ts

@@ -232,7 +232,7 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
   if (head === "ground-lock") {
     if (!current) return { line: ln.line, message: "`ground-lock` outside of a step" };
     if (t[1]?.type !== "colon") {
-      return { line: ln.line, message: "expected `ground-lock: <effectors>`" };
+      return { line: ln.line, message: "expected `ground-lock: <contacts>`" };
     }
     const words = t.slice(2).filter((tok) => tok.type === "word").map((tok) => tok.value);
     const effectors: string[] = [];
@@ -255,7 +255,7 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
       effectors.push(value);
     }
     if (effectors.length === 0) {
-      return { line: ln.line, message: "`ground-lock` requires at least one effector" };
+      return { line: ln.line, message: "`ground-lock` requires at least one contact" };
     }
     current.groundLock = effectors;
     current.groundLockLine = ln.line;

packages/posecode-parser/src/types.ts

@@ -67,7 +67,7 @@ export interface Phase {
   durationSec: number;
   easing: Easing;
   targets: JointTarget[];
-  /** Grouped or per-side floor effectors pinned for this phase, e.g. ["feet"] or ["foot_right"]. */
+  /** Grouped, per-side, or axial floor contacts held this phase, e.g. ["foot_right"] or ["back"]. */
   groundLock: string[];
   /** Reach-IK goals active during this phase. */
   reaches: ReachTarget[];

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

@@ -263,6 +263,29 @@ describe("reach/pin effectors", () => {
   });
 });
 
+describe("ground-lock contacts", () => {
+  it("accepts back as a supine floor contact", () => {
+    const result = parse(`posecode exercise "Dead bug"
+  rig humanoid
+  pose start = supine
+  step "Extend" 1s settle:
+    ground-lock: back`);
+    expect(result.errors).toEqual([]);
+    expect(result.ir?.phases[0]?.groundLock).toEqual(["back"]);
+  });
+
+  it("rejects unknown contacts instead of silently ignoring them", () => {
+    const result = parse(`posecode posture "Floor"
+  rig humanoid
+  step "Hold" 1s linear:
+    ground-lock: shoulders`);
+    expect(result.ir).toBeNull();
+    expect(result.errors).toEqual([
+      expect.objectContaining({ line: 4, message: expect.stringContaining("shoulders") }),
+    ]);
+  });
+});
+
 describe("clip directive", () => {
   const doc = (clipLine: string): string =>
     [

packages/posecode-render/src/groundlock.ts

@@ -3,8 +3,8 @@
  * render loop and the headless eval harness (posecode-eval) use the identical
  * solver.
  *
- * "Ground-lock" = keep the declared grouped or per-side effectors planted while the
- * body moves, tuned per support type:
+ * "Ground-lock" = keep the declared grouped, per-side, or axial contacts
+ * planted while the body moves, tuned per support type:
  *
  * - **Hands + feet (push-up / plank):** pivot the whole rigid body about the
  *   foot line (the toes stay planted) until the hands reach the floor. As the
@@ -23,6 +23,8 @@
  *   the heels). Only feet near the floor anchor (a swing leg in a curl or
  *   march must stay free), and only the average delta is corrected so
  *   symmetric spreads (jumping jacks) don't fight the lock.
+ * - **Back (dead bug / supine floor work):** translate the body vertically so
+ *   the pelvis-to-ribcage surface stays on the floor while the limbs move.
  *
  * Both paths ground the visible MESH (bounding boxes), not just bone origins:
  * an ankle bone sits ~0.04m above the sole, so anchoring bones alone left the
@@ -97,8 +99,14 @@ export function applyGroundLock(
   const hands = ids.filter((id) => id.startsWith("wrist"));
   const forearms = ids.filter((id) => id.startsWith("elbow"));
   const feet = ids.filter((id) => id.startsWith("ankle"));
+  const back = ids.filter((id) => id === "pelvis" || id === "spine" || id === "chest");
   const upperSupports = forearms.length > 0 ? forearms : hands;
 
+  if (back.length > 0) {
+    dropOwnMeshesToFloor(m, back);
+    return;
+  }
+
   if (upperSupports.length > 0 && feet.length > 0) {
     // Plant the feet FIRST: drop the body so the foot mesh rests on the floor,
     // so the pivot the body then rotates about is itself at floor level. The
@@ -146,6 +154,37 @@ export function applyGroundLock(
   }
 }
 
+/**
+ * Drop only the meshes owned by the selected bones onto the floor. `Box3` on
+ * a torso bone would include its child limbs, so an overhead arm could
+ * otherwise lift a supine person's back. Bone child subtrees are deliberately
+ * excluded; non-bone groups (capsules/ellipsoids) remain part of the surface.
+ */
+function dropOwnMeshesToFloor(m: Mannequin, boneIds: string[]): void {
+  const boneNodes = new Set(m.bones.values());
+  const box = new THREE.Box3();
+  const childBox = new THREE.Box3();
+  let found = false;
+
+  for (const id of boneIds) {
+    const bone = m.bones.get(id);
+    if (!bone) continue;
+    for (const child of bone.children) {
+      if (boneNodes.has(child)) continue;
+      childBox.setFromObject(child);
+      if (!childBox.isEmpty()) {
+        box.union(childBox);
+        found = true;
+      }
+    }
+  }
+
+  if (found && Number.isFinite(box.min.y)) {
+    m.root.position.y -= box.min.y;
+    m.root.updateMatrixWorld(true);
+  }
+}
+
 /**
  * Drop the whole body vertically so the lowest FOOT-mesh point rests on the
  * floor. Grounds the visible sole (bounding box), not the ankle bone, which

packages/posecode-render/src/index.ts

@@ -4,8 +4,9 @@
  * `createViewer(canvas)` sets up a Three.js studio scene with the procedural
  * mannequin and returns a controller. `load(ir)` builds a timeline from a parsed
  * PosecodeIR; the render loop applies forward kinematics each frame, then keeps
- * ground-locked contacts (hands/feet) planted via floating-root solving. The
- * camera auto-frames the figure and eases smoothly when a new movement loads.
+ * ground-locked contacts (hands/forearms/feet/back) planted via floating-root
+ * solving. The camera auto-frames the figure and eases smoothly when a new
+ * movement loads.
  */
 
 import * as THREE from "three";
@@ -1055,6 +1056,11 @@ function contactBoneIds(info: {
       ids.add("elbow_left");
       ids.add("elbow_right");
     }
+    if (effector === "back") {
+      ids.add("pelvis");
+      ids.add("spine");
+      ids.add("chest");
+    }
   };
   for (const group of info.groundLock) addEffector(group);
   for (const contact of [...info.grips, ...info.pins]) addEffector(contact.effector);