@rig-c/parts 1.25.0 → 1.26.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,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
@@ -206,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;
@@ -260,7 +272,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})`);

package/src/config.ts

@@ -256,6 +256,8 @@ export interface ChainBones {
   parent: string;
   points: Point[];
   tip: Point;
+  /** Expanded link name -> rig-c inherit mode (issue #369); absent links keep normal inheritance. */
+  link_inherit?: Record<string, RigBoneInherit>;
 }
 
 export type BoneEntry = SingleBone | ChainBones;
@@ -725,6 +727,8 @@ export interface CharacterConfig {
   scene?: SceneSpec;
   /** The cloth and hair recipe `propose --cloth` drafts from (issue #364, `src/cloth.ts`): read by propose only, so no byte of any rig output moves with it. */
   cloth?: ClothRecipes;
+  /** The `assemble.rig_scale` (`parts.json`'s `scale_rig_per_source`) `propose` drafted the rig sections at (issue #354): absent on a hand-authored config, held equal to `assemble.rig_scale` when present. */
+  proposed_rig_scale?: number;
 }
 
 /** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
@@ -1029,9 +1033,11 @@ export interface AssembleConfig {
   /** Issue #349: read with `bones` (the joints are the bones' origins) when present. */
   limbs?: Record<string, Limb>;
   bones?: BoneEntry[];
+  /** Issue #354: the `rig_scale` `propose` drafted the rig sections at, held equal to `assemble.rig_scale` when present. */
+  proposed_rig_scale?: number;
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -1081,6 +1087,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'assemble') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     const made = 'assemble' in t ? checkAssemble(c, t.assemble, door) : { parts: [], patches: [], cuts: [] };
+    checkProposedRigScale(c, t);
     if ('scene' in t) checkScene(c, t.scene);
     // Issue #349: the limbs' joints are their bones' origins, so the bones are read with them, and only then.
     if ('limbs' in t) {
@@ -1234,6 +1241,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('generation' in t) checkGeneration(c, t.generation);
   if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
   const { parts, patches, cuts } = 'assemble' in t ? checkAssemble(c, t.assemble, 'full') : { parts: [], patches: [], cuts: [] };
+  checkProposedRigScale(c, t);
   const names = 'bones' in t ? checkBones(c, t.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
   const limbs = 'limbs' in t ? checkLimbs(c, t.limbs, { parts, patches, cuts }, 'bones' in t ? names : null) : null;
   if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains);
@@ -1252,6 +1260,29 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   return { config: raw as CharacterConfig, animations };
 }
 
+/**
+ * Issue #354: `propose` records `parts.json`'s `scale_rig_per_source` on the
+ * proposal as `proposed_rig_scale`, and pasting the proposal into `config.json`
+ * carries it. When present, `assemble`, `rig` and `build` compare it against
+ * `assemble.rig_scale` and refuse a mismatch: the bones, mesh spacings, segment
+ * coordinates and motion amplitudes are in the proposed rig canvas's pixels and
+ * do not scale when `assemble.rig_scale` changes. A hand-authored config with
+ * no `proposed_rig_scale` is not refused.
+ */
+function checkProposedRigScale(c: Check, t: Record<string, Json>): void {
+  if (!('proposed_rig_scale' in t)) return;
+  if (!c.number('config.proposed_rig_scale', t.proposed_rig_scale, 'positive')) return;
+  const a = isPlainObject(t.assemble) ? t.assemble : null;
+  if (a === null || !('rig_scale' in a) || !(typeof a.rig_scale === 'number' && Number.isFinite(a.rig_scale) && a.rig_scale > 0)) return;
+  if (t.proposed_rig_scale !== a.rig_scale) {
+    c.fail(
+      'CONFIG_PROPOSED_RIG_SCALE',
+      'config.proposed_rig_scale',
+      `is ${t.proposed_rig_scale}, and config.assemble.rig_scale is ${a.rig_scale} — the bones, meshes, limbs and motion were proposed at rig_scale ${t.proposed_rig_scale} and are in that rig canvas's pixels, so they do not scale when assemble.rig_scale changes; re-run assemble and propose at rig_scale ${a.rig_scale} and paste the new proposal, or restore config.assemble.rig_scale to ${t.proposed_rig_scale}`,
+    );
+  }
+}
+
 function isPlainObject(v: Json): v is Record<string, Json> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -1404,9 +1435,9 @@ export interface SkeletonSections {
 /**
  * A `proposal.json` as `propose` writes it — `bones`, `meshes`, `regions`,
  * `motion` and `notes` (strings), `limbs` when `propose --keypoints` drafted
- * them (issue #349) and `constraints` when `propose --cloth` did (issue #364;
+ * them (issue #349), `constraints` when `propose --cloth` did (issue #364;
  * both read here since issue #372, whose `wind` example tracks such a
- * proposal) — under the full loader's own rules for those sections (issue
+ * proposal), and `proposed_rig_scale` (issue #354) — under the full loader's own rules for those sections (issue
  * #85). There is no plan to hold the meshes, regions and limbs against, so
  * the coverage rule (every plan part exactly one of a mesh or a region) is
  * not run, and a limb segment's `from` is held to no plan part (the parts
@@ -1414,9 +1445,9 @@ export interface SkeletonSections {
  * both before writing (`checkProposal`). A key the loader would not take is
  * refused by name, as in a config. Refusals name the fields `proposal.…`.
  */
-export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[] } {
+export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number } {
   const c = new Check();
-  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops']);
+  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops', 'proposed_rig_scale']);
   if (top !== null) {
     const names = 'bones' in top ? checkBones(c, top.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
     if ('limbs' in top) {
@@ -1430,10 +1461,11 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
     if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
     if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
     if ('stops' in top) checkStops(c, top.stops, names.bones, names.chains);
+    if ('proposed_rig_scale' in top) c.number('config.proposed_rig_scale', top.proposed_rig_scale, 'positive');
     if ('notes' in top && c.array('config.notes', top.notes, false)) (top.notes as Json[]).forEach((n, i) => c.string(`config.notes[${i}]`, n, false));
   }
   refuseIfAny(c.problems.map((p) => ({ ...p, object: p.object.replace(/^config\b/, 'proposal') })));
-  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[] };
+  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number };
 }
 
 /**
@@ -1761,7 +1793,7 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
     const at = `config.bones[${i}]`;
     const isChain = typeof entry === 'object' && entry !== null && 'chain' in entry;
     if (isChain) {
-      const b = c.object(at, entry, ['chain', 'parent', 'points', 'tip'], []);
+      const b = c.object(at, entry, ['chain', 'parent', 'points', 'tip'], ['link_inherit']);
       if (b === null) return;
       if ('parent' in b && c.string(`${at}.parent`, b.parent) && !bones.has(b.parent)) {
         c.fail('CONFIG_NAME_RESOLVES', `${at}.parent`, `names "${b.parent}", which is not "${ROOT_BONE}" or a bone declared above it; parents come first`);
@@ -1779,6 +1811,21 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
           else if (typeof b.parent === 'string' && !parents.has(`${name}0`)) parents.set(`${name}0`, b.parent);
         });
         chains.set(name, points.length);
+        if ('link_inherit' in b) {
+          const path = `${at}.link_inherit`;
+          const links = points.map((_, k) => `${name}${k}`);
+          if (!isPlainObject(b.link_inherit)) {
+            c.fail('CONFIG_FIELD_TYPE', path, `is ${show(b.link_inherit)}; an object mapping this chain's expanded link names to rig-c inherit modes is required`);
+          } else {
+            for (const [link, mode] of Object.entries(b.link_inherit)) {
+              const field = `${path}.${link}`;
+              if (!links.includes(link)) c.fail('CONFIG_NAME_RESOLVES', field, `names "${link}", which is not a link of chain "${name}"; its declared links are ${links.map((n) => `"${n}"`).join(', ')}`);
+              if (c.string(field, mode) && !(RIG_BONE_INHERIT as readonly string[]).includes(mode)) {
+                c.fail('CONFIG_BONE_INHERIT', field, `is ${show(mode)}; one of rig-c's inherit modes, spelled as its table spells them, is required — ${RIG_BONE_INHERIT.join(', ')} (rig-c's RigBone.inherit; nothing here folds a case or maps a name)`);
+              }
+            }
+          }
+        }
       }
       return;
     }
@@ -2766,7 +2813,7 @@ function attachedParts(meshes: Json, regions: Json): Set<string> {
  * - `part` on a tag other than `bottomwear` (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`):
  *   the field hands the skirt's recipe to a part of another tag (issue #402),
  *   and only the skirt has a recipe that part can take; whether the part
- *   exists, and is a `topwear` that hangs below the hip, is read off the parts
+ *   exists, and is a `topwear` part or its cut piece hanging below the hip, is read off the assembled parts
  *   by `propose` (`PROPOSE_CLOTH_PART`);
  * - a strength, declared or the recipe's default, whose spring is unstable at
  *   a damping the recipe runs at — k = strength·massInverse·step² at or past
@@ -2795,8 +2842,9 @@ 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], ['chains', 'links', 'wind', 'gravity'], ['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']);
     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;
     const links = 'links' in r && c.int(`${path}.links`, r.links, 1) ? (r.links as number) : null;
     if ('split' in r) {
@@ -2851,7 +2899,7 @@ function checkCloth(c: Check, v: Json): void {
     }
     if ('part' in r) {
       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 that holds a skirt (a dress) — leave it out here`);
+        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 ('swing' in r) {