@rig-c/parts 1.27.0 → 1.29.0

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];
@@ -139,9 +139,29 @@ export interface Generation {
   control?: Control;
 }
 
+export type ArmSplitTag = 'handwear-r' | 'handwear-l';
+export const ARM_SPLIT_TAGS: readonly ArmSplitTag[] = ['handwear-r', 'handwear-l'];
+
+/**
+ * Issue #439: an optional declaration on `config.seethrough` that separates
+ * overlapping arms in the full run into `handwear-r` (smaller image x, the
+ * character's right as they face the viewer) and `handwear-l` (larger image x,
+ * the character's left) in the draw order `order` states, back to front.
+ * Exactly one of `x` (an integer column on the full run's canvas) or `line`
+ * (a polyline of at least two `[x, y]` integer points on the full run's
+ * canvas) is given.
+ */
+export interface ArmSplit {
+  x?: number;
+  line?: Array<[number, number]>;
+  order: ['handwear-r', 'handwear-l'] | ['handwear-l', 'handwear-r'];
+}
+
 export interface SeeThrough {
   /** Square crop `[x0, y0, x1, y1]` in source pixels for the second, head-only run. */
   head_box?: [number, number, number, number];
+  /** Issue #439: arm separation when both arms overlap in the full run. */
+  arm_split?: ArmSplit;
   resolution: number;
   steps: number;
   seed: number;
@@ -701,9 +721,21 @@ export interface LimbSegment {
   cut_band?: number;
 }
 
+/**
+ * Issue #446: a per-limb split declared on the covering limb where two limbs
+ * share one part and cross: either `line` (a polyline of two or more `[x, y]`
+ * points in rig px along the covering limb's seam) or `edge: "painting"`
+ * (traces the covering limb's painted stroke or silhouette across the crossing).
+ */
+export interface LimbSplit {
+  line?: Array<[number, number]>;
+  edge?: 'painting';
+}
+
 /** A limb (issue #349): its segments, upper first; each segment's bone is the child of the one before. */
 export interface Limb {
   segments: LimbSegment[];
+  split?: LimbSplit;
 }
 
 export interface CharacterConfig {
@@ -1571,10 +1603,10 @@ function checkGeneration(c: Check, v: Json): void {
 }
 
 function checkSeeThrough(c: Check, v: Json): void {
-  const s = c.object('config.seethrough', v, ['resolution', 'steps', 'seed', 'offload'], ['head_box']);
+  const s = c.object('config.seethrough', v, ['resolution', 'steps', 'seed', 'offload'], ['head_box', 'arm_split']);
   if (s === null) return;
   const p = 'config.seethrough';
-  if ('resolution' in s) c.int(`${p}.resolution`, s.resolution, 1);
+  const res = 'resolution' in s && c.int(`${p}.resolution`, s.resolution, 1) ? (s.resolution as number) : null;
   if ('steps' in s) c.int(`${p}.steps`, s.steps, 1);
   if ('seed' in s) c.int(`${p}.seed`, s.seed, 0);
   if ('offload' in s && typeof s.offload !== 'boolean') c.fail('CONFIG_FIELD_TYPE', `${p}.offload`, `is ${show(s.offload)}; true or false is required`);
@@ -1589,6 +1621,55 @@ function checkSeeThrough(c: Check, v: Json): void {
       }
     }
   }
+  if ('arm_split' in s) checkArmSplit(c, `${p}.arm_split`, s.arm_split, res);
+}
+
+function checkArmSplit(c: Check, path: string, v: Json, resolution: number | null): void {
+  const a = c.object(path, v, ['order'], ['x', 'line']);
+  if (a === null) return;
+  if (!('x' in a) && !('line' in a)) {
+    c.fail('CONFIG_FIELD_PRESENT', path, 'has neither x nor line; a split column ("x") or a polyline ("line") is required to separate the arms');
+  } else if ('x' in a && 'line' in a) {
+    c.fail('CONFIG_FIELD_TYPE', `${path}.line`, 'is set alongside x; give either a split column ("x") or a polyline ("line"), not both');
+  }
+  if ('x' in a && c.number(`${path}.x`, a.x, 'non-negative')) {
+    const x = a.x as number;
+    if (resolution !== null && x > resolution) {
+      c.fail('CONFIG_FIELD_TYPE', `${path}.x`, `is ${x}; a column inside the ${resolution}x${resolution} run canvas (0 <= x <= ${resolution}) is required`);
+    }
+  }
+  if ('line' in a) {
+    const l = a.line;
+    if (!Array.isArray(l) || l.length < 2) {
+      c.fail('CONFIG_FIELD_TYPE', `${path}.line`, `is ${show(l)}; an array of at least 2 [x, y] points in run pixels is required`);
+    } else {
+      l.forEach((pt, i) => {
+        const ok = Array.isArray(pt) && pt.length === 2 && pt.every((n) => typeof n === 'number' && Number.isFinite(n));
+        if (!ok) {
+          c.fail('CONFIG_FIELD_TYPE', `${path}.line[${i}]`, `is ${show(pt)}; a point [x, y] in run pixels is required`);
+          return;
+        }
+        const [px, py] = pt as [number, number];
+        if (px < 0 || py < 0 || (resolution !== null && (px > resolution || py > resolution))) {
+          c.fail(
+            'CONFIG_FIELD_TYPE',
+            `${path}.line[${i}]`,
+            `is [${px}, ${py}]; ${resolution !== null ? `a point inside the ${resolution}x${resolution} run canvas (0 <= x, y <= ${resolution})` : 'x >= 0 and y >= 0'} is required`,
+          );
+        }
+      });
+    }
+  }
+  if ('order' in a) {
+    const o = a.order;
+    const valid =
+      Array.isArray(o) &&
+      o.length === 2 &&
+      ((o[0] === 'handwear-r' && o[1] === 'handwear-l') || (o[0] === 'handwear-l' && o[1] === 'handwear-r'));
+    if (!valid) {
+      c.fail('CONFIG_FIELD_TYPE', `${path}.order`, `is ${show(o)}; ["handwear-r", "handwear-l"] or ["handwear-l", "handwear-r"] (back to front) is required`);
+    }
+  }
 }
 
 function checkRunTag(c: Check, path: string, run: Json, tag: Json): void {
@@ -2309,10 +2390,39 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
   }
   const sources = new Set([...made.parts, ...made.cuts]);
   const firstAt = new Map<string, string>();
