@rig-c/parts 1.24.0 → 1.26.0

package/src/propose.ts

@@ -21,7 +21,10 @@
  *   hip would sit above `HIP_MIN_FRACTION` of the figure's height (a long
  *   robe tagged `bottomwear` starts at the collar): then `hip` is the waist,
  *   the narrowest torso row between the shoulder line and the figure's
- *   middle, and 0.32 of the figure height when no row narrows enough.
+ *   middle, and 0.32 of the figure height when no row narrows enough. With
+ *   `cloth.bottomwear.part` naming a dress (issue #402), a `bottomwear` part
+ *   lying on the dress's tree links rides them (issue #416), by the rule a
+ *   layer on a tail does (below), and gets no trees of its own.
  * - `topwear` -> two outer-robe chains, only when it hangs below the hip line;
  *   a side whose link falls off the art is dropped.
  * - `handwear-*` -> two blobs: one sleeve chain per blob, its mesh taking that
@@ -143,8 +146,9 @@ import { configRoles, type RoleOf } from './structure.ts';
 import { AUTHOR_NO_ROLE, isAuthorTag } from './tags.ts';
 import { TURN_BONE, TURN_CARRIER_TAG, TURN_PLACES, TURN_RIDER_OFFSET, TURN_RIDER_TAGS, turnFractions, turnNearest, turnPivot, turnRiderDepth, type TurnSpec } from './turn.ts';
 import { edgeLength } from './length.ts';
-import { chainSqueezes, type SqueezeFinding } from './squeeze.ts';
-import { RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, swingName, type Tail, tailOverlap, type TailSpan, treeConstraints, type TreeChain, type TreeInput } from './cloth.ts';
+import { limbWidth } from './limbs.ts';
+import { type BranchSqueezeFinding, branchSqueezes, chainSqueezes, type SqueezeFinding } from './squeeze.ts';
+import { RECIPE_BACK_HAIR_CHAINS, RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, swingName, type Tail, tailOverlap, type TailOverlap, type TailSpan, treeConstraints, type TreeChain, type TreeInput } from './cloth.ts';
 import { TEXTURE_STRETCH_CEILING } from './check.ts';
 
 // ---------------------------------------------------------------------------
@@ -274,20 +278,23 @@ export interface Proposal {
   constraints?: ConfigConstraint[];
   /** Only with `propose --full`/`--head` (issue #251, {@link draftTurn}); absent otherwise, so a proposal without them is the one written before it. */
   turn?: TurnSpec;
+  /** The `assemble.rig_scale` (`parts.json`'s `scale_rig_per_source`) its coordinates were drafted at (issue #354). */
+  proposed_rig_scale: number;
   notes: string[];
 }
 
 /**
  * Every section of a proposal that is a config section, in the order the
  * proposal writes them: what an author copies into the config (issue #375).
- * `notes` is the proposal's own and is copied nowhere. Two of them are written
- * only on request — `limbs` under `--keypoints`, `turn` under `--full`/`--head`
- * — and a `limbs` block left behind is refused at the next step, by the name of
- * every part it cuts. {@link checkProposal} reads the proposal through the config
- * loader by this list, the type below refuses a {@link Proposal} key it does not
- * hold, and the selftest's `TY18` holds every paste sentence in the documents to it.
+ * `notes` is the proposal's own and is copied nowhere. Three of them are written
+ * only on request — `limbs` under `--keypoints`, `constraints` under `--cloth`,
+ * `turn` under `--full`/`--head` — and a `limbs` block left behind is refused
+ * at the next step, by the name of every part it cuts. {@link checkProposal} reads
+ * the proposal through the config loader by this list, the type below refuses a
+ * {@link Proposal} key it does not hold, and the selftest's `TY18` holds every
+ * paste sentence in the documents to it.
  */
-export const PROPOSAL_CONFIG_SECTIONS = ['bones', 'meshes', 'regions', 'limbs', 'motion', 'constraints', 'turn'] as const satisfies ReadonlyArray<Exclude<keyof Proposal, 'notes'>>;
+export const PROPOSAL_CONFIG_SECTIONS = ['bones', 'meshes', 'regions', 'limbs', 'motion', 'constraints', 'turn', 'proposed_rig_scale'] as const satisfies ReadonlyArray<Exclude<keyof Proposal, 'notes'>>;
 
 /** A {@link Proposal} key that is neither `notes` nor in {@link PROPOSAL_CONFIG_SECTIONS}; `never` while the list is whole. */
 type UnlistedProposalSection = Exclude<keyof Proposal, 'notes' | (typeof PROPOSAL_CONFIG_SECTIONS)[number]>;
@@ -410,7 +417,7 @@ export function proposalAssemble(P: PartSet): Record<string, unknown> {
   const planned = run.filter((r) => r.cut_from === undefined && firstOf.get(r.from) === r.name);
   const pieces = run.filter((r) => r.cut_from !== undefined || firstOf.get(r.from) !== r.name);
   return {
-    rig_scale: 1,
+    rig_scale: P.rigScale,
     plan: planned.map((r) => [r.name, ...splitFrom(r.from)]),
     patches: painted.map((r) => ({ name: r.name, box: [r.x, r.y, r.x + r.w, r.y + r.h], alpha: 'box', draw: 'front' })),
     ...(pieces.length === 0
@@ -607,7 +614,7 @@ export function withTurn(p: Proposal, draft: { turn: TurnSpec | null; notes: str
     }
     turn = { pivot: turn.pivot, depths };
   }
-  return { bones: p.bones, meshes: p.meshes, regions: p.regions, ...(p.limbs === undefined ? {} : { limbs: p.limbs }), motion: p.motion, ...(p.constraints === undefined ? {} : { constraints: p.constraints }), ...(turn === null ? {} : { turn }), notes: [...p.notes, ...draft.notes] };
+  return { bones: p.bones, meshes: p.meshes, regions: p.regions, ...(p.limbs === undefined ? {} : { limbs: p.limbs }), motion: p.motion, ...(p.constraints === undefined ? {} : { constraints: p.constraints }), ...(turn === null ? {} : { turn }), proposed_rig_scale: p.proposed_rig_scale, notes: [...p.notes, ...draft.notes] };
 }
 
 // ---------------------------------------------------------------------------
@@ -618,12 +625,14 @@ export function withTurn(p: Proposal, draft: { turn: TurnSpec | null; notes: str
 export class PartSet {
   readonly W: number;
   readonly H: number;
+  readonly rigScale: number;
   readonly recs: readonly PartRecord[];
   readonly images: ReadonlyMap<string, Raster>;
   private readonly masks = new Map<string, Mask>();
 
   constructor(file: PartsFile, images: ReadonlyMap<string, Raster>) {
     [this.W, this.H] = file.rig_size;
+    this.rigScale = file.scale_rig_per_source;
     this.recs = file.parts;
     this.images = images;
   }
@@ -1373,7 +1382,7 @@ export function proposeWithBasis(
   const tails: Tail[] = [];
   const T = (p: PartRecord, tag: ClothTarget, r: ClothRecipe, input: TreeInput): TreeChain[] => {
     const trees = draftTrees(input, r);
-    const constants = [konst('cloth_chains', r.chains), konst('cloth_links', r.links), konst('length_ratio', roundTo(r.length_ratio ?? RECIPE_LENGTH_RATIO, 6))];
+    const constants = [konst('cloth_chains', r.chains ?? RECIPE_BACK_HAIR_CHAINS), konst('cloth_links', r.links), konst('length_ratio', roundTo(r.length_ratio ?? RECIPE_LENGTH_RATIO, 6))];
     for (const t of trees) {
       C(
         t.chain,
@@ -1530,13 +1539,69 @@ export function proposeWithBasis(
     } else if (recipeOf('back hair') !== null) {
       // Issue #364: the recipe's trees, per side of the eye axis (twin tails are a side each), from the eye line to
       // 4 px above the part's bottom, in place of the two keyed chains.
-      const rcp = recipeOf('back hair') as ClothRecipe;
+      // Issue #390: the tree count per side derives from the tail's opaque width at the root row (`floor(width / grid)`
+      // on each side, and every tree root inside the 15 px dilated art); a declared count that does not fit is refused
+      // by name (`PROPOSE_CLOTH_BACK_HAIR_CHAINS`).
+      const rawRcp = recipeOf('back hair') as ClothRecipe;
       const mask = P.alpha(p);
+      const dilated = dilate(mask, 31);
+      const y0 = pyRound(eyeY);
+      const sideOpaqueWidth = (s: 'r' | 'l'): number => {
+        if (y0 < 0 || y0 >= mask.height) return 0;
+        let w = 0;
+        for (let x = 0; x < mask.width; x++) {
+          if ((s === 'r' ? x < axis : x >= axis) && mask.data[y0 * mask.width + x]) w++;
+        }
+        return w;
+      };
+      const prefixOf = (s: 'r' | 'l'): string => (P.headFirst('back hair').length === 1 ? `hairback_${s}` : `hairback_${p.name}_${s}`);
+      const offRootsAt = (cnt: number, s: 'r' | 'l'): Array<{ bone: string; at: Point; alpha: number }> => {
+        const pref = prefixOf(s);
+        const im = P.images.get(p.name) as Raster;
+        const off: Array<{ bone: string; at: Point; alpha: number }> = [];
+        for (let k = 0; k < cnt; k++) {
+          const fc = (k + 0.5) / cnt;
+          const rx = pyRound(bandX(mask, eyeY, { frac: fc, side: s, axis }) ?? axis);
+          if (!isOn(dilated, rx, y0)) {
+            const lx = rx - p.x;
+            const ly = y0 - p.y;
+            const alpha = lx >= 0 && lx < p.w && ly >= 0 && ly < p.h ? im.data[(ly * p.w + lx) * 4 + 3] : 0;
+            off.push({ bone: `${pref}${k}_0`, at: [rx, y0], alpha });
+          }
+        }
+        return off;
+      };
+      const wR = sideOpaqueWidth('r');
+      const wL = sideOpaqueWidth('l');
+      const widthCap = Math.max(1, Math.min(Math.floor(wR / g), Math.floor(wL / g)));
+      let maxFit = 1;
+      for (let cnt = widthCap; cnt >= 1; cnt--) {
+        if (offRootsAt(cnt, 'r').length === 0 && offRootsAt(cnt, 'l').length === 0) {
+          maxFit = cnt;
+          break;
+        }
+      }
+      if (rawRcp.chains !== undefined) {
+        const offRoots = [...offRootsAt(rawRcp.chains, 'r'), ...offRootsAt(rawRcp.chains, 'l')];
+        if (rawRcp.chains > widthCap || offRoots.length > 0) {
+          throw new PartsError([
+            {
+              code: 'PROPOSE_CLOTH_BACK_HAIR_CHAINS',
+              object: 'config.cloth."back hair".chains',
+              detail:
+                `declares ${rawRcp.chains} tree(s) per side on "${p.name}", and at the root row y=${y0} the tail is ${wR} px wide on the r side and ${wL} px on the l side on a ${g} px mesh grid (at most ${maxFit} tree(s) per side fit inside the art` +
+                (offRoots.length > 0 ? `; off the art: ${offRoots.map((o) => `${o.bone} at [${o.at[0]}, ${o.at[1]}] (alpha ${o.alpha})`).join(', ')}` : '') +
+                `) — set chains to at most ${maxFit}, or leave chains out to derive it from the tail's width`,
+            },
+          ]);
+        }
+      }
+      const rcp: ClothRecipe = { ...rawRcp, chains: rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit) };
       const segs: Segment[] = [['head', rnd(head), rnd([axis, top + 13])]];
       const all: TreeChain[] = [];
       let n = 0;
       for (const [side] of SIDES) {
-        const prefix = P.headFirst('back hair').length === 1 ? `hairback_${side}` : `hairback_${p.name}_${side}`;
+        const prefix = prefixOf(side);
         const trees = T(p, 'back hair', rcp, {
           prefix,
           parent: 'head',
@@ -1554,7 +1619,7 @@ export function proposeWithBasis(
         all.push(...trees);
       }
       notes.push(clothNote(p.name, 'back hair', all, rcp, n, ' per side of the eye axis, from head, rooted on the eye line and tipped 4 px above its bottom'));
-      meshes[p.name] = { grid: g, r, segments: segs };
+      meshes[p.name] = { grid: g, r: rcp.split?.hold_tip === true ? Math.max(r, g) : r, segments: segs };
       // Issue #391: the spans are this mesh's segments, the head's fixed one and every tree link, in segment order.
       const spans: TailSpan[] = [{ bone: 'head', a: rnd(head), b: rnd([axis, top + 13]), link: false }];
       for (const t of all) {
@@ -1728,7 +1793,8 @@ export function proposeWithBasis(
       tracks.push({ chain: name, amps: [0.8, 1.6, 2.6, 3.6], period: 4.0, phase: 0.16, lag: 0.07 });
       k++;
     }
-    meshes[p.name] = { grid: g, r, segments: segs };
+    const frontRcp = recipeOf('front hair');
+    meshes[p.name] = { grid: g, r: frontRcp?.split?.hold_tip === true && k > 0 ? Math.max(r, g) : r, segments: segs };
   }
 
   // ---- accessories: rigid body + pendant chain where the part narrows, or one pendulum chain per hanging strand
@@ -2114,9 +2180,10 @@ export function proposeWithBasis(
       throw new PartsError([{ code: 'PROPOSE_CLOTH_PART', object: 'config.cloth."bottomwear".part', detail }]);
     };
     const q = P.recs.find((x) => x.name === name);
-    if (q === undefined) return refuse(`names "${name}", which is no part in parts.json; a topwear part whose art hangs below the hip (a dress) is required`);
-    if (q.cut_from !== undefined) return refuse(`names "${name}", a piece an assemble.cuts entry took from ${q.cut_from}; name the part the plan made, ${q.cut_from}, or leave part out`);
-    if (!tw.includes(q)) {
+    if (q === undefined) return refuse(`names "${name}", which is no part in parts.json; a topwear part or its cut skirt piece whose art hangs below the hip (a dress) is required`);
+    // An explicit name may select a topwear cut piece; automatic tag rules still exclude pieces.
+    const [run, tag] = splitFrom(q.from);
+    if (run === PAINTING_RUN || tag !== 'topwear') {
       return refuse(
         `names "${name}", from ${q.from}; ${splitFrom(q.from)[1] === 'bottomwear' ? 'a bottomwear part takes the recipe by its tag already — leave part out' : "only a topwear part takes the skirt's recipe by name (a skirt See-through returned inside topwear, a dress)"}`,
       );
@@ -2156,8 +2223,8 @@ export function proposeWithBasis(
             ['chest', rnd(along(hip, trunk.u, artExtent(mask, p, hip, trunk.u)[0])), rnd(along(hip, trunk.u, -20))],
             ['hip', rnd(along(hip, trunk.u, -20)), rnd(along(hip, trunk.u, 100))],
           ];
-    if (bw.length > 0 && bot < hip[1] + TOPWEAR_HANGS_FACE_HEIGHTS * fh) {
-      // A bodice that stops at the waist: robe chains down to the hem would fall off the art.
+    if ((bw.length > 0 || namedSkirt?.cut_from === p.name) && bot < hip[1] + TOPWEAR_HANGS_FACE_HEIGHTS * fh) {
+      // A bodice above bottomwear, including its explicitly named cut skirt: robe chains would fall off the art.
       meshes[p.name] = { grid: g, r, segments: segs };
       notes.push(`${p.name} ends at y=${bot} (hip ${pyFixed(hip[1], 0)}): no robe chains -- add a sash chain by hand if one hangs`);
       continue;
@@ -2204,12 +2271,8 @@ export function proposeWithBasis(
   }
 
   // ---- skirt (bottomwear, and the topwear part config.cloth.bottomwear.part names: issue #402)
-  const skirts = namedSkirt === null ? bw : [...bw, namedSkirt];
-  for (const p of skirts) {
-    const [g, r] = gridR(p);
-    const mask = P.alpha(p);
-    const bot = p.y + p.h;
-    const y0 = hip[1] + 20;
+  // The fixed segments of a skirt's mesh, and the note when it hangs from the waist (pushed by the drafting loop only).
+  const skirtFrame = (p: PartRecord, mask: Mask): { segs: Segment[]; hangs: string | null } => {
     let segs: Segment[] = [
       ['chest', rnd([chest[0], chest[1] - 30]), rnd([chest[0], hip[1] - 20])],
       ['hip', rnd([p.x + 0.09 * p.w, hip[1] + 5]), rnd([p.x + 0.91 * p.w, hip[1] + 5])],
@@ -2231,26 +2294,67 @@ export function proposeWithBasis(
     const down: readonly [number, number] = trunk === null ? [0, 1] : trunk.u;
     const artTop = artExtent(mask, p, hip, down)[0];
     const chestAt = (chest[0] - hip[0]) * down[0] + (chest[1] - hip[1]) * down[1];
-    if (artTop >= chestAt) {
-      segs = segs.filter((s) => typeof s === 'string' || s[0] !== 'chest');
-      notes.push(
-        `${p.name} (${p.from}): its art starts ${pyFixed(artTop - chestAt, 1)} px below chest's origin, so it hangs from the waist — its mesh takes the hip line and its skirt chains, no chest segment, and the breath does not carry its root`,
-      );
+    if (artTop < chestAt) return { segs, hangs: null };
+    return {
+      segs: segs.filter((s) => typeof s === 'string' || s[0] !== 'chest'),
+      hangs: `${p.name} (${p.from}): its art starts ${pyFixed(artTop - chestAt, 1)} px below chest's origin, so it hangs from the waist — its mesh takes the hip line and its skirt chains, no chest segment, and the breath does not carry its root`,
+    };
+  };
+  // Where the recipe's trees hang on a skirt: from 20 px below the hip to 4 px above the part's bottom, across its art.
+  const skirtInput = (p: PartRecord, mask: Mask, prefix: string): TreeInput => ({
+    prefix,
+    parent: 'hip',
+    rootY: hip[1] + 20,
+    tipY: p.y + p.h - 4,
+    xAt: (y, f) => bandX(mask, y, { frac: f }),
+    fallbackX: (f) => p.x + f * p.w,
+    frame: `${p.name}'s art (no art in the band: that share of its box's width)`,
+    edges: 'both',
+  });
+  // Issue #416: a bottomwear part lying on the trees of the dress config.cloth.bottomwear.part names (a ruffle hem
+  // See-through returned on its own) rides the links it overlaps, as a layer wrapped round a tail does (issue #391),
+  // and gets no trees of its own: one skirt carries one set of trees. The dress's mesh is the tail — its fixed
+  // segments and every tree link, in segment order — and the links are read off the overlap, never off the part's
+  // name. Which parts ride is read here, before any bone is named, off the trees as the recipe places them (a tree's
+  // points do not depend on its prefix); a part over no link keeps its own trees below. Only with the field.
+  const dressTail = (p: PartRecord, segs: readonly Segment[], trees: readonly TreeChain[]): Tail => {
+    const spans: TailSpan[] = [];
+    for (const s of segs) if (typeof s !== 'string') spans.push({ bone: s[0], a: s[1], b: s[2], link: false });
+    for (const t of trees) {
+      const line = [...t.points, t.tip];
+      t.points.forEach((q, i) => spans.push({ bone: `${t.chain}${i}`, a: q, b: line[i + 1], link: true }));
     }
+    return { part: p.name, mask: P.alpha(p), spans };
+  };
+  const overLinks = (tail: Tail, q: PartRecord): { o: TailOverlap; rides: boolean } => {
+    const o = tailOverlap(tail, P.alpha(q), q);
+    return { o, rides: tail.spans.some((sp, k) => sp.link && o.counts[k] > 0) };
+  };
+  const dressRecipe = recipeOf('bottomwear');
+  const riders: PartRecord[] =
+    namedSkirt === null || dressRecipe === null
+      ? []
+      : ((): PartRecord[] => {
+          const mask = P.alpha(namedSkirt);
+          const tail = dressTail(namedSkirt, skirtFrame(namedSkirt, mask).segs, draftTrees(skirtInput(namedSkirt, mask, 'skirt'), dressRecipe));
+          return bw.filter((q) => overLinks(tail, q).rides);
+        })();
+  let dressDrafted: Tail | null = null;
+  const skirts = namedSkirt === null ? bw : [...bw.filter((q) => !riders.includes(q)), namedSkirt];
+  for (const p of skirts) {
+    const [g, r] = gridR(p);
+    const mask = P.alpha(p);
+    const bot = p.y + p.h;
+    const y0 = hip[1] + 20;
+    const { segs, hangs } = skirtFrame(p, mask);
+    if (hangs !== null) notes.push(hangs);
     // Issue #364: with config.cloth.bottomwear, the recipe's trees hang from the hip in place of the three keyed chains.
     const skirtRecipe = recipeOf('bottomwear');
     if (skirtRecipe !== null) {
       const prefix = skirts.length === 1 ? 'skirt' : `skirt_${p.name}`;
-      const trees = T(p, 'bottomwear', skirtRecipe, {
-        prefix,
-        parent: 'hip',
-        rootY: y0,
-        tipY: bot - 4,
-        xAt: (y, f) => bandX(mask, y, { frac: f }),
-        fallbackX: (f) => p.x + f * p.w,
-        frame: `${p.name}'s art (no art in the band: that share of its box's width)`,
-        edges: 'both',
-      });
+      const fixed = [...segs];
+      const trees = T(p, 'bottomwear', skirtRecipe, skirtInput(p, mask, prefix));
+      if (p === namedSkirt) dressDrafted = dressTail(p, fixed, trees);
       for (const t of trees) segs.push(t.chain);
       let swing: { bone: string; rest: number } | null = null;
       if (skirtRecipe.swing !== undefined) {
@@ -2283,7 +2387,7 @@ export function proposeWithBasis(
           p === namedSkirt ? p.from : undefined,
         ),
       );
-      meshes[p.name] = { grid: g, r, segments: segs };
+      meshes[p.name] = { grid: g, r: skirtRecipe.split?.hold_tip === true ? Math.max(r, g) : r, segments: segs };
       continue;
     }
     for (const [tag, f, ph] of [
@@ -2308,6 +2412,28 @@ export function proposeWithBasis(
     }
     meshes[p.name] = { grid: g, r, segments: segs };
   }
+  // Issue #416: each rider's mesh takes the dress's spans its pixels over the dress's art fall nearest — a link by its
+  // bone, a fixed segment written out as the dress's mesh writes it — so every vertex weights by the rule the dress's
+  // own art does, and the note names each span with its pixel count.
+  for (const q of riders) {
+    const tail = dressDrafted as Tail | null;
+    if (tail === null) break;
+    const { o } = overLinks(tail, q);
+    const segments: Segment[] = [];
+    const links: string[] = [];
+    const on: string[] = [];
+    tail.spans.forEach((sp, k) => {
+      if (o.counts[k] === 0) return;
+      on.push(`${sp.link ? sp.bone : `${sp.bone}'s fixed segment`} ${o.counts[k]}`);
+      segments.push(sp.link ? sp.bone : [sp.bone, sp.a, sp.b]);
+      if (sp.link) links.push(sp.bone);
+    });
+    const [g, r] = gridR(q);
+    meshes[q.name] = { grid: g, r, segments };
+    notes.push(
+      `${q.name} (${q.from}): lies on the trees of ${tail.part}, which config.cloth."bottomwear".part names — ${o.over} of its ${o.total} px lie over ${tail.part}'s art, nearest its spans ${on.join(', ')} px — so its mesh's segments are those spans and it rides the links ${links.join(', ')} with the dress; no trees of its own are drafted for it, so the skirt carries one set (issue #416)`,
+    );
+  }
 
   // ---- legs (issue #241)
   // Only with joints: a legwear part whose art holds the ankle of a leg whose hip, knee and ankle are all given is
@@ -2451,7 +2577,7 @@ export function proposeWithBasis(
   }
   const constrained = clothConstraints.length === 0 ? {} : { constraints: clothConstraints };
   return {
-    proposal: { bones, meshes, regions, ...drafted, motion: blink === undefined ? { duration: IDLE_SECONDS, tracks: idleTracks } : { duration: IDLE_SECONDS, tracks: idleTracks, blink }, ...constrained, notes },
+    proposal: { bones, meshes, regions, ...drafted, motion: blink === undefined ? { duration: IDLE_SECONDS, tracks: idleTracks } : { duration: IDLE_SECONDS, tracks: idleTracks, blink }, ...constrained, proposed_rig_scale: P.rigScale, notes },
     basis: { frame, bones: records },
   };
 }
@@ -3243,7 +3369,45 @@ export interface ChainNotAdvancingFinding {
 /** Issue #314: two chains on one lattice whose own swing closes or opens an edge between them past check's TEXTURE_STRETCH bar (`src/squeeze.ts`). */
 export type SqueezeLintFinding = { kind: 'squeeze' } & SqueezeFinding;
 
-export type LintFinding = OffArtFinding | OffLockFinding | HipAboveChestFinding | HipTooHighFinding | ChestNotBetweenFinding | HipNotPastChestFinding | HipNearerNeckFinding | ChainNotAdvancingFinding | SqueezeLintFinding;
+/**
+ * Issue #400: a hand layer (`handwear-r` or `handwear-l`, un-cut) whose side's wrist keypoint is placed is held to at
+ * least this share of the other hand layer's opaque pixel count (`ceil(HAND_MIN_OF_OTHER * other.opaque_px)`), or, when
+ * the other side has no hand layer and the side's elbow and wrist keypoints are placed, to a square of the forearm's
+ * width (`ceil(width²)`). On issue #400's overlapping-hands decomposition, See-through put 1,923 px into `handwear_l`
+ * and 123 px of finger slivers into `handwear_r` (6.4 % of the other hand, below `ceil(0.25 * 1923) = 481` px); on two
+ * separate hands (`standing` 1,200 / 1,200, `seated` 816 / 816, `lying` 1,120 / 1,120) the two layers are equal.
+ */
+export const HAND_MIN_OF_OTHER = 0.25;
+
+/**
+ * Issue #400: a hand layer holding fewer opaque pixels than the bar derived from the other hand layer or from the
+ * forearm's width, while its side's wrist keypoint says a hand is there.
+ */
+export interface NearEmptyHandFinding {
+  kind: 'near-empty-hand';
+  part: string;
+  from: string;
+  side: 'r' | 'l';
+  wrist: KeypointName;
+  wristAt: [number, number];
+  opaquePx: number;
+  bar: number;
+  basis:
+    | { kind: 'other-hand'; otherPart: string; otherFrom: string; otherPx: number; share: number }
+    | { kind: 'forearm-width'; width: number };
+}
+
+export type LintFinding =
+  | OffArtFinding
+  | OffLockFinding
+  | HipAboveChestFinding
+  | HipTooHighFinding
+  | ChestNotBetweenFinding
+  | HipNotPastChestFinding
+  | HipNearerNeckFinding
+  | ChainNotAdvancingFinding
+  | SqueezeLintFinding
+  | NearEmptyHandFinding;
 
 /** Which rule set read the torso and the sleeve chains, under `--keypoints`. */
 export interface LintBasis {
@@ -3263,6 +3427,8 @@ export interface LintResult {
   missingTorsoBones: string[];
   /** Issue #314: the pairs of keyed chains on one mesh the squeeze check could not build a lattice for, and why. Empty when it read every pair or had none. */
   squeezeUnread: string[];
+  /** Issue #403: sibling branch pairs on a fork whose cell-boundary weights and spring strengths are unheld. */
+  branchSqueezes: BranchSqueezeFinding[];
   /** Present only under `--keypoints`: the rule set that read the torso and the chains. */
   basis?: LintBasis;
   /** One record per bone of the spec, in its bone order (chain links as `<chain><i>`): which checks read it, or why none did (issue #86). */
@@ -3470,9 +3636,68 @@ export function lint(
       }
     }
   }
+  // Issue #400: when a hand layer holds fewer opaque pixels than the bar derived from the other hand layer, or from the
+  // forearm's width when the other side has no hand layer, while the wrist keypoint says a hand is there.
+  if (joints !== undefined) {
+    const handOf = (s: 'r' | 'l'): PartRecord | null => {
+      const ps = P.byTag(`handwear-${s}`).filter((p) => p.limb === undefined);
+      return ps.length === 1 ? ps[0] : null;
+    };
+    for (const s of ['r', 'l'] as const) {
+      const wrist: KeypointName = `${s}_wrist`;
+      const wristAt = joints.joints[wrist].at;
+      const part = handOf(s);
+      if (wristAt === null || part === null) continue;
+      const other = handOf(s === 'r' ? 'l' : 'r');
+      if (other !== null) {
+        const bar = Math.ceil(HAND_MIN_OF_OTHER * other.opaque_px);
+        if (part.opaque_px < bar) {
+          findings.push({
+            kind: 'near-empty-hand',
+            part: part.name,
+            from: part.from,
+            side: s,
+            wrist,
+            wristAt: [wristAt[0], wristAt[1]],
+            opaquePx: part.opaque_px,
+            bar,
+            basis: { kind: 'other-hand', otherPart: other.name, otherFrom: other.from, otherPx: other.opaque_px, share: HAND_MIN_OF_OTHER },
+          });
+        }
+        continue;
+      }
+      const elAt = joints.joints[`${s}_elbow`].at;
+      if (elAt === null) continue;
+      const dx = wristAt[0] - elAt[0];
+      const dy = wristAt[1] - elAt[1];
+      const len = edgeLength(dx, dy);
+      if (len === 0) continue;
+      const armMasks = [...P.byTag('topwear'), part].map((p) => P.alpha(p));
+      const art = (x: number, y: number): boolean => x >= 0 && y >= 0 && x < P.W && y < P.H && armMasks.some((m) => m.data[y * P.W + x] === 1);
+      const mid: [number, number] = [(elAt[0] + wristAt[0]) / 2, (elAt[1] + wristAt[1]) / 2];
+      const axis: [number, number] = [dx / len, dy / len];
+      const w = limbWidth({ at: mid, axis }, art, [0, 0, P.W - 1, P.H - 1]) ?? limbWidth({ at: elAt, axis }, art, [0, 0, P.W - 1, P.H - 1]);
+      if (w === null) continue;
+      const bar = Math.ceil(w * w);
+      if (part.opaque_px < bar) {
+        findings.push({
+          kind: 'near-empty-hand',
+          part: part.name,
+          from: part.from,
+          side: s,
+          wrist,
+          wristAt: [wristAt[0], wristAt[1]],
+          opaquePx: part.opaque_px,
+          bar,
+          basis: { kind: 'forearm-width', width: w },
+        });
+      }
+    }
+  }
   // Issue #314: every pair of keyed chains a lattice mesh names, swung on the rig stage's own lattice and weights, held
   // to check's TEXTURE_STRETCH bar (src/squeeze.ts). Only with a motion: without one nothing swings.
-  const sq = chainSqueezes({ bones: spec.bones, meshes: spec.meshes, motion: spec.motion }, new Map(P.recs.filter((p) => P.images.has(p.name)).map((p) => [p.name, { x: p.x, y: p.y, image: P.images.get(p.name) as Raster }])));
+  const partImages = new Map(P.recs.filter((p) => P.images.has(p.name)).map((p) => [p.name, { x: p.x, y: p.y, image: P.images.get(p.name) as Raster }]));
+  const sq = chainSqueezes({ bones: spec.bones, meshes: spec.meshes, motion: spec.motion }, partImages);
   for (const { mesh, a, b } of sq.read) {
     for (const [c, other] of [[a, b], [b, a]]) {
       const e = spec.bones.find((x) => 'chain' in x && x.chain === c);
@@ -3481,10 +3706,11 @@ export function lint(
   }
   for (const f of sq.findings) findings.push({ kind: 'squeeze', ...f });
   const squeezeUnread = sq.unread;
+  const branchSq = branchSqueezes({ bones: spec.bones, meshes: spec.meshes, constraints: spec.constraints }, partImages);
   const coverage = lintCoverage(spec, byName, read, findings, unknownMeshes, basis);
   return basis === undefined
-    ? { findings, unknownMeshes, lockUnread, missingTorsoBones, squeezeUnread, coverage }
-    : { findings, unknownMeshes, lockUnread, missingTorsoBones, squeezeUnread, basis, coverage };
+    ? { findings, unknownMeshes, lockUnread, missingTorsoBones, squeezeUnread, branchSqueezes: branchSq, coverage }
+    : { findings, unknownMeshes, lockUnread, missingTorsoBones, squeezeUnread, branchSqueezes: branchSq, basis, coverage };
 }
 
 /** The bones a finding names: the off-art link; hip and chest for a relation between them; a chain's last link for its tip. */
@@ -3503,6 +3729,8 @@ function findingBones(f: LintFinding, bones: readonly BoneEntry[]): string[] {
       return ['chest'];
     case 'squeeze':
       return [...new Set(f.vertices.map((v) => v.weights[0]?.bone).filter((n): n is string => n !== undefined))];
+    case 'near-empty-hand':
+      return [];
     case 'chain-not-advancing': {
       if (!f.point.endsWith(' tip')) return [f.point];
       const chain = f.point.slice(0, -' tip'.length);
@@ -3670,6 +3898,13 @@ export function lintLine(f: LintFinding): string {
       return `LINT hip at ${pyIntList(f.hip)} is nearer the neck joint ${fmtAt(f.neck)} (${pyFixed(f.dNeck, 1)} px) than the midpoint of the hip joints ${fmtAt(f.hips)} (${pyFixed(f.dHips, 1)} px): a hip at the shoulders`;
     case 'squeeze':
       return squeezeLine(f);
+    case 'near-empty-hand': {
+      const why =
+        f.basis.kind === 'other-hand'
+          ? `${f.basis.share} of ${f.basis.otherPart} (${f.basis.otherFrom}), ${f.basis.otherPx} px`
+          : `forearm width ${pyFixed(f.basis.width, 1)} px squared`;
+      return `LINT ${f.part} (${f.from}) holds ${f.opaquePx} opaque px while ${f.wrist} at ${fmtAt(f.wristAt)} says a hand is there — below the bar of ${f.bar} px (${why}): the hands may overlap in the other layer and leave finger slivers here`;
+    }
     case 'chain-not-advancing':
       return `LINT ${f.point} at ${pyIntList(f.at)} does not advance from ${f.fromJoint} toward ${f.toJoint}: it falls ${pyFixed(f.t, 1)} px along that line and ${f.previous} ${pyFixed(f.tPrevious, 1)} px, and each must fall further than the one before`;
   }
@@ -3704,6 +3939,23 @@ function squeezeLine(f: SqueezeLintFinding): string {
   );
 }
 
+/**
+ * Issue #403: the note line naming a branch tip's squeezed triangle, the bones (`a` and `b` forked from `parent`),
+ * the mechanism (`the weights where two branches' cells meet` and, when present, unequal spring strength on the fork),
+ * and the setting (`split.hold_tip: true`) that holds the tip.
+ */
+export function branchSqueezeLine(f: BranchSqueezeFinding): string {
+  const stiff =
+    f.strengthA !== null && f.strengthB !== null && f.strengthA !== f.strengthB
+      ? ` and unequal spring strength on the fork (${f.a} ${f.strengthA} vs ${f.b} ${f.strengthB})`
+      : '';
+  return (
+    `LINT ${f.a} and ${f.b} (forked from ${f.parent}) on mesh ${pyRepr(f.mesh)} squeeze their tip: triangle ${f.triangle} across edge ${f.edge[0]}-${f.edge[1]} (tips ${pyFixed(f.tipGap, 1)} px apart) ` +
+    `is squeezed by the weights where two branches' cells meet (vertex ${f.edge[0]} rides ${f.a} ${pyFixed(f.weightA, 5)}, vertex ${f.edge[1]} rides ${f.b} ${pyFixed(f.weightB, 5)} at r=${f.r} on a ${f.grid} px lattice)${stiff} — ` +
+    `set split.hold_tip: true to hold the branch tips (keeps branch strength across the fork and raises r to grid)`
+  );
+}
+
 export interface Comparison {
   rows: Array<[string, number]>;
   onlyConfig: string[];