@rig-c/parts 1.32.0 → 1.34.0

package/src/turn.ts

@@ -29,6 +29,7 @@
  * one piece. Pure: no file, no clock.
  */
 import { computeWorldTransforms, toBoneLocalVector, toWorld, type BoneTransform } from './coords.ts';
+import { type Problem, refuseIfAny } from './errors.ts';
 import { pyRound } from './round.ts';
 
 /**
@@ -108,8 +109,6 @@ export const FACE_DEFORM_FRACTIONS = {
   tilt_topknot_y: 0.5,
   /** Forehead bang forward parallax per degree of yaw (`W/deg`; `-3.50 px` at `+15°` on `W = 106`). */
   turn_bang_parallax_x: -(3.5 / 15) / 106,
-  /** Share of the cheek yaw horizontal field carried by lower `hair_back` (`0.90×` of `dxCheek`). */
-  turn_hair_back_cheek_x: 0.9,
   /** Rear bun counter-parallax per degree of yaw (`W/deg`; `+8.00 px` at `+15°` on `W = 106`). */
   turn_bun_counter_x: 8.0 / 15 / 106,
   /** Rear hairpin counter-parallax per degree of yaw (`W/deg`; `+6.00 px` at `+15°` on `W = 106`). */
@@ -143,7 +142,6 @@ export const FACE_DEFORM_RANGES: Readonly<Record<FaceDeformKey, readonly [number
   tilt_ear_y: [0, 1.5],
   tilt_topknot_y: [0, 1.5],
   turn_bang_parallax_x: [-0.015, 0],
-  turn_hair_back_cheek_x: [0, 1.5],
   turn_bun_counter_x: [0, 0.02],
   turn_hairpin_counter_x: [0, 0.02],
   turn_ear_x: [0, 1.5],
@@ -165,13 +163,93 @@ export function resolveFaceDeformFractions(overrides?: Readonly<Partial<FaceDefo
   return out;
 }
 
-/** `config.turn`: the pivot depth, each carried part's See-through `depth_median`, and optional face surface deform overrides. */
+/**
+ * Issue #472: the rated band of a single face plate — yaw `±15°`, pitch `±12°`.
+ * Beyond this band on one plate, the foreshortened far eye runs out of cheek to
+ * sit on; going further takes an alternate face set (`assemble.alternates`),
+ * whose swap threshold is this band edge.
+ */
+export const FACE_RATED_YAW_BAND = 15;
+export const FACE_RATED_PITCH_BAND = 12;
+export const FACE_RATED_BAND = { yaw: FACE_RATED_YAW_BAND, pitch: FACE_RATED_PITCH_BAND } as const;
+
+/**
+ * Issue #477: allowed `[min, max]` range (in rig px) for an authored ear
+ * `derive.depth` in `turn` or `tilt`. Ears sit at or behind the head pivot
+ * (`depth <= 0`, where `-14` moves the ears slightly against the face turn); a
+ * depth outside `[-50, 0]` is refused by `CONFIG_TURN_EAR_DEPTH_RANGE`.
+ */
+export const EAR_DEPTH_RANGE: readonly [number, number] = [-50, 0];
+
+/** Default part names belonging to the `head` subtree when computing the head-only turn pivot (issue #478). */
+export const DEFAULT_HEAD_TURN_PARTS: readonly string[] = [
+  'face',
+  'nose',
+  'mouth',
+  'eyewhite_r',
+  'eyewhite_l',
+  'iris_r',
+  'iris_l',
+  'irides_r',
+  'irides_l',
+  'lash_r',
+  'lash_l',
+  'eyelash_r',
+  'eyelash_l',
+  'brow_r',
+  'brow_l',
+  'eyebrow_r',
+  'eyebrow_l',
+  'ear_r',
+  'ear_l',
+  'ears',
+  'hair_front',
+  'hair_back',
+  'hairpin',
+  'headwear',
+  'bun',
+  'topknot',
+];
+
+/** `config.turn`: the pivot depth, each carried part's See-through `depth_median`, optional head-only pivot override, optional curved-surface cylinder radius, optional rated band, and optional face surface deform overrides. */
 export interface TurnSpec {
   pivot: number;
   depths: Record<string, number>;
+  head?: { pivot?: number; radius?: number };
+  surface?: { radius?: number };
+  radius?: number;
+  band?: number | { yaw?: number; pitch?: number };
   deform?: Partial<FaceDeformFractions>;
 }
 
+/**
+ * Issue #479: the cylinder radius `R` (in rig px) for the curved-surface face
+ * yaw projection — `spec.surface.radius`, `spec.radius`, or `spec.head.radius`
+ * when declared, defaulting to half the face plate's opaque width (`W / 2`).
+ */
+export function turnSurfaceRadius(spec: TurnSpec | null | undefined, W: number): number {
+  const r = spec?.surface?.radius ?? spec?.radius ?? spec?.head?.radius;
+  return typeof r === 'number' && Number.isFinite(r) && r > 0 ? r : W / 2;
+}
+
+/**
+ * Issue #479: horizontal displacement `Δx` of a point at rest offset `x`
+ * (`hx - X0`) on a vertical cylinder of radius `radius` turned by `deg`
+ * degrees of yaw (`θ = deg · π / 180`), with the rotated surface angle clamped
+ * to the visible limb `[-π/2, π/2]`. At the leading limb (`u = -sign(deg)`),
+ * `Δx = 0` so the leading outline holds fixed; across the interior (`|u| < 1`),
+ * points slide toward the leading side (`-radius · sin θ` at `x = 0`), widening
+ * the trailing cheek and foreshortening the leading cheek.
+ */
+export function cylinderYawDx(x: number, deg: number, radius: number): number {
+  if (deg === 0 || !(radius > 0)) return 0;
+  const theta = (deg * Math.PI) / 180;
+  const u = Math.max(-1, Math.min(1, x / radius));
+  const phi0 = Math.asin(u);
+  const phi1 = Math.max(-Math.PI / 2, Math.min(Math.PI / 2, phi0 - theta));
+  return radius * (Math.sin(phi1) - u);
+}
+
 /** One carried part: its depth and the fraction of the control's offset it travels. */
 export interface TurnFraction {
   part: string;
@@ -218,6 +296,48 @@ export function turnPivot(rows: ReadonlyArray<{ depth: number; area: number }>):
   return a > 0 ? pyRound(ad / a, TURN_PLACES) : null;
 }
 
+/**
+ * Issue #478: the head-only turn pivot — either `spec.head.pivot` when
+ * declared, or the `opaque_px`-weighted mean of `spec.depths` restricted to the
+ * `head` subtree parts (`headParts`). Neck and torso parts are excluded so a
+ * front-heavy body does not pull the head's rotation axis forward of the skull.
+ */
+export function headTurnPivot(
+  spec: TurnSpec,
+  headParts: ReadonlySet<string> = new Set(DEFAULT_HEAD_TURN_PARTS),
+  partAreas?: Readonly<Record<string, number>>,
+): number | null {
+  if (typeof spec.head?.pivot === 'number' && Number.isFinite(spec.head.pivot)) {
+    return pyRound(spec.head.pivot, TURN_PLACES);
+  }
+  const headEntries = Object.entries(spec.depths).filter(([part, d]) => headParts.has(part) && typeof d === 'number' && Number.isFinite(d));
+  const entries = headEntries.length > 0 ? headEntries : Object.entries(spec.depths).filter(([, d]) => typeof d === 'number' && Number.isFinite(d));
+  return turnPivot(entries.map(([part, depth]) => ({ depth, area: partAreas?.[part] ?? 1 })));
+}
+
+/**
+ * Issue #478: a head-mounted part's turn fraction `(headPivot − depth) / (headPivot − headNearest)`
+ * about the head-only pivot. Parts behind `headPivot` (`hair_back`, rear `hairpin`)
+ * receive a negative fraction and move opposite to the face and irises.
+ */
+export function headTurnFraction(
+  spec: TurnSpec,
+  part: string,
+  headParts: ReadonlySet<string> = new Set(DEFAULT_HEAD_TURN_PARTS),
+  partAreas?: Readonly<Record<string, number>>,
+): number | null {
+  const depth = spec.depths[part];
+  if (typeof depth !== 'number' || !Number.isFinite(depth)) return null;
+  const pivot = headTurnPivot(spec, headParts, partAreas);
+  const headDepths: Record<string, number> = {};
+  for (const [p, d] of Object.entries(spec.depths)) {
+    if (headParts.has(p) && typeof d === 'number' && Number.isFinite(d)) headDepths[p] = d;
+  }
+  const nearest = turnNearest(Object.keys(headDepths).length > 0 ? headDepths : spec.depths);
+  if (pivot === null || nearest === null || !(pivot > nearest.depth)) return null;
+  return turnFraction(pivot, nearest.depth, depth);
+}
+
 /** The leaf bone that carries `part`'s share of `bone` under the turn: an identity child of `bone`, so it follows everything `bone` does. */
 export function turnTwin(part: string, bone: string): string {
   return `${TURN_BONE}_${part}_${bone}`;
@@ -257,7 +377,10 @@ export function evalPitchFaceSurface(
 
 /**
  * Evaluate the yaw (`turn`) surface deformation field `(dx, dy)` in `head`
- * space at `(hx, hy)` for `deg` degrees of yaw.
+ * space at `(hx, hy)` for `deg` degrees of yaw (issue #479: cylinder projection
+ * of radius `radius`, default `W / 2`, with lower-face jaw taper so the leading
+ * jaw edge holds and the trailing cheek widens; `flatYawTable: true` restores
+ * the flat yaw table for the Bar 4 negative control or explicit fraction overrides).
  */
 export function evalYawFaceSurface(
   hx: number,
@@ -268,16 +391,28 @@ export function evalYawFaceSurface(
   X0: number,
   Y0: number,
   f: Readonly<FaceDeformFractions> = FACE_DEFORM_FRACTIONS,
+  radius?: number,
+  flatYawTable = false,
 ): [number, number] {
   if (deg === 0) return [0, 0];
   const s = Math.sign(deg);
   const ux = Math.max(-1.35, Math.min(1.35, (hx - X0) / (W / 2)));
   const uy = Math.max(-1.35, Math.min(1.35, (hy - Y0) / (H / 2)));
-  const uLead = Math.min(1.2, Math.max(0, -s * ux));
-  const uTrail = Math.min(1.2, Math.max(0, s * ux));
-  const fracXPerDeg = unmult(f.turn_mid_x) + unmult(f.turn_lead_compress_x) * Math.pow(uLead, 1.2) + unmult(f.turn_trail_shift_x) * Math.pow(uTrail, 1.2);
   const fracYPerDeg = unmult(f.turn_cheek_arch_y) * (-s * ux) * Math.max(0, 1 - Math.abs(uy));
-  return [FACE_DEFORM_MULT * deg * W * fracXPerDeg, FACE_DEFORM_MULT * deg * H * fracYPerDeg];
+  const dy = FACE_DEFORM_MULT * deg * H * fracYPerDeg;
+  if (flatYawTable) {
+    const uLead = Math.min(1.2, Math.max(0, -s * ux));
+    const uTrail = Math.min(1.2, Math.max(0, s * ux));
+    const fracXPerDeg = unmult(f.turn_mid_x) + unmult(f.turn_lead_compress_x) * Math.pow(uLead, 1.2) + unmult(f.turn_trail_shift_x) * Math.pow(uTrail, 1.2);
+    return [FACE_DEFORM_MULT * deg * W * fracXPerDeg, dy];
+  }
+  const R = radius !== undefined && radius > 0 ? radius : W / 2;
+  const rawDx = cylinderYawDx(hx - X0, deg, R);
+  const absUx = Math.abs((hx - X0) / (W / 2));
+  const tOutline = Math.max(0, Math.min(1, (absUx - 0.7) / (1.0 - 0.7)));
+  const wOutline = 1 - tOutline * tOutline * (3 - 2 * tOutline);
+  const dx = rawDx * wOutline;
+  return [dx, dy];
 }
 
 export interface FaceSurfaceDeformOptions {
@@ -291,6 +426,37 @@ export interface FaceSurfaceDeformOptions {
   opaqueHeight?: number;
   /** Recipe overrides for {@link FACE_DEFORM_FRACTIONS}. */
   overrides?: Readonly<Partial<FaceDeformFractions>> | null;
+  /**
+   * Issue #472: true when `assemble.alternates` declares an alternate face set
+   * for the overflow beyond `±15°` yaw / `±12°` pitch. When false or absent,
+   * any `yaw` / `pitch` slider constraints on the rig are preceded by clamping
+   * transform constraints holding the dial bones to `[-15, 15]` and `[-12, 12]`.
+   */
+  hasAlternateFaceSet?: boolean;
+  /** Issue #478: `config.turn` holding `pivot`, `depths` and optional `head.pivot` / `radius`. */
+  turn?: TurnSpec | null;
+  /** Issue #478: each part's `opaque_px` from `parts.json` for weighting the head-only pivot. */
+  partAreas?: Readonly<Record<string, number>>;
+  /**
+   * Issue #478: when true, refuse by `CONFIG_TURN_REQUIRED` if `turn` is absent
+   * or missing `depths` for attached `face`, `hair_front`, or `hair_back`.
+   */
+  requireTurn?: boolean;
+  /**
+   * Issue #478 Bar 4 negative control: when true, flip the back-layer fraction
+   * sign so `hair_back` and `hairpin` move with the face instead of against it.
+   */
+  flipBackLayerSignMutant?: boolean;
+  /**
+   * Issue #479: explicit cylinder radius override in rig px (defaults to
+   * `turnSurfaceRadius(turn, W)` = `W / 2`).
+   */
+  surfaceRadius?: number;
+  /**
+   * Issue #479 Bar 4 negative control: when true, restore the flat yaw table
+   * instead of the cylinder projection.
+   */
+  flatYawTableMutant?: boolean;
 }
 
 interface DeformWeight {
@@ -328,7 +494,7 @@ interface DeriveSpec {
 
 interface SliderKey {
   t: number;
-  v?: number[];
+  v?: number[] | Record<string, number[]>;
   derive?: DeriveSpec;
 }
 
@@ -390,14 +556,16 @@ function buildFaceGrid(width: number, height: number): { points: Array<[number,
 /**
  * Promote the `face` region on `head` to a 5×5 grid mesh and populate the
  * `tilt` and `turn` slider animations with the Set B ×2.5 face and hair mesh
- * deform timelines and ear/topknot tracks (issue #436). When `motion` holds
- * neither `tilt` nor `turn` with slider `derive` keys, neither `rig` nor
- * `motion` is touched.
+ * deform timelines, feature field-sampled tracks (#468) and ear/topknot tracks
+ * (issues #436, #477, #478). When `motion` holds neither `tilt` nor `turn` with
+ * slider `derive` keys, neither `rig` nor `motion` is touched.
  */
 export function applyFaceSurfaceDeform(
   rig: {
     bones: Array<{ name: string; parent?: string; x: number; y: number; rotation?: number; length?: number; inherit?: string }>;
+    slots?: Array<{ name: string; bone: string }>;
     skins: { default: Record<string, Record<string, DeformMeshAttachment | DeformRegionAttachment>> };
+    constraints?: Array<Record<string, unknown>>;
     invariants?: Record<string, unknown>;
   },
   motion: {
@@ -413,17 +581,141 @@ export function applyFaceSurfaceDeform(
     (rawTilt?.tracks?.some((tr) => tr.keys?.some((k) => k.derive !== undefined)) ?? false) ||
     (rawTurn?.tracks?.some((tr) => tr.keys?.some((k) => k.derive !== undefined)) ?? false);
   if (!hasDerive) return;
-  const tiltAnim = rawTilt === undefined ? undefined : structuredClone(rawTilt);
-  const turnAnim = rawTurn === undefined ? undefined : structuredClone(rawTurn);
-  if (tiltAnim !== undefined) motion.animations.tilt = tiltAnim;
-  if (turnAnim !== undefined) motion.animations.turn = turnAnim;
 
   const isOpts =
     options !== undefined &&
     options !== null &&
-    ('imageWidth' in options || 'imageHeight' in options || 'opaqueWidth' in options || 'opaqueHeight' in options || 'overrides' in options);
+    ('imageWidth' in options ||
+      'imageHeight' in options ||
+      'opaqueWidth' in options ||
+      'opaqueHeight' in options ||
+      'overrides' in options ||
+      'hasAlternateFaceSet' in options ||
+      'turn' in options ||
+      'partAreas' in options ||
+      'requireTurn' in options ||
+      'flipBackLayerSignMutant' in options ||
+      'surfaceRadius' in options ||
+      'flatYawTableMutant' in options);
   const opts: FaceSurfaceDeformOptions = isOpts ? (options as FaceSurfaceDeformOptions) : { overrides: options as Readonly<Partial<FaceDeformFractions>> | null | undefined };
+
+  // Issue #477 & #478: refuse an out-of-range ear derive.depth or missing config.turn by name before touching rig or motion.
+  const preProblems: Problem[] = [];
+  if (opts.requireTurn === true) {
+    if (opts.turn === undefined || opts.turn === null) {
+      preProblems.push({
+        code: 'CONFIG_TURN_REQUIRED',
+        object: 'config.turn',
+        detail: 'is absent and required when motion.animations_from carries a turn or tilt slider animation with derive keys; copy the turn block propose drafted into config.turn so the head pivot and each head part\'s depth are declared',
+      });
+    } else {
+      for (const reqPart of ['face', 'hair_front', 'hair_back'] as const) {
+        if (rig.skins.default[reqPart]?.[reqPart] !== undefined && !(reqPart in opts.turn.depths)) {
+          preProblems.push({
+            code: 'CONFIG_TURN_REQUIRED',
+            object: `config.turn.depths.${reqPart}`,
+            detail: `is absent and required when motion.animations_from carries a turn or tilt slider animation with derive keys and "${reqPart}" is attached; include "${reqPart}"'s See-through depth_median in config.turn.depths so the head pivot and fraction are defined`,
+          });
+        }
+      }
+    }
+  }
+  const [earLo, earHi] = EAR_DEPTH_RANGE;
+  for (const [animName, anim] of [
+    ['tilt', rawTilt],
+    ['turn', rawTurn],
+  ] as const) {
+    if (anim === undefined) continue;
+    anim.tracks.forEach((tr, ti) => {
+      const isEarTrack = tr.group === 'ears' || tr.bone === 'ear_r' || tr.bone === 'ear_l';
+      if (!isEarTrack) return;
+      tr.keys.forEach((k, ki) => {
+        const d = k.derive?.depth;
+        if (typeof d === 'number') {
+          if (d < earLo || d > earHi) {
+            preProblems.push({
+              code: 'CONFIG_TURN_EAR_DEPTH_RANGE',
+              object: `animations.${animName}.tracks[${ti}].keys[${ki}].derive.depth`,
+              detail: `is ${d}; an ear depth in [${earLo}, ${earHi}] (at or behind the head pivot) is required`,
+            });
+          }
+        } else if (d !== undefined && typeof d === 'object') {
+          for (const [member, val] of Object.entries(d)) {
+            if (typeof val === 'number' && (val < earLo || val > earHi)) {
+              preProblems.push({
+                code: 'CONFIG_TURN_EAR_DEPTH_RANGE',
+                object: `animations.${animName}.tracks[${ti}].keys[${ki}].derive.depth.${member}`,
+                detail: `is ${val}; an ear depth in [${earLo}, ${earHi}] (at or behind the head pivot) is required`,
+              });
+            }
+          }
+        }
+      });
+    });
+  }
+  refuseIfAny(preProblems);
+
+  const tiltAnim = rawTilt === undefined ? undefined : structuredClone(rawTilt);
+  const turnAnim = rawTurn === undefined ? undefined : structuredClone(rawTurn);
+  if (tiltAnim !== undefined) motion.animations.tilt = tiltAnim;
+  if (turnAnim !== undefined) motion.animations.turn = turnAnim;
+
   const f = resolveFaceDeformFractions(opts.overrides);
+  const hasFlatYawOverride =
+    opts.overrides !== undefined &&
+    opts.overrides !== null &&
+    (opts.overrides.turn_mid_x !== undefined ||
+      opts.overrides.turn_lead_compress_x !== undefined ||
+      opts.overrides.turn_trail_shift_x !== undefined);
+  const useFlatYaw = opts.flatYawTableMutant === true || hasFlatYawOverride;
+
+  // Issue #472: when no alternate face set is declared, clamp dial bones to the single-plate rated band (±15° yaw, ±12° pitch).
+  if (!opts.hasAlternateFaceSet && Array.isArray(rig.constraints)) {
+    const nextConstraints: Array<Record<string, unknown>> = [];
+    const existingNames = new Set(rig.constraints.map((c) => c.name));
+    const makeClampConstraint = (name: string, bone: string, prop: unknown, band: number): Record<string, unknown> => {
+      const useX = prop === 'x' || prop === 'translatex';
+      const key = useX ? 'x' : 'rotate';
+      const mixKey = useX ? 'mixX' : 'mixRotate';
+      return {
+        name,
+        type: 'transform',
+        source: bone,
+        bones: [bone],
+        localSource: true,
+        localTarget: true,
+        clamp: true,
+        properties: {
+          [key]: {
+            offset: -band,
+            to: {
+              [key]: {
+                offset: -band,
+                max: band,
+                scale: 1,
+              },
+            },
+          },
+        },
+        [mixKey]: 1,
+      };
+    };
+    for (const c of rig.constraints) {
+      if (c.type === 'slider' && typeof c.bone === 'string') {
+        const isYaw = c.name === 'yaw' || c.animation === 'turn';
+        const isPitch = c.name === 'pitch' || c.animation === 'tilt';
+        if (isYaw && !existingNames.has('yaw_clamp')) {
+          existingNames.add('yaw_clamp');
+          nextConstraints.push(makeClampConstraint('yaw_clamp', c.bone, c.property, FACE_RATED_YAW_BAND));
+        } else if (isPitch && !existingNames.has('pitch_clamp')) {
+          existingNames.add('pitch_clamp');
+          nextConstraints.push(makeClampConstraint('pitch_clamp', c.bone, c.property, FACE_RATED_PITCH_BAND));
+        }
+      }
+      nextConstraints.push(c);
+    }
+    rig.constraints = nextConstraints;
+  }
 
   const faceSlot = rig.skins.default.face;
   if (faceSlot === undefined || faceSlot.face === undefined) return;
@@ -434,13 +726,15 @@ export function applyFaceSurfaceDeform(
   let faceRegX = -1;
   let faceRegY = 49;
 
+  const faceBone = rig.slots?.find((s) => s.name === 'face')?.bone ?? (rig.bones.some((b) => b.name === 'turn_face_head') ? 'turn_face_head' : 'head');
+
   if (!('type' in faceAtt)) {
     faceRegX = faceAtt.x;
     faceRegY = faceAtt.y;
     const grid = buildFaceGrid(faceW, faceH);
     const faceWeights: DeformWeight[][] = grid.points.map(([px, py]) => [
       {
-        bone: 'head',
+        bone: faceBone,
         x: pyRound(faceRegX - faceW / 2 + px, 6),
         y: pyRound(faceRegY + faceH / 2 - py, 6),
         weight: 1,
@@ -470,8 +764,8 @@ export function applyFaceSurfaceDeform(
       sumY += w[0]?.y ?? 0;
     }
     if (faceAtt.weights.length > 0) {
-      faceRegX = Math.round(sumX / faceAtt.weights.length);
-      faceRegY = Math.round(sumY / faceAtt.weights.length);
+      faceRegX = Math.round((sumX / faceAtt.weights.length) * 2) / 2;
+      faceRegY = Math.round((sumY / faceAtt.weights.length) * 2) / 2;
     }
   }
 
@@ -479,9 +773,13 @@ export function applyFaceSurfaceDeform(
   const H = opts.opaqueHeight ?? faceH - 8;
   const X0 = faceRegX;
   const Y0 = faceRegY - 1;
+  const cylRadius =
+    opts.surfaceRadius !== undefined && Number.isFinite(opts.surfaceRadius) && opts.surfaceRadius > 0
+      ? opts.surfaceRadius
+      : turnSurfaceRadius(opts.turn, W);
 
   const boneOrder = new Map<string, number>(rig.bones.map((b, i) => [b.name, i]));
-  for (const slotName of ['hair_front', 'hair_back']) {
+  for (const slotName of ['hair_front', 'hair_back', 'hairpin']) {
     const slotObj = rig.skins.default[slotName];
     const att = slotObj?.[slotName];
     if (att !== undefined && 'type' in att) {
@@ -531,8 +829,31 @@ export function applyFaceSurfaceDeform(
   };
 
   const boneMap = new Map(rig.bones.map((b) => [b.name, b]));
+  const referencedGroups = new Set<string>();
+  for (const anim of [tiltAnim, turnAnim]) {
+    for (const tr of anim?.tracks ?? []) {
+      if (tr.group !== undefined) referencedGroups.add(tr.group);
+    }
+  }
+  const defaultGroups: Readonly<Record<string, readonly string[]>> = {
+    features: ['eye_r', 'eye_l', 'brow_r', 'brow_l', 'pupil_r', 'pupil_l', 'eyelash_r', 'eyelash_l', 'eyebrow_r', 'eyebrow_l', 'nose', 'mouth'],
+    ears: ['ear_r', 'ear_l'],
+    bangs: ['bang_r0', 'bang_c0', 'bang_l0'].map((b) => (boneMap.has(`${b}_ctl`) ? `${b}_ctl` : b)),
+    topknot: ['bun_ctl', 'hairpin', 'headwear'],
+  };
+  for (const g of referencedGroups) {
+    if (motion.groups?.[g] === undefined && defaultGroups[g] !== undefined) {
+      const members = defaultGroups[g].filter((b) => boneMap.has(b));
+      if (members.length > 0) {
+        motion.groups ??= {};
+        motion.groups[g] = members;
+      }
+    }
+  }
+
   const evalDeriveKey = (boneName: string, k: SliderKey): number => {
     if (Array.isArray(k.v)) return k.v[0] ?? 0;
+    if (k.v !== undefined && typeof k.v === 'object') return k.v[boneName]?.[0] ?? 0;
     const d = k.derive;
     if (d === undefined) return 0;
     const b = boneMap.get(boneName);
@@ -546,27 +867,44 @@ export function applyFaceSurfaceDeform(
   };
 
   const mapParent: Readonly<Record<string, string>> = {
-    bang_r0: 'bang_r0_ctl',
-    bang_r1: 'bang_r0_ctl',
-    bang_c0: 'bang_c0_ctl',
-    bang_c1: 'bang_c0_ctl',
-    bang_l0: 'bang_l0_ctl',
-    bang_l1: 'bang_l0_ctl',
-    bun: 'bun_ctl',
+    bang_r0: boneMap.has('bang_r0_ctl') ? 'bang_r0_ctl' : 'bang_r0',
+    bang_r1: boneMap.has('bang_r0_ctl') ? 'bang_r0_ctl' : 'bang_r0',
+    bang_c0: boneMap.has('bang_c0_ctl') ? 'bang_c0_ctl' : 'bang_c0',
+    bang_c1: boneMap.has('bang_c0_ctl') ? 'bang_c0_ctl' : 'bang_c0',
+    bang_l0: boneMap.has('bang_l0_ctl') ? 'bang_l0_ctl' : 'bang_l0',
+    bang_l1: boneMap.has('bang_l0_ctl') ? 'bang_l0_ctl' : 'bang_l0',
+    bun: boneMap.has('bun_ctl') ? 'bun_ctl' : 'bun',
   };
 
   const getBoneDeltaAtTime = (tracks: readonly SliderTrack[], t: number, boneName: string): [number, number] => {
-    const driver = mapParent[boneName] ?? boneName;
+    const drivers = new Set<string>();
+    let cur: string | undefined = boneName;
+    const visited = new Set<string>();
+    while (cur !== undefined && !visited.has(cur) && cur !== 'head' && cur !== 'turn_face_head' && cur !== 'root') {
+      visited.add(cur);
+      if (!cur.startsWith('turn_')) {
+        drivers.add(mapParent[cur] ?? cur);
+      }
+      cur = boneMap.get(cur)?.parent;
+    }
+    if (drivers.size === 0) {
+      const stripped = boneName.replace(/^turn_[^_]+_/, '');
+      if (stripped !== 'head' && stripped !== 'root') {
+        drivers.add(mapParent[stripped] ?? stripped);
+      }
+    }
     let dx = 0;
     let dy = 0;
-    for (const tr of tracks) {
-      const inGroup = tr.group !== undefined && (motion.groups?.[tr.group]?.includes(driver) ?? false);
-      if (tr.bone !== driver && !inGroup) continue;
-      const key = tr.keys.find((k) => Math.abs(k.t - t) < 1e-6);
-      if (key === undefined) continue;
-      const val = evalDeriveKey(driver, key);
-      if (tr.property === 'translatex') dx = val;
-      if (tr.property === 'translatey') dy = val;
+    for (const driver of drivers) {
+      for (const tr of tracks) {
+        const inGroup = tr.group !== undefined && (motion.groups?.[tr.group]?.includes(driver) ?? false);
+        if (tr.bone !== driver && !inGroup) continue;
+        const key = tr.keys.find((k) => Math.abs(k.t - t) < 1e-6);
+        if (key === undefined) continue;
+        const val = evalDeriveKey(driver, key);
+        if (tr.property === 'translatex') dx += val;
+        if (tr.property === 'translatey') dy += val;
+      }
     }
     return [dx, dy];
   };
@@ -586,10 +924,14 @@ export function applyFaceSurfaceDeform(
   const faceVerts = getMeshSetup(faceMesh);
   const hairFrontAtt = rig.skins.default.hair_front?.hair_front;
   const hairBackAtt = rig.skins.default.hair_back?.hair_back;
+  const hairpinAtt = rig.skins.default.hairpin?.hairpin;
   const hairFrontVerts = hairFrontAtt !== undefined && 'type' in hairFrontAtt ? getMeshSetup(hairFrontAtt) : null;
   const hairBackVerts = hairBackAtt !== undefined && 'type' in hairBackAtt ? getMeshSetup(hairBackAtt) : null;
+  const hairpinVerts = hairpinAtt !== undefined && 'type' in hairpinAtt && !boneMap.has('hairpin') ? getMeshSetup(hairpinAtt) : null;
 
   const hyCrown = Y0 + (67 / 128) * H;
+  const hyCrownStart = Y0 + (24 / 128) * H;
+  const hyCrownZero = Y0 + (48 / 128) * H;
   const hyBunSpan = (85 / 128) * H;
   const hyBangBottom = Y0 - (68 / 128) * H;
   const hyBangSpan = (130 / 128) * H;
@@ -598,16 +940,37 @@ export function applyFaceSurfaceDeform(
   const hyEar = Y0 - (16 / 128) * H;
   const earRx = boneMap.get('ear_r')?.x ?? -51;
   const earLx = boneMap.get('ear_l')?.x ?? 47.5;
+  const featRx = (24 / 106) * W;
+  const featRy = (12 / 128) * H;
+  const featMembers = motion.groups?.features ?? [];
+
+  const minDepthOf = (depth: number | Readonly<Record<string, number>> | undefined, fallback: number): number => {
+    if (typeof depth === 'number') return depth > 0 ? depth : fallback;
+    if (depth === undefined) return fallback;
+    const vals = Object.values(depth).filter((v): v is number => typeof v === 'number' && v > 0);
+    return vals.length > 0 ? Math.min(...vals) : fallback;
+  };
+
+  const memberDepthOf = (depth: number | Readonly<Record<string, number>> | undefined, boneName: string, zRef: number): number => {
+    if (typeof depth === 'number') return depth;
+    return depth?.[boneName] ?? zRef;
+  };
 
   if (tiltAnim !== undefined) {
     const origTiltTracks = tiltAnim.tracks.map((tr) => ({ ...tr, keys: [...tr.keys] }));
-    const tiltKeys: Array<{ t: number; deg: number }> = [
-      { t: 0, deg: -25 },
-      { t: 0.75, deg: -10 },
-      { t: 1.25, deg: 0 },
-      { t: 2.0, deg: 15 },
-      { t: 2.5, deg: 25 },
-    ];
+    const refTiltTrack = origTiltTracks.find((tr) => tr.keys.some((k) => k.derive !== undefined)) ?? origTiltTracks[0];
+    const isLegacyTilt =
+      tiltAnim.duration === 2.5 &&
+      Math.abs(refTiltTrack?.keys[0]?.derive?.degrees ?? 0) === 25;
+    const tiltKeys: Array<{ t: number; deg: number }> = isLegacyTilt
+      ? [
+          { t: 0, deg: -25 },
+          { t: 0.75, deg: -10 },
+          { t: 1.25, deg: 0 },
+          { t: 2.0, deg: 15 },
+          { t: 2.5, deg: 25 },
+        ]
+      : (refTiltTrack?.keys ?? []).map((k) => ({ t: k.t, deg: k.derive?.degrees ?? 0 }));
     const tiltDeform: DeformTimelineEntry[] = [
       {
         slot: 'face',
@@ -657,6 +1020,31 @@ export function applyFaceSurfaceDeform(
       });
     }
     for (const tr of tiltAnim.tracks) {
+      if (tr.group === 'features' && (tr.property === 'translatey' || tr.property === 'scaley') && featMembers.length > 0) {
+        const zRef = minDepthOf(tr.keys[0]?.derive?.depth, 34);
+        tr.keys = tr.keys.map((k) => {
+          const deg = k.derive?.degrees ?? 0;
+          if (deg === 0) return { t: k.t, v: tr.property === 'scaley' ? [1] : [0] };
+          const vMap: Record<string, number[]> = {};
+          for (const bname of featMembers) {
+            const b = boneMap.get(bname);
+            const bx = b?.x ?? 0;
+            const by = b?.y ?? Y0;
+            const z = memberDepthOf(k.derive?.depth, bname, zRef);
+            const dFrac = zRef > 0 ? z / zRef : 1;
+            const uy = Math.max(-1, Math.min(1, (by - Y0) / (H / 2)));
+            const effDeg = deg * (1 + (dFrac - 1) * Math.max(0, 1 - uy * uy));
+            const [, dyD] = evalPitchFaceSurface(bx, by - featRy, effDeg, W, H, X0, Y0, f);
+            const [, dyU] = evalPitchFaceSurface(bx, by + featRy, effDeg, W, H, X0, Y0, f);
+            if (tr.property === 'translatey') {
+              vMap[bname] = [pyRound(0.5 * (dyD + dyU), 4)];
+            } else {
+              vMap[bname] = [pyRound(Math.max(0.2, 1 + (dyU - dyD) / (2 * featRy)), 4)];
+            }
+          }
+          return { t: k.t, v: vMap };
+        });
+      }
       if (tr.group === 'ears' && tr.property === 'translatey') {
         tr.keys = tr.keys.map((k) => {
           const deg = k.derive?.degrees ?? 0;
@@ -674,7 +1062,7 @@ export function applyFaceSurfaceDeform(
         });
       }
     }
-    const refTiltKeys = origTiltTracks[0]?.keys ?? [];
+    const refTiltKeys = refTiltTrack?.keys ?? [];
     for (const [earBone, earHx] of [
       ['ear_r', earRx],
       ['ear_l', earLx],
@@ -696,19 +1084,191 @@ export function applyFaceSurfaceDeform(
 
   if (turnAnim !== undefined) {
     const origTurnTracks = turnAnim.tracks.map((tr) => ({ ...tr, keys: [...tr.keys] }));
-    const turnKeys: Array<{ t: number; deg: number }> = [
-      { t: 0, deg: -30 },
-      { t: 0.75, deg: -15 },
-      { t: 1.5, deg: 0 },
-      { t: 2.25, deg: 15 },
-      { t: 3.0, deg: 30 },
-    ];
+    const refTurnTrack = origTurnTracks.find((tr) => tr.keys.some((k) => k.derive !== undefined)) ?? origTurnTracks[0];
+    const isLegacyTurn =
+      turnAnim.duration === 3.0 &&
+      Math.abs(refTurnTrack?.keys[0]?.derive?.degrees ?? 0) === 30;
+    const turnKeys: Array<{ t: number; deg: number }> = isLegacyTurn
+      ? [
+          { t: 0, deg: -30 },
+          { t: 0.75, deg: -15 },
+          { t: 1.5, deg: 0 },
+          { t: 2.25, deg: 15 },
+          { t: 3.0, deg: 30 },
+        ]
+      : (refTurnTrack?.keys ?? []).map((k) => ({ t: k.t, deg: k.derive?.degrees ?? 0 }));
+    const refTurnKeys = refTurnTrack?.keys ?? [];
+
+    // Issue #478: compute head-subtree turn fractions about the head-only pivot.
+    const headParts = new Set<string>(DEFAULT_HEAD_TURN_PARTS);
+
+    const backSign = opts.flipBackLayerSignMutant === true ? -1 : 1;
+    const rawBackFrac = opts.turn != null ? headTurnFraction(opts.turn, 'hair_back', headParts, opts.partAreas) : null;
+    const rawHairpinFrac = opts.turn != null ? headTurnFraction(opts.turn, 'hairpin', headParts, opts.partAreas) : null;
+    const hairpinRidesBack =
+      hairpinAtt !== undefined &&
+      'type' in hairpinAtt &&
+      hairpinAtt.weights.some((infls) => infls.some((w) => w.bone.includes('hairback_')));
+
+    const dxFaceCenterAt = (deg: number): number => FACE_DEFORM_MULT * deg * W * unmult(f.turn_mid_x);
+    const dxBunAt = (deg: number): number =>
+      backSign * FACE_DEFORM_MULT * (deg / 15) * pyRound((f.turn_bun_counter_x * 15 * W) / FACE_DEFORM_MULT, 8);
+    const dxBackAt = (deg: number): number => {
+      if (rawBackFrac !== null) {
+        return backSign * rawBackFrac * dxFaceCenterAt(deg);
+      }
+      return dxBunAt(deg);
+    };
+    const dxHairpinAt = (deg: number): number => {
+      if (rawHairpinFrac !== null && rawHairpinFrac < 0) {
+        return backSign * rawHairpinFrac * dxFaceCenterAt(deg);
+      }
+      if (hairpinRidesBack && rawBackFrac !== null) {
+        const ratio = f.turn_bun_counter_x > 0 ? f.turn_hairpin_counter_x / f.turn_bun_counter_x : 0.75;
+        return dxBackAt(deg) * ratio;
+      }
+      return backSign * FACE_DEFORM_MULT * (deg / 15) * pyRound((f.turn_hairpin_counter_x * 15 * W) / FACE_DEFORM_MULT, 8);
+    };
+
+    const earMembers = motion.groups?.ears ?? ['ear_r', 'ear_l'].filter((b) => boneMap.has(b));
+    const hasAuthoredEarTurnTx = turnAnim.tracks.some(
+      (tr) => tr.property === 'translatex' && (tr.group === 'ears' || tr.bone === 'ear_r' || tr.bone === 'ear_l'),
+    );
+    turnAnim.tracks = turnAnim.tracks.filter(
+      (tr) => !(tr.group === 'topknot' && tr.property === 'translatex'),
+    );
+    for (const tr of turnAnim.tracks) {
+      if (tr.group === 'features' && (tr.property === 'translatex' || tr.property === 'scalex') && featMembers.length > 0) {
+        const zRef = minDepthOf(tr.keys[0]?.derive?.depth, 36);
+        tr.keys = tr.keys.map((k) => {
+          const deg = k.derive?.degrees ?? 0;
+          if (deg === 0) return { t: k.t, v: tr.property === 'scalex' ? [1] : [0] };
+          const vMap: Record<string, number[]> = {};
+          const s = Math.sign(deg);
+          for (const bname of featMembers) {
+            const b = boneMap.get(bname);
+            const bx = b?.x ?? X0;
+            const by = b?.y ?? Y0;
+            const z = memberDepthOf(k.derive?.depth, bname, zRef);
+            const dFrac = zRef > 0 ? z / zRef : 1;
+            const ux = Math.max(-1, Math.min(1, (bx - X0) / (W / 2)));
+            const effDeg = deg * (1 + (dFrac - 1) * Math.max(0, 1 - ux * ux));
+            const [dxL] = evalYawFaceSurface(bx - featRx, by, effDeg, W, H, X0, Y0, f, cylRadius, useFlatYaw);
+            const [dxR] = evalYawFaceSurface(bx + featRx, by, effDeg, W, H, X0, Y0, f, cylRadius, useFlatYaw);
+            const rawDelta = (dxR - dxL) / (2 * featRx);
+            const isTrailing = s * (bx - X0) > featRx * 0.5;
+            let sx: number;
+            if (!useFlatYaw && isTrailing) {
+              const cylL = cylinderYawDx(bx - X0 - featRx * 0.5, effDeg, cylRadius);
+              const cylR = cylinderYawDx(bx - X0 + featRx * 0.5, effDeg, cylRadius);
+              sx = 1 + Math.abs((cylR - cylL) / featRx);
+            } else {
+              sx = isTrailing ? 1 + Math.abs(rawDelta) : Math.max(0.2, 1 + rawDelta);
+            }
+            sx = pyRound(sx, 4);
+            let dx: number;
+            if (useFlatYaw) {
+              dx = isTrailing
+                ? (s > 0 ? dxR - featRx * (sx - 1) : dxL + featRx * (sx - 1))
+                : 0.5 * (dxL + dxR);
+            } else {
+              const [dxCenter] = evalYawFaceSurface(bx, by, effDeg, W, H, X0, Y0, f, cylRadius, false);
+              if (Math.abs(deg) > FACE_RATED_YAW_BAND) {
+                const [plateLeftDx] = evalYawFaceSurface(X0 - W / 2, by, deg, W, H, X0, Y0, f, cylRadius, false);
+                const [plateRightDx] = evalYawFaceSurface(X0 + W / 2, by, deg, W, H, X0, Y0, f, cylRadius, false);
+                const plateMinX = X0 - W / 2 + plateLeftDx;
+                const plateMaxX = X0 + W / 2 + plateRightDx;
+                const minDx = Math.ceil((plateMinX - bx + featRx * sx - 1e-9) * 10000) / 10000;
+                const maxDx = Math.floor((plateMaxX - bx - featRx * sx + 1e-9) * 10000) / 10000;
+                dx = Math.max(minDx, Math.min(maxDx, dxCenter));
+              } else {
+                dx = dxCenter;
+              }
+            }
+            if (tr.property === 'translatex') {
+              vMap[bname] = [pyRound(dx, 4)];
+            } else {
+              vMap[bname] = [sx];
+            }
+          }
+          return { t: k.t, v: vMap };
+        });
+      } else if (tr.group === 'ears' && tr.property === 'translatex' && earMembers.length > 0) {
+        tr.keys = tr.keys.map((k) => {
+          if (k.derive === undefined) return k;
+          const deg = k.derive.degrees;
+          if (deg === 0) return { t: k.t, v: [0] };
+          const vMap: Record<string, number[]> = {};
+          for (const bname of earMembers) {
+            vMap[bname] = [evalDeriveKey(bname, k)];
+          }
+          return { t: k.t, v: vMap };
+        });
+      } else if ((tr.bone === 'ear_r' || tr.bone === 'ear_l') && tr.property === 'translatex') {
+        const bname = tr.bone;
+        tr.keys = tr.keys.map((k) => {
+          if (k.derive === undefined) return k;
+          const deg = k.derive.degrees;
+          if (deg === 0) return { t: k.t, v: [0] };
+          return { t: k.t, v: [evalDeriveKey(bname, k)] };
+        });
+      }
+    }
+    if (!hasAuthoredEarTurnTx) {
+      for (const [earBone, earHx] of [
+        ['ear_r', earRx],
+        ['ear_l', earLx],
+      ] as const) {
+        if (!boneMap.has(earBone)) continue;
+        turnAnim.tracks.push({
+          bone: earBone,
+          property: 'translatex',
+          keys: refTurnKeys.map((k) => {
+            const deg = k.derive?.degrees ?? 0;
+            if (deg === 0) return { t: k.t, v: [0] };
+            const [dxCheekEdge] = evalYawFaceSurface(earHx, hyEar, deg, W, H, X0, Y0, f, cylRadius, useFlatYaw);
+            return { t: k.t, v: [pyRound(dxCheekEdge * f.turn_ear_x, 4)] };
+          }),
+        });
+      }
+    }
+    for (const [tkBone, evalTkDx] of [
+      ['bun_ctl', dxBunAt],
+      ['hairpin', dxHairpinAt],
+    ] as const) {
+      if (!boneMap.has(tkBone)) continue;
+      turnAnim.tracks.push({
+        bone: tkBone,
+        property: 'translatex',
+        keys: refTurnKeys.map((k) => {
+          const deg = k.derive?.degrees ?? 0;
+          if (deg === 0) return { t: k.t, v: [0] };
+          return { t: k.t, v: [pyRound(evalTkDx(deg), 4)] };
+        }),
+      });
+    }
+    // Issue #478: cloth chain roots parented to head on hair_back follow hair_back's counter-parallax fraction.
+    for (const b of rig.bones) {
+      if (b.parent === 'head' && b.name.startsWith('hairback_') && b.name.endsWith('_0')) {
+        if (turnAnim.tracks.some((tr) => tr.bone === b.name && tr.property === 'translatex')) continue;
+        turnAnim.tracks.push({
+          bone: b.name,
+          property: 'translatex',
+          keys: refTurnKeys.map((k) => {
+            const deg = k.derive?.degrees ?? 0;
+            if (deg === 0) return { t: k.t, v: [0] };
+            return { t: k.t, v: [pyRound(dxBackAt(deg), 4)] };
+          }),
+        });
+      }
+    }
+
     const turnDeform: DeformTimelineEntry[] = [
       {
         slot: 'face',
         attachment: 'face',
         keys: turnKeys.map(({ t, deg }) =>
-          deg === 0 ? { t } : { t, vertices: expandToDeform(faceVerts, (v) => evalYawFaceSurface(v.hx, v.hy, deg, W, H, X0, Y0, f)) },
+          deg === 0 ? { t } : { t, vertices: expandToDeform(faceVerts, (v) => evalYawFaceSurface(v.hx, v.hy, deg, W, H, X0, Y0, f, cylRadius, useFlatYaw)) },
         ),
       },
     ];
@@ -722,11 +1282,18 @@ export function applyFaceSurfaceDeform(
             : {
                 t,
                 vertices: expandToDeform(hairFrontVerts, (v) => {
-                  const [dxSurf, dySurf] = evalYawFaceSurface(v.hx, v.hy, deg, W, H, X0, Y0, f);
-                  const [bx, by] = getVertexBoneDelta(v, origTurnTracks, t);
+                  const [dxSurf, dySurf] = evalYawFaceSurface(v.hx, v.hy, deg, W, H, X0, Y0, f, cylRadius, useFlatYaw);
+                  const [bx, by] = getVertexBoneDelta(v, turnAnim.tracks, t);
                   const uBang = Math.max(0, Math.min(1, (v.hy - hyTurnBangBottom) / hyTurnBangSpan));
                   const bangParallaxX = (deg / 15) * pyRound(f.turn_bang_parallax_x * 15 * W, 8) * uBang;
-                  return [bangParallaxX + dxSurf - bx, dySurf - by];
+                  const hyFrontCrownStart = Y0 + (36 / 128) * H;
+                  const hyFrontCrownZero = Y0 + (60 / 128) * H;
+                  const tCrown = Math.max(0, Math.min(1, (v.hy - hyFrontCrownStart) / (hyFrontCrownZero - hyFrontCrownStart)));
+                  const wCrown = 1 - tCrown * tCrown * (3 - 2 * tCrown);
+                  const absUx = Math.abs((v.hx - X0) / (W / 2));
+                  const tLat = Math.max(0, Math.min(1, (absUx - 0.96) / (1.28 - 0.96)));
+                  const wLat = 1 - tLat * tLat * (3 - 2 * tLat);
+                  return [(bangParallaxX + dxSurf) * wCrown * wLat - bx, dySurf * wCrown * wLat - by];
                 }),
               },
         ),
@@ -742,51 +1309,43 @@ export function applyFaceSurfaceDeform(
             : {
                 t,
                 vertices: expandToDeform(hairBackVerts, (v) => {
-                  const [bx, by] = getVertexBoneDelta(v, origTurnTracks, t);
-                  const [dxCheek, dyCheek] = evalYawFaceSurface(v.hx, v.hy, deg, W, H, X0, Y0, f);
+                  const [bx, by] = getVertexBoneDelta(v, turnAnim.tracks, t);
+                  const [, dyCheek] = evalYawFaceSurface(v.hx, v.hy, deg, W, H, X0, Y0, f, cylRadius, useFlatYaw);
                   const uBun = Math.max(0, Math.min(1, (v.hy - hyCrown) / hyBunSpan));
-                  const bunCounterX = FACE_DEFORM_MULT * (deg / 15) * pyRound((f.turn_bun_counter_x * 15 * W) / FACE_DEFORM_MULT, 8);
-                  const targetDx = (1 - uBun) * (dxCheek * f.turn_hair_back_cheek_x) + uBun * bunCounterX;
-                  return [targetDx - bx, (1 - uBun) * dyCheek - by];
+                  const wBun =
+                    (v.boneWeights.bun ?? 0) +
+                    (v.boneWeights.bun_ctl ?? 0) +
+                    (v.boneWeights.turn_hair_back_bun ?? 0) +
+                    (v.boneWeights.turn_hair_back_bun_ctl ?? 0);
+                  const wTopBun = Math.max(uBun, wBun);
+                  const tCrown = Math.max(0, Math.min(1, (v.hy - hyCrownStart) / (hyCrownZero - hyCrownStart)));
+                  const wCrown = 1 - tCrown * tCrown * (3 - 2 * tCrown);
+                  const tCraniumY = Math.max(0, Math.min(1, (v.hy - (Y0 - (24 / 128) * H)) / ((32 / 128) * H)));
+                  const absUx = Math.abs((v.hx - X0) / (W / 2));
+                  const tLat = Math.max(0, Math.min(1, (absUx - 0.55) / (0.95 - 0.55)));
+                  const wLatCranium = 1 - tCraniumY * (tLat * tLat * (3 - 2 * tLat));
+                  const targetDx = (1 - wTopBun) * (dxBackAt(deg) * wCrown * wLatCranium) + wTopBun * dxBunAt(deg);
+                  return [targetDx - bx, (1 - wTopBun) * dyCheek * wCrown - by];
                 }),
               },
         ),
       });
     }
-    const refTurnKeys = origTurnTracks[0]?.keys ?? [];
-    turnAnim.tracks = turnAnim.tracks.filter(
-      (tr) => !(tr.group === 'ears' && tr.property === 'translatex') && !(tr.group === 'topknot' && tr.property === 'translatex'),
-    );
-    for (const [earBone, earHx] of [
-      ['ear_r', earRx],
-      ['ear_l', earLx],
-    ] as const) {
-      if (!boneMap.has(earBone)) continue;
-      turnAnim.tracks.push({
-        bone: earBone,
-        property: 'translatex',
-        keys: refTurnKeys.map((k) => {
-          const deg = k.derive?.degrees ?? 0;
-          if (deg === 0) return { t: k.t, v: [0] };
-          const [dxCheekEdge] = evalYawFaceSurface(earHx, hyEar, deg, W, H, X0, Y0, f);
-          return { t: k.t, v: [pyRound(dxCheekEdge * f.turn_ear_x, 4)] };
-        }),
-      });
-    }
-    for (const [tkBone, tkFrac] of [
-      ['bun_ctl', f.turn_bun_counter_x],
-      ['hairpin', f.turn_hairpin_counter_x],
-    ] as const) {
-      if (!boneMap.has(tkBone)) continue;
-      turnAnim.tracks.push({
-        bone: tkBone,
-        property: 'translatex',
-        keys: refTurnKeys.map((k) => {
-          const deg = k.derive?.degrees ?? 0;
-          if (deg === 0) return { t: k.t, v: [0] };
-          const tkPx = pyRound((tkFrac * 15 * W) / FACE_DEFORM_MULT, 8);
-          return { t: k.t, v: [pyRound(FACE_DEFORM_MULT * (deg / 15) * tkPx, 4)] };
-        }),
+    if (hairpinVerts !== null) {
+      turnDeform.push({
+        slot: 'hairpin',
+        attachment: 'hairpin',
+        keys: turnKeys.map(({ t, deg }) =>
+          deg === 0
+            ? { t }
+            : {
+                t,
+                vertices: expandToDeform(hairpinVerts, (v) => {
+                  const [bx, by] = getVertexBoneDelta(v, turnAnim.tracks, t);
+                  return [dxHairpinAt(deg) - bx, -by];
+                }),
+              },
+        ),
       });
     }
     turnAnim.deform = turnDeform;