@rig-c/parts 1.33.0 → 1.34.0

package/docs/AUTHORING.md

@@ -124,7 +124,7 @@ read by no CPU stage).
 | `motion.animations_from` | rig; check (named; read for folds) | optional, never proposed (issue #183): a path, relative to the config file's directory, to a file in rig-c's motion-spec shape, `{"spec": "rigc-motion/1", "animations": {"<name>": {"duration": …, "tracks": [...]}, …}}` — an expression, a gesture, anything beside the idle. On every `rig` and `build` each of its animations is written into `rig/motion.json` after `idle`, as read: nothing added, re-keyed or judged here, and each is rigc's to accept or refuse at the rig stage's gate, in rigc's words. It may name what `motion.json` already holds — the bones `bones` declares, the easings `shut` and `open`, the groups `eyes` and `brows` when the blink writes them — and nothing else from the file reaches it. The loader refuses, every problem at once: no such file or one that cannot be read (`CONFIG_FILE_PRESENT`), text that is not JSON (`CONFIG_IS_JSON`), a file that is not an object, a `spec` other than `"rigc-motion/1"`, an `animations` that is not a table of objects (`CONFIG_FIELD_TYPE`), any other key — rig-c's `easings`, `groups`, `setup`, `physics`, `mix`, `archetype` and `cut` included, which would be read and not written (`CONFIG_KEY_KNOWN`), an animation named `idle` (`CONFIG_ANIMATION_NAME_FREE`), and a key written twice in one object of the file, which JSON would fold into its last value without a word (`CONFIG_KEY_UNIQUE`). `check` names the others on one line (`beside the idle: …`) and reads each for folds, with the idle — `ANIMATIONS_DO_NOT_FOLD` (§7, issues #320, #333); every other bar reads the idle. Absent, `motion.json` holds the idle alone, byte for byte as before, and `check` reads that idle for folds |
 | `constraints` | rig (handed to rig-c as `rig.json`'s `constraints`); `compare` and the coverage lines (roles) | **authored**, optional; `propose` writes none, but with `--cloth` (issue #364), where it writes the recipe's physics and swing transforms (*Recipe: cloth and hair that answer the world*, below). A list of constraints in **rig-c's own rig-spec shape** (`RigConstraint`: `ik`, `transform`, `path`, `physics`, `slider` — rig-c's `src/rig.ts` documents every field), in the order rigc applies them. The loader checks only what this package owns: each entry is an object with a `type` rigc names (`CONFIG_CONSTRAINT_TYPE_KNOWN`) and a non-empty `name`, unique within its kind as rigc finds constraints (`CONFIG_CONSTRAINT_NAME_UNIQUE`; an ik and a transform may share one); every bone it names — `bones`, an ik's `target`, a transform's `source`, a physics or slider constraint's `bone` — is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`); the bone a constraint follows does not sit under a bone it drives (`CONFIG_CONSTRAINT_TARGET_DETACHED`). Every other field (`mix`, `softness`, `properties`, a path's `slot`, a slider's `animation`) and every value is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`) — an ik's `bones` as a shape too: from rig-c 2.15.0 rigc refuses an ik over more than two bones, or over a pair whose second bone is not the first's child (issue #103; this loader refused both itself until then). A note and an `x-` record may ride on an entry; the rig stage leaves them out of what it hands rigc. Under the default `--idle-keys ctl` a two-bone ik whose child link the idle keys is split by that link's control, and rigc refuses the pair: run `rig --idle-keys direct` or `build --idle-keys direct` (the rig stage adds that sentence, naming the flag on the command that ran, to rigc's line; `build` forwards it to its rig stage, issue #95). Each bone a constraint follows is declared to rigc as `invariants.detached` from every bone it drives, which rigc's gate rule `A25` checks |
 | `stops` | rig (handed to rig-c as `rig.json`'s `stops`, and moves slots, mesh weights and child bones on stopped links onto `<link>_d`); `propose --from-config` (`LINT stop on <chain> …`) | **authored**, optional (issues #404, #447): `[{chain, links?, against, at, inward, outward, lower?: {inward, outward}}]` — rig-c's leg stops (`RigStop`, rig-c 2.56.0, `rig-c/src/stop.ts`). `chain` is a chain `bones` declares (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `links`, optional, is a non-empty list of links of that chain (`CONFIG_NAME_RESOLVES`, `CONFIG_FIELD_TYPE`), or absent for every link of `chain` in chain order; `against` is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `at` is `[x, y]` in `against`'s local space, as rig-c's stop takes it (`CONFIG_FIELD_TYPE`): since each chain link (`leg_r0`, `leg_r1`) is turned to point along its segment (`+x` from origin to next link or tip, `+y` 90° counter-clockwise in Spine world), `at: [d, n]` sits `d` px from `against`'s origin toward its end and `n` px perpendicular to it; `inward`, `outward` and `lower.inward`, `lower.outward` are finite numbers (`CONFIG_FIELD_TYPE`). Every other stop rule — non-negative bounds, each stopped link written by a constraint, `against` not under the stopped chain, the aim not degenerate, `\|rest\| + outward <= 180°` (`RIG_STOP_BOUNDS`) — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). **Rising-limb / prone geometry (issue #447):** rig-c's `expandStops` aims `<chain>_rest` from `links[0]`'s setup origin at `<chain>_touch` (`at` in `against`'s local frame) and clamps `<link>_d` inside `[rest − inward, rest + outward]`; Spine wraps rotation at `±180°`, so `\|rest\| + outward <= 180°` is required (`RIG_STOP_BOUNDS`). Whenever `<chain>_touch` lies **above** `links[0]`'s root in rig pixels (`ty < y0`, i.e. higher Spine `y` — e.g. stopping a hanging cloth chain against a rising shin `leg_<s1>` in a prone or kneeling pose where the knee sits below `links[0]` and the ankle above it, so positive `at[0]` walks upward along the shin past `links[0]`'s root), `rest` lands in the upper half-plane (`\|rest\| > 90°`) and `\|rest\| + outward` exceeds `180°`. Stop against the descending thigh (`leg_<s0>`), set `links` to start at a link whose root sits above `<chain>_touch`, or omit the stop when the rising shin sits outside the hanging chain's sweep; `propose --from-config` prints `LINT stop on <chain> …` with the exact coordinates and angles when `<chain>_touch` lies above `links[0]`'s root or `\|rest\| + outward > 180°`. For every stopped link `<link>`, the rig stage moves any slot on `<link>`, any mesh weight on `<link>`, and any bone whose parent is `<link>` (a branched cloth tree's branches hanging from `<trunk_last>`, before `--idle-keys ctl` adds `<bone>_ctl` and before `turn` adds `turn_<part>_<bone>`) onto `<link>_d`, the drawn link bone rig-c's `expandStops` creates at `<link>`'s setup frame to carry the clamped rotation. Absent, `rig.json` carries no `stops` and no byte of any output moves |
-| `turn` | rig (adds the turn control) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected: `{pivot, depths, deform?, band?}`. `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median. With no `face` part, or more than one, the riders keep their own and a note says so. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening slightly on the trailing side with its outer edge anchored to the field, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); the pivot must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
+| `turn` | rig (adds the turn control) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected: `{pivot, depths, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}}`. `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median. With no `face` part, or more than one, the riders keep their own and a note says so. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it requires `config.turn` (`CONFIG_TURN_REQUIRED`, issue #478; `propose --full`/`--head` drafts it), promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening on the trailing side, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). On yaw (`issue #479`), `evalYawFaceSurface` evaluates a **cylinder projection** (`cylinderYawDx`: `Δx(x, θ, R) = R · (sin(clamp(arcsin(clamp(x / R, −1, 1)) − θ, −π/2, π/2)) − clamp(x / R, −1, 1))`) of radius `R` (`turnSurfaceRadius`: `turn.surface.radius ?? turn.radius ?? turn.head.radius`, positive rig px checked by `CONFIG_FIELD_TYPE`, defaulting to half the face plate's opaque width `W / 2`) tapered by a cubic Hermite outline weight (`wOutline = 1` for `\|ux\| <= 0.7`, reaching `0` at `\|ux\| = 1.0`) so features slide across a fixed outline (`iris` shift within `±2%` of `cylinderYawDx`), the trailing cheek strip widens (`>= 1.54×` at `±15°`), and the leading jaw edge holds fixed (`0 px` shift) unless explicit horizontal `turn.deform` overrides (`turn_mid_x`, `turn_lead_compress_x`, `turn_trail_shift_x`) request the flat yaw table. On yaw (`issue #478`), `applyFaceSurfaceDeform` also derives a **head-only pivot** (`headTurnPivot`: `turn.head.pivot` when authored, otherwise the `opaque_px`-weighted mean of `depths[part]` across the head parts `DEFAULT_HEAD_TURN_PARTS` — `face`, `hair_front`, `hair_back`, `ear_r`, `ear_l`, `hairpin` — from `parts.json`, falling back to `turn.pivot`) so a forward torso or arm in `turn.depths` does not pull the head's rotation axis in front of `face`: `hair_back` (`depth_median > headPivot`, negative `headTurnFraction`) and `hairpin` behind `headPivot` translate opposite to the face's turn (`dx = s · turn_face_center_x · W · (headPivot − depth) / (headPivot − nearestHeadDepth)`), emerging on the trailing side to compensate for the leading-cheek foreshortening and keeping the combined head silhouette width near-constant across `±15°` without any same-sign `turn_hair_back_cheek_x` term. Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); `pivot` and `head.pivot` must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
 | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite, and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
 | `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?}`. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts |
 | `proposed_rig_scale` | assemble, rig, build, `propose --from-config`/`--compare` | **proposed** by `propose` (issue #354): `parts.json`'s `scale_rig_per_source`, the `assemble.rig_scale` the rig sections (`bones`, `meshes`, `limbs`, `motion`) were drafted at. Held equal to `assemble.rig_scale` when present (`CONFIG_PROPOSED_RIG_SCALE`; 0, negative or not a number: `CONFIG_FIELD_TYPE`). Absent on a hand-authored config, where no byte of any output moves |
@@ -2676,6 +2676,7 @@ See-through with another seed.
 | <a id="CONFIG_TURN_BONE_FREE"></a>`CONFIG_TURN_BONE_FREE` | the config has `turn` and `bones` declares a bone named `turn`, the control the rig stage adds | rename that bone |
 | <a id="CONFIG_TURN_DEFORM_RANGE"></a>`CONFIG_TURN_DEFORM_RANGE` | an entry in `turn.deform` lies outside its allowed `[min, max]` interval in `FACE_DEFORM_RANGES` (`src/turn.ts`, issue #436); the detail gives the value found, the interval required and the default fraction | put that `turn.deform.<key>` inside the stated range, or remove it to take the Set B ×2.5 default |
 | <a id="CONFIG_TURN_EAR_DEPTH_RANGE"></a>`CONFIG_TURN_EAR_DEPTH_RANGE` | an ear track (`group: "ears"` or `bone: "ear_r" \| "ear_l"`) in `turn` or `tilt` declares a `derive.depth` outside `EAR_DEPTH_RANGE` (`[-50, 0]`, `src/turn.ts`, issue #477); the detail gives the value found and the interval required | put the ear `derive.depth` in `[-50, 0]` (at or behind the head pivot, e.g. `-14`) |
+| <a id="CONFIG_TURN_REQUIRED"></a>`CONFIG_TURN_REQUIRED` | `motion.animations_from` carries `turn` or `tilt` `derive` keys while `config.turn` is absent, or an attached head part (`face`, `hair_front`, `hair_back`) is missing from `config.turn.depths` (issue #478): without `turn.depths` the head pivot and back-of-head counter-parallax cannot be derived | run `propose --full` (or `--head`) to draft `config.turn`, or declare `config.turn` with `pivot` and `depths` covering `face`, `hair_front` and `hair_back` |
 | <a id="CONFIG_FACE_BAND_EXCEEDED"></a>`CONFIG_FACE_BAND_EXCEEDED` | `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` exceeds the single-plate rated band (`FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`, issue #472) while no `assemble.alternates` entry replaces `face`; the detail gives the requested angle, the rated limit and both remedies | clamp the angle to `±15°` yaw / `±12°` pitch, or declare an `assemble.alternates` entry covering `face` for the 3/4 or profile plate |
 | <a id="CONFIG_PROPOSED_RIG_SCALE"></a>`CONFIG_PROPOSED_RIG_SCALE` | `proposed_rig_scale` (the `scale_rig_per_source` `propose` drafted the rig sections at, issue #354) differs from `assemble.rig_scale`: the coordinates in `bones`, `meshes`, `limbs` and `motion` are in that rig canvas's pixels and do not scale when `assemble.rig_scale` changes | re-run `assemble` and `propose` at the new `assemble.rig_scale`, or restore `assemble.rig_scale` to `proposed_rig_scale` |
 

package/docs/STABILITY.md

@@ -162,10 +162,12 @@ part name, `[i]` an entry of a list):
 - **motion.blink** — required: `t`, `eyes`, `squash`; optional: `brows`, `brow_drop`, `still`
 - **motion.blink.still.<part>** — required: `row`, `bone`
 - **motion.animations_from**, the file it names — required: `spec`, `animations`
-- **turn** — required: `pivot`, `depths`; optional: `deform`, `band`
+- **turn** — required: `pivot`, `depths`; optional: `deform`, `band`, `radius`, `surface`, `head`
 - **turn.depths.<part>** — a See-through depth
 - **turn.deform.<key>** — a per-degree fraction or coupling share (FACE_DEFORM_FRACTIONS, issue #436)
 - **turn.band**, when an object — optional: `yaw`, `pitch` (issue #472)
+- **turn.surface**, when an object — optional: `radius` (issue #479)
+- **turn.head**, when an object — optional: `pivot`, `radius` (issues #478, #479)
 - **scene** — no field (`{}`; a record or an annotation only)
 - **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `limbs` under `--keypoints` where an arm or a leg is drafted from its joints (issue #349), `stops` when supplied, `motion` under the rules above, `turn` with `--full`/`--head`, `proposed_rig_scale` (issue #354), and `notes`
 <!-- /stable:config -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/config.ts

@@ -1305,13 +1305,14 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
   if ('stops' in t) checkStops(c, t.stops, names.bones, names.chains);
+  const attached = attachedParts(t.meshes, t.regions);
   const hasAltFace = hasAlternateFaceSet(t.assemble, [...parts, ...cuts]);
-  if ('turn' in t) checkTurn(c, t.turn, attachedParts(t.meshes, t.regions), names.bones, hasAltFace);
+  if ('turn' in t) checkTurn(c, t.turn, attached, names.bones, hasAltFace);
   if ('scene' in t) checkScene(c, t.scene);
   if ('cloth' in t) checkCloth(c, t.cloth);
   const from = isPlainObject(t.motion) ? t.motion.animations_from : undefined;
   const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, resolve(base, from)) : null;
-  if (animations !== null) checkFaceAnimationBand(c, animations, hasAltFace);
+  if (animations !== null) checkFaceAnimationBand(c, animations, hasAltFace, t.turn, attached);
   if (base !== null) poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
   return { config: raw as CharacterConfig, animations };
@@ -3219,10 +3220,29 @@ function maxDeriveDegrees(anim: unknown): number {
   return maxDeg;
 }
 
-function checkFaceAnimationBand(c: Check, animations: AnimationsFrom, hasAltFace: boolean): void {
+function checkFaceAnimationBand(c: Check, animations: AnimationsFrom, hasAltFace: boolean, turn?: Json, attached?: Set<string>): void {
   const at = `config.motion.animations_from (${animations.file}).animations`;
   const maxYaw = maxDeriveDegrees(animations.table.turn);
   const maxPitch = maxDeriveDegrees(animations.table.tilt);
+  if (maxYaw > 0 || maxPitch > 0) {
+    if (turn === undefined) {
+      c.fail(
+        'CONFIG_TURN_REQUIRED',
+        'config.turn',
+        "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 if (isPlainObject(turn) && isPlainObject(turn.depths) && attached !== undefined) {
+      for (const reqPart of ['face', 'hair_front', 'hair_back'] as const) {
+        if (attached.has(reqPart) && !(reqPart in turn.depths)) {
+          c.fail(
+            'CONFIG_TURN_REQUIRED',
+            `config.turn.depths.${reqPart}`,
+            `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`,
+          );
+        }
+      }
+    }
+  }
   if (maxYaw > FACE_RATED_YAW_BAND && !hasAltFace) {
     c.fail(
       'CONFIG_FACE_BAND_EXCEEDED',
@@ -3276,9 +3296,24 @@ function checkFaceAnimationBand(c: Check, animations: AnimationsFrom, hasAltFace
 
 function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>, hasAltFace: boolean): void {
   const at = 'config.turn';
-  const o = c.object(at, v, ['pivot', 'depths'], ['deform', 'band']);
+  const o = c.object(at, v, ['pivot', 'depths'], ['head', 'deform', 'band', 'radius', 'surface']);
   if (o === null) return;
   const pivot = 'pivot' in o && c.number(`${at}.pivot`, o.pivot) ? (o.pivot as number) : null;
+  if ('radius' in o) c.number(`${at}.radius`, o.radius, 'positive');
+  if ('surface' in o) {
+    const so = c.object(`${at}.surface`, o.surface, [], ['radius']);
+    if (so !== null && 'radius' in so) c.number(`${at}.surface.radius`, so.radius, 'positive');
+  }
+  let headPivot: number | null = null;
+  if ('head' in o) {
+    const ho = c.object(`${at}.head`, o.head, [], ['pivot', 'radius']);
+    if (ho !== null) {
+      if ('pivot' in ho && c.number(`${at}.head.pivot`, ho.pivot)) {
+        headPivot = ho.pivot as number;
+      }
+      if ('radius' in ho) c.number(`${at}.head.radius`, ho.radius, 'positive');
+    }
+  }
   const depths: Record<string, number> = {};
   let depthsOk = false;
   if ('depths' in o) {
@@ -3369,6 +3404,16 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>,
       );
     }
   }
+  if (headPivot !== null && depthsOk) {
+    const nearest = turnNearest(depths);
+    if (nearest !== null && !(headPivot > nearest.depth)) {
+      c.fail(
+        'CONFIG_TURN_PIVOT_BEHIND_NEAREST',
+        `${at}.head.pivot`,
+        `is ${headPivot}; the nearest part, "${nearest.part}", lies at depth ${nearest.depth}, and a head pivot above that (further back) is required`,
+      );
+    }
+  }
   if (bones.has(TURN_BONE)) {
     c.fail('CONFIG_TURN_BONE_FREE', `bone "${TURN_BONE}"`, `is the control the rig stage adds under root for config.turn, and config.bones already declares a bone of that name; rename it`);
   }

package/src/rig.ts

@@ -2296,6 +2296,8 @@ export function buildRig(
   if (axes.length > 0) rig.invariants = { ...rig.invariants, axes };
   const faceImg = outImages.find(([k]) => k === 'face.png')?.[1];
   const facePart = parts.parts.find((p) => p.name === 'face');
+  const partAreas: Record<string, number> = {};
+  for (const p of parts.parts) partAreas[p.name] = p.opaque_px;
   bindFaceSurfaceDeform(motion, (merged) => {
     applyFaceSurfaceDeform(rig, merged, {
       imageWidth: faceImg?.width,
@@ -2304,6 +2306,9 @@ export function buildRig(
       opaqueHeight: facePart?.h,
       overrides: cfg.turn?.deform,
       hasAlternateFaceSet,
+      turn: cfg.turn,
+      partAreas,
+      requireTurn: true,
     });
     if (sets !== undefined && (merged.animations.turn !== undefined || merged.animations.tilt !== undefined)) {
       for (const entry of Object.values(sets.sets)) {

package/src/turn.ts

@@ -109,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`). */
@@ -144,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],
@@ -184,14 +181,75 @@ export const FACE_RATED_BAND = { yaw: FACE_RATED_YAW_BAND, pitch: FACE_RATED_PIT
  */
 export const EAR_DEPTH_RANGE: readonly [number, number] = [-50, 0];
 
-/** `config.turn`: the pivot depth, each carried part's See-through `depth_median`, optional rated band, and optional face surface deform overrides. */
+/** 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;
@@ -238,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}`;
@@ -277,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,
@@ -288,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 {
@@ -318,6 +433,30 @@ export interface FaceSurfaceDeformOptions {
    * 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 {
@@ -418,8 +557,8 @@ 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, feature field-sampled tracks (#468) and ear/topknot tracks
- * (issue #436). When `motion` holds neither `tilt` nor `turn` with slider
- * `derive` keys, neither `rig` nor `motion` is touched.
+ * (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: {
@@ -443,8 +582,44 @@ export function applyFaceSurfaceDeform(
     (rawTurn?.tracks?.some((tr) => tr.keys?.some((k) => k.derive !== undefined)) ?? false);
   if (!hasDerive) return;
 
-  // Issue #477: refuse an out-of-range ear derive.depth by name before touching rig or motion.
-  const earProblems: Problem[] = [];
+  const isOpts =
+    options !== undefined &&
+    options !== null &&
+    ('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],
@@ -458,7 +633,7 @@ export function applyFaceSurfaceDeform(
         const d = k.derive?.depth;
         if (typeof d === 'number') {
           if (d < earLo || d > earHi) {
-            earProblems.push({
+            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`,
@@ -467,7 +642,7 @@ export function applyFaceSurfaceDeform(
         } else if (d !== undefined && typeof d === 'object') {
           for (const [member, val] of Object.entries(d)) {
             if (typeof val === 'number' && (val < earLo || val > earHi)) {
-              earProblems.push({
+              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`,
@@ -478,24 +653,21 @@ export function applyFaceSurfaceDeform(
       });
     });
   }
-  refuseIfAny(earProblems);
+  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 isOpts =
-    options !== undefined &&
-    options !== null &&
-    ('imageWidth' in options ||
-      'imageHeight' in options ||
-      'opaqueWidth' in options ||
-      'opaqueHeight' in options ||
-      'overrides' in options ||
-      'hasAlternateFaceSet' in options);
-  const opts: FaceSurfaceDeformOptions = isOpts ? (options as FaceSurfaceDeformOptions) : { overrides: options as Readonly<Partial<FaceDeformFractions>> | null | undefined };
   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)) {
@@ -592,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;
     }
   }
 
@@ -601,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) {
@@ -701,18 +877,34 @@ export function applyFaceSurfaceDeform(
   };
 
   const getBoneDeltaAtTime = (tracks: readonly SliderTrack[], t: number, boneName: string): [number, number] => {
-    const baseBone = boneName.replace(/^turn_[^_]+_/, '');
-    const driver = mapParent[baseBone] ?? baseBone;
+    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];
   };
@@ -732,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;
@@ -901,57 +1097,39 @@ export function applyFaceSurfaceDeform(
           { t: 3.0, deg: 30 },
         ]
       : (refTurnTrack?.keys ?? []).map((k) => ({ t: k.t, deg: k.derive?.degrees ?? 0 }));
-    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)) },
-        ),
-      },
-    ];
-    if (hairFrontVerts !== null) {
-      turnDeform.push({
-        slot: 'hair_front',
-        attachment: 'hair_front',
-        keys: turnKeys.map(({ t, deg }) =>
-          deg === 0
-            ? { t }
-            : {
-                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 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];
-                }),
-              },
-        ),
-      });
-    }
-    if (hairBackVerts !== null) {
-      turnDeform.push({
-        slot: 'hair_back',
-        attachment: 'hair_back',
-        keys: turnKeys.map(({ t, deg }) =>
-          deg === 0
-            ? { t }
-            : {
-                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 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 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'),
@@ -975,18 +1153,42 @@ export function applyFaceSurfaceDeform(
             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);
-            const [dxR] = evalYawFaceSurface(bx + featRx, by, effDeg, W, H, X0, Y0, f);
+            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;
-            const sx = isTrailing ? 1 + Math.abs(rawDelta) : Math.max(0.2, 1 + rawDelta);
-            const dx = isTrailing
-              ? (s > 0 ? dxR - featRx * (sx - 1) : dxL + featRx * (sx - 1))
-              : 0.5 * (dxL + dxR);
+            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] = [pyRound(sx, 4)];
+              vMap[bname] = [sx];
             }
           }
           return { t: k.t, v: vMap };
@@ -1024,15 +1226,15 @@ export function applyFaceSurfaceDeform(
           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);
+            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, tkFrac] of [
-      ['bun_ctl', f.turn_bun_counter_x],
-      ['hairpin', f.turn_hairpin_counter_x],
+    for (const [tkBone, evalTkDx] of [
+      ['bun_ctl', dxBunAt],
+      ['hairpin', dxHairpinAt],
     ] as const) {
       if (!boneMap.has(tkBone)) continue;
       turnAnim.tracks.push({
@@ -1041,11 +1243,111 @@ export function applyFaceSurfaceDeform(
         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)] };
+          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, cylRadius, useFlatYaw)) },
+        ),
+      },
+    ];
+    if (hairFrontVerts !== null) {
+      turnDeform.push({
+        slot: 'hair_front',
+        attachment: 'hair_front',
+        keys: turnKeys.map(({ t, deg }) =>
+          deg === 0
+            ? { t }
+            : {
+                t,
+                vertices: expandToDeform(hairFrontVerts, (v) => {
+                  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;
+                  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];
+                }),
+              },
+        ),
+      });
+    }
+    if (hairBackVerts !== null) {
+      turnDeform.push({
+        slot: 'hair_back',
+        attachment: 'hair_back',
+        keys: turnKeys.map(({ t, deg }) =>
+          deg === 0
+            ? { t }
+            : {
+                t,
+                vertices: expandToDeform(hairBackVerts, (v) => {
+                  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 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];
+                }),
+              },
+        ),
+      });
+    }
+    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;
   }
 }