Merge branch 'main' into codex/fix-hand-grip-animation

Author: a-baran-orhan

packages/posecode-eval/src/checks.ts

@@ -90,6 +90,18 @@ export function genericChecks(result: ProbeResult): CheckOutcome[] {
       detail: `lowest bone ${lowestPoint(p).toFixed(3)}m (want > -0.05)`,
     });
 
+    // A ground-locked phase declares its effectors planted, so the visible mesh
+    // must actually rest on the floor — not hover above it. Guards the
+    // levitating-squat/deadlift regression where levelPlantedFeet lifted the
+    // sole after ground-lock and an up-only clamp left the whole figure floating.
+    if (p.groundLock.length > 0) {
+      out.push({
+        id: `grounded-not-floating:${p.name}`,
+        pass: p.meshMinY < 0.02,
+        detail: `mesh floats ${p.meshMinY.toFixed(3)}m above floor (want < 0.020)`,
+      });
+    }
+
     const floorHands = new Set<string>();
     for (const r of p.reaches) {
       if (r.target !== "floor") continue;

packages/posecode-eval/src/probe.ts

@@ -22,6 +22,7 @@ import {
   buildTimeline,
   depenetrate,
   groundFigure,
+  levelPlantedFeet,
 } from "posecode-render";
 
 export type Vec3 = readonly [x: number, y: number, z: number];
@@ -40,6 +41,12 @@ export interface PhasePose {
   rootYaw: number;
   /** True when the phase relies on pins/reach-IK the probe cannot solve. */
   usesSceneIk: boolean;
+  /**
+   * Height of the lowest visible-mesh point above the floor after the full
+   * contact solve. ~0 for a grounded pose; a positive value means the figure
+   * floats (the bug that levelPlantedFeet used to cause on squat/deadlift).
+   */
+  meshMinY: number;
   /** World-space position of every bone at the END of this phase. */
   bones: ReadonlyMap<string, Vec3>;
   /** World-space orientation of every bone at the end of the phase. */
@@ -160,13 +167,20 @@ export function probeMovement(source: string): ProbeResult {
       }
     }
     alignFloorPalms(m, info.reaches, info.pins);
-    // Viewer safety net: never leave the lowest mesh point below the floor.
+    // Plantigrade correction (viewer parity): flatten planted soles. This lifts
+    // the foot mesh a little, so it must run BEFORE the floor clamp reconciles.
+    levelPlantedFeet(m, info.groundLock);
+    // Viewer safety net: a ground-locked phase is planted, so clamp both ways
+    // (its lowest point sits exactly on the floor); an unlocked phase may be
+    // airborne, so only rescue parts that dip below y=0. Mirror index.ts.
     m.root.updateMatrixWorld(true);
     const box = new THREE.Box3().setFromObject(m.root);
-    if (box.min.y < 0) {
+    const planted = info.groundLock.length > 0;
+    if (box.min.y < 0 || (planted && box.min.y > 0)) {
       m.root.position.y -= box.min.y;
       m.root.updateMatrixWorld(true);
     }
+    const finalBox = new THREE.Box3().setFromObject(m.root);
     return {
       name: seg.name,
       durationSec: authored.durationSec,
@@ -177,6 +191,7 @@ export function probeMovement(source: string): ProbeResult {
       rootOffset: [info.rootOffset.x, 0, info.rootOffset.z],
       rootYaw: info.rootYaw,
       usesSceneIk: info.pins.length > 0 || info.reaches.length > 0 || info.grips.length > 0,
+      meshMinY: Number.isFinite(finalBox.min.y) ? finalBox.min.y : 0,
       bones: snapshotBones(m.bones),
       boneQuaternions: snapshotBoneQuaternions(m.bones),
     };

packages/posecode-render/src/contacts.ts

@@ -138,38 +138,68 @@ 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;
+/**
+ * Relaxed resting finger curl (radians) for an idle hand in the air. A truly
+ * relaxed hand is not flat: the fingers settle into a soft inward hook (~30°),
+ * which reads as a natural cupped hand instead of a stiff splayed palm.
+ */
+export const REST_CURL = 0.55;
+/** Slight finger adduction (radians) drawing splayed digits toward the middle
+ * finger, so a relaxed hand closes softly rather than fanning like jazz-hands. */
+export const REST_ADDUCT = 0.12;
+/**
+ * Near-flat curl (radians) for a hand pressed onto the floor (plank, push-up,
+ * cobra). The palm lies flat with the fingers extended forward; the resting
+ * inward hook would instead claw the fingertips into the ground.
+ */
+export const FLOOR_CURL = 0.06;
 
 /**
- * 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.
+ * Give idle hands a natural relaxed shape 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).
+ *
+ * Two resting shapes by context:
+ * - **Free hand** (arms swinging, a crunch, hands by the hips): a soft inward
+ *   hook with the fingers drawn slightly together — a relaxed cupped hand.
+ * - **Floor-planted hand** (`reach`/`pin: hands floor`): fingers stay extended
+ *   and flat so the palm rests on the ground instead of clawing into it.
+ *
+ * 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>,
+  floorSides: ReadonlySet<"left" | "right"> = new Set(),
 ): void {
   let changed = false;
   for (const side of ["left", "right"] as const) {
     if (gripSides.has(side)) continue;
+    const planted = floorSides.has(side);
+    const curl = planted ? FLOOR_CURL : REST_CURL;
+    // Adduction sign: fingers on each hand draw toward the middle, i.e. toward
+    // the thumb side, which is +Z on the left hand and -Z on the right.
+    const adduct = planted ? 0 : side === "left" ? REST_ADDUCT : -REST_ADDUCT;
     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);
+        bone.rotation.set(curl, 0, adduct);
         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);
+        // Planted: thumb lies alongside the flat palm. Free: opposes softly.
+        const thumbCurl = planted ? FLOOR_CURL : REST_CURL * 0.6;
+        const thumbOppose = planted ? 0 : REST_CURL;
+        thumb.rotation.set(thumbCurl, 0, side === "left" ? -thumbOppose : thumbOppose);
         changed = true;
       }
     }

packages/posecode-render/src/index.ts

@@ -93,9 +93,12 @@ export interface ViewerOptions {
   clips?: Record<string, string>;
   /**
    * Keep the procedural figure visible while a skinned `characterUrl` loads.
-   * This viewer always shows the procedural figure during load (and on load
-   * failure), so the flag is accepted for API compatibility; the default
-   * behavior already matches `true`.
+   * Defaults to `true` (the procedural figure poses the scene during the load,
+   * matching callers that never set this). Set `false` alongside a
+   * `characterUrl` to hide the procedural meshes until the character resolves —
+   * so a page load shows the skinned figure or nothing, never a blink of the
+   * crude procedural figure. On load failure the procedural figure is revealed
+   * regardless, so the scene never stays blank.
    */
   showProceduralWhileLoading?: boolean;
 }
@@ -182,10 +185,20 @@ export function createViewer(
   enableShadows(mannequin.root);
   scene.add(mannequin.root);
 
+  // When a skinned character is requested and the caller opted out of the
+  // procedural fallback during load, hide the procedural meshes up front so the
+  // crude figure never flashes for the character's fetch time on a page load.
+  // The skeleton still drives animation and grounding; only the meshes hide
+  // (same as the post-load swap). Revealed again if the character fails to load.
+  const deferProceduralMeshes =
+    Boolean(opts.characterUrl) && opts.showProceduralWhileLoading === false;
+  if (deferProceduralMeshes) setMeshVisibility(mannequin.root, false);
+
   // Skinned character layer (optional). While loading (and on failure) the
-  // procedural figure stays; once ready, the driver skeleton is rebuilt with
-  // the character's proportions, its meshes are hidden (they keep feeding the
-  // bounding-box grounding), and the character mirrors it every frame.
+  // procedural figure stays — unless deferred above; once ready, the driver
+  // skeleton is rebuilt with the character's proportions, its meshes are hidden
+  // (they keep feeding the bounding-box grounding), and the character mirrors it
+  // every frame.
   let character: Character | null = null;
 
   // Mocap-clip layer (optional, character-only). When the loaded document
@@ -637,21 +650,33 @@ export function createViewer(
       // L4.2 aliveness: contralateral arm swing during locomotion (free arms only).
       swingArms(mannequin, authoredShoulders, gripSidesOf(info.grips));
       // L4.1 aliveness: relax idle hands into a natural curl (grips still wrap).
-      relaxHands(mannequin, gripSidesOf(info.grips), authoredFingers);
+      relaxHands(
+        mannequin,
+        gripSidesOf(info.grips),
+        authoredFingers,
+        floorHandSidesOf(info.reaches, info.pins),
+      );
       // L4.3 aliveness: turn the head toward the active contact (bar / floor reach).
       applyLookAt(info);
-      // 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
-      // elevated (bbox min already ≥ 0). This also catches phases with
-      // neither ground-lock nor a pin (the root stays frozen at the base
-      // pose's grounded height while FK animates freely on top of it, e.g. a
-      // prone "superman" lift), and pinned phases where a fixed-height anchor
-      // (a low chair seat) combined with static leg FK can otherwise let the
-      // feet sink through the floor as the arms fold (e.g. a chair dip).
+      // Safety net: reconcile the fully-solved pose with the floor.
+      //
+      // A ground-locked phase asserts its effectors (feet, and for a plank the
+      // forearms) are PLANTED, so its lowest mesh point must sit exactly on the
+      // floor — clamp the root BOTH ways. This is essential because
+      // levelPlantedFeet() rotates the ankle flat AFTER ground-lock dropped the
+      // body, which lifts the sole a couple centimetres; an up-only clamp could
+      // never recover it and the whole figure floated (squat, deadlift,
+      // good-morning, forward-fold, plank, …).
+      //
+      // A phase with NO ground-lock may be intentionally airborne (a prone
+      // "superman" lift, a jump), so it stays up-only: never yank a lifted body
+      // down, only rescue parts that dip below y=0. Pinned phases with a
+      // fixed-height anchor (a low chair seat) also rely on this up-only rescue
+      // as the legs fold.
       mannequin.root.updateMatrixWorld(true);
       const box = new THREE.Box3().setFromObject(mannequin.root);
-      if (box.min.y < 0) {
+      const planted = info.groundLock.length > 0;
+      if (box.min.y < 0 || (planted && box.min.y > 0)) {
         mannequin.root.position.y -= box.min.y;
         mannequin.root.updateMatrixWorld(true);
       }
@@ -742,7 +767,12 @@ export function createViewer(
       authoredShoulders = new Set(timeline.bonesUsed.filter((id) => id.startsWith("shoulder_")));
       authoredHead = timeline.bonesUsed.some((id) => id === "head" || id === "neck");
       swingArms(mannequin, authoredShoulders, gripSidesOf(ir.phases[0]?.grips ?? []));
-      relaxHands(mannequin, gripSidesOf(ir.phases[0]?.grips ?? []), authoredFingers);
+      relaxHands(
+        mannequin,
+        gripSidesOf(ir.phases[0]?.grips ?? []),
+        authoredFingers,
+        floorHandSidesOf(ir.phases[0]?.reaches ?? [], ir.phases[0]?.pins ?? []),
+      );
       applyLookAt({ grips: ir.phases[0]?.grips ?? [], reaches: ir.phases[0]?.reaches ?? [] });
       captureGroundTargets();
       baseRootPos.copy(mannequin.root.position);
@@ -828,9 +858,7 @@ export function createViewer(
         scene.remove(mannequin.root);
         disposeTree(mannequin.root);
         mannequin = buildMannequin(undefined, char.proportions);
-        mannequin.root.traverse((obj) => {
-          if ((obj as THREE.Mesh).isMesh) obj.visible = false;
-        });
+        setMeshVisibility(mannequin.root, false);
         scene.add(mannequin.root);
         scene.add(char.group);
         character = char;
@@ -842,14 +870,27 @@ export function createViewer(
         else char.sync(mannequin);
       })
       .catch(() => {
-        // Keep the procedural figure. Deliberately silent: an offline embed
-        // or a blocked CDN should degrade, not error.
+        // Character failed (offline embed, blocked/404 CDN): reveal the
+        // procedural figure we may have hidden, so the scene degrades to the
+        // working fallback instead of staying blank. Deliberately silent.
+        if (deferProceduralMeshes) setMeshVisibility(mannequin.root, true);
       });
   }
 
   return api;
 }
 
+/**
+ * Show or hide a figure's meshes. The skeleton keeps driving animation and
+ * bounding-box grounding regardless, so hiding only the meshes lets a hidden
+ * procedural figure still pose the scene while its character stand-in loads.
+ */
+function setMeshVisibility(root: THREE.Object3D, visible: boolean): void {
+  root.traverse((obj) => {
+    if ((obj as THREE.Mesh).isMesh) obj.visible = visible;
+  });
+}
+
 /** 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);
@@ -865,6 +906,25 @@ function gripSidesOf(grips: readonly { effector: string }[]): Set<"left" | "righ
   return sides;
 }
 
+/**
+ * Hand sides pressed onto the floor this phase (a `reach`/`pin: hands floor`).
+ * Their fingers rest flat instead of taking the idle inward hook, so a plank or
+ * push-up hand lies on the ground rather than clawing into it.
+ */
+function floorHandSidesOf(
+  reaches: readonly { effector: string; target: string }[],
+  pins: readonly { effector: string; anchor: string }[],
+): Set<"left" | "right"> {
+  const sides = new Set<"left" | "right">();
+  const add = (effector: string): void => {
+    if (effector.endsWith("_left") || effector === "hands") sides.add("left");
+    if (effector.endsWith("_right") || effector === "hands") sides.add("right");
+  };
+  for (const r of reaches) if (r.target === "floor") add(r.effector);
+  for (const p of pins) if (p.anchor === "floor") add(p.effector);
+  return sides;
+}
+
 function enableShadows(root: THREE.Object3D): void {
   root.traverse((obj) => {
     if ((obj as THREE.Mesh).isMesh) {
@@ -902,5 +962,5 @@ export {
   type ClipSource,
 } from "./clips.js";
 export { depenetrate } from "./depenetrate.js";
-export { alignFloorPalms } from "./contacts.js";
+export { alignFloorPalms, levelPlantedFeet } from "./contacts.js";
 export type { PhaseSegment } from "./timeline.js";

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

@@ -74,6 +74,18 @@ describe("relaxHands (L4.1)", () => {
     relaxHands(m, new Set(), new Set(["index_left"]));
     expect(m.bones.get("index_left")!.rotation.x).toBeCloseTo(1.4, 5);
   });
+
+  it("keeps a floor-planted hand's fingers flat instead of clawing", () => {
+    const m = buildMannequin();
+    // A free hand takes the soft inward hook...
+    relaxHands(m, new Set(), new Set(), new Set());
+    const freeCurl = m.bones.get("index_left")!.rotation.x;
+    expect(freeCurl).toBeGreaterThan(0.3);
+    // ...but a hand pressed to the floor (plank/push-up) lies extended.
+    relaxHands(m, new Set(), new Set(), new Set(["left"]));
+    expect(m.bones.get("index_left")!.rotation.x).toBeLessThan(0.1); // flat
+    expect(m.bones.get("index_right")!.rotation.x).toBeGreaterThan(0.3); // right still hooked
+  });
 });
 
 describe("swingArms (L4.2)", () => {