@rig-c/parts 1.29.0 → 1.31.0

package/src/build.ts

@@ -43,7 +43,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, hiddenLines, SINGLE_RUN_FACE_TAGS, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeKindsLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, hiddenLines, SINGLE_RUN_FACE_TAGS, singleRunHeadBox, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeKindsLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, sourceSelfFailure, stimulusMotion, withStimulus } from './automotion.ts';
@@ -71,18 +71,18 @@ import {
   untestedIntervals,
 } from './autoreplay.ts';
 import { besideIdleLine, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
-import { type Cut, type Limb, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
+import { type Cut, type Extend, type Limb, loadConfig, loadConfigAndAnimations, loadEarlyConfig, type Patch, type PlanEntry } from './config.ts';
 import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
 import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
 import type { PaletteError } from './palette.ts';
 import { type LayerSet, readLayers } from './layers.ts';
-import { type PartRecord, readParts, type SingleRunPad, tagOf, writeParts } from './parts.ts';
+import { type AlternatePartsRecord, type PartRecord, readParts, type RecompositeRecord, type SingleRunPad, tagOf, writeParts } from './parts.ts';
 import { encodePngBytes, readPng, writePng } from './raster/png.ts';
 import type { Raster } from './raster/types.ts';
 import { readRequirements, type RequirementLine, summaryText } from './requirements.ts';
-import { type AutoMeshReport, buildRig, DEFAULT_IDLE_KEYS, type FaceAxis, type IdleKeys, type MeshReport, type RigCommand, rigJsonText, type RigOutput, type RigSpec, type StrayCleared, type TurnRow } from './rig.ts';
+import { type AutoMeshReport, buildRig, DEFAULT_IDLE_KEYS, type FaceAxis, type IdleKeys, type MeshReport, type RigCommand, rigJsonText, type RigOutput, type RigSpec, SETS_FILE, type StrayCleared, type TurnRow } from './rig.ts';
 import { AUTHOR_NO_ROLE, isAuthorTag } from './tags.ts';
 import { TURN_BONE } from './turn.ts';
 import { pyRound } from './round.ts';
@@ -130,6 +130,14 @@ export function readRuns(full: string, head: string | null): { full: LayerSet; h
   return { full: f as LayerSet, head: h as LayerSet, single: head === null };
 }
 
+/** One `--alt <name>=<source>:<full>[:<head>]` argument (issue #454). */
+export interface AlternateCliInput {
+  name: string;
+  source: string;
+  full: string;
+  head?: string;
+}
+
 export interface AssembleStageInput {
   source: string;
   full: string;
@@ -138,6 +146,8 @@ export interface AssembleStageInput {
   config: string;
   seam: SeamRule;
   project: ProjectRule;
+  /** `--alt` entries, merged with `config.assemble.alternates` by set name (issue #454). */
+  alts?: readonly AlternateCliInput[];
 }
 
 /** Where the assemble stage writes: `parts.json`, the directory of part PNGs, the recomposite, and its error map. */
@@ -246,6 +256,191 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   const under = readUnders(input.config, fields.cuts);
   const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
   const result = assemble({ source: src, full: runs.full, head: runs.head, ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: input.seam, projectRule: input.project });
+
+  // Issue #454: alternate painting sets, assembled before any file is written.
+  const configDir = dirname(resolve(input.config));
+  const cliAlts = input.alts ?? [];
+  const cfgAlts = cfg.assemble.alternates ?? [];
+  const cliByName = new Map<string, AlternateCliInput>();
+  for (const a of cliAlts) cliByName.set(a.name, a);
+  const mergedAlts: Array<{
+    name: string;
+    at: string;
+    source?: string;
+    full?: string;
+    head?: string;
+    parts?: string[];
+    hides?: string[];
+    head_box?: [number, number, number, number];
+    cuts?: Cut[];
+  }> = cfgAlts.map((a, i) => {
+    const cli = cliByName.get(a.name);
+    if (cli !== undefined) cliByName.delete(a.name);
+    return {
+      name: a.name,
+      at: `config.assemble.alternates[${i}] (set "${a.name}")`,
+      source: cli?.source ?? (a.source === undefined ? undefined : resolve(configDir, a.source)),
+      full: cli?.full ?? (a.full === undefined ? undefined : resolve(configDir, a.full)),
+      head: cli !== undefined ? cli.head : a.head === undefined ? undefined : resolve(configDir, a.head),
+      parts: a.parts,
+      hides: a.hides,
+      head_box: a.head_box,
+      cuts: a.cuts,
+    };
+  });
+  for (const cli of cliByName.values()) {
+    mergedAlts.push({
+      name: cli.name,
+      at: `--alt ${cli.name}`,
+      source: cli.source,
+      full: cli.full,
+      head: cli.head,
+    });
+  }
+
+  const altProblems: Problem[] = [];
+  const altBuilt: Array<{ record: AlternatePartsRecord; images: Array<{ name: string; image: Raster }> }> = [];
+  const baseSlots = result.parts.parts.map((p) => p.name);
+  for (const alt of mergedAlts) {
+    if (alt.source === undefined || alt.full === undefined) {
+      altProblems.push({
+        code: 'ASSEMBLE_ALT_INPUT_PRESENT',
+        object: alt.at,
+        detail: 'is missing source or full; declare source and full on the alternate set in config.assemble.alternates, or supply --alt <name>=<source>:<full>[:<head>]',
+      });
+      continue;
+    }
+    if (!existsSync(alt.source)) {
+      altProblems.push({
+        code: 'ASSEMBLE_ALT_INPUT_PRESENT',
+        object: `${alt.source} (alternate set "${alt.name}")`,
+        detail: 'no such file; the alternate painting is required',
+      });
+      continue;
+    }
+    if (!existsSync(alt.full)) {
+      altProblems.push({
+        code: 'ASSEMBLE_ALT_INPUT_PRESENT',
+        object: `${alt.full} (alternate set "${alt.name}")`,
+        detail: 'no such file or directory; the alternate full run is required',
+      });
+      continue;
+    }
+    if (alt.head !== undefined && !existsSync(alt.head)) {
+      altProblems.push({
+        code: 'ASSEMBLE_ALT_INPUT_PRESENT',
+        object: `${alt.head} (alternate set "${alt.name}")`,
+        detail: 'no such file or directory; the alternate head run is required when named',
+      });
+      continue;
+    }
+    const altSrc = readSource(alt.source);
+    if (altSrc.width !== src.width || altSrc.height !== src.height) {
+      altProblems.push({
+        code: 'ASSEMBLE_ALT_CANVAS_SIZE',
+        object: `${alt.source} (alternate set "${alt.name}")`,
+        detail: `is ${altSrc.width}x${altSrc.height}, while the primary painting ${input.source} is ${src.width}x${src.height}; an alternate painting must share the primary painting's canvas size so its parts land in the same rig frame`,
+      });
+      continue;
+    }
+    const altRuns = readRuns(alt.full, alt.head ?? null);
+    const hidesSet = new Set(alt.hides ?? []);
+    const declaredSlots = alt.parts !== undefined ? alt.parts.filter((p) => !hidesSet.has(p)) : baseSlots.filter((p) => !hidesSet.has(p));
+    const coveredSet = new Set(declaredSlots);
+    const rawCuts = alt.cuts !== undefined ? alt.cuts : fields.cuts.filter((c) => coveredSet.has(c.into) && coveredSet.has(c.from)).map((c) => ({ ...c, under: undefined }));
+    const altLimbs: Record<string, Limb> = {};
+    if (fields.limbs !== undefined) {
+      for (const [ln, limb] of Object.entries(fields.limbs)) {
+        if (limb.segments.every((sg) => coveredSet.has(sg.part))) {
+          altLimbs[ln] = { ...limb, segments: limb.segments.map((sg) => ({ ...sg, cap: undefined })) };
+        }
+      }
+    }
+    const neededPlan = new Set<string>();
+    for (const [name] of fields.plan) {
+      if (
+        coveredSet.has(name) ||
+        rawCuts.some((c) => c.from === name) ||
+        Object.values(altLimbs).some((l) => l.segments.some((sg) => sg.from === name))
+      ) {
+        neededPlan.add(name);
+      }
+    }
+    const altPlan: PlanEntry[] = fields.plan
+      .filter(([name]) => neededPlan.has(name))
+      .map(([name, run, tag]): PlanEntry => (altRuns.single ? [name, 'full', tag] : [name, run, tag]));
+    let missingLayer = false;
+    for (const [name, run, tag] of altPlan) {
+      const l = altRuns[run].layers.find((x) => x.name === tag);
+      if (l === undefined || l.opaquePx === 0) {
+        altProblems.push({
+          code: 'ASSEMBLE_ALT_INPUT_PRESENT',
+          object: `alternate set "${alt.name}" (part "${name}")`,
+          detail: `takes ${run}:${tag}, which ${l === undefined ? 'is absent' : 'has 0 opaque pixels'} in ${altRuns[run].source}; every covered part of the alternate set must be present in its runs, or listed in hides`,
+        });
+        missingLayer = true;
+      }
+    }
+    if (missingLayer) continue;
+    const altPlanNames = new Set(altPlan.map((e) => e[0]));
+    const remapDraw = (d: Patch['draw']): Patch['draw'] => {
+      if (typeof d !== 'object') return d;
+      if (altPlanNames.has(d.before)) return d;
+      const baseIdx = fields.plan.findIndex((e) => e[0] === d.before);
+      for (let i = Math.max(0, baseIdx); i < fields.plan.length; i++) {
+        if (altPlanNames.has(fields.plan[i][0])) return { before: fields.plan[i][0] };
+      }
+      return 'front';
+    };
+    const altExtend: Extend[] = altRuns.single ? [] : fields.extend.filter((e) => altPlanNames.has(e.part));
+    const altPatches: Patch[] = fields.patches.filter((p) => coveredSet.has(p.name)).map((p) => ({ ...p, draw: remapDraw(p.draw) }));
+    const altCuts: Cut[] = rawCuts.map((c) => ({ ...c, draw: remapDraw(c.draw) }));
+    const altUnder = alt.cuts !== undefined ? readUnders(input.config, altCuts) : altCuts.map(() => null);
+    const altHeadBox = alt.head_box ?? (altRuns.single ? singleRunHeadBox(altSrc.width, altSrc.height, fields.resolution) : fields.headBox);
+    const altRes = assemble({
+      source: altSrc,
+      full: altRuns.full,
+      head: altRuns.head,
+      resolution: fields.resolution,
+      headBox: altHeadBox,
+      rigScale: fields.rigScale,
+      plan: altPlan,
+      extend: altExtend,
+      patches: altPatches,
+      cuts: altCuts,
+      under: altUnder,
+      ...(Object.keys(altLimbs).length > 0 ? { limbs: altLimbs, bones: fields.bones } : {}),
+      ...(fields.scene === undefined ? {} : { scene: fields.scene }),
+      ...(fields.armSplit !== undefined && altPlan.some((e) => e[1] === 'full' && (e[2] === 'handwear-r' || e[2] === 'handwear-l')) ? { armSplit: fields.armSplit } : {}),
+      seamRule: input.seam,
+      projectRule: input.project,
+    });
+    const keptImages = altRes.images
+      .filter(({ record }) => coveredSet.has(record.name))
+      .map(({ record, image }) => ({ name: `${alt.name}_${record.name}`, image }));
+    const keptRecords = altRes.parts.parts.filter((p) => coveredSet.has(p.name));
+    const slots: Record<string, string> = {};
+    for (const r of keptRecords) slots[r.name] = `${alt.name}_${r.name}`;
+    altBuilt.push({
+      record: {
+        name: alt.name,
+        ...(alt.parts === undefined ? {} : { parts: [...alt.parts] }),
+        ...(alt.hides === undefined || alt.hides.length === 0 ? {} : { hides: [...alt.hides] }),
+        slots,
+        records: keptRecords,
+        ghost_px: altRes.parts.ghost_px,
+        recomposite: altRes.parts.recomposite as RecompositeRecord,
+        ...(altRes.parts.scene === undefined ? {} : { scene: altRes.parts.scene }),
+        ...(altRes.parts.single_run_pad === undefined ? {} : { single_run_pad: altRes.parts.single_run_pad }),
+      },
+      images: keptImages,
+    });
+  }
+  refuseIfAny(altProblems);
+  if (altBuilt.length > 0) {
+    result.parts.alternates = altBuilt.map((b) => b.record);
+  }
+
   // Emit only after green: every refusal above has already thrown.
   mkdirSync(outs.partsDir, { recursive: true });
   mkdirSync(dirname(outs.partsJson), { recursive: true });
@@ -253,6 +448,9 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   mkdirSync(dirname(outs.errorMap), { recursive: true });
   writeParts(outs.partsJson, result.parts);
   for (const { record, image } of result.images) writePng(join(outs.partsDir, `${record.name}.png`), image);
+  for (const b of altBuilt) {
+    for (const { name, image } of b.images) writePng(join(outs.partsDir, `${name}.png`), image);
+  }
   writePng(outs.recomposite, result.recomposite);
   writePng(outs.errorMap, result.errorMap);
   // Issue #242: under config.scene, the figure the recomposite was read inside, beside the recomposite.
@@ -820,11 +1018,19 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
     const png = join(input.parts, 'parts', `${p.name}.png`);
     if (existsSync(png)) images.set(p.name, readPng(png));
   }
+  for (const alt of parts.alternates ?? []) {
+    for (const p of alt.records) {
+      const attName = `${alt.name}_${p.name}`;
+      const png = join(input.parts, 'parts', `${attName}.png`);
+      if (existsSync(png)) images.set(attName, readPng(png));
+    }
+  }
   const first = buildRig(cfg, parts, images, undefined, input.idleKeys ?? DEFAULT_IDLE_KEYS, input.reduce);
   const textsOf = (r: RigOutput): Array<[string, string]> => [
     ['rig.json', rigJsonText(r.rig)],
     ['motion.json', rigJsonText(withAnimations(r.motion, from === null ? null : from.table))],
     ['mesh_report.json', rigJsonText(r.meshReport)],
+    ...(r.sets === undefined ? [] : [[SETS_FILE, rigJsonText(r.sets)] as [string, string]]),
   ];
   const firstTexts = textsOf(first);
   // The gate runs before the lines are printed, and its lines print where they always did: an automatic part's motion
@@ -855,7 +1061,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
   const replays = new Map<string, ReplayRow | MultiIntervalRow>();
   if (settled) {
     const swapped = JSON.parse(rigJsonText(first.rig)) as RigSpec;
-    for (const k of chosen) swapped.skins.default[k.part] = { [k.part]: k.candidate.attachment };
+    for (const k of chosen) swapped.skins.default[k.part] = { ...swapped.skins.default[k.part], [k.part]: k.candidate.attachment };
     rig = { ...first, rig: swapped, meshReport: first.meshReport.map((m) => chosen.find((k) => k.part === m.part)?.candidate.row ?? m) };
     texts = textsOf(rig);
     let model: string | null = null;
@@ -1499,6 +1705,8 @@ export interface BuildInput {
   seamPairs?: boolean;
   /** `--keep-stills`, forwarded to the check as `check` takes it (issue #257): the setup-pose still under `check/setup_still/`; absent, nothing moves. */
   keepStills?: boolean;
+  /** `--alt`, forwarded to the assemble stage as `assemble` takes it (issue #454). */
+  alts?: readonly AlternateCliInput[];
 }
 
 /** What `build` does with one flag `check` takes: hands it to its check stage, takes it as its own, or refuses it because build supplies the value itself. */
@@ -1617,7 +1825,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
     // The same for the requirements file's own shape; its names resolve against the rig, in the check, before it builds.
     if (input.requirements !== undefined) readRequirements(input.requirements);
     assembleStage(
-      { source: input.source, full: input.full, head: input.head, config: input.config, seam: input.seam, project: input.project },
+      { source: input.source, full: input.full, head: input.head, config: input.config, seam: input.seam, project: input.project, ...(input.alts === undefined ? {} : { alts: input.alts }) },
       { partsJson: join(out, 'parts.json'), partsDir: join(out, 'parts'), recomposite: join(out, 'recomposite_rig.png'), errorMap: join(out, ERROR_MAP_FILE) },
       prefixed('assemble'),
     );

package/src/check.ts

@@ -2569,7 +2569,7 @@ export function stressPlan(rig: Record<string, unknown>, motion: Record<string,
       continue;
     }
     const onSlot = skin[p.name];
-    const atts: unknown[] = isRecord(onSlot) ? Object.values(onSlot) : [];
+    const atts: unknown[] = isRecord(onSlot) ? (isRecord(onSlot[p.name]) ? [onSlot[p.name]] : 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) {
       notRead.push({ part: p.name, reason: 'it is not a weighted mesh, so it rides one bone whole and cannot stretch' });
@@ -4252,7 +4252,7 @@ function offChainClause(rig: Record<string, unknown>, motion: Record<string, unk
   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 atts: unknown[] = isRecord(onSlot) ? (isRecord(onSlot[part]) ? [onSlot[part]] : 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);
@@ -4295,7 +4295,8 @@ function boundBones(rig: Record<string, unknown>, part: string): Set<string> {
   const slot = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find((sl) => sl.name === part);
   const skins = isRecord(rig.skins) ? rig.skins : {};
   const skin = isRecord(skins.default) ? skins.default : {};
-  const atts = isRecord(skin[part]) ? Object.values(skin[part]) : [];
+  const onSlot = skin[part];
+  const atts = isRecord(onSlot) ? (isRecord(onSlot[part]) ? [onSlot[part]] : Object.values(onSlot)) : [];
   const bound = new Set<string>();
   for (const a of atts) {
     if (isRecord(a) && Array.isArray(a.weights)) for (const v of a.weights) for (const w of Array.isArray(v) ? v : []) if (isRecord(w) && typeof w.bone === 'string') bound.add(w.bone);
@@ -4345,7 +4346,8 @@ function breathCarrier(
   // The one weighted mesh the part draws, its weights in the order of the geometry's vertices.
   const skins = isRecord(rig.skins) ? rig.skins : {};
   const skin = isRecord(skins.default) ? skins.default : {};
-  const atts = isRecord(skin[part]) ? Object.values(skin[part]) : [];
+  const onSlot = skin[part];
+  const atts = isRecord(onSlot) ? (isRecord(onSlot[part]) ? [onSlot[part]] : Object.values(onSlot)) : [];
   const first = m.shown[0];
   if (atts.length !== 1 || first === null || first === undefined) return null;
   const att = atts[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