Merge remote-tracking branch 'origin/main' into fix/animation-overshoot-and-floor-contacts

# Conflicts:
#	packages/posecode-eval/src/probe.ts

Author: a-baran-orhan

CHANGELOG.md

@@ -11,11 +11,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Realistic human figure**: the playground, landing hero, and `<posecode-player>` embeds now render a fully rigged, textured human character (hands with articulated fingers, sneakers, face) instead of the procedural capsule mannequin. All solving (FK, ground-lock, pins, reach-IK) still runs on the driver skeleton, rebuilt to the character's exact proportions and retargeted bone-for-bone every frame; the procedural figure remains as an automatic fallback (and via `?figure=classic` / `character="off"`).
 - **Self-collision resolution**: a capsule-based de-penetration pass keeps forearms/hands out of the torso, head, and legs (and shins out of each other), clamped to healthy ROM, so limbs no longer pass through the body mid-movement.
+- **Solid props**: props now declare blocking faces (the wall's surface, the chair's backrest and seat edge, the box's near face) and a contact pass keeps the body out of them — translating the whole figure along the face normal, or bending the offending leg's hip clear (ROM-clamped). Limbs pinned/gripped/reached to a prop anchor stay exempt as declared support. A new `solid-props` eval invariant (independent geometry re-derivation) guards every prop movement against this bug class.
 - `viewer.characterActive`, `createViewer({ characterUrl })`, and the embed `character` attribute.
 - `scripts/capture-gifs.mjs` (`npm run gifs`): reproducible headless regeneration of the README movement GIFs from the live renderer.
 
 ### Fixed
 
+- Wall sit no longer clips through the wall: the body now translates forward until the back rests on the wall's surface (feet walking out, thighs parallel), the physically correct wall-sit geometry. Sit-to-stand and box-squat land against the chair's backrest instead of sinking into it, a standing figure's calves clear the seat edge, and a step-up's trailing shin bends over the box edge instead of sweeping through it.
 - Deadlift arms now hang toward the bar during the hinge (were authored as shoulder extension, flying up behind the back).
 - Crunch keeps the feet planted with bent knees (shins previously folded through the floor and jacked the body up).
 - Touch-toes folds like a human (hinge depth and knee bend were over-authored, collapsing the figure).

ROADMAP.md

@@ -41,6 +41,11 @@ These are the unlocks, roughly in order of leverage:
    Powers `sit-to-stand`, `box-squat`, `wall-sit`, `dead-hang`, `hanging-knee-raise`.
    Bar and dip-bar contacts now resolve to independent left/right anchors with
    terminal wrist orientation; mocap is contact-corrected after blending.
+   Props are now **solid**: declared blocking faces (wall surface, chair
+   backrest + seat edge, box edge) physically stop the body — a wall-sit
+   slides down the wall instead of through it, a sit lands against the
+   backrest, a swing leg steps over the box edge — guarded by a `solid-props`
+   eval invariant on every prop movement.
    Next: more props (bench, rings, bands), load cues, arbitrary surface shapes.
 4. ~~**Lying & seated base poses**~~:  **shipped.** `supine | prone | seated`
    start poses (grounded by a bounding-box drop). Powers `glute-bridge`,
@@ -84,7 +89,9 @@ Each prop is a small scene object + an anchor type; movements then reference it
 - A **starter** prop set (chair / wall / bar / box / dip bars): no bench,
   rings, bands, or loaded implements yet, and props sit at fixed default
   placements.
-- Props are visual + reach anchors (no physical sit/lean solve).
+- Prop solidity is face-based: each built-in prop declares its blocking
+  surfaces (wall face, backrest, seat edge, box edge). Arbitrary-shape
+  collision and load/pressure simulation are future.
 - Fingers are **single-DOF** curls, good for grip and rough gesture, not exact
   sign language. The head has no facial articulation.
 

package.json

@@ -15,6 +15,7 @@
     "coverage": "vitest run --coverage",
     "dev": "npm run dev -w playground",
     "build": "npm run build -w playground",
+    "prepare:xbot": "node scripts/prepare-xbot.mjs",
     "eval": "tsx packages/posecode-eval/src/cli.ts",
     "typecheck": "for p in packages/*/tsconfig.json playground/tsconfig.json editors/*/tsconfig.json; do tsc --noEmit -p \"$p\" || exit 1; done",
     "gifs": "node scripts/capture-gifs.mjs"

packages/posecode-eval/src/checks.ts

@@ -18,6 +18,7 @@ import {
   lowestPoint,
   palmFloorAngleDeg,
   phaseMaxLandmarkSpeed,
+  propPenetrationDepth,
   segmentTiltDeg,
   spineCurlDeg,
   torsoPitchDeg,
@@ -94,7 +95,7 @@ export function genericChecks(result: ProbeResult): CheckOutcome[] {
     // 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) {
+    if (p.floorBound) {
       out.push({
         id: `grounded-not-floating:${p.name}`,
         pass: p.meshMinY < 0.02,
@@ -137,6 +138,19 @@ export function genericChecks(result: ProbeResult): CheckOutcome[] {
         detail: `${clearance.toFixed(3)}m clearance (want > -0.01m)`,
       });
     }
+
+    // Props are solid: no body capsule may sit inside a prop's blocking face
+    // (the wall-sit-through-the-wall class of bug). Independent re-derivation
+    // of the face geometry, so it fails loudly if resolvePropContacts or a
+    // prop's collider declaration regresses.
+    const penetration = propPenetrationDepth(result, p);
+    if (Number.isFinite(penetration)) {
+      out.push({
+        id: `solid-props:${p.name}`,
+        pass: penetration < 0.03,
+        detail: `${penetration.toFixed(3)}m into a solid prop face (want < 0.030)`,
+      });
+    }
   }
 
   for (let i = 1; i < result.phases.length; i++) {

packages/posecode-eval/src/metrics.ts

@@ -196,6 +196,90 @@ export function headPropClearance(result: ProbeResult, pose: PhasePose): number
   return clearance;
 }
 
+interface SolidFace {
+  point: Vec3;
+  normal: Vec3;
+  tangentU: Vec3;
+  halfU: number;
+  tangentV: Vec3;
+  halfV: number;
+  captureDepth: number;
+  blocks: readonly string[];
+}
+
+/** The solid prop faces, re-derived from the prop geometry independently of
+ * the renderer's collider declarations so a regression in either is caught. */
+function solidFaces(propTypes: readonly string[]): SolidFace[] {
+  const out: SolidFace[] = [];
+  const all = ["torso", "head", "thigh", "shin", "arm"];
+  if (propTypes.includes("wall")) {
+    out.push({ point: [0, 1.3, -0.29], normal: [0, 0, 1], tangentU: [1, 0, 0], halfU: 1.1, tangentV: [0, 1, 0], halfV: 1.3, captureDepth: 0.8, blocks: all });
+  }
+  if (propTypes.includes("chair")) {
+    out.push(
+      { point: [0, 0.78, -0.31], normal: [0, 0, 1], tangentU: [1, 0, 0], halfU: 0.21, tangentV: [0, 1, 0], halfV: 0.25, captureDepth: 0.4, blocks: ["torso", "head"] },
+      { point: [0, 0.47, 0.05], normal: [0, 0, 1], tangentU: [1, 0, 0], halfU: 0.21, tangentV: [0, 1, 0], halfV: 0.03, captureDepth: 0.42, blocks: ["shin"] },
+    );
+  }
+  if (propTypes.includes("box")) {
+    out.push({ point: [0, 0.15, 0.11], normal: [0, 0, -1], tangentU: [1, 0, 0], halfU: 0.25, tangentV: [0, 1, 0], halfV: 0.15, captureDepth: 0.42, blocks: ["shin"] });
+  }
+  return out;
+}
+
+/** Body capsule radii matching the render mannequin (see mannequin.ts). */
+const PART_RADII = { torso: 0.13, head: 0.105, thigh: 0.075, shin: 0.055, arm: 0.038 } as const;
+
+/**
+ * Worst body penetration into a solid prop face (metres, ≤0 when clear), or
+ * -Infinity when the document declares no solid-faced prop. Limbs pinned or
+ * reached to a non-floor anchor are that phase's declared prop support and
+ * don't count (a foot standing ON the box is not "in" the box).
+ */
+export function propPenetrationDepth(result: ProbeResult, pose: PhasePose): number {
+  const faces = solidFaces(result.propTypes);
+  if (faces.length === 0) return -Infinity;
+  const exemptLegs = new Set<string>();
+  const contacts = [
+    ...pose.pins,
+    ...pose.reaches.map((r) => ({ effector: r.effector, anchor: r.target })),
+  ];
+  for (const c of contacts) {
+    if (c.anchor === "floor") continue;
+    if (c.effector === "feet" || c.effector === "foot_left") exemptLegs.add("left");
+    if (c.effector === "feet" || c.effector === "foot_right") exemptLegs.add("right");
+  }
+  const segments: [string, string, keyof typeof PART_RADII][] = [
+    ["pelvis", "neck", "torso"],
+    ["neck", "head", "head"],
+  ];
+  for (const side of ["left", "right"]) {
+    segments.push([`shoulder_${side}`, `elbow_${side}`, "arm"], [`elbow_${side}`, `wrist_${side}`, "arm"]);
+    if (exemptLegs.has(side)) continue;
+    segments.push([`hip_${side}`, `knee_${side}`, "thigh"], [`knee_${side}`, `ankle_${side}`, "shin"]);
+  }
+  let worst = -Infinity;
+  for (const [aId, bId, part] of segments) {
+    const a = pose.bones.get(aId);
+    const b = pose.bones.get(bId);
+    if (!a || !b) continue;
+    const r = PART_RADII[part];
+    for (const t of [0, 0.25, 0.5, 0.75, 1]) {
+      const p: Vec3 = [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+      for (const f of faces) {
+        if (!f.blocks.includes(part)) continue;
+        const rel = sub(p, f.point);
+        const d = dot(rel, f.normal);
+        if (d < -f.captureDepth) continue;
+        if (Math.abs(dot(rel, f.tangentU)) > f.halfU + r) continue;
+        if (Math.abs(dot(rel, f.tangentV)) > f.halfV + r) continue;
+        worst = Math.max(worst, r - d);
+      }
+    }
+  }
+  return worst;
+}
+
 /** Fastest landmark's average speed from the previous endpoint into this phase. */
 export function phaseMaxLandmarkSpeed(previous: PhasePose | null, pose: PhasePose): number {
   if (!previous || pose.durationSec <= 0) return 0;
@@ -209,8 +293,11 @@ export function phaseMaxLandmarkSpeed(previous: PhasePose | null, pose: PhasePos
 
 export function footSkateDistance(previous: PhasePose, pose: PhasePose, side: "left" | "right"): number {
   const id = `ankle_${side}`;
+  // Authored travel AND the solid-prop contact push both translate the whole
+  // body deliberately, feet included; skate is what's left after removing them.
   const local = (p: Vec3, phase: PhasePose): readonly [number, number] => {
-    const x = p[0] - phase.rootOffset[0], z = p[2] - phase.rootOffset[2];
+    const x = p[0] - phase.rootOffset[0] - phase.propPush[0];
+    const z = p[2] - phase.rootOffset[2] - phase.propPush[2];
     const c = Math.cos(-phase.rootYaw), s = Math.sin(-phase.rootYaw);
     return [x * c - z * s, x * s + z * c];
   };
@@ -224,7 +311,8 @@ export function feetCenterSkateDistance(previous: PhasePose, pose: PhasePose): n
     const id = `ankle_${side}`;
     const a = bone(previous, id), b = bone(pose, id);
     const unyaw = (p: Vec3, phase: PhasePose) => {
-      const x = p[0] - phase.rootOffset[0], z = p[2] - phase.rootOffset[2];
+      const x = p[0] - phase.rootOffset[0] - phase.propPush[0];
+      const z = p[2] - phase.rootOffset[2] - phase.propPush[2];
       const c = Math.cos(-phase.rootYaw), s = Math.sin(-phase.rootYaw);
       return [x * c - z * s, x * s + z * c] as const;
     };

packages/posecode-eval/src/probe.ts

@@ -23,6 +23,8 @@ import {
   depenetrate,
   groundFigure,
   levelPlantedFeet,
+  propContactExemptions,
+  resolvePropContacts,
 } from "posecode-render";
 
 export type Vec3 = readonly [x: number, y: number, z: number];
@@ -39,8 +41,18 @@ export interface PhasePose {
   reaches: readonly ReachTarget[];
   rootOffset: Vec3;
   rootYaw: number;
+  /**
+   * Horizontal body translation applied by the solid-prop contact solve
+   * (resolvePropContacts): the feet legitimately glide by this much while the
+   * body is pressed out of a prop (a wall-sit walks the feet forward as the
+   * back slides down the wall), so skate metrics compensate for it like they
+   * do for authored travel.
+   */
+  propPush: Vec3;
   /** True when the phase relies on pins/reach-IK the probe cannot solve. */
   usesSceneIk: boolean;
+  /** Whether the phase should rest on the floor (no elevated prop/grip support). */
+  floorBound: 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
@@ -87,6 +99,11 @@ export function probeMovement(source: string): ProbeResult {
   m.root.updateMatrixWorld(true);
   depenetrate(m);
   groundFigure(m);
+  resolvePropContacts(m, propScene.colliders, propContactExemptions([
+    ...(ir.phases[0]?.pins ?? []),
+    ...(ir.phases[0]?.grips ?? []),
+    ...(ir.phases[0]?.reaches ?? []).map((r) => ({ effector: r.effector, anchor: r.target })),
+  ]));
   const baseRootPos = m.root.position.clone();
   const baseRootQuat = m.root.quaternion.clone();
 
@@ -100,6 +117,67 @@ export function probeMovement(source: string): ProbeResult {
     }
   }
 
+  // Precompute world positions of all effectors at start of each segment
+  const segmentStartEffectors: Map<string, THREE.Vector3>[] = [];
+  const tempYawQ = new THREE.Quaternion();
+  
+  const getEffectorId = (eff: string) => {
+    if (eff === "hand_left") return "wrist_left";
+    if (eff === "hand_right") return "wrist_right";
+    if (eff === "foot_left") return "ankle_left";
+    if (eff === "foot_right") return "ankle_right";
+    return eff;
+  };
+
+  let prevEffectorsMap: Map<string, THREE.Vector3> | null = null;
+  let prevPins: typeof ir.phases[number]["pins"] = [];
+
+  for (let i = 0; i < tl.segments.length; i++) {
+    const seg = tl.segments[i]!;
+    for (const bone of m.bones.values()) bone.quaternion.identity();
+    const info = tl.sample(seg.start, m.bones);
+    
+    const wasPinned = (id: string) => prevPins.some(p => getEffectorId(p.effector) === id && p.anchor === "floor");
+    const isPinned = (id: string) => info.pins.some(p => getEffectorId(p.effector) === id && p.anchor === "floor");
+
+    m.root.position.copy(baseRootPos);
+    m.root.quaternion.copy(baseRootQuat);
+    if (info.rootYaw !== 0) {
+      tempYawQ.setFromAxisAngle(WORLD_Y, info.rootYaw);
+      m.root.quaternion.premultiply(tempYawQ);
+    }
+    m.root.position.x += info.rootOffset.x;
+    m.root.position.z += info.rootOffset.z;
+    m.root.updateMatrixWorld(true);
+    depenetrate(m);
+
+    const effectorsMap = new Map<string, THREE.Vector3>();
+    for (const ids of Object.values(m.effectors)) {
+      for (const id of ids) {
+        const node = m.bones.get(id);
+        if (node) {
+          if (i > 0 && wasPinned(id) && isPinned(id) && prevEffectorsMap && prevEffectorsMap.has(id)) {
+            effectorsMap.set(id, prevEffectorsMap.get(id)!);
+          } else {
+            effectorsMap.set(id, node.getWorldPosition(new THREE.Vector3()));
+          }
+        }
+      }
+    }
+    segmentStartEffectors.push(effectorsMap);
+    prevEffectorsMap = effectorsMap;
+    prevPins = info.pins;
+  }
+
+  // Restore initial state
+  for (const bone of m.bones.values()) bone.quaternion.identity();
+  tl.sample(0, m.bones);
+  m.root.position.copy(baseRootPos);
+  m.root.quaternion.copy(baseRootQuat);
+  m.root.updateMatrixWorld(true);
+  depenetrate(m);
+  groundFigure(m);
+
   // Sample the end of each phase, applying the viewer's per-frame root
   // pipeline: base root → yaw/travel → ground-lock → floor safety clamp.
   const yawQ = new THREE.Quaternion();
@@ -149,8 +227,14 @@ export function probeMovement(source: string): ProbeResult {
         if (!effector) continue;
         let target: THREE.Vector3 | null = null;
         if (pin.anchor === "floor") {
-          target = effector.getWorldPosition(new THREE.Vector3());
-          target.y = 0;
+          const startPos = segmentStartEffectors[phaseIndex]?.get(effectorId);
+          if (startPos) {
+            target = startPos.clone();
+            target.y = 0;
+          } else {
+            target = effector.getWorldPosition(new THREE.Vector3());
+            target.y = 0;
+          }
         } else if (propScene.anchors.has(pin.anchor)) {
           target = propScene.anchors.get(pin.anchor)!.clone();
         } else {
@@ -166,6 +250,16 @@ export function probeMovement(source: string): ProbeResult {
         m.root.updateMatrixWorld(true);
       }
     }
+    // Props are solid (viewer parity): after the root solvers place the body,
+    // push it back out of any prop face it crossed and bend swing legs clear.
+    // Limbs pinned/gripped to a prop anchor are declared support, exempt.
+    const prePush = m.root.position.clone();
+    resolvePropContacts(m, propScene.colliders, propContactExemptions([
+      ...info.pins,
+      ...info.grips,
+      ...info.reaches.map((r) => ({ effector: r.effector, anchor: r.target })),
+    ]));
+    const propPush: Vec3 = [m.root.position.x - prePush.x, 0, m.root.position.z - prePush.z];
     alignFloorPalms(m, info.reaches, info.pins, info.groundLock);
     // Plantigrade correction (viewer parity): flatten planted soles. This lifts
     // the foot mesh a little, so it must run BEFORE the floor clamp reconciles.
@@ -175,8 +269,8 @@ export function probeMovement(source: string): ProbeResult {
     // 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);
-    const planted = info.groundLock.length > 0;
-    if (box.min.y < 0 || (planted && box.min.y > 0)) {
+    const floorBound = info.grips.length === 0 && !info.pins.some((pin) => pin.anchor !== "floor");
+    if (box.min.y < 0 || (floorBound && box.min.y > 0)) {
       m.root.position.y -= box.min.y;
       m.root.updateMatrixWorld(true);
     }
@@ -190,7 +284,9 @@ export function probeMovement(source: string): ProbeResult {
       reaches: [...info.reaches],
       rootOffset: [info.rootOffset.x, 0, info.rootOffset.z],
       rootYaw: info.rootYaw,
+      propPush,
       usesSceneIk: info.pins.length > 0 || info.reaches.length > 0 || info.grips.length > 0,
+      floorBound,
       meshMinY: Number.isFinite(finalBox.min.y) ? finalBox.min.y : 0,
       bones: snapshotBones(m.bones),
       boneQuaternions: snapshotBoneQuaternions(m.bones),