@ikijs/editor 0.4.0 → 0.5.0

package/dist/index.mjs

@@ -1605,9 +1605,10 @@ import {
 } from "@ikijs/format";
 var ROLE_TABLE = {
   // The silhouette behind the face. It rides the rigid head (not faceWarp,
-  // whose grid it would stretch across the shoulders) as a MESH: it bends on
-  // the turn through its own part warp (bakeHairBackTurnWarp) and swings its
-  // ends on the hair-sway warps.
+  // whose grid it would stretch across the shoulders) as a MESH, so its ends
+  // can swing on the hair-sway warps. It holds the head's outline STILL
+  // through the turn — the head it hangs off no longer travels and it has no
+  // turn warp of its own — while the face slides inside it.
   hair_back: { deformer: "headDeformer", order: 0, mesh: true },
   // The torso. It rides its own rigid deformer, not the head's: the head turns
   // about the neck pivot while the shoulders follow at BODY_TURN_FOLLOW and
@@ -1789,8 +1790,8 @@ var FACE_GRID_CELLS = 6;
 var HEAD_CYLINDER_RADIUS_FACTOR = 0.6 / 0.5;
 var HEAD_TURN_MAX_DEG = 30;
 var HEAD_TURN_STOPS = [-30, -15, 0, 15, 30];
-function headTurnParallaxUnit(gridHalfWidth) {
-  return gridHalfWidth * HEAD_CYLINDER_RADIUS_FACTOR * Math.sin(HEAD_TURN_MAX_DEG * (Math.PI / 180));
+function headTurnParallaxUnit(radius) {
+  return radius * Math.sin(HEAD_TURN_MAX_DEG * (Math.PI / 180));
 }
 function gridReach(grid, axis, center) {
   let reach = 0;
@@ -1803,9 +1804,16 @@ function pinnedCylinderBend(local, radius, theta) {
   const alpha = Math.asin(Math.max(-1, Math.min(1, local / radius)));
   return radius * Math.sin(alpha + theta) - local - radius * Math.sin(theta);
 }
-function bakeHeadTurnGridWarp2DCentered(grid, parameterX, parameterY, centerX, centerY) {
+function boundedCylinderBend(local, radius, theta) {
+  const bound = radius / HEAD_CYLINDER_RADIUS_FACTOR;
+  const onSurface = Math.max(-bound, Math.min(bound, local));
+  return pinnedCylinderBend(onSurface, radius, theta);
+}
+function turnSlide(travel, angleX) {
+  return travel * angleX / HEAD_TURN_MAX_DEG;
+}
+function bakeHeadTurnGridWarp2DCentered(grid, parameterX, parameterY, centerX, centerY, radiusX, travel) {
   const STOPS = [...HEAD_TURN_STOPS];
-  const RADIUS_X = gridReach(grid, 0, centerX) * HEAD_CYLINDER_RADIUS_FACTOR;
   const RADIUS_Y = gridReach(grid, 1, centerY) * HEAD_CYLINDER_RADIUS_FACTOR;
   const pointCount = grid.points.length / 2;
   const DEG_TO_RAD = Math.PI / 180;
@@ -1814,10 +1822,11 @@ function bakeHeadTurnGridWarp2DCentered(grid, parameterX, parameterY, centerX, c
     const thetaY = angleY * NOD_BEND * DEG_TO_RAD;
     for (const angleX of STOPS) {
       const thetaX = angleX * DEG_TO_RAD;
+      const slide = turnSlide(travel, angleX);
       const offsets = [];
       for (let i = 0; i < pointCount; i++) {
         offsets.push(
-          pinnedCylinderBend(grid.points[i * 2] - centerX, RADIUS_X, thetaX),
+          boundedCylinderBend(grid.points[i * 2] - centerX, radiusX, thetaX) + slide,
           pinnedCylinderBend(
             grid.points[i * 2 + 1] - centerY,
             RADIUS_Y,
@@ -1836,16 +1845,757 @@ function bakeHeadTurnGridWarp2DCentered(grid, parameterX, parameterY, centerX, c
     keyforms2d
   };
 }
+function turnColumnMap(grid, faceCenterX, radiusX, angleX, travel) {
+  if (Math.abs(angleX) > HEAD_TURN_MAX_DEG) {
+    throw new Error(
+      `auto-rig: turnColumnMap: angleX ${angleX}\xB0 is outside the turn's \xB1${HEAD_TURN_MAX_DEG}\xB0 range`
+    );
+  }
+  const theta = angleX * (Math.PI / 180);
+  const slide = turnSlide(travel, angleX);
+  const restX = [];
+  const warpedX = [];
+  for (let col = 0; col <= grid.cols; col++) {
+    const x = grid.points[col * 2];
+    restX.push(x);
+    warpedX.push(
+      x + boundedCylinderBend(x - faceCenterX, radiusX, theta) + slide
+    );
+  }
+  const cellFor = (v, edges) => {
+    for (let c = 0; c < grid.cols; c++) {
+      if (v < edges[c + 1]) return c;
+    }
+    return grid.cols - 1;
+  };
+  return {
+    restX,
+    warpedX,
+    mapX(x) {
+      const c = cellFor(x, restX);
+      const s = Math.max(
+        0,
+        Math.min(1, (x - restX[c]) / (restX[c + 1] - restX[c]))
+      );
+      return warpedX[c] + (warpedX[c + 1] - warpedX[c]) * s;
+    },
+    invertX(X) {
+      const c = cellFor(X, warpedX);
+      const s = Math.max(
+        0,
+        Math.min(1, (X - warpedX[c]) / (warpedX[c + 1] - warpedX[c]))
+      );
+      return restX[c] + (restX[c + 1] - restX[c]) * s;
+    }
+  };
+}
+var TurnTargetError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TurnTargetError";
+  }
+};
+var DEFAULT_TURN_TARGETS = {
+  eyeShift: 0.22,
+  farEyeRatio: 0.67,
+  silhouetteRatio: 1
+};
+var NOSE_SHIFT_SHARE = 1.36;
+var MOUTH_SHIFT_SHARE = 1.18;
+var TURN_RATIO_MAX = 1.5;
+var SILHOUETTE_RATIO_MIN = 0.5;
+function resolveTurnTargets(targets = {}) {
+  const eyeShift = targets.eyeShift ?? DEFAULT_TURN_TARGETS.eyeShift;
+  const check = (field, value, ok, expected) => {
+    if (value === void 0) return;
+    if (!Number.isFinite(value) || !ok(value)) {
+      const derived = (field === "noseShift" || field === "mouthShift") && targets[field] === void 0;
+      const from = derived ? `, derived from turnTargets.eyeShift (${eyeShift}),` : "";
+      throw new TurnTargetError(
+        `auto-rig: turnTargets.${field} (${value})${from} must be ${expected}`
+      );
+    }
+  };
+  const farEyeRatio = targets.farEyeRatio ?? DEFAULT_TURN_TARGETS.farEyeRatio;
+  const silhouetteRatio = targets.silhouetteRatio ?? DEFAULT_TURN_TARGETS.silhouetteRatio;
+  const noseShift = targets.noseShift ?? NOSE_SHIFT_SHARE * eyeShift;
+  const mouthShift = targets.mouthShift ?? MOUTH_SHIFT_SHARE * eyeShift;
+  const isShift = (v) => Math.abs(v) <= 1;
+  const shiftRange = "a fraction of the head half-width, |value| <= 1";
+  check("eyeShift", eyeShift, isShift, shiftRange);
+  check(
+    "farEyeRatio",
+    farEyeRatio,
+    (v) => v > 0 && v <= TURN_RATIO_MAX,
+    `in (0, ${TURN_RATIO_MAX}]`
+  );
+  check(
+    "silhouetteRatio",
+    silhouetteRatio,
+    (v) => v >= SILHOUETTE_RATIO_MIN && v <= TURN_RATIO_MAX,
+    `in [${SILHOUETTE_RATIO_MIN}, ${TURN_RATIO_MAX}]`
+  );
+  check("noseShift", noseShift, isShift, shiftRange);
+  check("mouthShift", mouthShift, isShift, shiftRange);
+  check("headHalfWidth", targets.headHalfWidth, (v) => v > 0, "positive");
+  const defaulted = new Set(
+    [
+      "eyeShift",
+      "farEyeRatio",
+      "silhouetteRatio",
+      "noseShift",
+      "mouthShift"
+    ].filter((field) => targets[field] === void 0)
+  );
+  return {
+    eyeShift,
+    farEyeRatio,
+    silhouetteRatio,
+    noseShift,
+    mouthShift,
+    headHalfWidth: targets.headHalfWidth,
+    defaulted
+  };
+}
+function turnLandmarks(layers) {
+  const markOf = (role) => {
+    const layer = layers.find((l) => l.role === role);
+    if (!layer) return void 0;
+    const t = bboxToTransform(layer.bbox, layer.canvasW, layer.canvasH, role);
+    return { x: t.x, y: t.y, w: layer.cropW };
+  };
+  const pairOf = (left, right) => {
+    const l = markOf(left);
+    const r = markOf(right);
+    return l && r ? [l, r] : void 0;
+  };
+  const one = (role) => {
+    const m = markOf(role);
+    return m ? [m] : [];
+  };
+  return {
+    eye: pairOf("eye_L", "eye_R") ?? [],
+    nose: one("nose"),
+    mouth: one("mouth")
+  };
+}
+var TURN_BISECT_STEPS = 40;
+var TURN_DEPTH_EPS = 1e-6;
+function solveTurnDepthSigned(target, landmarks, unit, map, holdEdgeX, plateEdgeX) {
+  if (landmarks.length === 0) {
+    throw new Error("auto-rig: solveTurnDepth: no landmark to slide");
+  }
+  const farEdge = Math.min(...landmarks.map((l) => l.x - l.w / 2));
+  const floor = Math.max(map.invertX(holdEdgeX), map.restX[0], plateEdgeX);
+  const cap = Math.max(0, (farEdge - floor) / unit);
+  const achieved = (d) => landmarks.reduce((sum, l) => sum + (map.mapX(l.x - d * unit) - l.x), 0) / landmarks.length;
+  const atCap = achieved(cap);
+  const atRest = achieved(0);
+  const attainable = [atCap, atRest];
+  if (target > atRest + TURN_DEPTH_EPS)
+    return { reached: false, depth: 0, achieved: atRest, attainable };
+  if (target < atCap - TURN_DEPTH_EPS)
+    return { reached: false, depth: cap, achieved: atCap, attainable };
+  const clampedTarget = Math.min(Math.max(target, atCap), atRest);
+  let lo = 0;
+  let hi = cap;
+  for (let i = 0; i < TURN_BISECT_STEPS; i++) {
+    const mid = (lo + hi) / 2;
+    if (achieved(mid) > clampedTarget) lo = mid;
+    else hi = mid;
+  }
+  const depth = (lo + hi) / 2;
+  return { reached: true, depth, achieved: achieved(depth), attainable };
+}
+var TURN_SWEEP_MAX_FACTOR = 8;
+var TURN_SWEEP_SAMPLES = 32;
+var HOLD_CLEARANCE = 1;
+var TURN_HOLD_SAMPLES = 16;
+var TURN_HOLD_SATURATION_PASSES = 4;
+function hairFrontHoldTarget(x, faceCenterX, faceHalfWidth, holdBase, holdEdge, map) {
+  const local = x - faceCenterX;
+  const dist = Math.abs(local);
+  const side = Math.sign(local);
+  const sideIdx = side < 0 ? 0 : 1;
+  if (dist <= faceHalfWidth) return map.mapX(x);
+  if (dist <= holdBase) {
+    const inner = map.mapX(faceCenterX + side * faceHalfWidth);
+    const u = (dist - faceHalfWidth) / (holdBase - faceHalfWidth);
+    return inner + (faceCenterX + side * holdEdge[sideIdx] - inner) * u;
+  }
+  return x + side * (holdEdge[sideIdx] - holdBase);
+}
+function hairFrontLandingAt(x, hairFront, faceCenterX, faceHalfWidth, holdBase, cappedHoldEdge, map, leadTipShift, leadRow) {
+  const { cols, rows } = meshCellsFor(hairFront.cropW, hairFront.cropH);
+  const preBindAt = (col2) => {
+    const colX = hairFront.x - hairFront.cropW / 2 + col2 / cols * hairFront.cropW;
+    const target = hairFrontHoldTarget(
+      colX,
+      faceCenterX,
+      faceHalfWidth,
+      holdBase,
+      cappedHoldEdge,
+      map
+    );
+    return map.invertX(target);
+  };
+  const leadAt = (row2) => -leadTipShift * Math.pow(row2 / rows, HAIR_SWAY_CURL);
+  const bracket = (v, cells) => {
+    const lo = Math.max(0, Math.min(cells, Math.floor(v)));
+    return {
+      lo,
+      hi: Math.max(0, Math.min(cells, lo + 1)),
+      t: Math.max(0, Math.min(1, v - lo))
+    };
+  };
+  const col = bracket(
+    (x - hairFront.x + hairFront.cropW / 2) / hairFront.cropW * cols,
+    cols
+  );
+  const row = bracket(leadRow * rows, rows);
+  const landingAt = (c, r) => map.mapX(preBindAt(c) + leadAt(r));
+  const tl = landingAt(col.lo, row.lo);
+  const br = landingAt(col.hi, row.hi);
+  if (col.t <= row.t) {
+    const bl = landingAt(col.lo, row.hi);
+    return tl + row.t * (bl - tl) + col.t * (br - bl);
+  }
+  const tr = landingAt(col.hi, row.lo);
+  return tl + col.t * (tr - tl) + row.t * (br - tr);
+}
+function shellTravelCap(faceCenterX, faceHalfWidth, askedTravel, bendOnlyMapAt, holdEdgeAt) {
+  let cap = Infinity;
+  for (const deg of HEAD_TURN_STOPS) {
+    if (deg === 0) continue;
+    const map = bendOnlyMapAt(deg);
+    const slideSign = turnSlide(askedTravel, deg) < 0 ? -1 : 1;
+    const towardReach = Math.max(
+      ...[-1, 1].map(
+        (side) => slideSign * (map.mapX(faceCenterX + side * faceHalfWidth) - faceCenterX)
+      )
+    );
+    cap = Math.min(
+      cap,
+      Math.max(0, holdEdgeAt(deg, slideSign) - HOLD_CLEARANCE - towardReach) * HEAD_TURN_MAX_DEG / Math.abs(deg)
+    );
+  }
+  return cap;
+}
+function evaluateTurnCandidate(ctx, radius) {
+  const bendOnlyMapAt = (deg) => turnColumnMap(ctx.faceGrid, ctx.faceCenterX, radius, deg, 0);
+  const measuredEdgeAt = (side) => {
+    const candidates = side < 0 ? ctx.headEdges?.left : ctx.headEdges?.right;
+    if (candidates === void 0 || candidates.length === 0) return void 0;
+    const xs = candidates.map((c) => c.x);
+    return side < 0 ? Math.min(...xs) : Math.max(...xs);
+  };
+  const shellHalfWidthAt = (side) => {
+    const edge = measuredEdgeAt(side);
+    return edge === void 0 ? ctx.headHalfWidth : side * (edge - ctx.faceCenterX);
+  };
+  const unit = headTurnParallaxUnit(radius);
+  const leadTipShift = ctx.hairFrontLeadFraction === void 0 ? 0 : HAIR_FRONT_DEPTH * unit;
+  const leadRow = ctx.hairFrontLeadFraction ?? 0;
+  const evaluateHold = (ratio) => {
+    const holdEdgeFrom = (base) => (deg) => base * (1 + (ratio - 1) * Math.abs(deg) / HEAD_TURN_MAX_DEG);
+    const travel2 = ctx.headHalfWidth === void 0 ? ctx.travel : Math.min(
+      ctx.travel,
+      shellTravelCap(
+        ctx.faceCenterX,
+        ctx.faceHalfWidth,
+        ctx.travel,
+        bendOnlyMapAt,
+        (deg, side) => {
+          const rest = shellHalfWidthAt(side);
+          return Math.min(rest, holdEdgeFrom(rest)(deg));
+        }
+      )
+    );
+    const columnMapAt = (deg) => turnColumnMap(ctx.faceGrid, ctx.faceCenterX, radius, deg, travel2);
+    const holdBase2 = ctx.headHalfWidth ?? plateReach(ctx.faceCenterX, ctx.faceHalfWidth, columnMapAt) + HOLD_CLEARANCE;
+    const holdEdgeAt2 = holdEdgeFrom(holdBase2);
+    let foldLowerBound = -Infinity;
+    let folds = false;
+    for (const deg of HEAD_TURN_STOPS) {
+      if (deg === 0) continue;
+      const reach = plateReachAt(
+        columnMapAt(deg),
+        ctx.faceCenterX,
+        ctx.faceHalfWidth
+      );
+      foldLowerBound = Math.max(
+        foldLowerBound,
+        1 + ((reach + HOLD_CLEARANCE) / holdBase2 - 1) * (HEAD_TURN_MAX_DEG / Math.abs(deg))
+      );
+      if (holdEdgeAt2(deg) <= reach) folds = true;
+    }
+    const map2 = columnMapAt(-HEAD_TURN_MAX_DEG);
+    const requestedHoldEdge = holdEdgeAt2(HEAD_TURN_MAX_DEG);
+    const gridReach2 = [
+      Math.abs(map2.warpedX[0] - ctx.faceCenterX),
+      Math.abs(map2.warpedX[map2.warpedX.length - 1] - ctx.faceCenterX)
+    ];
+    const cappedHoldEdge = [
+      Math.min(requestedHoldEdge, gridReach2[0] - HOLD_CLEARANCE),
+      Math.min(requestedHoldEdge, gridReach2[1] - HOLD_CLEARANCE)
+    ];
+    const restAt = (side) => {
+      const edge = measuredEdgeAt(side);
+      if (edge !== void 0) return edge;
+      return ctx.headHalfWidth !== void 0 || ctx.hairFrontSilhouette === void 0 ? ctx.faceCenterX + side * holdBase2 : ctx.hairFrontSilhouette.x + side * ctx.hairFrontSilhouette.cropW / 2;
+    };
+    const hairFrontAt = (x) => ctx.hairFrontSilhouette === void 0 ? x : hairFrontLandingAt(
+      x,
+      ctx.hairFrontSilhouette,
+      ctx.faceCenterX,
+      ctx.faceHalfWidth,
+      holdBase2,
+      cappedHoldEdge,
+      map2,
+      leadTipShift,
+      leadRow
+    );
+    const landingOfRole = (role, x) => {
+      if (role === "hair_front") return hairFrontAt(x);
+      if (role === "hair_back") {
+        return x;
+      }
+      if (role === "body") {
+        return x - BODY_TURN_FOLLOW * travel2;
+      }
+      if (role === "face" || FEATURE_NOD_DEPTH[roleFamily(role)] !== void 0) {
+        return map2.mapX(x);
+      }
+      throw new Error(
+        `auto-rig: evaluateTurnCandidate: unrecognised role "${role}"`
+      );
+    };
+    const landingAt = (side) => {
+      const candidates = side < 0 ? ctx.headEdges?.left : ctx.headEdges?.right;
+      if (candidates === void 0 || candidates.length === 0) {
+        return hairFrontAt(restAt(side));
+      }
+      const landings = candidates.map((c) => landingOfRole(c.role, c.x));
+      return side < 0 ? Math.min(...landings) : Math.max(...landings);
+    };
+    return {
+      ratio,
+      travel: travel2,
+      map: map2,
+      holdBase: holdBase2,
+      holdEdgeAt: holdEdgeAt2,
+      folds,
+      foldLowerBound,
+      gridReach: gridReach2,
+      // How far the silhouette's own centre drifts off the face centre at full
+      // turn, against how far it already sat off centre at rest (zero unless
+      // hair_front's crop is itself off-centre) — the held shell keeps its own
+      // place while the face slides inside it, so this is the drift the hold
+      // and the bangs' lead leave behind, and the slide itself shows up in the
+      // eye cue instead of cancelling out of it.
+      // `measure_turn_reference` reads the eye pair against THIS moved centre,
+      // not the face centre, so it is what the eye cue is corrected by.
+      silhouetteCenterShift: (landingAt(1) + landingAt(-1)) / 2 - (restAt(1) + restAt(-1)) / 2,
+      // What a render actually shows: the real landing span over the real rest
+      // span, the same pair silhouetteCenterShift reads — the measure the
+      // hold is FITTED against, see this function's own doc.
+      renderedSilhouetteRatio: (landingAt(1) - landingAt(-1)) / (restAt(1) - restAt(-1)),
+      restSpan: restAt(1) - restAt(-1)
+    };
+  };
+  const saturatedHold = () => {
+    let hold2 = evaluateHold(1);
+    for (let i = 0; i < TURN_HOLD_SATURATION_PASSES; i++) {
+      const needed = (Math.max(hold2.gridReach[0], hold2.gridReach[1]) - HOLD_CLEARANCE) / hold2.holdBase;
+      if (needed <= hold2.ratio) break;
+      hold2 = evaluateHold(needed);
+    }
+    return hold2;
+  };
+  const holdRange = () => {
+    const ceiling = saturatedHold();
+    if (ceiling.folds) return void 0;
+    let floor = evaluateHold(Math.min(ceiling.foldLowerBound, ceiling.ratio));
+    if (floor.folds) {
+      let lo = floor;
+      let hi = ceiling;
+      for (let i = 0; i < TURN_BISECT_STEPS; i++) {
+        const mid = evaluateHold((lo.ratio + hi.ratio) / 2);
+        if (mid.folds) lo = mid;
+        else hi = mid;
+      }
+      floor = hi;
+    }
+    const samples = [floor];
+    for (let i = 1; i < TURN_HOLD_SAMPLES; i++) {
+      const sample = evaluateHold(
+        floor.ratio + (ceiling.ratio - floor.ratio) * i / TURN_HOLD_SAMPLES
+      );
+      if (!sample.folds) samples.push(sample);
+    }
+    samples.push(ceiling);
+    return samples;
+  };
+  const silhouetteMiss = (span) => {
+    const lower = Math.max(span?.[0] ?? Infinity, SILHOUETTE_RATIO_MIN);
+    const upper = Math.min(span?.[1] ?? -Infinity, TURN_RATIO_MAX);
+    return lower > upper ? { blocked: "silhouetteRatio", lower: Infinity, upper: -Infinity } : { blocked: "silhouetteRatio", lower, upper };
+  };
+  const asked = ctx.silhouetteRatio;
+  const natural = evaluateHold(asked);
+  const eps = TURN_DEPTH_EPS / natural.restSpan;
+  let hold;
+  let silhouetteClamped = false;
+  if (!natural.folds && Math.abs(natural.renderedSilhouetteRatio - asked) <= eps) {
+    hold = natural;
+  } else {
+    const samples = holdRange();
+    if (samples === void 0) return silhouetteMiss();
+    const rendered = samples.map((h) => h.renderedSilhouetteRatio);
+    const span = [
+      Math.min(...rendered),
+      Math.max(...rendered)
+    ];
+    const nearer = (a, b) => {
+      const ea = Math.abs(a.renderedSilhouetteRatio - asked);
+      const eb = Math.abs(b.renderedSilhouetteRatio - asked);
+      if (ea <= eps && eb <= eps) {
+        return Math.abs(a.ratio - asked) <= Math.abs(b.ratio - asked) ? a : b;
+      }
+      return ea <= eb ? a : b;
+    };
+    if (asked < span[0] - eps || asked > span[1] + eps) {
+      if (!ctx.clampSilhouetteRatio) return silhouetteMiss(span);
+      const wanted = asked < span[0] ? span[0] : span[1];
+      hold = samples.reduce(
+        (a, b) => Math.abs(b.renderedSilhouetteRatio - wanted) < Math.abs(a.renderedSilhouetteRatio - wanted) ? b : a
+      );
+      silhouetteClamped = true;
+    } else {
+      let best = samples.reduce(nearer);
+      let lo;
+      let hi;
+      for (let i = 0; i + 1 < samples.length; i++) {
+        const a = samples[i].renderedSilhouetteRatio - asked;
+        const b = samples[i + 1].renderedSilhouetteRatio - asked;
+        if (a * b <= 0) {
+          lo = samples[i];
+          hi = samples[i + 1];
+          break;
+        }
+      }
+      for (let i = 0; lo !== void 0 && hi !== void 0; i++) {
+        if (i >= TURN_BISECT_STEPS || Math.abs(best.renderedSilhouetteRatio - asked) <= eps) {
+          break;
+        }
+        const mid = evaluateHold((lo.ratio + hi.ratio) / 2);
+        if (!mid.folds) best = nearer(best, mid);
+        if ((mid.renderedSilhouetteRatio - asked) * (lo.renderedSilhouetteRatio - asked) > 0) {
+          lo = mid;
+        } else {
+          hi = mid;
+        }
+      }
+      hold = best;
+    }
+  }
+  if (hold.folds) {
+    throw new Error(
+      "auto-rig: evaluateTurnCandidate: the hold it settled on folds"
+    );
+  }
+  const {
+    travel,
+    map,
+    holdBase,
+    holdEdgeAt,
+    silhouetteCenterShift,
+    renderedSilhouetteRatio
+  } = hold;
+  const holdEdgeX = ctx.faceCenterX - holdEdgeAt(HEAD_TURN_MAX_DEG);
+  const eye = solveTurnDepthSigned(
+    silhouetteCenterShift - ctx.eyeShift * ctx.hh,
+    ctx.landmarks.eye,
+    unit,
+    map,
+    holdEdgeX,
+    ctx.plateEdgeX
+  );
+  if (!eye.reached && !ctx.clampEyeShift) {
+    return {
+      blocked: "eyeShift",
+      // eyeShift is a MAGNITUDE (the sign is ignored — see TurnTargets), so a
+      // negative lower bound here would advertise a value the field's own
+      // contract already rules out; 0 is the true floor.
+      offeredShift: [
+        Math.max(0, (-eye.attainable[1] + silhouetteCenterShift) / ctx.hh),
+        (-eye.attainable[0] + silhouetteCenterShift) / ctx.hh
+      ]
+    };
+  }
+  const scaleOf = (l) => (map.mapX(l.x + l.w / 2 - eye.depth * unit) - map.mapX(l.x - l.w / 2 - eye.depth * unit)) / l.w;
+  const far = ctx.landmarks.eye.reduce((a, b) => b.x < a.x ? b : a);
+  const near = ctx.landmarks.eye.reduce((a, b) => b.x > a.x ? b : a);
+  return {
+    radius,
+    ratio: scaleOf(far) / scaleOf(near),
+    unit,
+    travel,
+    map,
+    holdBase,
+    holdEdgeAt,
+    holdEdgeX,
+    eye,
+    silhouetteClamped,
+    silhouetteCenterShift,
+    renderedSilhouetteRatio
+  };
+}
+function sweepTurnRadii(ctx) {
+  const minRadius = ctx.faceHalfWidth * HEAD_CYLINDER_RADIUS_FACTOR;
+  const maxRadius = ctx.faceHalfWidth * TURN_SWEEP_MAX_FACTOR;
+  const candidates = [];
+  let heldRatioLower = Infinity;
+  let heldRatioUpper = -Infinity;
+  let offeredShift;
+  for (let i = 0; i < TURN_SWEEP_SAMPLES; i++) {
+    const radius = minRadius * Math.pow(maxRadius / minRadius, i / (TURN_SWEEP_SAMPLES - 1));
+    const result = evaluateTurnCandidate(ctx, radius);
+    if (!("blocked" in result)) {
+      candidates.push({ ...result, sweepIndex: i });
+    } else if (result.blocked === "silhouetteRatio") {
+      heldRatioLower = Math.min(heldRatioLower, result.lower);
+      heldRatioUpper = Math.max(heldRatioUpper, result.upper);
+    } else {
+      offeredShift = offeredShift ? [
+        Math.min(offeredShift[0], result.offeredShift[0]),
+        Math.max(offeredShift[1], result.offeredShift[1])
+      ] : result.offeredShift;
+    }
+  }
+  return { candidates, heldRatioLower, heldRatioUpper, offeredShift };
+}
+function ratioClusters(candidates) {
+  const clusters = [];
+  let run = [];
+  const close = () => {
+    if (run.length === 0) return;
+    const ratios = run.map((c) => c.ratio);
+    clusters.push({
+      candidates: run,
+      ratios: [Math.min(...ratios), Math.max(...ratios)]
+    });
+    run = [];
+  };
+  for (const candidate of candidates) {
+    const previous = run[run.length - 1];
+    if (previous !== void 0 && candidate.sweepIndex !== previous.sweepIndex + 1) {
+      close();
+    }
+    run.push(candidate);
+  }
+  close();
+  return clusters;
+}
+function fitTurnRadius(ctx, candidates, target) {
+  let lo = candidates[0];
+  let hi = candidates[candidates.length - 1];
+  for (let i = candidates.length - 2; i >= 0; i--) {
+    if ((candidates[i].ratio - target) * (candidates[i + 1].ratio - target) <= 0) {
+      lo = candidates[i];
+      hi = candidates[i + 1];
+      break;
+    }
+  }
+  for (let i = 0; i < TURN_BISECT_STEPS; i++) {
+    const mid = evaluateTurnCandidate(ctx, Math.sqrt(lo.radius * hi.radius));
+    if ("blocked" in mid) break;
+    if ((mid.ratio - target) * (lo.ratio - target) <= 0) hi = mid;
+    else lo = mid;
+  }
+  return Math.abs(lo.ratio - target) <= Math.abs(hi.ratio - target) ? lo : hi;
+}
+function solveFeatureDepths(ctx, targets, best, eyeShift) {
+  const clamped = [];
+  const solved = {};
+  const families = [
+    ["noseShift", ctx.landmarks.nose, NOSE_SHIFT_SHARE],
+    ["mouthShift", ctx.landmarks.mouth, MOUTH_SHIFT_SHARE]
+  ];
+  for (const [field, marks, share] of families) {
+    const m = Math.abs(
+      targets.defaulted.has(field) ? share * eyeShift : targets[field]
+    );
+    const solution = solveTurnDepthSigned(
+      best.silhouetteCenterShift - m * ctx.hh,
+      marks,
+      best.unit,
+      best.map,
+      best.holdEdgeX,
+      ctx.plateEdgeX
+    );
+    if (!solution.reached) {
+      if (!targets.defaulted.has(field)) {
+        return {
+          blocked: field,
+          // noseShift/mouthShift are MAGNITUDES too (see the correction
+          // above), so a negative lower bound here would advertise a value
+          // the field's own contract already rules out; 0 is the true floor.
+          attainable: [
+            Math.max(
+              0,
+              (-solution.attainable[1] + best.silhouetteCenterShift) / ctx.hh
+            ),
+            (-solution.attainable[0] + best.silhouetteCenterShift) / ctx.hh
+          ]
+        };
+      }
+      clamped.push(field);
+    }
+    solved[field] = solution.depth;
+  }
+  return {
+    nose: solved.noseShift,
+    mouth: solved.mouthShift,
+    clamped
+  };
+}
+function solveTurnModel(targets, landmarks, faceGrid, faceCenterX, faceHalfWidth, hairFront, headEdges) {
+  if (targets.headHalfWidth !== void 0 && targets.headHalfWidth <= faceHalfWidth) {
+    throw new TurnTargetError(
+      `auto-rig: turnTargets.headHalfWidth (${targets.headHalfWidth}) must be wider than the face plate's own half-width (${faceHalfWidth})`
+    );
+  }
+  const eyeRowY = landmarks.eye.length === 2 && landmarks.eye[0].y !== void 0 && landmarks.eye[1].y !== void 0 ? (landmarks.eye[0].y + landmarks.eye[1].y) / 2 : void 0;
+  const hairFrontLeadFraction = hairFront === void 0 || eyeRowY === void 0 ? void 0 : Math.max(
+    0,
+    Math.min(
+      1,
+      (hairFront.centerY + hairFront.cropH / 2 - eyeRowY) / hairFront.cropH
+    )
+  );
+  const ctx = {
+    landmarks,
+    faceGrid,
+    faceCenterX,
+    faceHalfWidth,
+    plateEdgeX: faceCenterX - faceHalfWidth,
+    // What this plate asks the turn for; each candidate caps it to its own
+    // shell — see TurnSolveContext.travel.
+    travel: headTurnTravel(faceHalfWidth),
+    headHalfWidth: targets.headHalfWidth,
+    // The pixels the shift fractions are fractions of. Without a measured head
+    // the face plate stands in for it — see TurnTargets.headHalfWidth.
+    hh: targets.headHalfWidth ?? faceHalfWidth,
+    silhouetteRatio: targets.silhouetteRatio,
+    // The sign is ignored (see TurnTargets.eyeShift) — taken here, once, so
+    // every downstream use already has the magnitude.
+    eyeShift: Math.abs(targets.eyeShift),
+    clampEyeShift: targets.defaulted.has("eyeShift"),
+    clampSilhouetteRatio: targets.defaulted.has("silhouetteRatio"),
+    hairFrontLeadFraction,
+    hairFrontSilhouette: hairFront === void 0 ? void 0 : { x: hairFront.x, cropW: hairFront.cropW, cropH: hairFront.cropH },
+    // A companion to a MEASURED headHalfWidth only — see its own doc.
+    headEdges: targets.headHalfWidth === void 0 ? void 0 : headEdges
+  };
+  const clamped = [];
+  const clampInto = (value, [lo, hi]) => Math.min(Math.max(value, lo), hi);
+  const pass = sweepTurnRadii(ctx);
+  if (pass.candidates.length === 0) {
+    return pass.offeredShift ? {
+      unreachable: true,
+      field: "eyeShift",
+      value: targets.eyeShift,
+      attainable: pass.offeredShift
+    } : {
+      unreachable: true,
+      field: "silhouetteRatio",
+      value: targets.silhouetteRatio,
+      // Two different bounds, not one number twice, and computed the
+      // same way regardless of which ratio was actually rejected: both
+      // are ratios a RENDER could have shown (the measure the caller's
+      // own number came from), the narrowest and the widest any radius
+      // could be fitted to, with every ratio between them one it can be
+      // fitted to exactly; see evaluateTurnCandidate, which clips each
+      // radius' own range to the domain `resolveTurnTargets` accepts
+      // before it gets here. Absent when that left every radius with
+      // nothing: no ratio a caller is allowed to ask for renders at all.
+      attainable: pass.heldRatioLower === Infinity || pass.heldRatioUpper === -Infinity ? void 0 : [pass.heldRatioLower, pass.heldRatioUpper]
+    };
+  }
+  const clusters = ratioClusters(pass.candidates);
+  const distanceTo = (c) => Math.max(
+    c.ratios[0] - targets.farEyeRatio,
+    targets.farEyeRatio - c.ratios[1],
+    0
+  );
+  let farEyeRatio = targets.farEyeRatio;
+  let cluster = clusters.find(
+    (c) => farEyeRatio >= c.ratios[0] - TURN_DEPTH_EPS && farEyeRatio <= c.ratios[1] + TURN_DEPTH_EPS
+  );
+  if (cluster === void 0) {
+    cluster = clusters.reduce(
+      (a, b) => distanceTo(b) < distanceTo(a) ? b : a
+    );
+    if (!targets.defaulted.has("farEyeRatio")) {
+      return {
+        unreachable: true,
+        field: "farEyeRatio",
+        value: targets.farEyeRatio,
+        attainable: cluster.ratios
+      };
+    }
+    farEyeRatio = clampInto(farEyeRatio, cluster.ratios);
+    clamped.push("farEyeRatio");
+  }
+  const best = fitTurnRadius(ctx, cluster.candidates, farEyeRatio);
+  if (Math.abs(best.ratio - farEyeRatio) > TURN_DEPTH_EPS) {
+    if (!targets.defaulted.has("farEyeRatio")) {
+      return {
+        unreachable: true,
+        field: "farEyeRatio",
+        value: targets.farEyeRatio,
+        attainable: cluster.ratios
+      };
+    }
+    if (!clamped.includes("farEyeRatio")) clamped.push("farEyeRatio");
+  }
+  if (!best.eye.reached) clamped.push("eyeShift");
+  if (best.silhouetteClamped) clamped.push("silhouetteRatio");
+  const eyeShift = (-best.eye.achieved + best.silhouetteCenterShift) / ctx.hh;
+  const features = solveFeatureDepths(ctx, targets, best, eyeShift);
+  if ("blocked" in features) {
+    return {
+      unreachable: true,
+      field: features.blocked,
+      value: targets[features.blocked],
+      attainable: features.attainable
+    };
+  }
+  return {
+    unreachable: false,
+    radius: best.radius,
+    holdBase: best.holdBase,
+    holdEdgeAt: best.holdEdgeAt,
+    travel: best.travel,
+    depths: { eye: best.eye.depth, nose: features.nose, mouth: features.mouth },
+    achieved: {
+      eyeShift,
+      farEyeRatio: best.ratio,
+      silhouetteRatio: best.renderedSilhouetteRatio
+    },
+    clamped: [...clamped, ...features.clamped]
+  };
+}
 var EYE_STACK_PREFIXES = ["eye_", "iris_", "pupil_", "highlight_"];
 var HAIR_FRONT_DEPTH = 0.1;
-var HAIR_BACK_DEPTH = -0.08;
 var NOD_TRAVEL = 30;
 var NOD_BEND = 0.5;
 var HAIR_BACK_NOD_DEPTH = -0.135;
 function headNodParallaxUnit(gridHalfHeight) {
   return gridHalfHeight * HEAD_CYLINDER_RADIUS_FACTOR * Math.sin(HEAD_TURN_MAX_DEG * NOD_BEND * (Math.PI / 180));
 }
-var FEATURE_DEPTH = {
+var FEATURE_NOD_DEPTH = {
   eye: 0.04,
   iris: 0.04,
   pupil: 0.04,
@@ -1857,16 +2607,23 @@ var FEATURE_DEPTH = {
   mouth_open: 0.04,
   nose: 0.08
 };
-var HAIR_FRONT_NOD_DEPTH = FEATURE_DEPTH.brow;
+var HAIR_FRONT_NOD_DEPTH = FEATURE_NOD_DEPTH.brow;
 function roleFamily(role) {
   return role.replace(/_[LR]$/, "");
 }
+function turnFamily(role) {
+  const family = roleFamily(role);
+  if (family === "nose") return "nose";
+  if (family === "mouth" || family === "mouth_open") return "mouth";
+  return "eye";
+}
 function featureParallaxBindings(role, options) {
   if (!options.hasNose) return [];
-  const depth = FEATURE_DEPTH[roleFamily(role)];
-  if (depth === void 0) return [];
+  const nodDepth = FEATURE_NOD_DEPTH[roleFamily(role)];
+  if (nodDepth === void 0) return [];
   const bindings = [];
-  const shiftX = depth * (options.parallaxUnit ?? 0);
+  const turnDepth = options.turnDepths?.[turnFamily(role)] ?? 0;
+  const shiftX = turnDepth * (options.parallaxUnit ?? 0);
   if (shiftX !== 0) {
     bindings.push({
       parameter: StandardParameter.AngleX,
@@ -1875,7 +2632,7 @@ function featureParallaxBindings(role, options) {
       to: shiftX
     });
   }
-  const shiftY = depth * (options.parallaxUnitY ?? 0);
+  const shiftY = nodDepth * (options.parallaxUnitY ?? 0);
   if (shiftY !== 0) {
     bindings.push({
       parameter: StandardParameter.AngleY,
@@ -1995,17 +2752,6 @@ function roleOwnBindings(spec, role, cropW, cropH, options) {
   if (role === "hair_front" || role === "hair_back") {
     const isFront = role === "hair_front";
     const parallax = [];
-    if (!isFront) {
-      const shiftX = HAIR_BACK_DEPTH * (options.parallaxUnit ?? 0);
-      if (shiftX !== 0) {
-        parallax.push({
-          parameter: StandardParameter.AngleX,
-          channel: "translateX",
-          from: -shiftX,
-          to: shiftX
-        });
-      }
-    }
     const frontDepth = options.hasNose ? HAIR_FRONT_NOD_DEPTH : 0;
     const shiftY = (isFront ? frontDepth : HAIR_BACK_NOD_DEPTH) * (options.parallaxUnitY ?? 0);
     if (shiftY !== 0) {
@@ -2039,35 +2785,68 @@ function bakeEyelidFoldWarp(mesh, parameter, creaseOffsetY, k) {
     ]
   };
 }
-var HAIR_BACK_BEND_RADIUS_FACTOR = 2.5;
-var HAIR_BACK_FAR_BULGE = 0.22;
-function bakeHairBackTurnWarp(mesh, parameter) {
-  let left = Infinity;
-  let right = -Infinity;
-  for (let i = 0; i < mesh.vertices.length; i += 2) {
-    left = Math.min(left, mesh.vertices[i]);
-    right = Math.max(right, mesh.vertices[i]);
+function plateReach(faceCenterX, faceHalfWidth, columnMapAt) {
+  let reach = 0;
+  for (const deg of HEAD_TURN_STOPS) {
+    reach = Math.max(
+      reach,
+      plateReachAt(columnMapAt(deg), faceCenterX, faceHalfWidth)
+    );
   }
-  const halfWidth = (right - left) / 2;
-  const radius = halfWidth * HAIR_BACK_BEND_RADIUS_FACTOR;
-  const bulge = HAIR_BACK_FAR_BULGE * halfWidth;
-  const DEG_TO_RAD = Math.PI / 180;
+  return reach;
+}
+function plateReachAt(map, faceCenterX, faceHalfWidth) {
+  let reach = 0;
+  for (const side of [-1, 1]) {
+    const dest = map.mapX(faceCenterX + side * faceHalfWidth);
+    reach = Math.max(reach, Math.abs(dest - faceCenterX));
+  }
+  return reach;
+}
+function bakeHairFrontSilhouetteWarp(mesh, partX, faceCenterX, faceHalfWidth, holdBase, holdEdgeAt, columnMapAt) {
+  if (holdEdgeAt(0) !== holdBase) {
+    throw new Error(
+      `auto-rig: bakeHairFrontSilhouetteWarp: holdEdgeAt(0) is ${holdEdgeAt(0)}, not the hold edge's own rest distance ${holdBase}, so the bangs would move in the rest pose`
+    );
+  }
+  const SIDES = [-1, 1];
   const keyforms = HEAD_TURN_STOPS.map((deg) => {
-    const theta = deg * DEG_TO_RAD;
-    const s = Math.sign(deg);
-    const turnFraction = Math.abs(deg) / HEAD_TURN_MAX_DEG;
-    const fullTheta = s * HEAD_TURN_MAX_DEG * DEG_TO_RAD;
-    const bulgeAtStop = bulge * deg / HEAD_TURN_MAX_DEG;
+    const map = columnMapAt(deg);
+    const requestedHoldEdge = holdEdgeAt(deg);
+    const plateDest = SIDES.map(
+      (side) => map.mapX(faceCenterX + side * faceHalfWidth)
+    );
+    const reached = plateReachAt(map, faceCenterX, faceHalfWidth);
+    if (requestedHoldEdge <= reached) {
+      const side = Math.abs(plateDest[1] - faceCenterX) > Math.abs(plateDest[0] - faceCenterX) ? 1 : -1;
+      throw new Error(
+        `auto-rig: bakeHairFrontSilhouetteWarp: at ${deg}\xB0 on the ${side < 0 ? "-x" : "+x"} side the hold edge sits ${requestedHoldEdge} from the face centre but the plate's edge maps to ${reached}, so the ramp between them would fold`
+      );
+    }
+    const holdEdge = deg === 0 ? [requestedHoldEdge, requestedHoldEdge] : SIDES.map(
+      (_side, idx) => Math.min(
+        requestedHoldEdge,
+        Math.abs(
+          map.warpedX[idx === 0 ? 0 : map.warpedX.length - 1] - faceCenterX
+        ) - HOLD_CLEARANCE
+      )
+    );
     const offsets = [];
     for (let i = 0; i < mesh.vertices.length; i += 2) {
-      const x = mesh.vertices[i];
-      const far = Math.max(0, -s * x / halfWidth);
-      const bend = far > 0 ? turnFraction * pinnedCylinderBend(x, radius, fullTheta) : pinnedCylinderBend(x, radius, theta);
-      offsets.push(bend - bulgeAtStop * far, 0);
+      const x = partX + mesh.vertices[i];
+      const target = hairFrontHoldTarget(
+        x,
+        faceCenterX,
+        faceHalfWidth,
+        holdBase,
+        holdEdge,
+        map
+      );
+      offsets.push(map.invertX(target) - x, 0);
     }
     return { value: deg, offsets };
   });
-  return { parameter, keyforms };
+  return { parameter: StandardParameter.AngleX, keyforms };
 }
 var HAIR_SWAY_TIP_FRACTION = 0.09;
 var HAIR_SWAY_CURL = 1.5;
@@ -2095,11 +2874,14 @@ function bakeHairSwayWarp(mesh, parameter, tipShift, range) {
     ]
   };
 }
-var HEAD_TURN_TRAVEL = 50;
+var HEAD_TURN_TRAVEL_RATIO = 0.25;
+function headTurnTravel(faceHalfWidth) {
+  return HEAD_TURN_TRAVEL_RATIO * faceHalfWidth;
+}
 var BODY_TURN_FOLLOW = 0.3;
 var HEAD_BREATH_BOB = -12;
 var BODY_BREATH_FOLLOW = 0.5;
-function generateIkiFromLayerSet(layers, canvas) {
+function generateIkiFromLayerSet(layers, canvas, options = {}) {
   validateLayerInputs(layers, canvas);
   const hasHair = layers.some((l) => l.role === "hair_front");
   const hasMouthOpen = layers.some((l) => l.role === "mouth_open");
@@ -2281,7 +3063,52 @@ function generateIkiFromLayerSet(layers, canvas) {
   };
   const faceCenterY = faceTransform.y;
   const halfH = Math.max(faceCenterY - unionMinY, unionMaxY - faceCenterY);
-  const parallaxUnit = headTurnParallaxUnit(halfW);
+  const faceHalfWidth = faceLayer.cropW / 2;
+  const hairFrontLayer = layers.find((l) => l.role === "hair_front");
+  const turn = hasNose ? solveTurnModel(
+    resolveTurnTargets(options.turnTargets),
+    turnLandmarks(layers),
+    faceGrid,
+    faceCenterX,
+    faceHalfWidth,
+    hairFrontLayer && (() => {
+      const t = bboxToTransform(
+        hairFrontLayer.bbox,
+        hairFrontLayer.canvasW,
+        hairFrontLayer.canvasH,
+        "hair_front"
+      );
+      return {
+        x: t.x,
+        centerY: t.y,
+        cropW: hairFrontLayer.cropW,
+        cropH: hairFrontLayer.cropH
+      };
+    })(),
+    options.headEdges
+  ) : void 0;
+  if (turn?.unreachable) {
+    throw new TurnTargetError(
+      turn.attainable === void 0 ? (
+        // Only a silhouette can land here: nothing the field's own accepted
+        // range allows renders on this layer set, so there is no interval to
+        // offer instead — see `silhouetteMiss` in evaluateTurnCandidate.
+        `auto-rig: turnTargets.${turn.field} ${turn.value} is unreachable for this layer set, and so is every ${turn.field} in [${SILHOUETTE_RATIO_MIN}, ${TURN_RATIO_MAX}]`
+      ) : `auto-rig: turnTargets.${turn.field} ${turn.value} is unreachable for this layer set (attainable ${turn.attainable[0]}\u2026${turn.attainable[1]})`
+    );
+  }
+  if (turn) {
+    options.onTurnSolved?.({
+      radius: turn.radius,
+      holdBase: turn.holdBase,
+      depths: turn.depths,
+      achieved: turn.achieved,
+      clamped: turn.clamped
+    });
+  }
+  const faceRadius = turn?.radius ?? halfW * HEAD_CYLINDER_RADIUS_FACTOR;
+  const headTravel = turn?.travel ?? headTurnTravel(faceHalfWidth);
+  const parallaxUnit = headTurnParallaxUnit(faceRadius);
   const parallaxUnitY = headNodParallaxUnit(halfH);
   const faceBottom = faceTransform.y - faceCropH / 2;
   const neckPivot = {
@@ -2294,26 +3121,27 @@ function generateIkiFromLayerSet(layers, canvas) {
     StandardParameter.AngleX,
     StandardParameter.AngleY,
     faceCenterX,
-    faceCenterY
+    faceCenterY,
+    faceRadius,
+    headTravel
   );
   const deformers = [
     // headDeformer: rigid matrix rotating/translating the whole head about the
-    // neck pivot; bindings mirror sample-model.ts exactly.
+    // neck pivot. Same bindings as sample-model.ts apart from the turn, which
+    // moves the face inside the head rather than the head itself (see below).
     {
       id: "headDeformer",
       pivot: neckPivot,
       bindings: [
-        // The turn is a pure yaw: no roll rides on AngleX. The sample model's
-        // ±6° "lean into the turn" was tried here and dropped — rotating about
-        // the neck pivot swings the crown (~500px above it) far more than the
-        // chin, so the top of the head appeared to lunge ahead of the face on
-        // every turn. Roll is AngleZ's job, below.
-        {
-          parameter: StandardParameter.AngleX,
-          channel: "translateX",
-          from: -HEAD_TURN_TRAVEL,
-          to: HEAD_TURN_TRAVEL
-        },
+        // No AngleX binding: the turn moves NOTHING rigidly. Its sideways
+        // travel is baked into faceWarp's own grid (see
+        // bakeHeadTurnGridWarp2DCentered's `travel`) so the face slides inside
+        // a silhouette the bangs hold; a translate here would take the hair
+        // shell with it. Nor is the turn a roll — the sample model's ±6° "lean
+        // into the turn" was tried here and dropped, since rotating about the
+        // neck pivot swings the crown (~500px above it) far more than the chin,
+        // so the top of the head appeared to lunge ahead of the face on every
+        // turn. Roll is AngleZ's job, below.
         // Nod: a vertical translate only. No rotate — a pitch expressed as a
         // rigid rotation would sum with the AngleZ roll below at diagonal
         // poses, collapsing pitch into roll.
@@ -2366,12 +3194,13 @@ function generateIkiFromLayerSet(layers, canvas) {
       id: "bodyDeformer",
       pivot: { x: bt.x, y: bt.y - bodyLayer.cropH / 2 },
       bindings: [
-        // Low-weight follow of the turn, same direction as the head.
+        // Low-weight follow of the turn, same direction as the face's own
+        // slide — the only rigid part of the travel left.
         {
           parameter: StandardParameter.AngleX,
           channel: "translateX",
-          from: -BODY_TURN_FOLLOW * HEAD_TURN_TRAVEL,
-          to: BODY_TURN_FOLLOW * HEAD_TURN_TRAVEL
+          from: -BODY_TURN_FOLLOW * headTravel,
+          to: BODY_TURN_FOLLOW * headTravel
         },
         // Breath: follow the head's bob, same direction, half amplitude.
         {
@@ -2404,7 +3233,8 @@ function generateIkiFromLayerSet(layers, canvas) {
       hasMouthOpen,
       parallaxUnit,
       parallaxUnitY,
-      hasNose
+      hasNose,
+      turnDepths: turn?.depths
     });
     const deformerId = spec.deformer === "none" ? void 0 : spec.deformer;
     if (spec.mesh) {
@@ -2426,6 +3256,7 @@ function generateIkiFromLayerSet(layers, canvas) {
       if ((role === "hair_front" || role === "hair_back") && hasHair) {
         let tipShift = HAIR_SWAY_TIP_FRACTION * cropH;
         let leadWarp;
+        let silhouetteWarp;
         if (role === "hair_front") {
           const shift = HAIR_FRONT_DEPTH * parallaxUnit;
           const headroom = Math.min(
@@ -2442,6 +3273,17 @@ function generateIkiFromLayerSet(layers, canvas) {
             shift,
             HEAD_TURN_MAX_DEG
           );
+          const columnMapAt = (deg) => turnColumnMap(faceGrid, faceCenterX, faceRadius, deg, headTravel);
+          const holdBase = turn?.holdBase ?? plateReach(faceCenterX, faceHalfWidth, columnMapAt) + HOLD_CLEARANCE;
+          silhouetteWarp = bakeHairFrontSilhouetteWarp(
+            mesh,
+            t.x,
+            faceCenterX,
+            faceHalfWidth,
+            holdBase,
+            turn?.holdEdgeAt ?? (() => holdBase),
+            columnMapAt
+          );
         }
         part.warps = [
           bakeHairSwayWarp(
@@ -2456,13 +3298,8 @@ function generateIkiFromLayerSet(layers, canvas) {
             tipShift,
             HAIR_SWAY_RANGE
           ),
-          ...leadWarp ? [leadWarp] : []
-        ];
-      }
-      if (role === "hair_back") {
-        part.warps = [
-          ...part.warps ?? [],
-          bakeHairBackTurnWarp(mesh, StandardParameter.AngleX)
+          ...leadWarp ? [leadWarp] : [],
+          ...silhouetteWarp ? [silhouetteWarp] : []
         ];
       }
       if (spec.eyeSide !== void 0) {
@@ -2542,6 +3379,7 @@ export {
   AddPart,
   AddPhysicsRig,
   CaptureGridKeyform,
+  DEFAULT_TURN_TARGETS,
   DeleteDeformer,
   DeletePart,
   DeletePhysicsRig,
@@ -2561,6 +3399,7 @@ export {
   SetPartTransform,
   SetPartWidth,
   SetPhysicsRig,
+  TurnTargetError,
   UV_INSET_PX,
   captureBindingEndpoint,
   computeGridOffsets,