+  const limbFroms = new Map<string, Set<string>>();
+  const splitLimbs: string[] = [];
   for (const [limb, spec] of Object.entries(v)) {
     const at = `config.limbs.${limb}`;
-    const o = c.object(at, spec, ['segments'], []);
-    if (o === null || !('segments' in o)) continue;
+    const o = c.object(at, spec, ['segments'], ['split']);
+    if (o === null) continue;
+    if ('split' in o) {
+      const sp = c.object(`${at}.split`, o.split, [], ['line', 'edge']);
+      if (sp !== null) {
+        const hasLine = 'line' in sp;
+        const hasEdge = 'edge' in sp;
+        if ((hasLine && hasEdge) || (!hasLine && !hasEdge)) {
+          c.fail('CONFIG_FIELD_TYPE', `${at}.split`, `is ${show(o.split)}; either "line" (a polyline of two or more [x, y] points in rig px) or "edge": "painting" is required, not both and not neither`);
+        } else if (hasLine) {
+          const pts = sp.line;
+          const ok =
+            Array.isArray(pts) &&
+            pts.length >= 2 &&
+            pts.every((p) => Array.isArray(p) && p.length === 2 && typeof p[0] === 'number' && Number.isFinite(p[0]) && typeof p[1] === 'number' && Number.isFinite(p[1]));
+          if (!ok) {
+            c.fail('CONFIG_FIELD_TYPE', `${at}.split.line`, `is ${show(pts)}; an array of two or more [x, y] points in rig px is required`);
+          } else {
+            const typed = pts as Array<[number, number]>;
+            if (typed.every((p) => p[0] === typed[0][0] && p[1] === typed[0][1])) {
+              c.fail('CONFIG_FIELD_TYPE', `${at}.split.line`, `is ${show(pts)}; a polyline with non-zero length is required — all points stand on [${typed[0].join(', ')}]`);
+            } else splitLimbs.push(limb);
+          }
+        } else if (sp.edge !== 'painting') {
+          c.fail('CONFIG_FIELD_TYPE', `${at}.split.edge`, `is ${show(sp.edge)}; "painting" is required — traces the covering limb's edge across the crossing from the painting's own stroke or silhouette`);
+        } else splitLimbs.push(limb);
+      }
+    }
+    if (!('segments' in o)) continue;
     if (!Array.isArray(o.segments) || o.segments.length < 2) {
       c.fail('CONFIG_FIELD_TYPE', `${at}.segments`, `is ${show(o.segments)}; an array of two segments or more, upper first, is required — a limb is cut at a joint, and a joint has a segment on each side`);
       continue;
@@ -2382,6 +2492,7 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
         }
       }
     });
