@rig-c/parts 1.24.0 → 1.26.0

package/src/config.ts

@@ -86,7 +86,7 @@
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
+import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey, type RigStop } from 'rig-c/src/rig.ts';
 import { pyRound } from './round.ts';
 import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING, springStable } from './cloth.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
@@ -256,6 +256,8 @@ export interface ChainBones {
   parent: string;
   points: Point[];
   tip: Point;
+  /** Expanded link name -> rig-c inherit mode (issue #369); absent links keep normal inheritance. */
+  link_inherit?: Record<string, RigBoneInherit>;
 }
 
 export type BoneEntry = SingleBone | ChainBones;
@@ -648,6 +650,26 @@ export interface ConfigConstraint {
   [field: string]: unknown;
 }
 
+/**
+ * One entry of `config.stops` (issue #404): rig-c's `RigStop` (`rig-c` 2.56.0),
+ * a cloth chain's rotation clamped against a leg bone so the skirt cannot swing
+ * into the leg. `chain` names a chain declared in `config.bones`; `links` is
+ * the stopped links along it (when omitted, every link of `chain` in link
+ * order); `against` is the leg bone the point rides on; `at` is `[x, y]` in
+ * `against`'s local space; `inward` and `outward` are the first link's clamp
+ * bounds in degrees (positive away from `against`), and `lower` the lower
+ * links' bounds when more than one link is stopped.
+ */
+export interface ConfigStop {
+  chain: string;
+  links?: string[];
+  against: string;
+  at: Point;
+  inward: number;
+  outward: number;
+  lower?: { inward: number; outward: number };
+}
+
 /**
  * One segment of a limb (issue #349): the part it makes, the part whose
  * pixels it takes (`from`: a plan part or a cut's piece), and the one bone it
@@ -697,12 +719,16 @@ export interface CharacterConfig {
   regions: Record<string, string>;
   motion: Motion;
   constraints?: ConfigConstraint[];
+  /** Leg stops (issue #404, rig-c 2.56.0's `RigStop`): absent, no stop is added and no byte of any output moves. */
+  stops?: ConfigStop[];
   /** The turn control (issue #251, `src/turn.ts`): absent, no control is added and no byte of any output moves. */
   turn?: TurnSpec;
   /** The painting is a scene (issue #242): absent, no byte of any output moves. */
   scene?: SceneSpec;
   /** The cloth and hair recipe `propose --cloth` drafts from (issue #364, `src/cloth.ts`): read by propose only, so no byte of any rig output moves with it. */
   cloth?: ClothRecipes;
+  /** The `assemble.rig_scale` (`parts.json`'s `scale_rig_per_source`) `propose` drafted the rig sections at (issue #354): absent on a hand-authored config, held equal to `assemble.rig_scale` when present. */
+  proposed_rig_scale?: number;
 }
 
 /** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
@@ -760,6 +786,23 @@ export function constraintForRig(c: ConfigConstraint): Record<string, unknown> {
   return out;
 }
 
+/**
+ * A stop as the rig stage hands it to rigc (issue #404): its fields in
+ * `RigStop` order, `links` expanded from `chain` when omitted, and any records
+ * (`x-…`) or annotations (`note`, `…_note`) left out.
+ */
+export function stopForRig(s: ConfigStop, links: readonly string[]): RigStop {
+  return {
+    chain: s.chain,
+    links: [...links],
+    against: s.against,
+    at: [s.at[0], s.at[1]],
+    inward: s.inward,
+    outward: s.outward,
+    ...(s.lower === undefined ? {} : { lower: { inward: s.lower.inward, outward: s.lower.outward } }),
+  };
+}
+
 /** The single-value bone properties a sine track may drive — rigc's one-channel bone timelines. */
 export const SINGLE_PROPS = ['rotate', 'translatex', 'translatey', 'scalex', 'scaley', 'shearx', 'sheary'] as const;
 export type SingleProp = (typeof SINGLE_PROPS)[number];
