Support single-foot ground locking

Author: a-baran-orhan

packages/posecode-eval/src/metrics.ts

@@ -324,8 +324,10 @@ export function feetCenterSkateDistance(previous: PhasePose, pose: PhasePose): n
 }
 
 export function footIsSupported(pose: PhasePose, side: "left" | "right"): boolean {
-  return pose.groundLock.includes("feet") || pose.pins.some((p) =>
-    (p.effector === "feet" || p.effector === `foot_${side}`) && p.anchor === "floor");
+  return pose.groundLock.includes("feet")
+    || pose.groundLock.includes(`foot_${side}`)
+    || pose.pins.some((p) =>
+      (p.effector === "feet" || p.effector === `foot_${side}`) && p.anchor === "floor");
 }
 
 /** Lowest bone height in the pose (should never be much below 0). */

packages/posecode-language/src/vocab.ts

@@ -11,6 +11,7 @@ import {
   MODES,
   LEGACY_MODE_ALIASES,
   EFFECTOR_NAMES,
+  GROUND_LOCK_EFFECTOR_NAMES,
 } from "posecode-parser";
 
 export { JOINT_NAMES, ACTION_NAMES, EASINGS, MODES, LEGACY_MODE_ALIASES };
@@ -22,7 +23,7 @@ export const KINDS = ["exercise", "stretch", "posture"];
 export const POSES = ["neutral", "standing", "plank", "supine", "prone", "seated"];
 
 /** Effectors that can be ground-locked. */
-export const EFFECTORS = ["hands", "feet"];
+export const EFFECTORS = [...GROUND_LOCK_EFFECTOR_NAMES];
 
 /** Reach/pin effectors (groups + per-side aliases), sourced from the parser. */
 export const REACH_EFFECTORS = EFFECTOR_NAMES;
@@ -49,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 effectors (hands / feet) to the floor for this phase. Planted feet auto-level flat to the floor unless the ankle is plantarflexed (tiptoe).",
+  "ground-lock": "Pins grouped or per-side effectors to the floor for this phase: `ground-lock: feet`, `ground-lock: foot_right`. Planted feet auto-level flat unless the ankle is plantarflexed (tiptoe).",
   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,7 @@ describe("getCompletions", () => {
 
   it("suggests effectors after `ground-lock: `", () => {
     expect(onLine("    ground-lock: ", 17)).toEqual(
-      expect.arrayContaining(["hands", "feet"]),
+      expect.arrayContaining(["hands", "feet", "hand_left", "foot_right"]),
     );
   });
 

packages/posecode-parser/src/clamp.ts

@@ -26,6 +26,7 @@ import {
   expandEffector,
   expandJoint,
   flexionSign,
+  isGroundLockEffector,
   isLeft,
 } from "./joints.js";
 import { clampAngle, romFor } from "./rom.js";
@@ -125,6 +126,18 @@ function resolveStep(
     euler,
   }));
 
+  const groundLock: string[] = [];
+  for (const effector of step.groundLock) {
+    if (!isGroundLockEffector(effector)) {
+      errors.push({
+        line: step.groundLockLine ?? step.line,
+        message: `unknown ground-lock effector: "${effector}"`,
+      });
+      continue;
+    }
+    groundLock.push(effector);
+  }
+
   // Reach / pin effectors: expand symmetric groups (`hands` → both hands) and
   // reject unknown names, since a typo'd effector would otherwise be silently
   // ignored by the renderer, invisible to the authoring LLM.
@@ -176,7 +189,7 @@ function resolveStep(
     durationSec: step.durationSec,
     easing: step.easing as Phase["easing"],
     targets,
-    groundLock: step.groundLock,
+    groundLock,
     reaches,
     pins,
     grips,

packages/posecode-parser/src/index.ts

@@ -53,8 +53,10 @@ export {
   JOINT_NAMES,
   ACTION_NAMES,
   EFFECTOR_NAMES,
+  GROUND_LOCK_EFFECTOR_NAMES,
   expandJoint,
   expandEffector,
+  isGroundLockEffector,
   actionAxis,
   boneType,
 } from "./joints.js";

packages/posecode-parser/src/joints.ts

@@ -120,6 +120,30 @@ const EFFECTOR_GROUPS: Record<string, string[]> = {
 /** Every effector name `reach:` / `pin:` accept: groups + per-side aliases. */
 export const EFFECTOR_NAMES = [...Object.keys(EFFECTOR_GROUPS), ...EFFECTOR_SIDES];
 
+/**
+ * Effectors 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.
+ */
+export const GROUND_LOCK_EFFECTOR_NAMES = [
+  "hands",
+  "hand_left",
+  "hand_right",
+  "forearms",
+  "elbow_left",
+  "elbow_right",
+  "feet",
+  "foot_left",
+  "foot_right",
+] as const;
+
+const GROUND_LOCK_EFFECTOR_SET = new Set<string>(GROUND_LOCK_EFFECTOR_NAMES);
+
+/** True when an effector is implemented by the ground-lock solver. */
+export function isGroundLockEffector(name: string): boolean {
+  return GROUND_LOCK_EFFECTOR_SET.has(name);
+}
+
 const EFFECTOR_SIDE_SET = new Set<string>(EFFECTOR_SIDES);
 
 /**

packages/posecode-parser/src/parser.ts

@@ -35,6 +35,8 @@ export interface AstStep {
   easing: string;
   targets: AstJointTarget[];
   groundLock: string[];
+  /** Source line of the active `ground-lock:` declaration. */
+  groundLockLine?: number;
   reaches: AstReach[];
   pins: AstPin[];
   grips: AstPin[];
@@ -222,6 +224,7 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
       .filter((tok) => tok.type === "word")
       .map((tok) => tok.value);
     current.groundLock = effectors;
+    current.groundLockLine = ln.line;
     return null;
   }
 

packages/posecode-parser/src/schema.ts

@@ -60,6 +60,7 @@ const stepSchema = z.object({
   easing: z.enum(MODES),
   targets: z.array(jointTargetSchema),
   groundLock: z.array(z.string()),
+  groundLockLine: z.number().optional(),
   reaches: z.array(reachSchema),
   pins: z.array(pinSchema),
   grips: z.array(pinSchema),

packages/posecode-parser/src/types.ts

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

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

@@ -97,6 +97,34 @@ describe("parse", () => {
     expect(errors[0]!.message).toMatch(/unknown joint/i);
   });
 
+  it("accepts per-side ground-lock effectors", () => {
+    const src = [
+      'posecode exercise "Single-leg pivot"',
+      "  rig humanoid",
+      '  step "Turn" 1s linear:',
+      "    turn: 180",
+      "    ground-lock: foot_right",
+    ].join("\n");
+    const { ir, errors } = parse(src);
+    expect(errors).toEqual([]);
+    expect(ir!.phases[0]!.groundLock).toEqual(["foot_right"]);
+  });
+
+  it("reports a line-anchored error for an unsupported ground-lock effector", () => {
+    const src = [
+      'posecode exercise "Typo"',
+      "  rig humanoid",
+      '  step "Turn" 1s linear:',
+      "    turn: 180",
+      "    ground-lock: shoe_right",
+    ].join("\n");
+    const { ir, errors } = parse(src);
+    expect(ir).toBeNull();
+    expect(errors).toEqual([
+      { line: 5, message: 'unknown ground-lock effector: "shoe_right"' },
+    ]);
+  });
+
   it("reports an error when a step child has no enclosing step", () => {
     const src = [
       'posecode exercise "Orphan"',