+    limbFroms.set(limb, new Set(froms.filter((f): f is string => f !== null)));
     froms.forEach((f, i) => {
       if (f === null || i === 0 || froms[i - 1] === f) return;
       const back = froms.slice(0, i - 1).lastIndexOf(f);
@@ -2399,6 +2510,20 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
       });
     }
   }
+  for (const limb of splitLimbs) {
+    const myFroms = limbFroms.get(limb) ?? new Set<string>();
+    if (myFroms.size === 0) continue;
+    const sharers = [...limbFroms.entries()].filter(([other, fs]) => other !== limb && [...myFroms].some((f) => fs.has(f)));
+    if (sharers.length === 0) {
+      c.fail('CONFIG_FIELD_TYPE', `config.limbs.${limb}.split`, `is declared on "${limb}", whose from part(s) (${[...myFroms].map((f) => `"${f}"`).join(', ')}) no other limb takes; a per-limb split divides a part shared by two limbs`);
+    } else {
+      const otherSplit = sharers.find(([other]) => splitLimbs.includes(other));
+      if (otherSplit !== undefined) {
+        const sharedFrom = [...myFroms].find((f) => otherSplit[1].has(f)) as string;
+        c.fail('CONFIG_FIELD_TYPE', `config.limbs.${limb}.split`, `is declared on "${limb}" and on "${otherSplit[0]}", which both take "${sharedFrom}"; declare split on the covering limb alone`);
+      }
+    }
+  }
   return out;
 }
 
@@ -2975,7 +3100,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> = {};
@@ -2996,6 +3121,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/diagnostics.ts

