feat(parser): grip directive with two-point side-anchor resolution

Author: a-baran-orhan

packages/posecode-parser/src/clamp.ts

@@ -9,6 +9,7 @@
 
 import type {
   EulerDeg,
+  GripTarget,
   JointTarget,
   PosecodeIR,
   ParseError,
@@ -146,6 +147,21 @@ function resolveStep(
     for (const effector of sides) pins.push({ effector, anchor: p.anchor });
   }
 
+  // Grip contacts: like pins, but each hand gets its OWN two-point anchor. A
+  // bare anchor (`bar`) is rewritten per side to `bar_left`/`bar_right` so the
+  // two hands grip shoulder-width apart; an already-sided anchor is kept as-is.
+  const grips: GripTarget[] = [];
+  for (const g of step.grips) {
+    const sides = expandEffector(g.effector);
+    if (sides.length === 0) {
+      errors.push({ line: g.line, message: `unknown grip effector: "${g.effector}"` });
+      continue;
+    }
+    for (const effector of sides) {
+      grips.push({ effector, anchor: sideAnchor(g.anchor, effector) });
+    }
+  }
+
   // 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
@@ -163,6 +179,7 @@ function resolveStep(
     groundLock: step.groundLock,
     reaches,
     pins,
+    grips,
     ...(step.turn !== undefined ? { turnDeg: step.turn } : {}),
     ...(travel ? { travel } : {}),
     ...(step.cue ? { cue: step.cue } : {}),
@@ -176,6 +193,19 @@ function clampNum(v: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, v));
 }
 
+/**
+ * Rewrite a grip anchor to the effector's side: a bare anchor (`bar`) becomes
+ * `bar_left`/`bar_right` so two hands grip shoulder-width apart. An anchor that
+ * is already sided, or an effector without a side, is returned unchanged. The
+ * renderer falls back to the bare anchor if a sided one isn't declared.
+ */
+function sideAnchor(anchor: string, effector: string): string {
+  if (/_(left|right)$/.test(anchor)) return anchor;
+  if (effector.endsWith("_left")) return `${anchor}_left`;
+  if (effector.endsWith("_right")) return `${anchor}_right`;
+  return anchor;
+}
+
 function ensure(map: Map<string, EulerDeg>, bone: string): EulerDeg {
   let euler = map.get(bone);
   if (!euler) {

packages/posecode-parser/src/index.ts

@@ -39,6 +39,7 @@ export type {
   JointTarget,
   ReachTarget,
   PinTarget,
+  GripTarget,
   Phase,
   PosecodeIR,
   Warning,

packages/posecode-parser/src/parser.ts

@@ -37,6 +37,7 @@ export interface AstStep {
   groundLock: string[];
   reaches: AstReach[];
   pins: AstPin[];
+  grips: 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. */
@@ -182,6 +183,7 @@ export function parseToAst(source: string): ParseAstResult {
           groundLock: [],
           reaches: [],
           pins: [],
+          grips: [],
           line: ln.line,
         };
         doc.steps.push(current);
@@ -247,6 +249,20 @@ function parseStepChild(ln: Line, current: AstStep | null): ParseError | null {
     return null;
   }
 
+  if (head === "grip") {
+    // `grip: <effector> <anchor>`: hold a bar/rail — arm IK to a two-point
+    // anchor + finger wrap. Parsed exactly like `pin`; the side-anchor rewrite
+    // happens in resolution.
+    if (!current) return { line: ln.line, message: "`grip` outside of a step" };
+    const effector = t[2]?.type === "word" ? t[2].value : null;
+    const anchor = t[3]?.type === "word" ? t[3].value : null;
+    if (t[1]?.type !== "colon" || !effector || !anchor) {
+      return { line: ln.line, message: "expected `grip: <effector> <anchor>`" };
+    }
+    current.grips.push({ effector, anchor, line: ln.line });
+    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.

packages/posecode-parser/src/schema.ts

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

packages/posecode-parser/src/types.ts

@@ -49,6 +49,17 @@ export interface PinTarget {
   anchor: string;
 }
 
+/**
+ * A grip contact: a hand holds a bar/rail. Unlike a pin (which only translates
+ * the body to an anchor), a grip also bends the arm via IK so each hand lands on
+ * its own two-point anchor (`bar_left`/`bar_right`) and wraps the fingers around
+ * the bar. Powers pull-up, dead-hang, hanging knee raise.
+ */
+export interface GripTarget {
+  effector: string;
+  anchor: string;
+}
+
 /** One concurrent phase of a movement (e.g. "Lower" in a push-up). */
 export interface Phase {
   name: string;
@@ -61,6 +72,8 @@ export interface Phase {
   reaches: ReachTarget[];
   /** Contact pins active during this phase (translate the body to the anchor). */
   pins: PinTarget[];
+  /** Grip contacts active this phase (arm IK to a two-point bar anchor + finger wrap). */
+  grips: GripTarget[];
   /**
    * Root facing (yaw about world Y, degrees) at the end of this phase, an
    * absolute target carried forward across phases. Powers turns / pirouettes.

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

@@ -301,3 +301,48 @@ describe("timing modes", () => {
     expect(errors[0]!.message.toLowerCase()).toContain("mode");
   });
 });
+
+describe("grip directive", () => {
+  it("resolves `grip: hands bar` to two per-side grips with sided anchors", () => {
+    const src = [
+      'posecode exercise "Pull-up"',
+      "  rig humanoid",
+      "  prop bar",
+      "  pose start = standing",
+      '  step "Hang" 1s flow:',
+      "    grip: hands bar",
+    ].join("\n");
+    const { ir, errors } = parse(src);
+    expect(errors).toEqual([]);
+    expect(ir!.phases[0]!.grips).toEqual([
+      { effector: "hand_left", anchor: "bar_left" },
+      { effector: "hand_right", anchor: "bar_right" },
+    ]);
+  });
+
+  it("keeps a side-specific grip anchor verbatim", () => {
+    const src = [
+      'posecode exercise "One-arm"',
+      "  rig humanoid",
+      "  prop bar",
+      '  step "Hang" 1s flow:',
+      "    grip: hand_left bar_left",
+    ].join("\n");
+    const { ir, errors } = parse(src);
+    expect(errors).toEqual([]);
+    expect(ir!.phases[0]!.grips).toEqual([{ effector: "hand_left", anchor: "bar_left" }]);
+  });
+
+  it("errors on an unknown grip effector with its line", () => {
+    const src = [
+      'posecode exercise "Bad"',
+      "  rig humanoid",
+      '  step "Hang" 1s flow:',
+      "    grip: tentacle bar",
+    ].join("\n");
+    const { errors } = parse(src);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]!.line).toBe(4);
+    expect(errors[0]!.message).toContain("tentacle");
+  });
+});