@rig-c/parts 1.26.0 → 1.28.0

package/docs/AUTHORING.md

@@ -512,7 +512,10 @@ layers, as follows; every step is arithmetic on the declared bones and the layer
   upper pixel inside it, above the line, keeps alpha × (its distance above the line ÷ the band's
   height there): 0 on the line, 1 on the band's arc. Over art that stays opaque under it at any
   angle, the rest pose composites to the hard cut's bytes and no bend shows through the fade what
-  lies behind the limb. The `limb cap:` line adds `edge "feather": N px of "<upper>" faded …`, and
+  lies behind the limb. A pixel the fade lowers to alpha 8 or below (`OPAQUE_ALPHA_ABOVE`) leaves the
+  upper piece's region (its opacity is held by the lower piece's cap beneath), and the rest of the
+  ramp is kept through `pushBackFringe` when another limb crosses in front of the joint (issue #444).
+  The `limb cap:` line adds `edge "feather": N px of "<upper>" faded …`, and
   the record `edge`, `feather_radius` and `feathered_px`.
 - **`cut_band: N`** (issue #360, opt-in on the segment below a joint whose two segments take one
   part). The cut is placed rather than typed: of the lines parallel to the joint line at whole-pixel
@@ -1591,7 +1594,7 @@ What each rule drafts (`src/cloth.ts` holds them):
 | response | link j of an n-link path takes `wind` and `gravity` at j/(n − 1) of the way from the root value to the tip value; a single-link path takes the tip value. Each is a scalar **multiplier** of the environment the consumer sets (spine-core's skeleton `windX, windY`, `gravityX, gravityY`; rig-c 2.52.0's live track `setEnvironment`, rig-play 1.10.0's `environment()`): no direction is drafted | `wind`, `gravity` |
 | out of phase | the odd trees take `alternate_damping`, the even ones `damping` | `damping`, `alternate_damping` |
 | flutter | the last link of every path gets a second physics constraint, `<bone>_translate`, moving x and y by `translate`, with the link's stiffness and damping and **no** wind or gravity response. spine-core scales a translate spring's response by the skeleton's reference scale (100) and a rotation's by the link's length over it, so one response on both pushes an end about 100/length times further than it turns it (the table below) | `translate` |
-| part | `bottomwear` only (issue #402): the named `topwear` part takes the skirt's rule as the `bottomwear` parts do — trees from `hip` over its art below the hip, its waist line, and, as its art reaches above the chest, the chest segment the long-robe `bottomwear` keeps — in place of the two robe chains the topwear rule drafts; the prefix is `skirt` when it is the only skirt, `skirt_<part>` beside another. A `bottomwear` part lying on the named part's tree links rides them and drafts no trees of its own (issue #416, *What rides a dress* below) | `part` |
+| part / parts | `part` (a string on `bottomwear` only, issue #402): the named `topwear` part takes the skirt's rule as the `bottomwear` parts do — trees from `hip` over its art below the hip, its waist line, and, as its art reaches above the chest, the chest segment the long-robe `bottomwear` keeps — in place of the two robe chains the topwear rule drafts; the prefix is `skirt` when it is the only skirt, `skirt_<part>` beside another. A `bottomwear` part lying on the named part's tree links rides them and drafts no trees of its own (issue #416, *What rides a dress* below). `parts` (or `part` as a list, on any tag, issue #437): a non-empty list of distinct part names in root-to-tip order (`["hair_back", "hair_back_front"]`) that share one set of trees drafted from the root part's origin to the last part's tip, each part's mesh receiving only the link segments whose span crosses its opaque art (`spanCrosses > 0`) | `part`, `parts` |
 | swing | `bottomwear` only: a bone `<prefix>_swing` under `hip` at the centre of the root row, one link long, straight down, with physics (the trunk's stiffness, the root's response); each tree's first link takes the swing's rotation times its scale — a transform `<swing>_<k>`, local source and target, additive, the swing's setup rotation in hip's frame (−90: hip is drafted unturned) subtracted — and no physics of its own | `swing.scales` |
 
 Every link but a swing-driven first link gets `<bone>_physics` (`rotate` 1), and no
@@ -2630,9 +2633,11 @@ See-through with another seed.
 | <a id="CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP"></a>`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP` | a `cloth` recipe's `wind` or `gravity` is `[root, tip]` with tip below root: the response grows from the root to the tip, where the motion accumulates down the chain | that pair |
 | <a id="CONFIG_CLOTH_ALTERNATE_DIFFERS"></a>`CONFIG_CLOTH_ALTERNATE_DIFFERS` | a `cloth` recipe's `alternate_damping` without `damping`, or equal to it: neighbouring trees are declared out of phase, and an alternate that alternates nothing declares nothing | `damping` beside it, a different value, or leave `alternate_damping` out |
 | <a id="CONFIG_CLOTH_SWING_SCALE_PER_TREE"></a>`CONFIG_CLOTH_SWING_SCALE_PER_TREE` | `swing` on a tag other than `bottomwear`, or `swing.scales` not one scale per tree (`chains`) | one scale per tree, in tree order across the skirt |
-| <a id="CONFIG_CLOTH_PART_ON_BOTTOMWEAR"></a>`CONFIG_CLOTH_PART_ON_BOTTOMWEAR` | `part` on a `cloth` recipe for a tag other than `bottomwear` (issue #402) | leave it out there; `part` hands the skirt's recipe to a `topwear` part that holds a skirt (a dress) |
+| <a id="CONFIG_CLOTH_PART_ON_BOTTOMWEAR"></a>`CONFIG_CLOTH_PART_ON_BOTTOMWEAR` | `part` as a string on a `cloth` recipe for a tag other than `bottomwear` (issue #402; a list of parts in `parts` or `part` is accepted on any tag, issue #437) | leave it out there, or pass a list of parts in root-to-tip order (`parts: [...]`); a single string `part` hands the skirt's recipe to a `topwear` part that holds a skirt (a dress) |
+| <a id="CONFIG_CLOTH_PARTS_UNIQUE"></a>`CONFIG_CLOTH_PARTS_UNIQUE` | a `cloth` recipe sets both `part` and `parts`, or its part list names the same part more than once (issue #437) | set at most one of `part` or `parts`, and list each part once in root-to-tip order |
 | <a id="CONFIG_CLOTH_SPRING_STABLE"></a>`CONFIG_CLOTH_SPRING_STABLE` | a `cloth` recipe's strength — declared, or the default 100 / 100 / 50 — whose spring is unstable at a damping the recipe runs at (`damping`, `alternate_damping`, or rig-c's 0.85 when `damping` is left out): k = strength·massInverse·step² at or past 2(1 + damping^(60·step)), step 1/60 and mass 1 (rig-c's defaults; the recipe sets neither). The detail gives k and the bound | a lower strength, or a higher damping |
 | <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_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` |
 
 ### inputs
@@ -2714,7 +2719,7 @@ says why each requirement exists and what breaks without it.
 | <a id="PROPOSE_CUT_FROM_RECORDED"></a>`PROPOSE_CUT_FROM_RECORDED` | two parts share one layer and none of them records `cut_from`: a `parts.json` an `assemble` before 1.6.0 wrote with `assemble.cuts`. The records are in draw order, so which is the plan part and which the piece cannot be read off the file; the message names the parts and the layer. Every other reader still takes the file | `--parts`: re-run assemble (1.6.0+) to record `cut_from` |
 | <a id="PROPOSE_LIMB_PARTS"></a>`PROPOSE_LIMB_PARTS` | `parts.json` holds parts `config.limbs` cut at their joints (issue #349); the limbs are drafted from the parts before the cut, which the rules read by layer | `--parts` a build assembled with the config's `limbs` left out; keep the block the config holds (its caps and ranges are the author's). `propose --from-config` reads the config's bones on either build |
 | <a id="PROPOSE_CLOTH_DRAFTED"></a>`PROPOSE_CLOTH_DRAFTED` | with `--cloth` (issue #364): the config's `cloth` block holds a recipe for a tag the proposer drafts no chain on — no part has that tag, or every `back hair` part ends above the shoulders (a bun bone, no chain). A `bottomwear` recipe with no `bottomwear` part names every `topwear` part shaped like a skirt (issue #402) | leave that recipe out, or assemble the layer it is for, or declare the named part in `cloth.bottomwear.part` |
-| <a id="PROPOSE_CLOTH_PART"></a>`PROPOSE_CLOTH_PART` | with `--cloth` (issue #402): `cloth.bottomwear.part` names no part, a part or cut piece whose source is not `topwear` (a `bottomwear` part takes the recipe by its tag already), or a target whose box ends above the hip + 0.25 face heights, the topwear rule's waist line | name the `topwear` part or its cut skirt piece that holds the skirt, or leave `part` out |
+| <a id="PROPOSE_CLOTH_PART"></a>`PROPOSE_CLOTH_PART` | with `--cloth` (issues #402, #437): `cloth.bottomwear.part` (a string) names no part, a part or cut piece whose source is not `topwear` (a `bottomwear` part takes the recipe by its tag already), or a target whose box ends above the hip + 0.25 face heights, the topwear rule's waist line; or `cloth.<tag>.parts` (or `part` as a list, issue #437) names a part not in `parts.json`, a part no link of the drafted tree crosses (`spanCrosses == 0`), or parts out of root-to-tip depth order along the chain | name the `topwear` part or its cut skirt piece that holds the skirt (or leave `part` out), or list only parts in `parts.json` that the drafted tree links cross in root-to-tip order |
 | <a id="PROPOSE_CLOTH_BACK_HAIR_CHAINS"></a>`PROPOSE_CLOTH_BACK_HAIR_CHAINS` | with `--cloth` (issue #390): `cloth."back hair".chains` exceeds what the narrower side's opaque width at the eye-line root row holds at the part's mesh grid (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`), or places a tree root outside the 15 px dilated art mask of the `back hair` part (e.g. an inner twin-tail root over the face where the hair has no pixel); the message names the part, each side's root-row width, the grid spacing, and any off-art root with its pixel alpha | lower `cloth."back hair".chains` to at most the max fit named in the message, or omit `chains` so `propose --cloth` derives the tree count per side from the root-row tail widths |
 | <a id="PROPOSE_ACCESSORY_BODY"></a>`PROPOSE_ACCESSORY_BODY` | an accessory has nothing above its pendant rows to hang its bone on | that part's plan entry, or author its bones by hand |
 | <a id="PROPOSE_TURN_RUN_GIVEN"></a><a id="PROPOSE_TURN_LAYER_PRESENT"></a><a id="PROPOSE_TURN_DEPTH_PRESENT"></a>`PROPOSE_TURN_RUN_GIVEN`, `PROPOSE_TURN_LAYER_PRESENT`, `PROPOSE_TURN_DEPTH_PRESENT` | with `--full`/`--head` (issue #251): a part came from a run whose layers were not given, the run given holds no layer of the part's tag, or its layer carries no `depth_median` while another part's layer carries one; a run with no depth on any part's layer (a PSD, or an export of one) is not refused — the turn is skipped, and the note says `turn: SKIP` and names the run (issue #359) | give the run the parts were assembled from, as the wrapper's `layers.json` |

package/docs/STABILITY.md

@@ -149,7 +149,7 @@ part name, `[i]` an entry of a list):
 - **meshes.<part>.auto.regions[i]** — required: `name`, `shape`, `maxEdgeLength`, `transition`, `grade`, `minArtSamples`, and `cx`, `cy`, `r` for a circle or `points` for a polygon; optional: `bone`, `band` (both or neither; with neither the region is density only)
 - **meshes.<part>.auto.boundaryRuns** — required: `maxVertices`
 - **meshes.<part>.auto.stimulus**, or each entry of it when a list — required: `chain`, `degrees`
-- **cloth.<tag>**, the tag bottomwear, back hair or front hair (issue #364; read by propose --cloth only) — required: `chains` (optional on `back hair`, issue #390), `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only), `part` (on bottomwear only)
+- **cloth.<tag>**, the tag bottomwear, back hair or front hair (issue #364; read by propose --cloth only) — required: `chains` (optional on `back hair`, issue #390), `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only), `part` (a string on bottomwear, or a list of parts in root-to-tip order on any tag, issue #437), `parts` (a list of parts in root-to-tip order on any tag, issue #437)
 - **cloth.<tag>.split** — required: `at`, `into`; optional: `hold_tip`
 - **cloth.<tag>.strength** — required: `trunk`, `branch`, `edge`
 - **cloth.<tag>.swing** — required: `scales`
@@ -160,8 +160,9 @@ 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`
+- **turn** — required: `pivot`, `depths`; optional: `deform`
 - **turn.depths.<part>** — a See-through depth
+- **turn.deform.<key>** — a per-degree fraction or coupling share (FACE_DEFORM_FRACTIONS, issue #436)
 - **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.26.0",
+  "version": "1.28.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/assemble.ts

@@ -1208,7 +1208,7 @@ function keepArtWhole(part: PlacedPart, cleared: Cleared[], holderAt: (q: number
  * hold the pixel after it); and every pixel at alpha >= `CORE_ALPHA`, which
  * is the seam override's.
  */
-export function pushBackFringe(parts: PlacedPart[], srcr: Raster, rule: SeamRule, silhouette: Mask | null): FringePushed[][] {
+export function pushBackFringe(parts: PlacedPart[], srcr: Raster, rule: SeamRule, silhouette: Mask | null, feathered: ReadonlyArray<Mask | null> | null = null): FringePushed[][] {
   const { width: W } = srcr;
   const { holder, cand } = seamCandidates(parts, srcr, rule, silhouette);
   const at = (i: number, d: number): number => {
@@ -1226,6 +1226,7 @@ export function pushBackFringe(parts: PlacedPart[], srcr: Raster, rule: SeamRule
     // cover itself the loop below has nothing to clear, and the seam override acts on the pixel as before.
     if (cand[d] === 0 || !shows(d)) continue;
     for (let i = holder[d] + 1; i < parts.length; i++) {
+      if (feathered?.[i]?.data[d] === 1) continue;
       const s = at(i, d);
       if (s < 0) continue;
       const img = parts[i].image.data;
@@ -1889,6 +1890,8 @@ interface Built {
   merged: number;
   /** The rig pixels this piece of the layer owns when the layer is cut, null when it is not: the counts are split by it. */
   region: Mask | null;
+  /** The rig pixels on an upper limb segment whose alpha `edge: "feather"` scaled down (issue #444). */
+  feathered?: Mask;
 }
 
 // ---------------------------------------------------------------------------
@@ -2263,6 +2266,9 @@ function cutLimbs(
       let featheredPx = 0;
       let band = 0;
       if (sg.edge === 'feather') {
+        const upperRegion = regions[upAt];
+        const upPiece = pieces[upAt] as Built;
+        const featheredMask = (upPiece.feathered ??= newMask(W, H));
         band = pyRound(Math.max(0, coveredRadius(line.at, radius, (x, y) => x >= 0 && y >= 0 && x < W && y < H && lower.data[(y * W + x) * 4 + 3] === 255)), 3);
         const fb = capBox(line.at, band);
         for (let y = Math.max(0, fb[1]); y < Math.min(H, fb[1] + fb[3]); y++) {
@@ -2276,6 +2282,11 @@ function cutLimbs(
             if (na === ua) continue;
             if (na === 0) upper.data.fill(0, p * 4, p * 4 + 4);
             else upper.data[p * 4 + 3] = na;
+            // Issue #444: a pixel the feather ramp fades to alpha <= OPAQUE_ALPHA_ABOVE is no longer opaque on the
+            // upper piece (its opacity is carried by the lower segment's opaque cap beneath), so it leaves the upper
+            // piece's region and its remaining ramp is marked feathered so pushBackFringe does not clear the fade.
+            if (na <= OPAQUE_ALPHA_ABOVE) upperRegion.data[p] = 0;
+            else featheredMask.data[p] = 1;
             featheredPx++;
           }
         }
@@ -2840,7 +2851,8 @@ export function assemble(input: AssembleInput): AssembleResult {
     const whole: PartRecord = { name, from: b.key, x: 0, y: 0, w: W, h: H, opaque_px: 0, projected_core_px: 0, source_px_taken: 0, refused_drift_px: 0, merged_px: 0, seam_override_px: 0 };
     return { record: whole, image: b.r };
   });
-  const pushedBy = pushBackFringe(stack, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null);
+  const featheredInOrder: Array<Mask | null> = order.map((d) => ('patch' in d ? null : (pieceAt(d).b.feathered ?? null)));
+  const pushedBy = pushBackFringe(stack, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null, featheredInOrder);
   // Issue #255: a part's drift refusals in a body, and who holds the body in the draw order (the push-back clears
   // only fringe below CORE_ALPHA, and the seam override only recolours, so the holders read here are final).
   const holderAt = new Int32Array(W * H).fill(-1);

package/src/check.ts

@@ -1045,6 +1045,21 @@ export interface LoopPhysics {
   in: 'rig.json' | 'motion.json';
 }
 
+/**
+ * A throwaway copy of `rig` whose accompanying `motion` replaces `animations`
+ * with a synthetic set (`still`, `blink_shut`, `stress ...`, `sweep ...`) omits
+ * any `slider` constraint whose target animation is not in that set.
+ */
+function withoutSliders(rig: Record<string, unknown>, animations: Record<string, unknown>): Record<string, unknown> {
+  if (!Array.isArray(rig.constraints)) return rig;
+  const kept = rig.constraints.filter((c) => !(isRecord(c) && c.type === 'slider' && typeof c.animation === 'string' && !(c.animation in animations)));
+  if (kept.length === rig.constraints.length) return rig;
+  const out: Record<string, unknown> = { ...rig };
+  if (kept.length > 0) out.constraints = kept;
+  else delete out.constraints;
+  return out;
+}
+
 /**
  * The rig spec and motion spec with every physics constraint left out, and
  * the constraints it left out; null when there is none, so a rig without one
@@ -3331,8 +3346,9 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
         mkdirSync(stressDir, { recursive: true });
         const base = stripped === null ? inp.rig : stripped.rig;
         const images = typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : inp.rig.images;
-        writeFileSync(join(stressDir, 'rig.json'), JSON.stringify({ ...base, images }));
-        writeFileSync(join(stressDir, 'motion.json'), JSON.stringify({ ...(stripped === null ? inp.motion : stripped.motion), animations: stressAnimations(plan) }));
+        const stressAnims = stressAnimations(plan);
+        writeFileSync(join(stressDir, 'rig.json'), JSON.stringify({ ...withoutSliders(base, stressAnims), images }));
+        writeFileSync(join(stressDir, 'motion.json'), JSON.stringify({ ...(stripped === null ? inp.motion : stripped.motion), animations: stressAnims }));
         const sb = rigc(['build', '--rig', join(stressDir, 'rig.json'), '--motion', join(stressDir, 'motion.json'), '--out', join(stressDir, 'build'), '--profile', 'spine']);
         if (sb.status !== 0) refuseIfAny(rigcFailed(`build (${STRESS_LINE}'s turned copy)`, sb, buildGateLines(sb.out)));
         const sr = rigc(['render', '--candidate', join(stressDir, 'build'), '--fps', String(IDLE_FPS), '--max', String(FOLD_RENDER_MAX), '--geometry', '--out', join(stressDir, 'render')]);
@@ -3380,7 +3396,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       const sets = new Map<string, { under: FrameSet; bare: FrameSet }>();
       if (copy.slots.length > 0) {
         for (const [file, image] of copy.images) writePng(join(imagesDir, file), image);
-        writeFileSync(join(sweepDir, 'rig.json'), JSON.stringify({ ...copy.rig, images: imagesDir }));
+        const sweepAnims = isRecord(copy.motion.animations) ? copy.motion.animations : {};
+        writeFileSync(join(sweepDir, 'rig.json'), JSON.stringify({ ...withoutSliders(copy.rig, sweepAnims), images: imagesDir }));
         writeFileSync(join(sweepDir, 'motion.json'), JSON.stringify(copy.motion));
         const sb = rigc(['build', '--rig', join(sweepDir, 'rig.json'), '--motion', join(sweepDir, 'motion.json'), '--out', join(sweepDir, 'build'), '--profile', 'spine']);
         if (sb.status !== 0) refuseIfAny(rigcFailed(`build (${SWEEP_LINE}'s bent copy)`, sb, buildGateLines(sb.out)));
@@ -3423,7 +3440,6 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     try {
       mkdirSync(stillDir, { recursive: true });
       const images = typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : inp.rig.images;
-      writeFileSync(join(stillDir, 'rig.json'), JSON.stringify({ ...inp.rig, images }));
       const eyes = full === null ? [] : partsTagged(full.parts, EYE_TAGS);
       const slotBone = new Map((Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => [String(sl.name), String(sl.bone)]));
       const shut = full === null ? [] : blinkTracks(inp.motion, eyeBones(inp.rig, eyes.map((p) => slotBone.get(p.name) ?? '')));
@@ -3437,6 +3453,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
           tracks: shut.map((b) => ({ ...b.target, property: 'scaley', keys: [{ t: 0, v: [b.closed] }, { t: STILL_DURATION, v: [b.closed] }] })),
         };
       }
+      const stillRig = { ...withoutSliders(inp.rig, animations), images };
+      writeFileSync(join(stillDir, 'rig.json'), JSON.stringify(stillRig));
       writeFileSync(join(stillDir, 'motion.json'), JSON.stringify({ ...inp.motion, animations }));
       const sb = rigc(['build', '--rig', join(stillDir, 'rig.json'), '--motion', join(stillDir, 'motion.json'), '--out', join(stillDir, 'build'), '--profile', 'spine']);
       if (sb.status !== 0) refuseIfAny(rigcFailed('build (the setup-pose still)', sb, buildGateLines(sb.out)));
@@ -3460,7 +3478,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       }
       if (inp.source !== null) {
         // The same pose with every slot tinted black, built with the same animations so rigc fits the same grid.
-        writeFileSync(join(stillDir, BLACK_RIG), JSON.stringify(blackRig({ ...inp.rig, images })));
+        writeFileSync(join(stillDir, BLACK_RIG), JSON.stringify(blackRig(stillRig)));
         const kb = rigc(['build', '--rig', join(stillDir, BLACK_RIG), '--motion', join(stillDir, 'motion.json'), '--out', join(stillDir, 'black_build'), '--profile', 'spine']);
         if (kb.status !== 0) refuseIfAny(rigcFailed('build (the setup-pose still, every slot tinted black)', kb, buildGateLines(kb.out)));
         const kr = rigc(['render', '--candidate', join(stillDir, 'black_build'), '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(maxSide), '--out', join(stillDir, 'black')]);

package/src/cloth.ts

@@ -95,8 +95,10 @@ export interface ClothRecipe {
   gravity: [number, number];
   translate?: number;
   swing?: { scales: number[] };
-  /** `bottomwear` only: a `topwear` part or its named cut skirt piece the skirt's trees are drafted on. */
-  part?: string;
+  /** `bottomwear` only when a string (a `topwear` part or its cut skirt piece, issue #402); on any target when a list of parts the recipe's trees run through from root to tip (issue #437; the single-part form is the one-element list). */
+  part?: string | string[];
+  /** A list of parts the recipe's trees run through in order from root to tip, one chain across the union and each link weighted to the part whose pixels it crosses (issue #437; the single-part form is the one-element list). */
+  parts?: string[];
 }
 
 export type ClothRecipes = Partial<Record<ClothTarget, ClothRecipe>>;
@@ -469,3 +471,28 @@ export function tailOverlap(tail: Tail, part: Mask, box: { x: number; y: number;
   }
   return { counts, over, total };
 }
+
+/**
+ * Issue #437: how many interior pixel steps along `span` (`a -> b`, sampled at
+ * `(s + 0.5) / ceil(|b - a|)` for `s = 0 .. ceil(|b - a|) - 1`) land on an
+ * opaque pixel of `mask`. Consecutive vertical links `[y0, y1]`, `[y1, y2]`
+ * sample half-open row intervals `[y0, y1)`, `[y1, y2)` with no shared boundary
+ * pixel at the joint `y1`, so a link strictly on one side of a horizontal seam
+ * takes 0 pixels on the other part.
+ */
+export function spanCrosses(span: Pick<TailSpan, 'a' | 'b'>, mask: Mask): number {
+  const [x0, y0] = span.a;
+  const [x1, y1] = span.b;
+  const dx = x1 - x0;
+  const dy = y1 - y0;
+  const steps = Math.max(1, Math.ceil(Math.sqrt(dx * dx + dy * dy)));
+  let count = 0;
+  for (let s = 0; s < steps; s++) {
+    const t = (s + 0.5) / steps;
+    const x = Math.floor(x0 + t * dx);
+    const y = Math.floor(y0 + t * dy);
+    if (x >= 0 && x < mask.width && y >= 0 && y < mask.height && mask.data[y * mask.width + x] !== 0) count++;
+  }
+  return count;
+}
+

package/src/config.ts

@@ -93,7 +93,7 @@ import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
 import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
-import { TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
+import { FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
 import { FLOOR_FORMS, type FloorForm, type MeshInfluences } from './weights.ts';
 
 export type Point = [number, number];
@@ -2842,7 +2842,7 @@ function checkCloth(c: Check, v: Json): void {
   for (const tag of CLOTH_TARGETS) {
     if (!(tag in v)) continue;
     const path = `${at}.${JSON.stringify(tag)}`;
-    const r = c.object(path, v[tag], ['links', 'wind', 'gravity'], ['chains', 'split', 'length_ratio', 'strength', 'damping', 'alternate_damping', 'translate', 'swing', 'part']);
+    const r = c.object(path, v[tag], ['links', 'wind', 'gravity'], ['chains', 'split', 'length_ratio', 'strength', 'damping', 'alternate_damping', 'translate', 'swing', 'part', 'parts']);
     if (r === null) continue;
     if (tag !== 'back hair' && !('chains' in r)) c.fail('CONFIG_FIELD_PRESENT', `${path}.chains`, 'is absent and required');
     const chains = 'chains' in r && c.int(`${path}.chains`, r.chains, 1) ? (r.chains as number) : null;
@@ -2897,11 +2897,32 @@ function checkCloth(c: Check, v: Json): void {
     if ('translate' in r && c.number(`${path}.translate`, r.translate, 'unit') && r.translate === 0) {
       c.fail('CONFIG_FIELD_TYPE', `${path}.translate`, 'is 0; a mix above 0 and at most 1 is required (leave translate out for none)');
     }
+    const checkPartList = (fieldPath: string, list: Json): void => {
+      if (!c.array(fieldPath, list, true)) return;
+      const seen = new Set<string>();
+      (list as Json[]).forEach((item, i) => {
+        if (c.string(`${fieldPath}[${i}]`, item)) {
+          const s = item as string;
+          if (seen.has(s)) {
+            c.fail('CONFIG_CLOTH_PARTS_UNIQUE', `${fieldPath}[${i}]`, `repeats "${s}"; each part in the list must be named once, in order from root to tip`);
+          }
+          seen.add(s);
+        }
+      });
+    };
+    if ('part' in r && 'parts' in r) {
+      c.fail('CONFIG_CLOTH_PARTS_UNIQUE', `${path}.parts`, 'is declared beside part; declare either parts (a list of parts from root to tip) or part, not both');
+    }
     if ('part' in r) {
-      if (tag !== 'bottomwear') {
+      if (Array.isArray(r.part)) {
+        checkPartList(`${path}.part`, r.part);
+      } else if (tag !== 'bottomwear') {
         c.fail('CONFIG_CLOTH_PART_ON_BOTTOMWEAR', `${path}.part`, `is declared on "${tag}"; part hands the skirt's recipe (bottomwear) to a topwear part or its cut skirt piece (a dress) — leave it out here`);
       } else c.string(`${path}.part`, r.part);
     }
+    if ('parts' in r) {
+      checkPartList(`${path}.parts`, r.parts);
+    }
     if ('swing' in r) {
       if (tag !== 'bottomwear') {
         c.fail('CONFIG_CLOTH_SWING_SCALE_PER_TREE', `${path}.swing`, `is declared on "${tag}"; the shared swing is the skirt's (bottomwear) — leave it out here`);
@@ -2954,7 +2975,7 @@ function checkScene(c: Check, v: Json): void {
 
 function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>): void {
   const at = 'config.turn';
-  const o = c.object(at, v, ['pivot', 'depths'], []);
+  const o = c.object(at, v, ['pivot', 'depths'], ['deform']);
   if (o === null) return;
   const pivot = 'pivot' in o && c.number(`${at}.pivot`, o.pivot) ? (o.pivot as number) : null;
   const depths: Record<string, number> = {};
@@ -2975,6 +2996,35 @@ function checkTurn(c: Check, v: Json, attached: Set<string>, bones: Set<string>)
       }
     }
   }
+  if ('deform' in o) {
+    const df = o.deform;
+    if (!isPlainObject(df)) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.deform`, `is ${show(df)}; an object of face deform key -> per-degree fraction is required`);
+    } else {
+      const known = Object.keys(FACE_DEFORM_FRACTIONS);
+      for (const [key, val] of Object.entries(df)) {
+        if (isRecordKey(key)) continue;
+        if (key === 'note' || key.endsWith('_note')) {
+          if (typeof val !== 'string') c.fail('CONFIG_FIELD_TYPE', `${at}.deform.${key}`, `is ${show(val)}; an annotation is a string`);
+          continue;
+        }
+        if (!Object.hasOwn(FACE_DEFORM_FRACTIONS, key)) {
+          c.fail('CONFIG_KEY_KNOWN', `${at}.deform.${key}`, `is not a known face deform fraction; expected one of ${known.join(', ')} — ${DOORS}`);
+          continue;
+        }
+        if (c.number(`${at}.deform.${key}`, val)) {
+          const [lo, hi] = FACE_DEFORM_RANGES[key as FaceDeformKey];
+          if (val < lo || val > hi) {
+            c.fail(
+              'CONFIG_TURN_DEFORM_RANGE',
+              `${at}.deform.${key}`,
+              `is ${val}; a per-degree fraction in [${lo}, ${hi}] is required (default ${FACE_DEFORM_FRACTIONS[key as FaceDeformKey]})`,
+            );
+          }
+        }
+      }
+    }
+  }
   if (pivot !== null && depthsOk) {
     const nearest = turnNearest(depths);
     if (nearest !== null && !(pivot > nearest.depth)) {

package/src/coords.ts

@@ -22,5 +22,5 @@
  * `flattenRig` goes back through `toWorld`. No rotation matrix is written out
  * by hand in this package.
  */
-export { computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toWorld } from 'rig-c/src/transform.ts';
+export { computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toBoneLocalVector, toWorld } from 'rig-c/src/transform.ts';
 export type { BoneTransform } from 'rig-c/src/transform.ts';

package/src/motion.ts

@@ -145,16 +145,26 @@ export interface MotionSpec {
   animations: { idle: { duration: number; loop: true; note: string; tracks: MotionTrack[] } };
 }
 
+const FACE_DEFORM_HOOK = new WeakMap<MotionSpec, (merged: MotionSpec & { animations: Record<string, unknown> }) => void>();
+
+/** Attach a face-surface-deform hook to `motion` so {@link withAnimations} applies it when `turn`/`tilt` slider animations are merged (issue #436). */
+export function bindFaceSurfaceDeform(motion: MotionSpec, hook: (merged: MotionSpec & { animations: Record<string, unknown> }) => void): void {
+  FACE_DEFORM_HOOK.set(motion, hook);
+}
+
 /**
  * The motion `motion.json` holds: the idle, and after it every animation the
- * file `config.motion.animations_from` names, as read (issue #183) — nothing
- * added, nothing re-keyed, nothing judged; each is rigc's to accept at the
- * gate. With none, `motion` itself, so a config that names no file writes the
- * bytes it wrote before the field existed.
+ * file `config.motion.animations_from` names, as read (issue #183) — plus, when
+ * those animations hold `turn` or `tilt` slider `derive` keys, the Set B ×2.5
+ * face surface deform (issue #436). With none, `motion` itself, so a config
+ * that names no file writes the bytes it wrote before the field existed.
  */
 export function withAnimations(motion: MotionSpec, extra: Readonly<Record<string, unknown>> | null): MotionSpec | Record<string, unknown> {
   if (extra === null) return motion;
-  return { ...motion, animations: { ...motion.animations, ...extra } };
+  const merged = { ...motion, animations: { ...motion.animations, ...extra } };
+  const hook = FACE_DEFORM_HOOK.get(motion);
+  if (hook !== undefined) hook(merged);
+  return merged;
 }
 
 /** One sine channel over an idle of `duration` seconds. */