@rig-c/parts 1.30.0 → 1.31.0

package/src/cloth.ts

@@ -107,11 +107,13 @@ export type ClothRecipes = Partial<Record<ClothTarget, ClothRecipe>>;
 
 /**
  * 📐 The fallback tree count when `draftTrees` is called without `chains` or
- * `masses` (issues #390, #445). When `chains` is omitted on
+ * `masses` (issues #390, #445, #461). When `chains` is omitted on
  * `config.cloth."back hair"`, `propose` derives the count per side from the
- * visible hair masses ({@link backHairMasses}): connected components of the
- * back-hair part's alpha below the root row (merged when they touch within one
- * grid cell), one tree per mass, rooted at that mass's own top row.
+ * visible hair masses ({@link backHairMasses}, {@link backHairMassTrees}):
+ * connected components of the back-hair part's alpha below the root row (merged
+ * when they touch within one grid cell), with `max(1, floor(w / (4 * grid)) + 1)`
+ * trees per mass across its root-row width `w`, rooted at that mass's own top
+ * row and inside its columns.
  */
 export const RECIPE_BACK_HAIR_CHAINS = 2;
 
@@ -185,13 +187,16 @@ export interface TreeChain {
 /** Which outer sides of the piece are edges: both (a skirt, a lock), or one side of the eye axis (back hair). */
 export type EdgeSides = 'both' | 'r' | 'l';
 
-/** Issue #445: one visible hair mass's own frame for a single tree rooted at that mass's top row. */
+/** Issue #445, #461: one visible hair mass's own frame for a tree rooted at that mass's top row. */
 export interface TreeMassInput {
   rootY: number;
   tipY: number;
   xAt: (y: number, frac: number) => number | null;
   fallbackX: (frac: number) => number;
   frame: string;
+  /** Issue #461: tree index within this mass (0-based, default 0) and total trees in this mass (default 1). */
+  treeInMass?: number;
+  treesInMass?: number;
 }
 
 export interface TreeColumnTip {
@@ -213,7 +218,7 @@ export interface TreeInput {
   /** What the cell's frame is, for the rules: "skirt's art", "the r side of back's art". */
   frame: string;
   edges: EdgeSides;
-  /** Issue #445: when present, one entry per visible hair mass; tree k sits inside `masses[k]` rather than cell [k/n, (k+1)/n] of the whole side. */
+  /** Issue #445: when present, one entry per drafted back-hair tree; tree k sits inside `masses[k]` rather than cell [k/n, (k+1)/n] of the whole side. */
   masses?: readonly TreeMassInput[];
   /**
    * Issue #438: when present, resolves the tip row (and an optional `xAt` bounded to that column's cloth rows) for
@@ -267,7 +272,9 @@ export function draftTrees(input: TreeInput, r: ClothRecipe): TreeChain[] {
   };
   for (const k of activeTrees) {
     const mass = input.masses?.[k];
-    const fc = mass === undefined ? (k + 0.5) / n : 0.5;
+    const tInMass = mass?.treeInMass ?? 0;
+    const nInMass = mass?.treesInMass ?? 1;
+    const fc = mass === undefined ? (k + 0.5) / n : (tInMass + 0.5) / nInMass;
     const trunkCol = trunkCols.get(k) ?? null;
     const branchCols: Array<TreeColumnTip | null> = [];
     if (into > 1 && mass === undefined && input.columnTip !== undefined) {
@@ -314,7 +321,7 @@ export function draftTrees(input: TreeInput, r: ClothRecipe): TreeChain[] {
     out.push(trunk);
     if (into === 1) continue;
     for (let b = 0; b < into; b++) {
-      const fb = mass === undefined ? (k + (b + 0.5) / into) / n : (b + 0.5) / into;
+      const fb = mass === undefined ? (k + (b + 0.5) / into) / n : (tInMass + (b + 0.5) / into) / nInMass;
       const bCol = branchCols[b] ?? trunkCol;
       const bTipY = bCol?.tipY ?? trunkTipY;
       const bRows = bTipY === trunkTipY ? rows : linkRows(input.rootY, bTipY, r.links, ratio);
@@ -764,3 +771,48 @@ export function backHairMasses(mask: Mask, side: 'r' | 'l', axis: number, y0: nu
   out.sort((a, b) => a.minX - b.minX);
   return out;
 }
+
+/**
+ * 📐 The horizontal influence reach of one back-hair tree in mesh grid cells: 4
+ * (2 grid cells on each side of the trunk, issue #461).
+ *
+ * Under the segment weight rule `w = 1 / (d + r)^2` (`src/weights.ts`) with
+ * `partGrid`'s falloff `r ≈ 0.42 * grid` and cutoff `MIN_WEIGHT = 0.03`, a
+ * tree's weight relative to `d = 0` (`(r / (d + r))^2`) drops to `MIN_WEIGHT`
+ * at `d = (1 / sqrt(0.03) - 1) * r = 4.7735 * 0.42 * grid = 2.0049 * grid ≈ 2 * grid`
+ * on each side of the trunk — a horizontal span of `4 * grid` per tree. Beyond
+ * that span a single tree leaves outer columns weighted to the static `head`
+ * segment while adjacent columns move with the tree, stretching the triangles
+ * across the boundary.
+ */
+export const BACK_HAIR_TREE_REACH_CELLS = 4;
+
+/**
+ * Opaque pixel count of a visible hair mass `m` along its own root row `m.minY`
+ * (issue #461).
+ */
+export function backHairMassRootWidth(m: BackHairMass): number {
+  const W = m.mask.width;
+  const H = m.mask.height;
+  if (m.minY < 0 || m.minY >= H) return 0;
+  let w = 0;
+  for (let x = m.minX; x <= m.maxX; x++) {
+    if (m.mask.data[m.minY * W + x] !== 0) w++;
+  }
+  return w > 0 ? w : m.maxX - m.minX + 1;
+}
+
+/**
+ * Number of trees placed inside one visible hair mass `m` on a `grid` px mesh
+ * (issue #461): `max(1, floor(w / (4 * grid)) + 1)` where `w` is the mass's
+ * root-row opaque width ({@link backHairMassRootWidth}).
+ *
+ * A narrow mass (`w < 4 * grid`) gets 1 tree; a wide undivided tail spanning
+ * `4 * grid <= w < 8 * grid` gets 2 trees; `8 * grid <= w < 12 * grid` gets 3.
+ */
+export function backHairMassTrees(m: BackHairMass, grid: number): number {
+  const step = Math.max(1, BACK_HAIR_TREE_REACH_CELLS * grid);
+  const w = backHairMassRootWidth(m);
+  return Math.max(1, Math.floor(w / step) + 1);
+}
+

package/src/config.ts

@@ -245,6 +245,17 @@ 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[];
+}
+
 export interface Assemble {
   /** Rig pixels per source pixel. */
   rig_scale: number;
@@ -252,6 +263,7 @@ export interface Assemble {
   extend_below_crop?: Extend[];
   patches?: Patch[];
   cuts?: Cut[];
+  alternates?: AlternateSetConfig[];
 }
 
 export interface SingleBone {
@@ -1112,7 +1124,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 +1134,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);
     }
   }
   if ('cloth' in t) checkCloth(c, t.cloth);
@@ -1276,6 +1292,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);
+  }
   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 +1621,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 +1640,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 +1709,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 +1763,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 +1815,56 @@ 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,
+): 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']);
+    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'] as const) {
+      if (k in e) c.string(`${at}.${k}`, e[k]);
+    }
+    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

@@ -241,6 +241,23 @@ export interface RecompositeRecord {
   holes: HoleRecord[];
 }
 
+export interface AlternateSetMap {
+  slots: Record<string, string>;
+  hides?: string[];
+}
+
+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;
+}
+
 export interface PartsFile {
   rig_size: [number, number];
   scale_rig_per_source: number;
@@ -252,6 +269,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 +305,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 +365,43 @@ 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]])) }),
+          })),
         }),
-    ...(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 +634,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(' -> '),