feat(render): relaxed resting hand pose (L4.1 secondary motion)

Author: a-baran-orhan

packages/posecode-render/src/contacts.ts

@@ -137,3 +137,42 @@ export function wrapGrip(m: Mannequin, grips: readonly GripTarget[]): void {
   }
   if (changed) m.root.updateMatrixWorld(true);
 }
+
+/** Relaxed resting finger curl (radians) for an idle hand. */
+export const REST_CURL = 0.32;
+
+/**
+ * Give idle hands a natural relaxed curl instead of a flat splayed palm. Applied
+ * every frame to any hand that is NOT gripping this phase (those are wrapped by
+ * `wrapGrip`) and whose fingers are NOT explicitly authored (make-a-fist,
+ * finger-spell, hand-wave keep their pose). A mesh-only-style aliveness layer:
+ * it writes only finger-bone locals, so it can never disturb the solved pose.
+ */
+export function relaxHands(
+  m: Mannequin,
+  gripSides: ReadonlySet<"left" | "right">,
+  authoredFingers: ReadonlySet<string>,
+): void {
+  let changed = false;
+  for (const side of ["left", "right"] as const) {
+    if (gripSides.has(side)) continue;
+    for (const f of FINGERS) {
+      const id = `${f}_${side}`;
+      if (authoredFingers.has(id)) continue;
+      const bone = m.bones.get(id);
+      if (bone) {
+        bone.rotation.set(REST_CURL, 0, 0);
+        changed = true;
+      }
+    }
+    const thumbId = `thumb_${side}`;
+    if (!authoredFingers.has(thumbId)) {
+      const thumb = m.bones.get(thumbId);
+      if (thumb) {
+        thumb.rotation.set(REST_CURL * 0.6, 0, side === "left" ? -REST_CURL : REST_CURL);
+        changed = true;
+      }
+    }
+  }
+  if (changed) m.root.updateMatrixWorld(true);
+}

packages/posecode-render/src/index.ts

@@ -27,7 +27,7 @@ import {
   type ClipSource,
 } from "./clips.js";
 import { depenetrate } from "./depenetrate.js";
-import { alignFloorPalms, levelPlantedFeet, wrapGrip } from "./contacts.js";
+import { alignFloorPalms, levelPlantedFeet, wrapGrip, relaxHands } from "./contacts.js";
 
 const DEG = Math.PI / 180;
 
@@ -267,6 +267,9 @@ export function createViewer(
   }
 
   let timeline: BuiltTimeline | null = null;
+  // Finger bones the loaded document explicitly poses (make-a-fist, finger-spell,
+  // hand-wave): the L4.1 resting-hand curl leaves these alone.
+  let authoredFingers = new Set<string>();
   // The last loaded document, kept so the viewer can re-solve base pose and
   // ground anchors when the character (with its own proportions) arrives.
   let lastIR: PosecodeIR | null = null;
@@ -593,6 +596,8 @@ export function createViewer(
       // lower-body poses (squat, lunge, deadlift) don't balance on the toes.
       // Runs before the floor clamp so the leveled sole is what rests on y=0.
       levelPlantedFeet(mannequin, info.groundLock);
+      // L4.1 aliveness: relax idle hands into a natural curl (grips still wrap).
+      relaxHands(mannequin, gripSidesOf(info.grips), authoredFingers);
       // Safety net: nothing above ever intentionally pushes part of the body
       // below the floor, so clamp the root up whenever the lowest point dips
       // below y=0, a no-op whenever the pose is legitimately grounded or
@@ -691,6 +696,8 @@ export function createViewer(
       depenetrate(mannequin);
       groundFigureOf(mannequin);
       levelPlantedFeet(mannequin, ir.phases[0]?.groundLock ?? []);
+      authoredFingers = new Set(timeline.bonesUsed.filter(isFingerId));
+      relaxHands(mannequin, gripSidesOf(ir.phases[0]?.grips ?? []), authoredFingers);
       captureGroundTargets();
       baseRootPos.copy(mannequin.root.position);
       baseRootQuat.copy(mannequin.root.quaternion);
@@ -797,6 +804,21 @@ export function createViewer(
   return api;
 }
 
+/** True for a finger bone id (thumb/index/middle/ring/pinky_left|right). */
+function isFingerId(id: string): boolean {
+  return /^(thumb|index|middle|ring|pinky)_/.test(id);
+}
+
+/** The hand sides ("left"/"right") gripping this phase, from its grip targets. */
+function gripSidesOf(grips: readonly { effector: string }[]): Set<"left" | "right"> {
+  const sides = new Set<"left" | "right">();
+  for (const g of grips) {
+    if (g.effector.endsWith("_left") || g.effector === "hands") sides.add("left");
+    if (g.effector.endsWith("_right") || g.effector === "hands") sides.add("right");
+  }
+  return sides;
+}
+
 function enableShadows(root: THREE.Object3D): void {
   root.traverse((obj) => {
     if ((obj as THREE.Mesh).isMesh) {

packages/posecode-render/test/contacts.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import * as THREE from "three";
 import { buildMannequin } from "../src/mannequin.js";
-import { levelPlantedFeet } from "../src/contacts.js";
+import { levelPlantedFeet, relaxHands } from "../src/contacts.js";
 import { groundFigure } from "../src/groundlock.js";
 
 const DEG = Math.PI / 180;
@@ -51,3 +51,27 @@ describe("levelPlantedFeet", () => {
     expect(m.bones.get("ankle_left")!.quaternion.angleTo(before)).toBeLessThan(1e-3);
   });
 });
+
+describe("relaxHands (L4.1)", () => {
+  it("curls the fingers of an idle, un-authored hand into a natural rest", () => {
+    const m = buildMannequin();
+    expect(m.bones.get("index_left")!.rotation.x).toBeCloseTo(0, 5); // flat at rest
+    relaxHands(m, new Set(), new Set());
+    expect(m.bones.get("index_left")!.rotation.x).toBeGreaterThan(0.1);
+    expect(m.bones.get("middle_right")!.rotation.x).toBeGreaterThan(0.1);
+  });
+
+  it("leaves a gripping hand for wrapGrip (skips grip sides)", () => {
+    const m = buildMannequin();
+    relaxHands(m, new Set(["left"]), new Set());
+    expect(m.bones.get("index_left")!.rotation.x).toBeCloseTo(0, 5); // untouched
+    expect(m.bones.get("index_right")!.rotation.x).toBeGreaterThan(0.1); // right relaxed
+  });
+
+  it("does not override an explicitly authored finger", () => {
+    const m = buildMannequin();
+    m.bones.get("index_left")!.rotation.x = 1.4; // authored fist
+    relaxHands(m, new Set(), new Set(["index_left"]));
+    expect(m.bones.get("index_left")!.rotation.x).toBeCloseTo(1.4, 5);
+  });
+});