@@ -990,9 +1033,11 @@ export interface AssembleConfig {
   /** Issue #349: read with `bones` (the joints are the bones' origins) when present. */
   limbs?: Record<string, Limb>;
   bones?: BoneEntry[];
+  /** Issue #354: the `rig_scale` `propose` drafted the rig sections at, held equal to `assemble.rig_scale` when present. */
+  proposed_rig_scale?: number;
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene', 'cloth'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth', 'proposed_rig_scale'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -1042,6 +1087,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'assemble') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     const made = 'assemble' in t ? checkAssemble(c, t.assemble, door) : { parts: [], patches: [], cuts: [] };
+    checkProposedRigScale(c, t);
     if ('scene' in t) checkScene(c, t.scene);
     // Issue #349: the limbs' joints are their bones' origins, so the bones are read with them, and only then.
     if ('limbs' in t) {
@@ -1195,6 +1241,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('generation' in t) checkGeneration(c, t.generation);
   if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
   const { parts, patches, cuts } = 'assemble' in t ? checkAssemble(c, t.assemble, 'full') : { parts: [], patches: [], cuts: [] };
+  checkProposedRigScale(c, t);
   const names = 'bones' in t ? checkBones(c, t.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
   const limbs = 'limbs' in t ? checkLimbs(c, t.limbs, { parts, patches, cuts }, 'bones' in t ? names : null) : null;
   if ('meshes' in t) checkMeshes(c, t.meshes, names.bones, names.chains);
@@ -1202,6 +1249,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions, limbs);
   if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
+  if ('stops' in t) checkStops(c, t.stops, names.bones, names.chains);
   if ('turn' in t) checkTurn(c, t.turn, attachedParts(t.meshes, t.regions), names.bones);
   if ('scene' in t) checkScene(c, t.scene);
   if ('cloth' in t) checkCloth(c, t.cloth);
@@ -1212,6 +1260,29 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   return { config: raw as CharacterConfig, animations };
 }
 
