@rig-c/parts 1.24.0 → 1.26.0

package/src/check.ts

@@ -155,7 +155,8 @@ import {
   type SeamPair,
   stretchRequirementLine,
 } from './requirements.ts';
-import { RIG_BONE_INHERIT } from 'rig-c/src/rig.ts';
+import { RIG_BONE_INHERIT, type RigSpec as RigcRigSpec } from 'rig-c/src/rig.ts';
+import { expandStops } from 'rig-c/src/stop.ts';
 import { alphaComposite } from './raster/composite.ts';
 import { readPng, writePng } from './raster/png.ts';
 import { newFloatImage, newRaster, type Raster } from './raster/types.ts';
@@ -1068,9 +1069,11 @@ export function withoutPhysics(rig: Record<string, unknown>, motion: Record<stri
   const table = isRecord(motion.physics) ? motion.physics : null;
   if (table !== null) for (const [name, e] of Object.entries(table)) physics.push({ name, bone: isRecord(e) ? String(e.bone) : '', in: 'motion.json' });
   if (physics.length === 0) return null;
-  const r: Record<string, unknown> = { ...rig };
-  if (constraints !== null) {
-    const kept = constraints.filter((c) => !(isRecord(c) && c.type === 'physics'));
+  const expanded = Array.isArray(rig.stops) ? (expandStops(rig as unknown as RigcRigSpec, 'rig.json') as unknown as Record<string, unknown>) : rig;
+  const r: Record<string, unknown> = { ...expanded };
+  delete r.stops;
+  if (Array.isArray(r.constraints)) {
+    const kept = r.constraints.filter((c) => !(isRecord(c) && c.type === 'physics'));
     if (kept.length > 0) r.constraints = kept;
     else delete r.constraints;
   }
@@ -2014,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;
@@ -2027,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`). */
@@ -2039,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[];
@@ -2127,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 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[]): FoldsLine {
+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 }));
@@ -3098,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 });
@@ -4063,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' : ''}`,
@@ -4085,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.
@@ -4106,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>,
@@ -4125,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)))];
@@ -4183,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

@@ -48,6 +48,9 @@
  *   hip, by the skirt's own rule, in place of the robe chains the topwear rule
  *   drafts; its art above the hip stays on the chest. The proposer never picks
  *   such a part by itself: it names a candidate, and the author declares it.
+ *   A `bottomwear` part lying on that part's tree links (a hem returned as a
+ *   layer of its own) rides them, as a layer on a tail does ({@link tailOverlap}),
+ *   and gets no trees of its own (issue #416): one skirt, one set of trees.
  * - **Swing** (`bottomwear` only). `swing.scales` declares one shared pendulum:
  *   a bone `<prefix>swing` under the attachment at the centre of the root row,
  *   one link long, with physics; each tree's first link takes the swing's
@@ -77,11 +80,11 @@ 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 };
+  split?: { at: number; into: number; hold_tip?: boolean };
   length_ratio?: number;
   strength?: ClothStrength;
   damping?: number;
@@ -92,12 +95,24 @@ 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. */
+  /** `bottomwear` only: a `topwear` part or its named cut skirt piece the skirt's trees are drafted on. */
   part?: 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
@@ -203,7 +218,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;
@@ -257,7 +272,7 @@ export function draftTrees(input: TreeInput, r: ClothRecipe): TreeChain[] {
         depths: [],
         last: [],
       };
-      const edge = 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})`);
@@ -383,7 +398,7 @@ export function clothNote(part: string, tag: ClothTarget, trees: readonly TreeCh
   const defaults: string[] = [];
   if (r.length_ratio === undefined) defaults.push(`length_ratio ${RECIPE_LENGTH_RATIO}`);
   if (r.strength === undefined) defaults.push(`strength ${RECIPE_STRENGTH.trunk}/${RECIPE_STRENGTH.branch}/${RECIPE_STRENGTH.edge}`);
-  const shape = r.split === undefined ? `${r.links} link(s) each` : `a ${r.split.at}-link trunk forking into ${r.split.into} branches, ${r.links} links root to tip`;
+  const shape = r.split === undefined ? `${r.links} link(s) each` : `a ${r.split.at}-link trunk forking into ${r.split.into} branches${r.split.hold_tip === true ? ' (tip held)' : ''}, ${r.links} links root to tip`;
   return (
     `${part} (${via === undefined ? tag : `${via}, which config.cloth."${tag}".part names`}): config.cloth."${tag}" -> ${r.chains} tree(s)${extra}, ${shape} (${trees.map((t) => t.chain).join(', ')}); ` +
     `${constraints} constraint(s), physics on every link, wind ${r.wind[0]} -> ${r.wind[1]} and gravity ${r.gravity[0]} -> ${r.gravity[1]} root to tip (multipliers of the consumer's environment; no direction is drafted), no idle key` +