@rig-c/parts 1.25.0 → 1.27.0

package/src/check.ts

@@ -2017,12 +2017,24 @@ export const FOLD_RENDER_MAX = 16;
 /** The fold render, under `--out`; removed before the stage returns. */
 const FOLD_SCRATCH = '_folds';
 
-/** One mesh that folds in one animation: rigc's figures, the declaration that takes it if any, and rigc's own line. */
+/** One side of a mesh's fold reading (with physics on or off): rigc's figures and its printed line. */
+export interface FoldSide {
+  /** How many frames show a folded triangle. */
+  frames: number;
+  /** The frame with the most, the earliest on a tie (rigc's `worst`). */
+  worst_frame: number;
+  /** How many triangles are folded on that frame. */
+  worst_triangles: number;
+  /** rigc's printed line for the mesh, verbatim (`rigc render --folds`). */
+  line: string;
+}
+
+/** One mesh that folds in one animation: rigc's figures, with physics on and off side by side, its physics constraints when only physics folds it, the declaration that takes it if any, and rigc's own line. */
 export interface FoldRow {
   animation: string;
   slot: string;
   attachment: string;
-  /** How many frames show a folded triangle. */
+  /** How many frames show a folded triangle (the active reading, physics on when the rig has physics). */
   frames: number;
   /** The frame with the most, the earliest on a tie (rigc's `worst`). */
   worst_frame: number;
@@ -2030,6 +2042,12 @@ export interface FoldRow {
   worst_triangles: number;
   /** How many triangles the mesh has. */
   triangles: number;
+  /** The reading with physics on, or null when the mesh folds only with physics off. */
+  physics_on: FoldSide | null;
+  /** The reading with physics off, or null when the mesh folds only with physics on. */
+  physics_off: FoldSide | null;
+  /** When the mesh folds only with physics on (`physics_on !== null && physics_off === null`), the physics constraints on its bones (`<name> on <bone>`); empty otherwise. */
+  physics_constraints: string[];
   /** The `may_fold` entry's why when the requirements file declares this slot and animation; null when nothing does. */
   declared: string | null;
   /** rigc's printed line for the mesh, verbatim (`rigc render --folds`). */
@@ -2042,7 +2060,7 @@ export interface FoldsLine {
   /** Every animation, the idle included, in motion.json's order: each one read. */
   animations: string[];
   fps: number;
-  /** How many physics constraints the read build left out ({@link withoutPhysics}); 0 when the rig has none. */
+  /** How many physics constraints the rig declares ({@link withoutPhysics}) — stepped in `physics_on` and left out in `physics_off`; 0 when the rig has none. */
   physics_left_out: number;
   /** Every mesh that folds in an animation read, in that animation's order and rigc's mesh order. */
   folding: FoldRow[];
@@ -2130,26 +2148,118 @@ export function readFoldSets(dir: string, named: readonly string[], fps: number,
 }
 
 /**
- * The fold line (issue #320) from the reading: every folding mesh a row, a
- * row no `may_fold` entry takes a `CHECK_ANIMATIONS_DO_NOT_FOLD` problem
- * naming the animation, the slot and rigc's line, and an entry no row
- * matches a problem of its own — a declaration that excepts nothing.
+ * The physics constraints on the bones a mesh attachment is bound to (or their
+ * ancestors, or `<bone>` when a stopped link is bound as `<bone>_d`), in
+ * {@link withoutPhysics} order, formatted `"<name> on <bone>"`.
  */
-export function foldsLine(named: readonly string[], fps: number, physicsLeftOut: number, readings: ReadonlyMap<string, readonly FoldingMesh[]>, mayFold: readonly MayFold[], requirementsPath: string | null, problems: Problem[]): FoldsLine {
+export function meshPhysicsConstraints(rig: Record<string, unknown>, slot: string, attachment: string, physics: readonly LoopPhysics[]): string[] {
+  if (physics.length === 0) return [];
+  const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord).filter((b) => typeof b.name === 'string');
+  const parent = new Map(bones.map((b) => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
+  const skins = isRecord(rig.skins) ? rig.skins : {};
+  const skin = isRecord(skins.default) ? skins.default : {};
+  const onSlot = isRecord(skin[slot]) ? skin[slot] : {};
+  const att = isRecord(onSlot[attachment]) ? onSlot[attachment] : null;
+  const bound = new Set<string>();
+  const addWithAncestors = (start: string): void => {
+    for (let b: string | null = start; b !== null && !bound.has(b); b = parent.get(b) ?? null) {
+      bound.add(b);
+      if (b.endsWith('_d')) bound.add(b.slice(0, -2));
+    }
+  };
+  if (att !== null && Array.isArray(att.weights)) {
+    for (const v of att.weights) {
+      if (!Array.isArray(v)) continue;
+      for (const w of v) if (isRecord(w) && typeof w.bone === 'string' && typeof w.weight === 'number' && w.weight > 0) addWithAncestors(w.bone);
+    }
+  }
+  if (bound.size === 0) {
+    const slotRec = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find((s) => s.name === slot);
+    if (slotRec !== undefined && typeof slotRec.bone === 'string') addWithAncestors(slotRec.bone);
+  }
+  const direct = physics.filter((p) => bound.has(p.bone));
+  return (direct.length > 0 ? direct : physics).map((p) => `${p.name} on ${p.bone}`);
+}
+
+/**
+ * The fold line (issues #320, #333, #363) from the reading: posed with physics
+ * stepping on the render clock (`readings`, and `readingsWithoutPhysics`
+ * beside it when the rig declares physics constraints), every folding mesh a
+ * row reporting `physics_on` and `physics_off` side by side, a row no
+ * `may_fold` entry takes a `CHECK_ANIMATIONS_DO_NOT_FOLD` problem naming the
+ * animation, the slot, the physics constraint(s) on its bones and the worst
+ * frame when the fold appears only with physics on, and rigc's line, and an
+ * entry no row matches a problem of its own — a declaration that excepts
+ * nothing.
+ */
+export function foldsLine(
+  named: readonly string[],
+  fps: number,
+  physicsLeftOut: number,
+  readings: ReadonlyMap<string, readonly FoldingMesh[]>,
+  mayFold: readonly MayFold[],
+  requirementsPath: string | null,
+  problems: Problem[],
+  readingsWithoutPhysics: ReadonlyMap<string, readonly FoldingMesh[]> = readings,
+  rig: Record<string, unknown> = {},
+  physicsList: readonly LoopPhysics[] = [],
+): FoldsLine {
+  const toSide = (m: FoldingMesh | undefined): FoldSide | null =>
+    m === undefined ? null : { frames: m.frames, worst_frame: m.worstFrame, worst_triangles: m.worstTriangles, line: m.line };
   const folding: FoldRow[] = [];
   for (const name of named) {
-    for (const m of readings.get(name) ?? []) {
-      const entry = mayFold.find((e) => e.slot === m.slot && e.animation === name);
-      folding.push({ animation: name, slot: m.slot, attachment: m.attachment, frames: m.frames, worst_frame: m.worstFrame, worst_triangles: m.worstTriangles, triangles: m.triangleCount, declared: entry === undefined ? null : entry.why, line: m.line });
+    const onList = readings.get(name) ?? [];
+    const offList = readingsWithoutPhysics.get(name) ?? [];
+    const seen = new Set<string>();
+    const keys: Array<{ slot: string; attachment: string }> = [];
+    for (const m of [...onList, ...offList]) {
+      const k = `${m.slot}\0${m.attachment}`;
+      if (!seen.has(k)) {
+        seen.add(k);
+        keys.push({ slot: m.slot, attachment: m.attachment });
+      }
+    }
+    for (const { slot, attachment } of keys) {
+      const on = onList.find((m) => m.slot === slot && m.attachment === attachment);
+      const off = offList.find((m) => m.slot === slot && m.attachment === attachment);
+      const primary = (on ?? off) as FoldingMesh;
+      const entry = mayFold.find((e) => e.slot === slot && e.animation === name);
+      const onlyPhysicsOn = on !== undefined && off === undefined;
+      const constraints = onlyPhysicsOn ? meshPhysicsConstraints(rig, slot, attachment, physicsList) : [];
+      folding.push({
+        animation: name,
+        slot,
+        attachment,
+        frames: primary.frames,
+        worst_frame: primary.worstFrame,
+        worst_triangles: primary.worstTriangles,
+        triangles: primary.triangleCount,
+        physics_on: toSide(on),
+        physics_off: toSide(off),
+        physics_constraints: constraints,
+        declared: entry === undefined ? null : entry.why,
+        line: primary.line,
+      });
     }
   }
-  const physics = physicsLeftOut === 0 ? '' : `, its ${physicsLeftOut} physics constraint(s) left out`;
+  const physics =
+    physicsLeftOut === 0
+      ? ''
+      : `, with its ${physicsLeftOut} physics constraint(s) on and off`;
   for (const r of folding) {
     if (r.declared !== null) continue;
+    const sideClause =
+      r.physics_on !== null && r.physics_off === null && physicsLeftOut > 0
+        ? ` (physics on: ${r.physics_on.frames} frame(s), worst frame ${r.physics_on.worst_frame} (${r.physics_on.worst_triangles}/${r.triangles} triangle(s)); physics off: 0 frame(s); physics constraint(s) on mesh "${r.attachment}": ${r.physics_constraints.join(', ')})`
+        : r.physics_on !== null && r.physics_off !== null && physicsLeftOut > 0
+          ? ` (physics on: ${r.physics_on.frames} frame(s), worst frame ${r.physics_on.worst_frame}; physics off: ${r.physics_off.frames} frame(s), worst frame ${r.physics_off.worst_frame})`
+          : r.physics_on === null && r.physics_off !== null && physicsLeftOut > 0
+            ? ` (physics on: 0 frame(s); physics off: ${r.physics_off.frames} frame(s), worst frame ${r.physics_off.worst_frame})`
+            : '';
     problems.push({
       code: `CHECK_${FOLD_LINE}`,
       object: `animation "${r.animation}", mesh "${r.attachment}" (slot "${r.slot}")`,
-      detail: `rigc render --folds at ${fps} fps${physics}: ${r.line}; no triangle turned over against the setup pose is required — a fold the art means is declared in the --requirements file's may_fold, { "slot": "${r.slot}", "animation": "${r.animation}", "why": … }`,
+      detail: `rigc render --folds at ${fps} fps${physics}${sideClause}: ${r.line}; no triangle turned over against the setup pose is required — a fold the art means is declared in the --requirements file's may_fold, { "slot": "${r.slot}", "animation": "${r.animation}", "why": … }`,
     });
   }
   const declaredNotFolding = mayFold.filter((e) => !folding.some((r) => r.slot === e.slot && r.animation === e.animation)).map((e) => ({ slot: e.slot, animation: e.animation }));
@@ -3101,26 +3211,46 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       written.push('motion_heat.png');
     }
 
-    // 3a. every animation, the idle included, read for folds by rigc (issues #320, #333) — only when there is one; at
-    // the idle's rate whatever --requirements says, so a requirements file moves only what it declares (CK78), from the keyed build
+    // 3a. every animation, the idle included, read for folds by rigc (issues #320, #333, #363) — only when there is one; at
+    // the idle's rate whatever --requirements says, so a requirements file moves only what it declares (CK78), with physics on and off
     if (animationNames.length > 0) {
       const fps = IDLE_FPS;
       try {
-        // Issue #348: with a foot to read, the same render writes each animation's geometry as well.
+        // Issue #348: with a foot to read, the keyed render writes each animation's geometry as well.
         const geometry = feet.length > 0 ? ['--geometry'] : [];
-        const fr = rigc(['render', '--candidate', keyedBuild('the animations with their physics constraint(s) left out'), '--folds', ...geometry, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', foldDir]);
-        if (fr.status !== 0) refuseIfAny(rigcFailed(`render --folds${geometry.map((g) => ` ${g}`).join('')} --fps ${fps}${stripped === null ? '' : ' (physics constraint(s) left out)'}`, fr, fr.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
-        const readings = readFoldSets(foldDir, animationNames, fps, fr.out);
-        folds = foldsLine(animationNames, fps, stripped === null ? 0 : stripped.physics.length, readings, reqFile === null ? [] : reqFile.may_fold, reqFile === null ? null : reqFile.path, foldProblems);
-        if (feet.length > 0) {
-          const sets = readJson(join(foldDir, 'frames.json'), []);
-          const listed = sets !== null && Array.isArray(sets.sets) ? sets.sets.filter(isRecord) : [];
-          // readFoldSets has refused a missing set by name, so each animation has its directory here.
-          const levelReadings = animationNames.map((name) => {
-            const dir = join(foldDir, String((listed.find((x) => x.animation === name) as Record<string, unknown>).dir));
-            return { animation: name, set: readFrameSet(dir), geometryPath: join(dir, GEOMETRY_FILE) };
-          });
-          level = levelLine(feet, inp.rig, levelReadings, fps, stripped === null ? 0 : stripped.physics.length, levelProblems);
+        if (stripped === null) {
+          const fr = rigc(['render', '--candidate', buildDir, '--folds', ...geometry, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', foldDir]);
+          if (fr.status !== 0) refuseIfAny(rigcFailed(`render --folds${geometry.map((g) => ` ${g}`).join('')} --fps ${fps}`, fr, fr.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+          const readings = readFoldSets(foldDir, animationNames, fps, fr.out);
+          folds = foldsLine(animationNames, fps, 0, readings, reqFile === null ? [] : reqFile.may_fold, reqFile === null ? null : reqFile.path, foldProblems, readings, inp.rig, []);
+          if (feet.length > 0) {
+            const sets = readJson(join(foldDir, 'frames.json'), []);
+            const listed = sets !== null && Array.isArray(sets.sets) ? sets.sets.filter(isRecord) : [];
+            const levelReadings = animationNames.map((name) => {
+              const dir = join(foldDir, String((listed.find((x) => x.animation === name) as Record<string, unknown>).dir));
+              return { animation: name, set: readFrameSet(dir), geometryPath: join(dir, GEOMETRY_FILE) };
+            });
+            level = levelLine(feet, inp.rig, levelReadings, fps, 0, levelProblems);
+          }
+        } else {
+          const onDir = join(foldDir, 'on');
+          const offDir = join(foldDir, 'off');
+          const frOn = rigc(['render', '--candidate', buildDir, '--folds', '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', onDir]);
+          if (frOn.status !== 0) refuseIfAny(rigcFailed(`render --folds --fps ${fps}`, frOn, frOn.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+          const frOff = rigc(['render', '--candidate', keyedBuild('the animations with their physics constraint(s) left out'), '--folds', ...geometry, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', offDir]);
+          if (frOff.status !== 0) refuseIfAny(rigcFailed(`render --folds${geometry.map((g) => ` ${g}`).join('')} --fps ${fps} (physics constraint(s) left out)`, frOff, frOff.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+          const readingsOn = readFoldSets(onDir, animationNames, fps, frOn.out);
+          const readingsOff = readFoldSets(offDir, animationNames, fps, frOff.out);
+          folds = foldsLine(animationNames, fps, stripped.physics.length, readingsOn, reqFile === null ? [] : reqFile.may_fold, reqFile === null ? null : reqFile.path, foldProblems, readingsOff, inp.rig, stripped.physics);
+          if (feet.length > 0) {
+            const sets = readJson(join(offDir, 'frames.json'), []);
+            const listed = sets !== null && Array.isArray(sets.sets) ? sets.sets.filter(isRecord) : [];
+            const levelReadings = animationNames.map((name) => {
+              const dir = join(offDir, String((listed.find((x) => x.animation === name) as Record<string, unknown>).dir));
+              return { animation: name, set: readFrameSet(dir), geometryPath: join(dir, GEOMETRY_FILE) };
+            });
+            level = levelLine(feet, inp.rig, levelReadings, fps, stripped.physics.length, levelProblems);
+          }
         }
       } finally {
         rmSync(foldDir, { recursive: true, force: true });
@@ -4066,12 +4196,17 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
     } else if (!ok) {
       failed = true;
       // Issue #262: a root the breath carries is named with its carrier, not blamed on the chain.
+      // Issue #351: when the breath carries the root and the chain is also below the bar, or when the mesh is weighted
+      // off its chain without a breath carrier, name that too instead of only blaming the chain's amplitudes.
       const carry = breathCarrier(inp.rig, inp.motion, p.name, geometryPath, frames, { art, box: p, stage: inp.stage, shown, toward: rises ? 'up' : 'down', root: t.root, tip: t.tip });
       if (carry !== null) rows[rows.length - 1] = { ...rows[rows.length - 1], carried_by: carry.bone, breath_rig_px: round3(carry.breath), root_without_breath_rig_px: round3(carry.root), tip_without_breath_rig_px: round3(carry.tip) };
+      const offChain = carry === null && round3(t.tip) > 0 ? offChainClause(inp.rig, inp.motion, p.name) : null;
       const why =
         carry === null
-          ? "the chain's amplitudes do not grow toward the tip, or the mesh is not weighted to the chain"
-          : `the root travels with the breath (${round3(t.root)} px of ${round3(carry.breath)} px): it is carried by \`${carry.bone}\`, which moves it more than the tip; with \`${carry.keyed}\`'s translate held still the root travels ${round3(carry.root)} rig px and the tip ${round3(carry.tip)}, which the bar passes (ratio ${carry.root > 0 ? round3(carry.tip / carry.root) : 'undefined: the root moves only with it'}) — bind the root to the bone the part hangs from, not to \`${carry.bone}\``;
+          ? `the chain's amplitudes do not grow toward the tip, or the mesh is not weighted to the chain${offChain === null ? '' : `; ${offChain}`}`
+          : carry.passes
+            ? `the root travels with the breath (${round3(t.root)} px of ${round3(carry.breath)} px): it is carried by \`${carry.bone}\`, which moves it more than the tip; with \`${carry.keyed}\`'s translate held still the root travels ${round3(carry.root)} rig px and the tip ${round3(carry.tip)}, which the bar passes (ratio ${carry.root > 0 ? round3(carry.tip / carry.root) : 'undefined: the root moves only with it'}) — bind the root to the bone the part hangs from, not to \`${carry.bone}\``
+            : `the root travels with the breath (${round3(t.root)} px of ${round3(carry.breath)} px): it is carried by \`${carry.bone}\`, which moves it more than the tip; with \`${carry.keyed}\`'s translate held still the root travels ${round3(carry.root)} rig px and the tip ${round3(carry.tip)}, which is still below the bar (ratio ${carry.root > 0 ? round3(carry.tip / carry.root) : 'undefined: the root moves only with it'}, < ${TIP_RATIO_FLOOR}) — drop the segment on \`${carry.bone}\` from \`meshes.${p.name}.segments\` (or bind the root to the bone the part hangs from, not to \`${carry.bone}\`) and grow the chain's amplitudes toward the tip`;
       problems.push({
         code: 'CHECK_TIP_OVER_ROOT',
         object: `part "${p.name}", box ${p.x},${p.y} ${p.w}x${p.h} rig px, posed by the idle's geometry${rises ? ', declared rises' : ''}`,
@@ -4088,6 +4223,52 @@ function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems
   return { status: failed ? 'FAIL' : 'PASS', ...declared, instrument: TIP_INSTRUMENT, parts: rows, ratio_floor: TIP_RATIO_FLOOR, ...(excepted.rests.length === 0 ? {} : { rest_ratio_ceiling: TIP_REST_RATIO_CEILING }) };
 }
 
+/**
+ * When a failing weighted mesh rides a chain (`chainsCarrying`) and also carries positive weight on a bone off that
+ * chain (neither a link nor under one, as {@link stressPlan} reads it), name the off-chain bones and their vertex
+ * counts so `CHECK_TIP_OVER_ROOT` does not only blame the chain's amplitudes (issue #351).
+ */
+function offChainClause(rig: Record<string, unknown>, motion: Record<string, unknown>, part: string): string | null {
+  const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord).filter((b) => typeof b.name === 'string');
+  const parent = new Map(bones.map((b) => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
+  const skins = isRecord(rig.skins) ? rig.skins : {};
+  const skin = isRecord(skins.default) ? skins.default : {};
+  const onSlot = skin[part];
+  const atts: unknown[] = isRecord(onSlot) ? Object.values(onSlot) : [];
+  const weighted = atts.filter((a): a is Record<string, unknown> & { weights: unknown[] } => isRecord(a) && Array.isArray(a.weights));
+  if (weighted.length === 0) return null;
+  const { found } = chainsCarrying(rig, motion, part);
+  if (found.length === 0) return null;
+  const links = new Set(found.flat());
+  const onChain = (b: string): boolean => {
+    const seen = new Set<string>();
+    for (let x: string | null = b; x !== null && !seen.has(x); x = parent.get(x) ?? null) {
+      if (links.has(x)) return true;
+      seen.add(x);
+    }
+    return false;
+  };
+  const off = new Map<string, { vertices: number; largest: number }>();
+  let of = 0;
+  for (const a of weighted) {
+    for (const v of a.weights) {
+      of++;
+      const ws = (Array.isArray(v) ? v : []).filter(isRecord).filter((w) => typeof w.bone === 'string' && typeof w.weight === 'number') as Array<{ bone: string; weight: number }>;
+      for (const w of ws) {
+        if (onChain(w.bone) || w.weight <= 0) continue;
+        const e = off.get(w.bone) ?? { vertices: 0, largest: 0 };
+        e.vertices++;
+        e.largest = Math.max(e.largest, w.weight);
+        off.set(w.bone, e);
+      }
+    }
+  }
+  if (off.size === 0) return null;
+  const list = [...off].map(([bone, e]) => `"${bone}" (${e.vertices} of ${of} vertices, largest weight ${round3(e.largest)})`).join(', ');
+  const drop = off.size === 1 ? `"${[...off.keys()][0]}"` : 'each of those bones';
+  return `it is weighted off the chain to ${list} — drop the segment on ${drop} in \`meshes.${part}.segments\`, or grow the chain's amplitudes toward the tip`;
+}
+
 /**
  * The bones a part's attachments are bound to in the default skin (issue #231): a mesh's weights, or its slot's
  * bone for an attachment that carries no weights.
@@ -4109,17 +4290,16 @@ function boundBones(rig: Record<string, unknown>, part: string): Set<string> {
 const BREATH_PROPS: readonly string[] = ['translate', 'translatex', 'translatey'];
 
 /**
- * The bone a failing part's root travels with, when that is the breath's (issue #262). The breath is every idle
+ * The bone a failing part's root travels with, when that is the breath's (issues #262, #351). The breath is every idle
  * track that translates a bone ({@link BREATH_PROPS}), each read on its own: `K` the bone it keys. Its motion is
  * `K`'s world origin less where `K`'s parent carries `K`'s setup position, frame by frame — what the translate keys
  * add — and the breath's travel is that, less its frame-0 value, at its largest. The part (one weighted mesh; a
  * region is carried whole and cannot stretch) is posed again with that motion taken out of every vertex in
  * proportion to its weight on `K` and the bones under it, and its halves measured as {@link halfTravels} measures
- * them. The root travels with the breath when the breath adds more to the root's travel than to the tip's and, held
- * still, the halves pass the bar: tip >= {@link TIP_RATIO_FLOOR} x root, the tip above 0 at the line's precision
- * (round3). The margin is the bar's own, so the line names the carrier exactly when the breath is what fails it;
- * the carrier named is the bone the part is bound to ({@link boundBones}) at or under `K` that no other such bone is
- * above (the sleeve's links ride `chest`, which is the carrier). Null otherwise.
+ * them. The root travels with the breath when the breath adds more to the root's travel than to the tip's and the tip
+ * moves above 0 at the line's precision (round3); `passes` records whether, held still, the halves pass the bar
+ * (tip >= {@link TIP_RATIO_FLOOR} x root). The carrier named is the bone the part is bound to ({@link boundBones}) at
+ * or under `K` that no other such bone is above (the sleeve's links ride `chest`, which is the carrier). Null otherwise.
  */
 function breathCarrier(
   rig: Record<string, unknown>,
@@ -4128,7 +4308,7 @@ function breathCarrier(
   geometryPath: string,
   frames: number,
   m: { art: ArtMask; box: { x: number; y: number; w: number; h: number }; stage: StageBox; shown: ReadonlyArray<PosedAttachment | null>; toward: 'down' | 'up'; root: number; tip: number },
-): { bone: string; keyed: string; breath: number; root: number; tip: number } | null {
+): { bone: string; keyed: string; breath: number; root: number; tip: number; passes: boolean } | null {
   const anims = isRecord(motion.animations) ? motion.animations : {};
   const idle = isRecord(anims.idle) ? anims.idle : {};
   const keyed = [...new Set((Array.isArray(idle.tracks) ? idle.tracks : []).filter(isRecord).filter((t) => typeof t.bone === 'string' && typeof t.property === 'string' && BREATH_PROPS.includes(t.property)).map((t) => String(t.bone)))];
@@ -4186,8 +4366,8 @@ function breathCarrier(
     const held = m.shown.map((f, i) => (f === null ? null : { rest: f.rest, triangles: f.triangles, posed: f.posed.map((v, j) => v - share[j >> 1] * delta[i][j & 1]) }));
     const t = halfTravels(m.art, m.box, m.stage, held, m.toward);
     if (t.root === null || t.tip === null) continue;
-    if (!(m.root - t.root > m.tip - t.tip) || round3(t.tip) === 0 || !(t.tip >= TIP_RATIO_FLOOR * t.root)) continue;
-    return { bone: carrier, keyed: k, breath, root: t.root, tip: t.tip };
+    if (!(m.root - t.root > Math.max(0, m.tip - t.tip)) || round3(t.tip) === 0) continue;
+    return { bone: carrier, keyed: k, breath, root: t.root, tip: t.tip, passes: t.tip >= TIP_RATIO_FLOOR * t.root };
   }
   return null;
 }

package/src/cloth.ts

@@ -80,9 +80,9 @@ export interface ClothStrength {
   edge: number;
 }
 
-/** One target's recipe, as `config.cloth.<tag>` declares it. */
+/** One target's recipe, as `config.cloth.<tag>` declares it (`chains` may be omitted on `"back hair"`, where it is derived from the tail's width at the root row). */
 export interface ClothRecipe {
-  chains: number;
+  chains?: number;
   links: number;
   split?: { at: number; into: number; hold_tip?: boolean };
   length_ratio?: number;
@@ -95,12 +95,26 @@ export interface ClothRecipe {
   gravity: [number, number];
   translate?: number;
   swing?: { scales: number[] };
-  /** `bottomwear` only (issue #402): a `topwear` part the skirt's trees are drafted on as well — a dress. */
-  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>>;
 
+/**
+ * 📐 The recipe's default maximum back-hair tree count per side when `chains`
+ * is omitted on `config.cloth."back hair"` (issue #390): 2 trees per side when
+ * the tail's opaque width at the root row holds at least two mesh-grid cells
+ * (`floor(width / grid) >= 2`, `fixtures/cloth.ts`: 48 px on a 14 px grid) and
+ * every tree root lies inside the art, and fewer when the tail at the root row
+ * is narrower or a root falls off the art (`examples/wind`: 45 px on the r side
+ * and 61 px on the l side at y=162 on a 28 px grid, with inner roots at
+ * [323, 162] and [496, 162] on alpha 0 -> 1 tree per side).
+ */
+export const RECIPE_BACK_HAIR_CHAINS = 2;
+
 /**
  * 📐 The default ratio of a path's last link to its first: 0.5, the recipe's
  * own. Measured on the cloth fixture (fixtures/cloth.ts, rig-c 2.47.1, the
@@ -206,7 +220,7 @@ const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
 
 /** The trees of one piece, in tree order, each trunk before its branches. */
 export function draftTrees(input: TreeInput, r: ClothRecipe): TreeChain[] {
-  const n = r.chains;
+  const n = r.chains ?? RECIPE_BACK_HAIR_CHAINS;
   const ratio = r.length_ratio ?? RECIPE_LENGTH_RATIO;
   const rows = linkRows(input.rootY, input.tipY, r.links, ratio);
   const at = r.split === undefined ? r.links : r.split.at;
@@ -260,7 +274,7 @@ export function draftTrees(input: TreeInput, r: ClothRecipe): TreeChain[] {
         depths: [],
         last: [],
       };
-      const edge = r.split?.hold_tip === true ? false : outerSide(k, b);
+      const edge = r.split?.hold_tip === true && r.strength === undefined ? false : outerSide(k, b);
       for (let j = trunkLinks; j < r.links; j++) {
         ch.points.push(j === trunkLinks ? trunk.tip : pt(rows[j], fb));
         ch.why.push(j === trunkLinks ? `the fork: the trunk ${trunk.chain}'s tip` : `${rowRule(j)}, ${pyRound(fb, 6)} of the way across ${input.frame} in the 24-row band there (branch ${b} of ${into} of tree ${k})`);
@@ -457,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;
+}
+