+/**
+ * Issue #354: `propose` records `parts.json`'s `scale_rig_per_source` on the
+ * proposal as `proposed_rig_scale`, and pasting the proposal into `config.json`
+ * carries it. When present, `assemble`, `rig` and `build` compare it against
+ * `assemble.rig_scale` and refuse a mismatch: the bones, mesh spacings, segment
+ * coordinates and motion amplitudes are in the proposed rig canvas's pixels and
+ * do not scale when `assemble.rig_scale` changes. A hand-authored config with
+ * no `proposed_rig_scale` is not refused.
+ */
+function checkProposedRigScale(c: Check, t: Record<string, Json>): void {
+  if (!('proposed_rig_scale' in t)) return;
+  if (!c.number('config.proposed_rig_scale', t.proposed_rig_scale, 'positive')) return;
+  const a = isPlainObject(t.assemble) ? t.assemble : null;
+  if (a === null || !('rig_scale' in a) || !(typeof a.rig_scale === 'number' && Number.isFinite(a.rig_scale) && a.rig_scale > 0)) return;
+  if (t.proposed_rig_scale !== a.rig_scale) {
+    c.fail(
+      'CONFIG_PROPOSED_RIG_SCALE',
+      'config.proposed_rig_scale',
+      `is ${t.proposed_rig_scale}, and config.assemble.rig_scale is ${a.rig_scale} — the bones, meshes, limbs and motion were proposed at rig_scale ${t.proposed_rig_scale} and are in that rig canvas's pixels, so they do not scale when assemble.rig_scale changes; re-run assemble and propose at rig_scale ${a.rig_scale} and paste the new proposal, or restore config.assemble.rig_scale to ${t.proposed_rig_scale}`,
+    );
+  }
+}
+
 function isPlainObject(v: Json): v is Record<string, Json> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -1364,9 +1435,9 @@ export interface SkeletonSections {
 /**
  * A `proposal.json` as `propose` writes it — `bones`, `meshes`, `regions`,
  * `motion` and `notes` (strings), `limbs` when `propose --keypoints` drafted
- * them (issue #349) and `constraints` when `propose --cloth` did (issue #364;
+ * them (issue #349), `constraints` when `propose --cloth` did (issue #364;
  * both read here since issue #372, whose `wind` example tracks such a
- * proposal) — under the full loader's own rules for those sections (issue
+ * proposal), and `proposed_rig_scale` (issue #354) — under the full loader's own rules for those sections (issue
  * #85). There is no plan to hold the meshes, regions and limbs against, so
  * the coverage rule (every plan part exactly one of a mesh or a region) is
  * not run, and a limb segment's `from` is held to no plan part (the parts
@@ -1374,9 +1445,9 @@ export interface SkeletonSections {
  * both before writing (`checkProposal`). A key the loader would not take is
  * refused by name, as in a config. Refusals name the fields `proposal.…`.
  */
-export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[] } {
+export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number } {
   const c = new Check();
-  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints']);
+  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops', 'proposed_rig_scale']);
   if (top !== null) {
     const names = 'bones' in top ? checkBones(c, top.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
     if ('limbs' in top) {
@@ -1389,10 +1460,12 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
     if ('regions' in top) checkRegions(c, top.regions, names.bones);
     if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
     if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
+    if ('stops' in top) checkStops(c, top.stops, names.bones, names.chains);
+    if ('proposed_rig_scale' in top) c.number('config.proposed_rig_scale', top.proposed_rig_scale, 'positive');
     if ('notes' in top && c.array('config.notes', top.notes, false)) (top.notes as Json[]).forEach((n, i) => c.string(`config.notes[${i}]`, n, false));
   }
   refuseIfAny(c.problems.map((p) => ({ ...p, object: p.object.replace(/^config\b/, 'proposal') })));
-  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[] };
+  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[]; proposed_rig_scale?: number };
 }
 
 /**
@@ -1720,7 +1793,7 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
     const at = `config.bones[${i}]`;
     const isChain = typeof entry === 'object' && entry !== null && 'chain' in entry;
     if (isChain) {
-      const b = c.object(at, entry, ['chain', 'parent', 'points', 'tip'], []);
+      const b = c.object(at, entry, ['chain', 'parent', 'points', 'tip'], ['link_inherit']);
       if (b === null) return;
       if ('parent' in b && c.string(`${at}.parent`, b.parent) && !bones.has(b.parent)) {
         c.fail('CONFIG_NAME_RESOLVES', `${at}.parent`, `names "${b.parent}", which is not "${ROOT_BONE}" or a bone declared above it; parents come first`);
@@ -1738,6 +1811,21 @@ function checkBones(c: Check, v: Json): { bones: Set<string>; chains: Map<string
           else if (typeof b.parent === 'string' && !parents.has(`${name}0`)) parents.set(`${name}0`, b.parent);
         });
         chains.set(name, points.length);
+        if ('link_inherit' in b) {
+          const path = `${at}.link_inherit`;
+          const links = points.map((_, k) => `${name}${k}`);
+          if (!isPlainObject(b.link_inherit)) {
+            c.fail('CONFIG_FIELD_TYPE', path, `is ${show(b.link_inherit)}; an object mapping this chain's expanded link names to rig-c inherit modes is required`);
+          } else {
+            for (const [link, mode] of Object.entries(b.link_inherit)) {
+              const field = `${path}.${link}`;
+              if (!links.includes(link)) c.fail('CONFIG_NAME_RESOLVES', field, `names "${link}", which is not a link of chain "${name}"; its declared links are ${links.map((n) => `"${n}"`).join(', ')}`);
+              if (c.string(field, mode) && !(RIG_BONE_INHERIT as readonly string[]).includes(mode)) {
+                c.fail('CONFIG_BONE_INHERIT', field, `is ${show(mode)}; one of rig-c's inherit modes, spelled as its table spells them, is required — ${RIG_BONE_INHERIT.join(', ')} (rig-c's RigBone.inherit; nothing here folds a case or maps a name)`);
+              }
+            }
+          }
+        }
       }
       return;
     }
@@ -2614,6 +2702,65 @@ function checkConstraints(c: Check, v: Json, bones: Set<string>, parents: Map<st
   });
 }
 
+/**
+ * `config.stops` (issue #404): rig-c 2.56.0's `RigStop` entries, each holding
+ * a swinging chain off a leg bone (`against`). `chain` resolves against the
+ * chains `config.bones` declares; `links` (when given) and `against` resolve
+ * against the bones `config.bones` declares (`CONFIG_NAME_RESOLVES`).
+ */
+function checkStops(c: Check, v: Json, bones: Set<string>, chains: Map<string, number>): void {
+  const p = 'config.stops';
+  if (!c.array(p, v, false)) return;
+  const declaredBones = [...bones].join(', ');
+  const declaredChains = [...chains.keys()].join(', ') || 'none';
+  (v as Json[]).forEach((entry, i) => {
+    const at = `${p}[${i}]`;
+    const o = c.object(at, entry, ['chain', 'against', 'at', 'inward', 'outward'], ['links', 'lower']);
+    if (o === null) return;
+    let chainLinks: number | undefined;
+    if ('chain' in o && c.string(`${at}.chain`, o.chain)) {
+      chainLinks = chains.get(o.chain);
+      if (chainLinks === undefined) {
+        c.fail('CONFIG_NAME_RESOLVES', `${at}.chain`, `names "${o.chain}", which config.bones does not declare as a chain; the chains that exist: ${declaredChains}`);
+      }
+    }
+    let linkCount = chainLinks ?? 0;
+    if ('links' in o && c.array(`${at}.links`, o.links, true)) {
+      const list = o.links as Json[];
+      linkCount = list.length;
+      list.forEach((l, k) => {
+        if (c.string(`${at}.links[${k}]`, l) && !bones.has(l)) {
+          c.fail('CONFIG_NAME_RESOLVES', `${at}.links[${k}]`, `names "${l}", which config.bones does not declare; the bones that exist: ${declaredBones}`);
+        }
+      });
+    }
+    if ('against' in o && c.string(`${at}.against`, o.against) && !bones.has(o.against)) {
+      c.fail('CONFIG_NAME_RESOLVES', `${at}.against`, `names "${o.against}", which config.bones does not declare; the bones that exist: ${declaredBones}`);
+    }
+    if ('at' in o) c.point(`${at}.at`, o.at);
+    const inward = 'inward' in o && c.number(`${at}.inward`, o.inward) ? (o.inward as number) : null;
+    const outward = 'outward' in o && c.number(`${at}.outward`, o.outward) ? (o.outward as number) : null;
+    if (inward !== null && outward !== null && inward > outward) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.inward`, `is ${inward}, above outward ${outward}; inward <= outward is required`);
+    }
+    if ('lower' in o) {
+      const lo = c.object(`${at}.lower`, o.lower, ['inward', 'outward'], []);
+      if (lo !== null) {
+        const li = 'inward' in lo && c.number(`${at}.lower.inward`, lo.inward) ? (lo.inward as number) : null;
+        const loOut = 'outward' in lo && c.number(`${at}.lower.outward`, lo.outward) ? (lo.outward as number) : null;
+        if (li !== null && loOut !== null && li > loOut) {
+          c.fail('CONFIG_FIELD_TYPE', `${at}.lower.inward`, `is ${li}, above lower.outward ${loOut}; inward <= outward is required`);
+        }
+      }
+      if (linkCount === 1) {
+        c.fail('CONFIG_FIELD_TYPE', `${at}.lower`, `is ${show(o.lower)} on a 1-link stop; lower holds the links below the first, so leave lower out when links has 1 bone`);
+      }
+    } else if (linkCount > 1) {
+      c.fail('CONFIG_FIELD_PRESENT', `${at}.lower`, `is absent and required when the stop holds ${linkCount} links (more than 1); state lower: { inward, outward } for the links below the first`);
+    }
+  });
+}
+
 /** The parts `meshes` and `regions` attach, read off whatever they hold; `turn.depths` may name only these. */
 function attachedParts(meshes: Json, regions: Json): Set<string> {
   const out = new Set<string>();
@@ -2666,7 +2813,7 @@ function attachedParts(meshes: Json, regions: Json): Set<string> {
  * - `part` on a tag other than `bottomwear` (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`):
  *   the field hands the skirt's recipe to a part of another tag (issue #402),
  *   and only the skirt has a recipe that part can take; whether the part
- *   exists, and is a `topwear` that hangs below the hip, is read off the parts
+ *   exists, and is a `topwear` part or its cut piece hanging below the hip, is read off the assembled parts
  *   by `propose` (`PROPOSE_CLOTH_PART`);
  * - a strength, declared or the recipe's default, whose spring is unstable at
  *   a damping the recipe runs at — k = strength·massInverse·step² at or past
@@ -2695,15 +2842,17 @@ function checkCloth(c: Check, v: Json): void {
   for (const tag of CLOTH_TARGETS) {
     if (!(tag in v)) continue;
     const path = `${at}.${JSON.stringify(tag)}`;
-    const r = c.object(path, v[tag], ['chains', 'links', 'wind', 'gravity'], ['split', 'length_ratio', 'strength', 'damping', 'alternate_damping', 'translate', 'swing', 'part']);
+    const r = c.object(path, v[tag], ['links', 'wind', 'gravity'], ['chains', 'split', 'length_ratio', 'strength', 'damping', 'alternate_damping', 'translate', 'swing', 'part']);
     if (r === null) continue;
+    if (tag !== 'back hair' && !('chains' in r)) c.fail('CONFIG_FIELD_PRESENT', `${path}.chains`, 'is absent and required');
     const chains = 'chains' in r && c.int(`${path}.chains`, r.chains, 1) ? (r.chains as number) : null;
     const links = 'links' in r && c.int(`${path}.links`, r.links, 1) ? (r.links as number) : null;
     if ('split' in r) {
-      const sp = c.object(`${path}.split`, r.split, ['at', 'into'], []);
+      const sp = c.object(`${path}.split`, r.split, ['at', 'into'], ['hold_tip']);
       if (sp !== null) {
         const sAt = 'at' in sp && c.int(`${path}.split.at`, sp.at, 1) ? (sp.at as number) : null;
         if ('into' in sp) c.int(`${path}.split.into`, sp.into, 2);
+        if ('hold_tip' in sp && typeof sp.hold_tip !== 'boolean') c.fail('CONFIG_FIELD_TYPE', `${path}.split.hold_tip`, `is ${show(sp.hold_tip)}; true or false is required`);
         if (sAt !== null && links !== null && sAt >= links) {
           c.fail('CONFIG_CLOTH_SPLIT_BEFORE_TIP', `${path}.split.at`, `is ${sAt} and links is ${links}; the trunk's ${sAt} link(s) would leave no link for the branches — split.at below links is required`);
         }
@@ -2750,7 +2899,7 @@ function checkCloth(c: Check, v: Json): void {
     }
     if ('part' in r) {
       if (tag !== 'bottomwear') {
-        c.fail('CONFIG_CLOTH_PART_ON_BOTTOMWEAR', `${path}.part`, `is declared on "${tag}"; part hands the skirt's recipe (bottomwear) to a topwear part that holds a skirt (a dress) — leave it out here`);
+        c.fail('CONFIG_CLOTH_PART_ON_BOTTOMWEAR', `${path}.part`, `is declared on "${tag}"; part hands the skirt's recipe (bottomwear) to a topwear part or its cut skirt piece (a dress) — leave it out here`);
       } else c.string(`${path}.part`, r.part);
     }
     if ('swing' in r) {

package/src/headbox.ts

@@ -42,6 +42,20 @@ export const HEAD_LAYER_MIN_PX = 150;
 
 export type Box = [number, number, number, number];
 
+export interface HeadBoxOptions {
+  /** Whether `"back hair"` is included in the union (issue #351); default `true`. */
+  backHair?: boolean;
+}
+
+export interface HeadBoxWithoutBackHair {
+  /** The square box's side in source px without `"back hair"`. */
+  edge: number;
+  /** The box without `"back hair"` before clamping to the painting. */
+  unclamped: Box;
+  /** The box without `"back hair"` held inside the painting, or `null` when `edge` exceeds a canvas side. */
+  head_box: Box | null;
+}
+
 export interface HeadBoxProposal {
   /** The square box, inside the painting: what goes into `seethrough.head_box`. */
   head_box: Box;
@@ -49,8 +63,10 @@ export interface HeadBoxProposal {
   unclamped: Box;
   /** How far the box was moved to stay inside, in source px. */
   shift: [number, number];
-  /** The layers that contributed, with their opaque pixel counts after the clean-up. */
+  /** The layers that contributed, with their opaque pixel counts after the ghost clean-up. */
   layers: Array<[string, number]>;
+  /** Present when `"back hair"` contributed (with `backHair !== false`, issue #351): the box without `"back hair"`. */
+  without_back_hair?: HeadBoxWithoutBackHair;
 }
 
 /**
@@ -90,7 +106,7 @@ function cleanedOpaque(pixels: { width: number; height: number; data: Uint8Clamp
  * `source.w` x `source.h` pixels. Every refusal names the value found and the
  * value required.
  */
-export function proposeHeadBox(full: LayerSet, source: { w: number; h: number }): HeadBoxProposal {
+export function proposeHeadBox(full: LayerSet, source: { w: number; h: number }, opts?: HeadBoxOptions): HeadBoxProposal {
   const problems: Problem[] = [];
   if (!(Number.isInteger(source.w) && Number.isInteger(source.h) && source.w > 0 && source.h > 0)) {
     problems.push({ code: 'HEADBOX_CANVAS_SIZE', object: '--canvas', detail: `is ${source.w}x${source.h}; the painting's size in positive integer pixels is required` });
@@ -102,12 +118,14 @@ export function proposeHeadBox(full: LayerSet, source: { w: number; h: number })
 
   const pad = squarePad(source.w, source.h);
   const k = pad.side / full.canvas.w;
+  const includeBackHair = opts?.backHair !== false;
   // The union does not depend on the order the layers are read in; a name
   // that appears twice is last-wins in draw order (the reference's dict was
   // last-wins in manifest order, and no wrapper output read so far repeats one).
   const boxes = new Map<string, { left: number; top: number; xs: number[]; ys: number[] }>();
   for (const L of full.layers) {
     if (!(HEAD_LAYERS as readonly string[]).includes(L.name)) continue;
+    if (!includeBackHair && L.name === 'back hair') continue;
     const { xs, ys } = cleanedOpaque(L.pixels);
     if (xs.length < HEAD_LAYER_MIN_PX) continue;
     boxes.set(L.name, { left: L.left, top: L.top, xs, ys });
@@ -130,44 +148,60 @@ export function proposeHeadBox(full: LayerSet, source: { w: number; h: number })
     if (f.top + y > fy1) fy1 = f.top + y;
   }
   const cut = fy1 + 0.35 * (fy1 - fy0);
-  let x0 = Infinity;
-  let x1 = -Infinity;
-  let y0 = Infinity;
-  let y1 = -Infinity;
-  for (const b of boxes.values()) {
-    for (let i = 0; i < b.xs.length; i++) {
-      const y = b.top + b.ys[i];
-      if (y > cut) continue;
-      const x = b.left + b.xs[i];
-      if (x < x0) x0 = x;
-      if (x > x1) x1 = x;
-      if (y < y0) y0 = y;
-      if (y > y1) y1 = y;
+  const measureUnion = (entries: Iterable<{ left: number; top: number; xs: number[]; ys: number[] }>): { edge: number; unclamped: Box; shift: [number, number]; head_box: Box | null } => {
+    let x0 = Infinity;
+    let x1 = -Infinity;
+    let y0 = Infinity;
+    let y1 = -Infinity;
+    for (const b of entries) {
+      for (let i = 0; i < b.xs.length; i++) {
+        const y = b.top + b.ys[i];
+        if (y > cut) continue;
+        const x = b.left + b.xs[i];
+        if (x < x0) x0 = x;
+        if (x > x1) x1 = x;
+        if (y < y0) y0 = y;
+        if (y > y1) y1 = y;
+      }
     }
-  }
-  const size = Math.max(x1 - x0, y1 - y0) * 1.12;
-  const cx = (x0 + x1) / 2;
-  const cy = (y0 + y1) / 2;
-  // Each edge rounded as the reference rounds it; then the side is the larger
-  // of the two rounded extents, so the box is square, never holds less than
-  // the reference's, and equals it wherever the reference's was square.
-  const ex = [pyRound((cx - size / 2) * k), pyRound((cx + size / 2) * k)];
-  const ey = [pyRound((cy - size / 2) * k), pyRound((cy + size / 2) * k)];
-  const edge = Math.max(ex[1] - ex[0], ey[1] - ey[0]);
-  const bx = ex[0] - pad.left;
-  const by = ey[0] - pad.top;
-  const unclamped: Box = [bx, by, bx + edge, by + edge];
-  if (edge > source.w || edge > source.h) {
+    const size = Math.max(x1 - x0, y1 - y0) * 1.12;
+    const cx = (x0 + x1) / 2;
+    const cy = (y0 + y1) / 2;
+    // Each edge rounded as the reference rounds it; then the side is the larger
+    // of the two rounded extents, so the box is square, never holds less than
+    // the reference's, and equals it wherever the reference's was square.
+    const ex = [pyRound((cx - size / 2) * k), pyRound((cx + size / 2) * k)];
+    const ey = [pyRound((cy - size / 2) * k), pyRound((cy + size / 2) * k)];
+    const edge = Math.max(ex[1] - ex[0], ey[1] - ey[0]);
+    const bx = ex[0] - pad.left;
+    const by = ey[0] - pad.top;
+    const unclamped: Box = [bx, by, bx + edge, by + edge];
+    if (edge > source.w || edge > source.h) return { edge, unclamped, shift: [0, 0], head_box: null };
+    const hold = (lo: number, extent: number): number => (lo < 0 ? -lo : lo + edge > extent ? extent - edge - lo : 0);
+    const shift: [number, number] = [hold(bx, source.w), hold(by, source.h)];
+    const head_box: Box = [bx + shift[0], by + shift[1], bx + shift[0] + edge, by + shift[1] + edge];
+    return { edge, unclamped, shift, head_box };
+  };
+  const main = measureUnion(boxes.values());
+  const without = includeBackHair && boxes.has('back hair') ? measureUnion([...boxes.entries()].filter(([n]) => n !== 'back hair').map(([, b]) => b)) : null;
+  if (main.head_box === null) {
+    const hairNote =
+      without !== null && without.edge < main.edge
+        ? ` ("back hair" grew the side from ${without.edge} to ${main.edge} px; without it${without.head_box !== null ? `, [${without.head_box.join(', ')}] (${without.edge}x${without.edge}) fits —` : ''} pass --no-back-hair)`
+        : '';
     refuseIfAny([
       {
         code: 'HEADBOX_FITS_CANVAS',
         object: 'head box',
-        detail: `is ${edge}x${edge} source px, proposed at [${unclamped.join(', ')}]; the ${source.w}x${source.h} painting cannot hold it at that size, and shrinking it would cut the head`,
+        detail: `is ${main.edge}x${main.edge} source px, proposed at [${main.unclamped.join(', ')}]; the ${source.w}x${source.h} painting cannot hold it at that size, and shrinking it would cut the head${hairNote}`,
       },
     ]);
   }
-  const hold = (lo: number, extent: number): number => (lo < 0 ? -lo : lo + edge > extent ? extent - edge - lo : 0);
-  const shift: [number, number] = [hold(bx, source.w), hold(by, source.h)];
-  const head_box: Box = [bx + shift[0], by + shift[1], bx + shift[0] + edge, by + shift[1] + edge];
-  return { head_box, unclamped, shift, layers: [...boxes.entries()].map(([n, b]) => [n, b.xs.length]) };
+  return {
+    head_box: main.head_box as Box,
+    unclamped: main.unclamped,
+    shift: main.shift,
+    layers: [...boxes.entries()].map(([n, b]) => [n, b.xs.length]),
+    ...(without === null ? {} : { without_back_hair: { edge: without.edge, unclamped: without.unclamped, head_box: without.head_box } }),
+  };
 }

package/src/limbs.ts

@@ -81,6 +81,17 @@
  *   cap's disc and the limb's width stay where the bone's origin puts them;
  *   only the line that splits the pixels between the two pieces moves, and
  *   the cap takes the disc's pixels on the upper side of that line.
+ * - **Overlapping hands** (issue #400, {@link assignOverlappingHands}). When
+ *   two forearm segments (`joint: "elbow"`, with a wrist end) share a part,
+ *   each hand's keypoint region is the disc of radius half its forearm's
+ *   length (`L / 2`) about its wrist, and its cuff is the line across the
+ *   forearm at `L - L / 2 = L / 2` from the elbow, where that disc meets the
+ *   bone's axis. When the two hand discs overlap, the overlapping hand region
+ *   goes to the front piece (the limb `config.limbs` declares later, which
+ *   `limbOrder` draws in front) in one piece, and the back piece ends at its
+ *   cuff; any 4-connected island on a forearm piece that leaves its own hand's
+ *   keypoint region is transferred to the other forearm piece, so no slivers
+ *   are cut out of the front hand for the back arm.
  */
 import type { BoneEntry, Limb } from './config.ts';
 
@@ -429,3 +440,163 @@ export function capBox(at: Pt, radius: number): [number, number, number, number]
 export function inDisc(at: Pt, radius: number, px: number, py: number): boolean {
   return (px + 0.5 - at[0]) ** 2 + (py + 0.5 - at[1]) ** 2 <= radius * radius;
 }
+
+/** A forearm segment on a shared part, for {@link assignOverlappingHands} (issue #400). */
+export interface ForearmShare {
+  /** The limb's index in `Object.keys(limbs)`. */
+  limb: number;
+  /** The forearm segment's index in `limbs[limb].segments`. */
+  seg: number;
+  /** The elbow bone origin, in rig px. */
+  elbow: Pt;
+  /** The wrist bone end (`tip`), in rig px. */
+  wrist: Pt;
+  /** Whether pixel `(x, y)` on `limb` falls on this forearm segment (`segmentOf === seg`). */
+  isSeg: (x: number, y: number) => boolean;
+}
+
+/**
+ * Issue #400: when two forearm segments (`back` and `front`, in `config.limbs`
+ * order so `front` is drawn over `back`) share a part, each hand's keypoint
+ * region is the disc of radius `r = L / 2` about its wrist (`L` the forearm
+ * bone's length), and `back`'s cuff is the line across the forearm at
+ * `L - r = L / 2` from `back.elbow`. When the two wrist discs overlap, `back`'s
+ * pixels past its cuff (or inside `front`'s hand disc) go to `front`'s forearm
+ * in one piece so `back` ends at its cuff; and any 4-connected island on a
+ * forearm piece that leaves its own hand's keypoint region goes to the other
+ * forearm piece. Mutates `own` and `segOverride` in place.
+ */
+export function assignOverlappingHands(back: ForearmShare, front: ForearmShare, W: number, H: number, own: Int32Array, segOverride: Int32Array): void {
+  const dx0 = back.wrist[0] - back.elbow[0];
+  const dy0 = back.wrist[1] - back.elbow[1];
+  const L0 = Math.sqrt(dx0 * dx0 + dy0 * dy0);
+  const dx1 = front.wrist[0] - front.elbow[0];
+  const dy1 = front.wrist[1] - front.elbow[1];
+  const L1 = Math.sqrt(dx1 * dx1 + dy1 * dy1);
+  if (L0 === 0 || L1 === 0) return;
+  const r0 = L0 / 2;
+  const r1 = L1 / 2;
+  const u0x = dx0 / L0;
+  const u0y = dy0 / L0;
+  const cuff0 = L0 - r0;
+  const proj0 = (x: number, y: number): number => (x + 0.5 - back.elbow[0]) * u0x + (y + 0.5 - back.elbow[1]) * u0y;
+  const onSeg = (f: ForearmShare, p: number): boolean => own[p] === f.limb && (segOverride[p] === f.seg || (segOverride[p] === -1 && f.isSeg(p % W, Math.floor(p / W))));
+  const wristsOverlap = (back.wrist[0] - front.wrist[0]) ** 2 + (back.wrist[1] - front.wrist[1]) ** 2 <= (r0 + r1) ** 2;
+  if (wristsOverlap) {
+    let cuffHasArt = false;
+    for (let y = 0; y < H && !cuffHasArt; y++) {
+      for (let x = 0; x < W && !cuffHasArt; x++) {
+        if (onSeg(back, y * W + x) && proj0(x, y) <= cuff0) cuffHasArt = true;
+      }
+    }
+    if (cuffHasArt) {
+      for (let y = 0; y < H; y++) {
+        for (let x = 0; x < W; x++) {
+          const p = y * W + x;
+          if (onSeg(back, p) && (proj0(x, y) > cuff0 || inDisc(front.wrist, r1, x, y)) && !inDisc(back.elbow, r0 / 2, x, y)) {
+            own[p] = front.limb;
+            segOverride[p] = front.seg;
+          } else if (own[p] === back.limb && inDisc(front.wrist, r1, x, y) && !inDisc(back.elbow, r0, x, y)) {
+            own[p] = front.limb;
+            segOverride[p] = front.seg;
+          }
+        }
+      }
+    }
+  }
+  const componentsOf = (f: ForearmShare): number[][] => {
+    const seen = new Uint8Array(W * H);
+    const comps: number[][] = [];
+    for (let p = 0; p < W * H; p++) {
+      if (seen[p] === 1 || !onSeg(f, p)) continue;
+      seen[p] = 1;
+      const comp: number[] = [p];
+      for (let h = 0; h < comp.length; h++) {
+        const q = comp[h];
+        const x = q % W;
+        const y = (q - x) / W;
+        for (const [nx, ny] of [
+          [x - 1, y],
+          [x + 1, y],
+          [x, y - 1],
+          [x, y + 1],
+        ]) {
+          if (nx < 0 || ny < 0 || nx >= W || ny >= H) continue;
+          const np = ny * W + nx;
+          if (seen[np] === 0 && onSeg(f, np)) {
+            seen[np] = 1;
+            comp.push(np);
+          }
+        }
+      }
+      comps.push(comp);
+    }
+    return comps;
+  };
+  const elbowDist2 = (comp: readonly number[], elbow: Pt): number => {
+    let best = Infinity;
+    for (const p of comp) {
+      const x = p % W;
+      const y = (p - x) / W;
+      const d = (x + 0.5 - elbow[0]) ** 2 + (y + 0.5 - elbow[1]) ** 2;
+      if (d < best) best = d;
+    }
+    return best;
+  };
+  const backComps = componentsOf(back);
+  if (backComps.length > 1) {
+    let main = 0;
+    let mainD = elbowDist2(backComps[0], back.elbow);
+    for (let i = 1; i < backComps.length; i++) {
+      const d = elbowDist2(backComps[i], back.elbow);
+      if (d < mainD) {
+        mainD = d;
+        main = i;
+      }
+    }
+    backComps.forEach((comp, i) => {
+      if (i === main) return;
+      const leavesBack = comp.some((p) => !inDisc(back.wrist, r0, p % W, Math.floor(p / W)));
+      const inFront = comp.some((p) => inDisc(front.wrist, r1, p % W, Math.floor(p / W)));
+      if (wristsOverlap || leavesBack || inFront) {
+        for (const p of comp) {
+          own[p] = front.limb;
+          segOverride[p] = front.seg;
+        }
+      }
+    });
+  }
+  const frontComps = componentsOf(front);
+  if (frontComps.length > 1) {
+    let main = 0;
+    let mainD = elbowDist2(frontComps[0], front.elbow);
+    for (let i = 1; i < frontComps.length; i++) {
+      const d = elbowDist2(frontComps[i], front.elbow);
+      if (d < mainD) {
+        mainD = d;
+        main = i;
+      }
+    }
+    frontComps.forEach((comp, i) => {
+      if (i === main) return;
+      const leavesFront = comp.some((p) => !inDisc(front.wrist, r1, p % W, Math.floor(p / W)));
+      const touchesBack = comp.some((p) => {
+        const x = p % W;
+        const y = (p - x) / W;
+        return (
+          (x > 0 && onSeg(back, p - 1)) ||
+          (x + 1 < W && onSeg(back, p + 1)) ||
+          (y > 0 && onSeg(back, p - W)) ||
+          (y + 1 < H && onSeg(back, p + W))
+        );
+      });
+      if (leavesFront && touchesBack) {
+        for (const p of comp) {
+          own[p] = back.limb;
+          segOverride[p] = back.seg;
+        }
+      }
+    });
+  }
+}
+