@@ -79,6 +79,7 @@ export interface BasisFile {
  * `derived` placement names at least one bone; a constant is a finite number.
  */
 export function checkBasis(P: PartSet, proposal: Proposal, basis: ProposalBasis): void {
+  P = P.beforeLimbs();
   const problems: Problem[] = [];
   const names = [...expand(proposal.bones).byName.keys()];
   const bones = new Set(names);

package/src/limbs.ts

@@ -92,8 +92,19 @@
  *   cuff; any 4-connected island on a forearm piece that leaves its own hand's
  *   keypoint region is transferred to the other forearm piece, so no slivers
  *   are cut out of the front hand for the back arm.
+ * - **Crossed limbs** (issue #446, {@link limbCrossing},
+ *   {@link assignCrossedLimbs}). When two limbs share a part and cross in an X,
+ *   the covering limb may declare `split` (`line` or `edge: "painting"`):
+ *   under `line`, rays from the covering limb's bone polyline split pixels at
+ *   the declared polyline (and its matching half-width on the opposite side
+ *   when one edge is given); under `edge: "painting"`, each ray from the
+ *   covering limb's bone polyline walks outward through the covering limb's
+ *   interior fill and stops at the outer edge of its dark stroke (`luma <=` the
+ *   part's Otsu split) or transparent silhouette. Without `split`,
+ *   {@link nearestLimb} stays as it was and `propose`'s `LINT` names the
+ *   crossing.
  */
-import type { BoneEntry, Limb } from './config.ts';
+import type { BoneEntry, Limb, LimbSplit } from './config.ts';
 
 export type Pt = [number, number];
 
@@ -600,3 +611,212 @@ export function assignOverlappingHands(back: ForearmShare, front: ForearmShare,
   }
 }
 
+/**
+ * Issue #446: the crossing point `[x, y]` (rig px) where two limb polylines `a`
+ * and `b` cross in an X, or `null` when they do not cross. Two polylines cross
+ * when a segment of `a` and a segment of `b` intersect in their interiors
+ * (`0 < ta < 1` and `0 < tb < 1`), or meet at an interior joint vertex while
+ * the two polylines' start-to-end chords cross in their interiors.
+ */
+export function limbCrossing(a: readonly Pt[], b: readonly Pt[]): Pt | null {
+  if (a.length < 2 || b.length < 2) return null;
+  const segHit = (p0: Pt, p1: Pt, q0: Pt, q1: Pt): { at: Pt; ta: number; tb: number } | null => {
+    const dax = p1[0] - p0[0];
+    const day = p1[1] - p0[1];
+    const dbx = q1[0] - q0[0];
+    const dby = q1[1] - q0[1];
+    const denom = dax * dby - day * dbx;
+    if (Math.abs(denom) <= 1e-9) return null;
+    const rx = q0[0] - p0[0];
+    const ry = q0[1] - p0[1];
+    const ta = (rx * dby - ry * dbx) / denom;
+    const tb = (rx * day - ry * dax) / denom;
+    if (ta < -1e-6 || ta > 1 + 1e-6 || tb < -1e-6 || tb > 1 + 1e-6) return null;
+    return { at: [p0[0] + ta * dax, p0[1] + ta * day], ta, tb };
+  };
+  const chordHit = segHit(a[0], a[a.length - 1], b[0], b[b.length - 1]);
+  if (chordHit === null || chordHit.ta <= 1e-6 || chordHit.ta >= 1 - 1e-6 || chordHit.tb <= 1e-6 || chordHit.tb >= 1 - 1e-6) return null;
+  for (let i = 0; i + 1 < a.length; i++) {
+    for (let j = 0; j + 1 < b.length; j++) {
+      const hit = segHit(a[i], a[i + 1], b[j], b[j + 1]);
+      if (hit !== null) return hit.at;
+    }
+  }
+  return chordHit.at;
+}
+
+/** The point on polyline `pts` nearest `(x, y)`. */
+function closestOnPolyline(pts: readonly Pt[], x: number, y: number): Pt {
+  if (pts.length === 1) return [pts[0][0], pts[0][1]];
+  let bestD = Infinity;
+  let best: Pt = [pts[0][0], pts[0][1]];
+  for (let i = 0; i + 1 < pts.length; i++) {
+    const [ax, ay] = pts[i];
+    const dx = pts[i + 1][0] - ax;
+    const dy = pts[i + 1][1] - ay;
+    const len2 = dx * dx + dy * dy;
+    const t = len2 === 0 ? 0 : Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / len2));
+    const qx = ax + t * dx;
+    const qy = ay + t * dy;
+    const d = (x - qx) ** 2 + (y - qy) ** 2;
+    if (d < bestD) {
+      bestD = d;
+      best = [qx, qy];
+    }
+  }
+  return best;
+}
+
+/**
+ * Issue #446: assign pixels of a shared part `r` between the covering limb
+ * (`coverIdx`, polyline `coverPoly`, declaring `split`) and the covered limb(s)
+ * (`underIndices`, polylines `underPolys`). Mutates `own` in place.
+ */
+export function assignCrossedLimbs(
+  coverIdx: number,
+  coverPoly: readonly Pt[],
+  split: LimbSplit,
+  underIndices: readonly number[],
+  underPolys: ReadonlyArray<readonly Pt[]>,
+  r: { width: number; height: number; data: ArrayLike<number> },
+  opaqueAlphaAbove: number,
+  own: Int32Array,
+): void {
+  if (underIndices.length === 0 || coverPoly.length === 0) return;
+  const W = r.width;
+  const H = r.height;
+  const nearestOwn = new Int32Array(own);
+  const underOf = (x: number, y: number): number => underIndices[underIndices.length === 1 ? 0 : nearestLimb(underPolys, x, y)];
+
+  if (split.line !== undefined) {
+    const line = split.line;
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const p = y * W + x;
+        if (r.data[p * 4 + 3] === 0) continue;
+        const px = x + 0.5;
+        const py = y + 0.5;
+        const c = closestOnPolyline(coverPoly, px, py);
+        const dx = px - c[0];
+        const dy = py - c[1];
+        const dP = Math.sqrt(dx * dx + dy * dy);
+        if (dP <= 1e-9) {
+          own[p] = coverIdx;
+          continue;
+        }
+        const ux = dx / dP;
+        const uy = dy / dP;
+        let hitPos: number | null = null;
+        let hitNeg: number | null = null;
+        for (let j = 0; j + 1 < line.length; j++) {
+          const sx = line[j + 1][0] - line[j][0];
+          const sy = line[j + 1][1] - line[j][1];
+          const denom = ux * sy - uy * sx;
+          if (Math.abs(denom) <= 1e-9) continue;
+          const rx = line[j][0] - c[0];
+          const ry = line[j][1] - c[1];
+          const s = (rx * sy - ry * sx) / denom;
+          const v = (rx * uy - ry * ux) / denom;
+          if (v < -1e-6 || v > 1 + 1e-6) continue;
+          if (s > 1e-6 && (hitPos === null || s < hitPos)) hitPos = s;
+          else if (s < -1e-6 && (hitNeg === null || -s < hitNeg)) hitNeg = -s;
+        }
+        if (hitPos !== null) {
+          own[p] = dP <= hitPos + 1e-9 ? coverIdx : underOf(x, y);
+        } else if (hitNeg !== null) {
+          own[p] = dP <= hitNeg + 1e-9 ? coverIdx : underOf(x, y);
+        }
+      }
+    }
+    return;
+  }
+
+  const hist = new Array<number>(256).fill(0);
+  for (let p = 0; p < W * H; p++) {
+    if (r.data[p * 4 + 3] > opaqueAlphaAbove) {
+      hist[luma601(r.data[p * 4], r.data[p * 4 + 1], r.data[p * 4 + 2])]++;
+    }
+  }
+  const strokeLumaMax = otsuDarkMax(hist);
+
+  const hasGapAlong = (c: Pt, px: number, py: number, dP: number): boolean => {
+    const steps = Math.max(1, Math.ceil(dP * 2));
+    const dx = px - c[0];
+    const dy = py - c[1];
+    for (let s = 0; s <= steps; s++) {
+      const sx = Math.min(W - 1, Math.max(0, Math.floor(c[0] + (dx * s) / steps)));
+      const sy = Math.min(H - 1, Math.max(0, Math.floor(c[1] + (dy * s) / steps)));
+      if (r.data[(sy * W + sx) * 4 + 3] <= opaqueAlphaAbove) return true;
+    }
+    return false;
+  };
+
+  let maxUncrossedHalfWidth = 0;
+  let maxFallbackHalfWidth = 0;
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const p = y * W + x;
+      if (r.data[p * 4 + 3] <= opaqueAlphaAbove || nearestOwn[p] !== coverIdx) continue;
+      const px = x + 0.5;
+      const py = y + 0.5;
+      const c = closestOnPolyline(coverPoly, px, py);
+      const dP = Math.sqrt((px - c[0]) ** 2 + (py - c[1]) ** 2);
+      if (hasGapAlong(c, px, py, dP)) continue;
+      if (dP > maxFallbackHalfWidth) maxFallbackHalfWidth = dP;
+      const dUnder = Math.sqrt(Math.min(...underPolys.map((up) => polylineDist2(up, px, py))));
+      if (dUnder > dP + 1.5 && dP > maxUncrossedHalfWidth) maxUncrossedHalfWidth = dP;
+    }
+  }
+  if (maxUncrossedHalfWidth === 0) maxUncrossedHalfWidth = maxFallbackHalfWidth;
+
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const p = y * W + x;
+      if (r.data[p * 4 + 3] === 0) continue;
+      const px = x + 0.5;
+      const py = y + 0.5;
+      const c = closestOnPolyline(coverPoly, px, py);
+      const dx = px - c[0];
+      const dy = py - c[1];
+      const dP = Math.sqrt(dx * dx + dy * dy);
+      if (dP <= 0.5) {
+        own[p] = coverIdx;
+        continue;
+      }
+      const steps = Math.max(1, Math.ceil(dP * 2));
+      let hitGap = false;
+      let seenFill = false;
+      let inStroke = false;
+      let exitedStroke = false;
+      for (let s = 0; s <= steps; s++) {
+        const sx = Math.min(W - 1, Math.max(0, Math.floor(c[0] + (dx * s) / steps)));
+        const sy = Math.min(H - 1, Math.max(0, Math.floor(c[1] + (dy * s) / steps)));
+        const sp = sy * W + sx;
+        if (r.data[sp * 4 + 3] <= opaqueAlphaAbove) {
+          hitGap = true;
+          break;
+        }
+        if (strokeLumaMax !== null) {
+          const l = luma601(r.data[sp * 4], r.data[sp * 4 + 1], r.data[sp * 4 + 2]);
+          if (l > strokeLumaMax) {
+            if (inStroke) {
+              exitedStroke = true;
+              break;
+            }
+            seenFill = true;
+          } else if (seenFill) {
+            inStroke = true;
+          }
+        }
+      }
+      if (hitGap) {
+        own[p] = nearestOwn[p];
+      } else if (strokeLumaMax !== null) {
+        own[p] = !exitedStroke && dP <= maxUncrossedHalfWidth + 1e-6 ? coverIdx : underOf(x, y);
+      } else {
+        own[p] = dP <= maxUncrossedHalfWidth + 1e-6 ? coverIdx : underOf(x, y);
+      }
+    }
+  }
+}
+

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. */