@rig-c/parts 1.30.0 → 1.32.0

package/src/config.ts

@@ -245,6 +245,19 @@ export interface Cut {
   under_fill?: 'colour';
 }
 
+export interface AlternateSetConfig {
+  name: string;
+  source?: string;
+  full?: string;
+  head?: string;
+  parts?: string[];
+  hides?: string[];
+  head_box?: [number, number, number, number];
+  cuts?: Cut[];
+  skeleton?: string;
+  drawn?: Record<string, number>;
+}
+
 export interface Assemble {
   /** Rig pixels per source pixel. */
   rig_scale: number;
@@ -252,6 +265,7 @@ export interface Assemble {
   extend_below_crop?: Extend[];
   patches?: Patch[];
   cuts?: Cut[];
+  alternates?: AlternateSetConfig[];
 }
 
 export interface SingleBone {
@@ -761,6 +775,8 @@ export interface CharacterConfig {
   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;
+  /** Alternate painting sets (issue #454): absent, no alternate sets are assembled or emitted. */
+  alternates?: AlternateSetConfig[];
 }
 
 /** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
@@ -1112,7 +1128,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'layers') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     if ('assemble' in t) {
-      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts']);
+      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates']);
       if (a !== null && 'rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
     }
   }
@@ -1122,10 +1138,14 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
     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.
+    let limbs: LimbNames | null = null;
     if ('limbs' in t) {
       if (!('bones' in t)) c.fail('CONFIG_FIELD_PRESENT', 'config.bones', 'is absent; config.limbs names bones, and each joint is its bone\'s origin, so assemble reads the bones with the limbs');
       const names = 'bones' in t ? checkBones(c, t.bones) : null;
-      checkLimbs(c, t.limbs, made, names);
+      limbs = checkLimbs(c, t.limbs, made, names);
+    }
+    if (isPlainObject(t.assemble) && 'alternates' in t.assemble) {
+      checkAlternates(c, t.assemble.alternates, made, limbs, null);
     }
   }
   if ('cloth' in t) checkCloth(c, t.cloth);
@@ -1276,6 +1296,9 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   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 (isPlainObject(t.assemble) && 'alternates' in t.assemble) {
+    checkAlternates(c, t.assemble.alternates, { parts, patches, cuts }, limbs, names.bones);
+  }
   if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains);
   if ('regions' in t) checkRegions(c, t.regions, names.bones);
   if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions, limbs);
@@ -1602,6 +1625,17 @@ function checkGeneration(c: Check, v: Json): void {
   }
 }
 
+function checkHeadBox(c: Check, path: string, b: Json): void {
+  const ints = Array.isArray(b) && b.length === 4 && b.every((n) => typeof n === 'number' && Number.isInteger(n));
+  if (!ints) c.fail('CONFIG_FIELD_TYPE', path, `is ${show(b)}; [x0, y0, x1, y1] in integer source pixels is required`);
+  else {
+    const [x0, y0, x1, y1] = b as number[];
+    if (!(x1 > x0 && y1 > y0 && x1 - x0 === y1 - y0)) {
+      c.fail('CONFIG_HEAD_BOX_SQUARE', path, `is ${x1 - x0}x${y1 - y0}; a non-empty square is required (the head run is fed a square crop)`);
+    }
+  }
+}
+
 function checkSeeThrough(c: Check, v: Json): void {
   const s = c.object('config.seethrough', v, ['resolution', 'steps', 'seed', 'offload'], ['head_box', 'arm_split']);
   if (s === null) return;
@@ -1610,17 +1644,7 @@ function checkSeeThrough(c: Check, v: Json): void {
   if ('steps' in s) c.int(`${p}.steps`, s.steps, 1);
   if ('seed' in s) c.int(`${p}.seed`, s.seed, 0);
   if ('offload' in s && typeof s.offload !== 'boolean') c.fail('CONFIG_FIELD_TYPE', `${p}.offload`, `is ${show(s.offload)}; true or false is required`);
-  if ('head_box' in s) {
-    const b = s.head_box;
-    const ints = Array.isArray(b) && b.length === 4 && b.every((n) => typeof n === 'number' && Number.isInteger(n));
-    if (!ints) c.fail('CONFIG_FIELD_TYPE', `${p}.head_box`, `is ${show(b)}; [x0, y0, x1, y1] in integer source pixels is required`);
-    else {
-      const [x0, y0, x1, y1] = b as number[];
-      if (!(x1 > x0 && y1 > y0 && x1 - x0 === y1 - y0)) {
-        c.fail('CONFIG_HEAD_BOX_SQUARE', `${p}.head_box`, `is ${x1 - x0}x${y1 - y0}; a non-empty square is required (the head run is fed a square crop)`);
-      }
-    }
-  }
+  if ('head_box' in s) checkHeadBox(c, `${p}.head_box`, s.head_box);
   if ('arm_split' in s) checkArmSplit(c, `${p}.arm_split`, s.arm_split, res);
 }
 
@@ -1689,7 +1713,7 @@ function checkRunTag(c: Check, path: string, run: Json, tag: Json): void {
  */
 function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
   const required = sectionRequired(door, 'assemble');
-  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts']);
+  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates']);
   if (a === null) return { parts: [], patches: [], cuts: [] };
   if (required.includes('plan') && !('plan' in a)) {
     c.fail('CONFIG_FIELD_PRESENT', 'config.assemble.plan', 'is absent and required; `assemble --propose-plan` prints one from the two runs — paste its plan and extend_below_crop into config.assemble');
@@ -1743,8 +1767,7 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
  * one polygon. `into` is a new part name: not a plan part, not a patch, not
  * another cut's. Returns the names the cuts make, in order.
  */
-function checkCuts(c: Check, v: Json, plan: string[], patches: string[]): string[] {
-  const p = 'config.assemble.cuts';
+function checkCuts(c: Check, v: Json, plan: string[], patches: string[], p = 'config.assemble.cuts'): string[] {
   const names: string[] = [];
   if (!c.array(p, v, false)) return names;
   const seen = new Map<string, number>();
@@ -1796,6 +1819,70 @@ function checkCuts(c: Check, v: Json, plan: string[], patches: string[]): string
   return names;
 }
 
+function checkAlternates(
+  c: Check,
+  v: Json,
+  made: { parts: string[]; patches: string[]; cuts: string[] },
+  limbs: LimbNames | null,
+  bones: Set<string> | null = null,
+): void {
+  const p = 'config.assemble.alternates';
+  if (!c.array(p, v, true)) return;
+  const allSlots = new Set<string>([...made.parts, ...made.patches, ...made.cuts, ...(limbs?.parts.keys() ?? [])]);
+  const seenNames = new Map<string, number>();
+  (v as Json[]).forEach((entry, i) => {
+    const at = `${p}[${i}]`;
+    const e = c.object(at, entry, ['name'], ['source', 'full', 'head', 'parts', 'hides', 'head_box', 'cuts', 'skeleton', 'drawn']);
+    if (e === null) return;
+    if ('name' in e && c.string(`${at}.name`, e.name)) {
+      if (!partNameOk(e.name)) c.fail('CONFIG_PART_NAME', `${at}.name`, `names the set ${show(e.name)}; a set name is a file prefix, so it may not be empty, start with "." or hold a slash`);
+      if (seenNames.has(e.name)) c.fail('CONFIG_PART_UNIQUE', `${at}.name`, `names the set "${e.name}" again (first at alternates[${seenNames.get(e.name)}])`);
+      else seenNames.set(e.name, i);
+    }
+    for (const k of ['source', 'full', 'head', 'skeleton'] as const) {
+      if (k in e) c.string(`${at}.${k}`, e[k]);
+    }
+    if ('drawn' in e) {
+      const d = e.drawn;
+      if (!isPlainObject(d) || Object.keys(d).length === 0) {
+        c.fail('CONFIG_FIELD_TYPE', `${at}.drawn`, `is ${show(d)}; a non-empty object of bone name -> drawn world angle in Spine degrees is required`);
+      } else {
+        for (const [bName, deg] of Object.entries(d)) {
+          if (bones !== null && !bones.has(bName)) {
+            c.fail('CONFIG_NAME_RESOLVES', `${at}.drawn.${bName}`, `names "${bName}", which config.bones does not declare`);
+          }
+          c.number(`${at}.drawn.${bName}`, deg);
+        }
+      }
+    }
+    if ('head_box' in e) checkHeadBox(c, `${at}.head_box`, e.head_box);
+    const altCuts = 'cuts' in e ? checkCuts(c, e.cuts, made.parts, [], `${at}.cuts`) : [];
+    const validParts = new Set<string>([...allSlots, ...altCuts]);
+    if ('parts' in e && c.array(`${at}.parts`, e.parts, true)) {
+      const seen = new Set<string>();
+      (e.parts as Json[]).forEach((pn, k) => {
+        if (!c.string(`${at}.parts[${k}]`, pn)) return;
+        if (!validParts.has(pn)) {
+          c.fail('CONFIG_NAME_RESOLVES', `${at}.parts[${k}]`, `is ${show(pn)}; a slot of the base rig (or a part made by this alternate's cuts) is required`);
+        } else if (seen.has(pn)) {
+          c.fail('CONFIG_PART_UNIQUE', `${at}.parts[${k}]`, `repeats "${pn}"; each covered part is named once`);
+        } else seen.add(pn);
+      });
+    }
+    if ('hides' in e && c.array(`${at}.hides`, e.hides, false)) {
+      const seen = new Set<string>();
+      (e.hides as Json[]).forEach((hn, k) => {
+        if (!c.string(`${at}.hides[${k}]`, hn)) return;
+        if (!allSlots.has(hn)) {
+          c.fail('CONFIG_NAME_RESOLVES', `${at}.hides[${k}]`, `is ${show(hn)}; a slot of the base rig is required`);
+        } else if (seen.has(hn)) {
+          c.fail('CONFIG_PART_UNIQUE', `${at}.hides[${k}]`, `repeats "${hn}"; each hidden slot is named once`);
+        } else seen.add(hn);
+      });
+    }
+  });
+}
+
 /**
  * `assemble.patches`: each entry `{name, box, alpha, draw}`, refused field by
  * field. What the config alone cannot know — whether the box lies inside the

package/src/parts.ts

@@ -83,6 +83,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { type Problem, refuseIfAny } from './errors.ts';
+import { KEYPOINT_NAMES, type PosePoints } from './skeleton.ts';
 import { readLayerTag } from './tags.ts';
 
 export interface PartRecord {
@@ -241,6 +242,26 @@ export interface RecompositeRecord {
   holes: HoleRecord[];
 }
 
+export interface AlternateSetMap {
+  slots: Record<string, string>;
+  hides?: string[];
+  drawn?: Record<string, number>;
+}
+
+export interface AlternatePartsRecord {
+  name: string;
+  parts?: string[];
+  hides?: string[];
+  slots: Record<string, string>;
+  records: PartRecord[];
+  ghost_px: Record<string, number>;
+  recomposite: RecompositeRecord;
+  scene?: SceneRecord;
+  single_run_pad?: SingleRunPad;
+  skeleton?: PosePoints;
+  drawn?: Record<string, number>;
+}
+
 export interface PartsFile {
   rig_size: [number, number];
   scale_rig_per_source: number;
@@ -252,6 +273,8 @@ export interface PartsFile {
   scene?: SceneRecord;
   /** Written only for one run whose file is not the resolution square (issue #366): where the file sat on the run's square; absent otherwise. */
   single_run_pad?: SingleRunPad;
+  /** Written only when alternate painting sets were assembled (issue #454); absent otherwise. */
+  alternates?: AlternatePartsRecord[];
 }
 
 /**
@@ -286,8 +309,8 @@ export interface SceneRecord {
   figure_mask: string;
 }
 
-const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad'] as const;
-const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad');
+const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad', 'alternates'] as const;
+const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad' && k !== 'alternates');
 export const SINGLE_RUN_PAD_KEYS = ['file_size', 'side', 'left', 'top'] as const;
 export const SCENE_KEYS = ['figure_alpha_above', 'figure_px', 'figure_mask'] as const;
 export const RECOMPOSITE_KEYS = ['mean_abs', 'within_limit', 'within_share', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed', 'holes'] as const;
@@ -346,24 +369,45 @@ export function tagOf(from: string): string | null {
   return f === null || f.run === 'painting' ? null : f.tag;
 }
 
+function serializePartList(parts: readonly PartRecord[]): Array<Record<string, unknown>> {
+  return parts.map((p) =>
+    Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : p[k]])),
+  );
+}
+
+function serializeRecomposite(r: RecompositeRecord): Record<string, unknown> {
+  return {
+    ...Object.fromEntries(RECOMPOSITE_KEYS.filter((k) => k !== 'holes').map((k) => [k, r[k]])),
+    holes: r.holes.map((h) => ({ ...Object.fromEntries(HOLE_KEYS.filter((k) => k !== 'borders').map((k) => [k, h[k]])), borders: h.borders.map((b) => ({ part: b.part, px: b.px })) })),
+  };
+}
+
 export function serializeParts(file: PartsFile): string {
   const ordered = {
     rig_size: file.rig_size,
     scale_rig_per_source: file.scale_rig_per_source,
-    parts: file.parts.map((p) =>
-      Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : p[k]])),
-    ),
+    parts: serializePartList(file.parts),
     ghost_px: Object.fromEntries(Object.keys(file.ghost_px).sort().map((k) => [k, file.ghost_px[k]])),
-    ...(file.recomposite === undefined
+    ...(file.recomposite === undefined ? {} : { recomposite: serializeRecomposite(file.recomposite) }),
+    ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
+    ...(file.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (file.single_run_pad as SingleRunPad)[k]])) }),
+    ...(file.alternates === undefined
       ? {}
       : {
-          recomposite: {
-            ...Object.fromEntries(RECOMPOSITE_KEYS.filter((k) => k !== 'holes').map((k) => [k, (file.recomposite as RecompositeRecord)[k]])),
-            holes: file.recomposite.holes.map((h) => ({ ...Object.fromEntries(HOLE_KEYS.filter((k) => k !== 'borders').map((k) => [k, h[k]])), borders: h.borders.map((b) => ({ part: b.part, px: b.px })) })),
-          },
+          alternates: file.alternates.map((a) => ({
+            name: a.name,
+            ...(a.parts === undefined ? {} : { parts: a.parts }),
+            ...(a.hides === undefined ? {} : { hides: a.hides }),
+            slots: a.slots,
+            records: serializePartList(a.records),
+            ghost_px: Object.fromEntries(Object.keys(a.ghost_px).sort().map((k) => [k, a.ghost_px[k]])),
+            recomposite: serializeRecomposite(a.recomposite),
+            ...(a.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (a.scene as SceneRecord)[k]])) }),
+            ...(a.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (a.single_run_pad as SingleRunPad)[k]])) }),
+            ...(a.skeleton === undefined ? {} : { skeleton: Object.fromEntries(KEYPOINT_NAMES.map((k) => [k, (a.skeleton as PosePoints)[k]])) }),
+            ...(a.drawn === undefined ? {} : { drawn: a.drawn }),
+          })),
         }),
-    ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
-    ...(file.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (file.single_run_pad as SingleRunPad)[k]])) }),
   };
   return `${JSON.stringify(ordered, null, 2)}\n`;
 }
@@ -596,6 +640,9 @@ function checkParts(raw: unknown, path: string): PartsFile {
     const names = Array.isArray(o.parts) ? new Set(o.parts.map((p) => (typeof p === 'object' && p !== null ? (p as Record<string, unknown>).name : undefined)).filter((n): n is string => typeof n === 'string')) : new Set<string>();
     checkRecomposite(o.recomposite, path, size as [number, number], names, fail);
   }
+  if ('alternates' in o && !Array.isArray(o.alternates)) {
+    fail('PARTS_FIELD_TYPE', `${path} field "alternates"`, `is ${show(o.alternates)}; an array of alternate set records is required`);
+  }
   refuseIfAny(problems);
   return raw as PartsFile;
 }

package/src/propose.ts

@@ -149,7 +149,7 @@ import { TURN_BONE, TURN_CARRIER_TAG, TURN_PLACES, TURN_RIDER_OFFSET, TURN_RIDER
 import { edgeLength } from './length.ts';
 import { bonePlaces, limbCrossing, limbPolyline, limbWidth } from './limbs.ts';
 import { type BranchSqueezeFinding, branchSqueezes, chainSqueezes, type SqueezeFinding } from './squeeze.ts';
-import { backHairMasses, type BackHairMass, RECIPE_BACK_HAIR_CHAINS, RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, spanCrosses, swingName, type Tail, tailOverlap, type TailOverlap, type TailSpan, treeConstraints, type TreeChain, type TreeInput, type TreeMassInput } from './cloth.ts';
+import { backHairMasses, type BackHairMass, backHairMassTrees, RECIPE_BACK_HAIR_CHAINS, RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, spanCrosses, swingName, type Tail, tailOverlap, type TailOverlap, type TailSpan, treeConstraints, type TreeChain, type TreeInput, type TreeMassInput } from './cloth.ts';
 import { TEXTURE_STRETCH_CEILING } from './check.ts';
 
 // ---------------------------------------------------------------------------
@@ -1849,12 +1849,29 @@ export function proposeWithBasis(
     const all: TreeChain[] = [];
     let n = 0;
     const partNamesLabel = list.map((q) => q.name).join(' -> ');
+    const sideTreeCounts: number[] = [];
     for (const [side] of activeSides) {
       const prefix = prefixOf(side);
       const sideMasses = massesBySide.get(side) ?? [];
       if (useMasses && sideMasses.length === 0) continue;
-      const sideRcp: ClothRecipe = { ...rawRcp, chains: useMasses ? sideMasses.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)) };
       const frame = `${partNamesLabel}'s art on the ${side} side of the eye axis (no art there in the band: the eye axis x)`;
+      const sideMassInputs: TreeMassInput[] | undefined = useMasses
+        ? sideMasses.flatMap((m): TreeMassInput[] => {
+            const count = backHairMassTrees(m, g);
+            return Array.from({ length: count }, (_, t): TreeMassInput => ({
+              rootY: m.minY <= y0 ? eyeY : m.minY,
+              tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
+              xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
+              fallbackX: m.minY <= y0 && sideMasses.length === 1 && count === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
+              frame,
+              treeInMass: t,
+              treesInMass: count,
+            }));
+          })
+        : undefined;
+      const sideCount = sideMassInputs !== undefined ? sideMassInputs.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit));
+      sideTreeCounts.push(sideCount);
+      const sideRcp: ClothRecipe = { ...rawRcp, chains: sideCount };
       const trees = T(list, 'back hair', sideRcp, {
         prefix,
         parent: 'head',
@@ -1864,15 +1881,7 @@ export function proposeWithBasis(
         fallbackX: () => axis,
         frame,
         edges: side,
-        masses: useMasses
-          ? sideMasses.map((m): TreeMassInput => ({
-              rootY: m.minY <= y0 ? eyeY : m.minY,
-              tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
-              xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
-              fallbackX: m.minY <= y0 && sideMasses.length === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
-              frame,
-            }))
-          : undefined,
+        masses: sideMassInputs,
       });
       const made = treeConstraints(trees, sideRcp, null);
       clothConstraints.push(...made);
@@ -1881,7 +1890,7 @@ export function proposeWithBasis(
     }
     const rcp: ClothRecipe = {
       ...rawRcp,
-      chains: useMasses ? Math.max(1, ...(activeSides.map(([s]) => (massesBySide.get(s) ?? []).length))) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
+      chains: useMasses ? Math.max(1, ...sideTreeCounts) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
     };
     const spans: Array<TailSpan & { depth: number }> = [{ bone: 'head', a: rnd(head), b: rnd([axis, top + 13]), link: false, depth: -1 }];
     for (const t of all) {
@@ -2037,12 +2046,32 @@ export function proposeWithBasis(
       const segs: Segment[] = [['head', rnd(head), rnd([axis, top + 13])]];
       const all: TreeChain[] = [];
       let n = 0;
+      const treeCountBySide = new Map<'r' | 'l', number>([
+        ['r', 0],
+        ['l', 0],
+      ]);
       for (const [side] of SIDES) {
         const prefix = prefixOf(side);
         const sideMasses = massesBySide.get(side) ?? [];
         if (useMasses && sideMasses.length === 0) continue;
-        const sideRcp: ClothRecipe = { ...rawRcp, chains: useMasses ? sideMasses.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)) };
         const frame = `${p.name}'s art on the ${side} side of the eye axis (no art there in the band: the eye axis x)`;
+        const sideMassInputs: TreeMassInput[] | undefined = useMasses
+          ? sideMasses.flatMap((m): TreeMassInput[] => {
+              const count = backHairMassTrees(m, g);
+              return Array.from({ length: count }, (_, t): TreeMassInput => ({
+                rootY: m.minY <= y0 ? eyeY : m.minY,
+                tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
+                xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
+                fallbackX: m.minY <= y0 && sideMasses.length === 1 && count === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
+                frame,
+                treeInMass: t,
+                treesInMass: count,
+              }));
+            })
+          : undefined;
+        const sideCount = sideMassInputs !== undefined ? sideMassInputs.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit));
+        treeCountBySide.set(side, sideCount);
+        const sideRcp: ClothRecipe = { ...rawRcp, chains: sideCount };
         const trees = T(p, 'back hair', sideRcp, {
           prefix,
           parent: 'head',
@@ -2052,15 +2081,7 @@ export function proposeWithBasis(
           fallbackX: () => axis,
           frame,
           edges: side,
-          masses: useMasses
-            ? sideMasses.map((m): TreeMassInput => ({
-                rootY: m.minY <= y0 ? eyeY : m.minY,
-                tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
-                xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
-                fallbackX: m.minY <= y0 && sideMasses.length === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
-                frame,
-              }))
-            : undefined,
+          masses: sideMassInputs,
         });
         for (const t of trees) segs.push(t.chain);
         const made = treeConstraints(trees, sideRcp, null);
@@ -2068,11 +2089,14 @@ export function proposeWithBasis(
         n += made.length;
         all.push(...trees);
       }
-      const sameSideCounts = !useMasses || rMasses.length === lMasses.length;
+      const rTreeCount = treeCountBySide.get('r') ?? 0;
+      const lTreeCount = treeCountBySide.get('l') ?? 0;
+      const sameSideCounts = !useMasses || rTreeCount === lTreeCount;
       const noteRcp: ClothRecipe = {
         ...rawRcp,
-        chains: useMasses ? (sameSideCounts ? rMasses.length : rMasses.length + lMasses.length) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
+        chains: useMasses ? (sameSideCounts ? rTreeCount : rTreeCount + lTreeCount) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
       };
+      const massReason = rTreeCount === rMasses.length && lTreeCount === lMasses.length ? 'one per visible hair mass' : 'across the visible hair masses by root-row width';
       notes.push(
         clothNote(
           p.name,
@@ -2082,7 +2106,7 @@ export function proposeWithBasis(
           n,
           sameSideCounts
             ? ' per side of the eye axis, from head, rooted on the eye line and tipped 4 px above its bottom'
-            : ` (${rMasses.length} on the r side and ${lMasses.length} on the l side of the eye axis, one per visible hair mass), from head, rooted on each mass's top row and tipped 4 px above its bottom`,
+            : ` (${rTreeCount} on the r side and ${lTreeCount} on the l side of the eye axis, ${massReason}), from head, rooted on each mass's top row and tipped 4 px above its bottom`,
         ),
       );
       meshes[p.name] = { grid: g, r: rawRcp.split?.hold_tip === true ? Math.max(r, g) : r, segments: segs };
@@ -4585,11 +4609,12 @@ export function lint(
             .sort((a, b) => Number(trunkRe.exec(a.chain)![1]) - Number(trunkRe.exec(b.chain)![1]));
           if (sideTrunks.length === 0) continue;
           const masses = backHairMasses(mask, side, axis, y0, shoulderLine, g);
+          const massSlots = masses.flatMap((x) => Array.from({ length: backHairMassTrees(x, g) }, () => x));
           const outside: Array<{ point: string; at: [number, number]; minX: number; maxX: number }> = [];
           const sideMinX = masses.length > 0 ? Math.min(...masses.map((x) => x.minX)) : 0;
           const sideMaxX = masses.length > 0 ? Math.max(...masses.map((x) => x.maxX)) : P.W - 1;
           sideTrunks.forEach((tr, k) => {
-            const target = k < masses.length ? masses[k] : null;
+            const target = k < massSlots.length ? massSlots[k] : null;
             const minX = target !== null ? target.minX : sideMinX;
             const maxX = target !== null ? target.maxX : sideMaxX;
             const treeBase = tr.chain.slice(0, -1);
@@ -4606,7 +4631,7 @@ export function lint(
               if (tx < minX || tx > maxX) outside.push({ point: `${c.chain} tip`, at: [tx, ty], minX, maxX });
             }
           });
-          if (sideTrunks.length !== masses.length || outside.length > 0) {
+          if (sideTrunks.length !== massSlots.length || outside.length > 0) {
             findings.push({
               kind: 'back-hair-masses',
               mesh: groupParts.map((q) => q.name).join(' -> '),