Fix mobile viewer and hand orientation (#78)

Author: a-baran-orhan

.changeset/heroic-owls-land.md

@@ -4,4 +4,7 @@
 "posecode-mcp": patch
 ---
 
-Strengthen Posecode motion authoring and playback with strict contact validation, grounded multi-contact solving, continuous sparse transitions, and more lifelike canonical movement guidance.
+Strengthen Posecode motion authoring and playback with strict contact validation,
+grounded multi-contact solving, continuous sparse transitions, explicit forearm
+roll guidance, natural relaxed hands, a mobile-safe phase rail, and more lifelike
+canonical movements.

packages/posecode-eval/src/checks.ts

@@ -21,6 +21,9 @@ import {
   kneeFlexionDeg,
   lowestPoint,
   palmFloorAngleDeg,
+  palmForwardAngleDeg,
+  palmInwardAngleDeg,
+  palmUpAngleDeg,
   phaseMaxLandmarkSpeed,
   propPenetrationDepth,
   segmentTiltDeg,
@@ -535,6 +538,81 @@ export const MOVEMENT_CHECKS: MovementChecks[] = [
         (v) => v > 1.0,
         "wrist > 1.0m",
       ),
+      phaseCheck(
+        "left-palm-up",
+        "Curl",
+        (p) => palmUpAngleDeg(p, "left"),
+        (v) => v < 55,
+        "< 55° from palm-up at peak flexion",
+      ),
+      phaseCheck(
+        "right-palm-up",
+        "Curl",
+        (p) => palmUpAngleDeg(p, "right"),
+        (v) => v < 55,
+        "< 55° from palm-up at peak flexion",
+      ),
+      phaseCheck(
+        "left-palm-forward-at-bottom",
+        "Lower",
+        (p) => palmForwardAngleDeg(p, "left"),
+        (v) => v < 25,
+        "< 25° from forward",
+      ),
+      phaseCheck(
+        "right-palm-forward-at-bottom",
+        "Lower",
+        (p) => palmForwardAngleDeg(p, "right"),
+        (v) => v < 25,
+        "< 25° from forward",
+      ),
+    ],
+  },
+  {
+    movement: "jab-cross",
+    checks: [
+      phaseCheck(
+        "jab-palm-down",
+        "Jab",
+        (p) => palmFloorAngleDeg(p, "left"),
+        (v) => v < 35,
+        "< 35° from palm-down",
+      ),
+      phaseCheck(
+        "cross-palm-down",
+        "Cross",
+        (p) => palmFloorAngleDeg(p, "right"),
+        (v) => v < 35,
+        "< 35° from palm-down",
+      ),
+      phaseCheck(
+        "lead-guard-palm-in",
+        "Recoil cross",
+        (p) => palmInwardAngleDeg(p, "left"),
+        (v) => v < 20,
+        "< 20° from inward",
+      ),
+      phaseCheck(
+        "rear-guard-palm-in",
+        "Recoil cross",
+        (p) => palmInwardAngleDeg(p, "right"),
+        (v) => v < 20,
+        "< 20° from inward",
+      ),
+      phaseCheck(
+        "lead-guard-high",
+        "Recoil cross",
+        (p) => heightOf(p, "wrist_left"),
+        (v) => v > 1.45,
+        "> 1.45m",
+      ),
+      phaseCheck(
+        "rear-guard-high",
+        "Recoil cross",
+        (p) => heightOf(p, "wrist_right"),
+        (v) => v > 1.45,
+        "> 1.45m",
+      ),
     ],
   },
   {

packages/posecode-eval/src/index.ts

@@ -29,6 +29,9 @@ export {
   kneeFlexionDeg,
   lowestPoint,
   palmFloorAngleDeg,
+  palmForwardAngleDeg,
+  palmInwardAngleDeg,
+  palmUpAngleDeg,
   phaseMaxLandmarkSpeed,
   segmentTiltDeg,
   soleUpAngleDeg,

packages/posecode-eval/src/metrics.ts

@@ -107,6 +107,31 @@ export function palmFloorAngleDeg(pose: PhasePose, side: "left" | "right"): numb
   return angleBetweenDeg(rotateByQuat([0, 0, 1], q), [0, -1, 0]);
 }
 
+/** Angle between the palm face normal and world-up (0 = palm facing up). */
+export function palmUpAngleDeg(pose: PhasePose, side: "left" | "right"): number {
+  const q = pose.boneQuaternions.get(`wrist_${side}`);
+  if (!q) return 180;
+  return angleBetweenDeg(rotateByQuat([0, 0, 1], q), [0, 1, 0]);
+}
+
+/** Angle between the palm face normal and character-forward (+Z at zero yaw). */
+export function palmForwardAngleDeg(pose: PhasePose, side: "left" | "right"): number {
+  const q = pose.boneQuaternions.get(`wrist_${side}`);
+  if (!q) return 180;
+  const forward: Vec3 = [Math.sin(pose.rootYaw), 0, Math.cos(pose.rootYaw)];
+  return angleBetweenDeg(rotateByQuat([0, 0, 1], q), forward);
+}
+
+/** Angle between a palm and the body's lateral midline direction. */
+export function palmInwardAngleDeg(pose: PhasePose, side: "left" | "right"): number {
+  const q = pose.boneQuaternions.get(`wrist_${side}`);
+  if (!q) return 180;
+  const inward = side === "left"
+    ? sub(bone(pose, "shoulder_right"), bone(pose, "shoulder_left"))
+    : sub(bone(pose, "shoulder_left"), bone(pose, "shoulder_right"));
+  return angleBetweenDeg(rotateByQuat([0, 0, 1], q), inward);
+}
+
 /** Angle between the semantic fist's knuckle direction and floor-down. */
 export function fistFloorAngleDeg(pose: PhasePose, side: "left" | "right"): number {
   const q = pose.boneQuaternions.get(`wrist_${side}`);

packages/posecode-language/src/hover.ts

@@ -57,12 +57,13 @@ export function getHover(
     if (bone && token !== "hold") {
       const rom = romFor(bone, token);
       if (rom) {
+        const detail = KEYWORD_DOCS[token];
         return md(
-          `**${boneType(bone)} · ${token}**: configured range **${rom.min}–${rom.max}°**. Angles beyond this are clamped with a diagnostic.`,
+          `**${boneType(bone)} · ${token}**: configured range **${rom.min}–${rom.max}°**. Angles beyond this are clamped with a diagnostic.${detail ? ` ${detail}` : ""}`,
         );
       }
     }
-    return md(`Action **${token}**.`);
+    return md(`Action **${token}**.${KEYWORD_DOCS[token] ? ` ${KEYWORD_DOCS[token]}` : ""}`);
   }
 
   if (JOINT_NAMES.includes(token)) {

packages/posecode-language/src/vocab.ts

@@ -74,4 +74,6 @@ export const KEYWORD_DOCS: Record<string, string> = {
   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: "Reset every rotation channel on this joint to its neutral / rest angle: `<joint>: hold neutral`.",
+  pronate: "Rolls the forearm toward palm-down. With upright arms at the sides, about 80° faces the palm inward toward the thigh; final world facing also depends on the arm pose.",
+  supinate: "Rolls the forearm in the palm-up direction; final world facing also depends on the shoulder and elbow pose.",
 };

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

@@ -59,7 +59,7 @@ describe("getCompletions", () => {
 
   it("suggests joints (and child keywords) at the start of an indented line", () => {
     const l = onLine("    ", 4);
-    expect(l).toEqual(expect.arrayContaining(["knees", "elbows"]));
+    expect(l).toEqual(expect.arrayContaining(["knees", "elbows", "forearms"]));
     expect(l).toContain("cue");
   });
 
@@ -87,6 +87,15 @@ describe("getCompletions", () => {
     expect(chestActions).not.toContain("rotate-out");
   });
 
+  it("offers and explains anatomical forearm rotation", () => {
+    expect(onLine("    forearms: ", 14)).toEqual(
+      expect.arrayContaining(["pronate", "supinate"]),
+    );
+    const line = "    forearms: pronate 80";
+    const hover = getHover(line, 0, line.indexOf("pronate") + 1);
+    expect(hover?.contents).toContain("thigh");
+  });
+
   it("suggests timing modes inside a step header", () => {
     expect(onLine('  step "y" 2s ', 14)).toEqual(
       expect.arrayContaining(["flow", "settle", "linear"]),

packages/posecode-mcp/src/guide.ts

@@ -60,9 +60,13 @@ posecode <kind> "<Name>"          # kind = exercise | stretch | posture
 \`\`\`
 
 Joints: neck head spine chest pelvis, and (singular or plural) shoulders elbows
-wrists hips knees ankles. Actions (degrees are absolute targets): flex/extend,
+forearms wrists hips knees ankles. \`forearms\` aliases the elbow bones for palm
+roll. Actions (degrees are absolute targets): flex/extend,
 abduct/adduct, rotate-in/rotate-out (shoulder/hip), twist-left/twist-right
-(axial joints), dorsiflex/plantarflex, hold neutral, and hinge (pelvis only).
+(axial joints), supinate/pronate (forearm roll), dorsiflex/plantarflex, hold
+neutral, and hinge (pelvis only). With upright arms at the sides,
+\`forearms: pronate 80\` faces the palms inward toward the thighs.
+At zero degrees, \`pronate 0\` and \`supinate 0\` are the same absolute target.
 Use only joint/action pairs and declared prop anchors accepted by the validator.
 Author the gross pose before reach; a parsed reach is not proof of contact.
 Keep cues, sides, and declared contacts consistent through every phase. Floor

packages/posecode-parser/src/joints.ts

@@ -70,6 +70,9 @@ const FINGERS_RIGHT: BoneId[] = [
 const GROUPS: Record<string, BoneId[]> = {
   shoulders: ["shoulder_left", "shoulder_right"],
   elbows: ["elbow_left", "elbow_right"],
+  // Anatomical authoring alias: forearm axial rotation lives on the elbow
+  // bone in the rig, but `forearms: pronate 80` is clearer to authors.
+  forearms: ["elbow_left", "elbow_right"],
   wrists: ["wrist_left", "wrist_right"],
   hips: ["hip_left", "hip_right"],
   knees: ["knee_left", "knee_right"],
@@ -196,8 +199,10 @@ const ACTIONS: Record<string, ActionAxis> = {
   // toward the person's left (+X), and -Y turns it right (-X).
   "twist-left": { axis: "y", sign: 1 },
   "twist-right": { axis: "y", sign: -1 },
-  supinate: { axis: "y", sign: 1 },
-  pronate: { axis: "y", sign: -1 },
+  // From the palm-forward driver rest, pronation turns each palm toward its
+  // own thigh. The left-side mirror in clamp.ts supplies the opposite sign.
+  supinate: { axis: "y", sign: -1 },
+  pronate: { axis: "y", sign: 1 },
   // The foot points FORWARD (+Z): lifting the toes toward the shin
   // (dorsiflexion) is a -X rotation, pointing them is +X.
   dorsiflex: { axis: "x", sign: -1 },

packages/posecode-parser/src/types.ts

@@ -47,9 +47,10 @@ export interface ReachTarget {
 
 /**
  * A contact pin: translate the whole figure so `effector` sits on a fixed
- * `anchor` (a prop anchor, a landmark, or `floor`). Unlike a reach (which moves
- * the limb to a target) a pin moves the BODY, so the figure can hang from a bar,
- * rise onto a box, or lower into a dip while the contact stays put.
+ * world `anchor` (a declared prop anchor or `floor`). Unlike a reach (which
+ * moves the limb to a target) a pin moves the BODY, so a body landmark cannot
+ * serve as its anchor: that landmark would move with the same root. Pins let the
+ * figure hang from a bar, rise onto a box, or keep one floor support fixed.
  */
 export interface PinTarget {
   effector: string;