@rig-c/parts 1.24.0 → 1.25.0

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;
+        }
+      }
+    });
+  }
+}
+

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_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';
 
 // ---------------------------------------------------------------------------
@@ -1554,7 +1558,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 +1732,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
@@ -2204,12 +2209,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 +2232,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 +2325,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 +2350,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
@@ -3243,7 +3307,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 +3365,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 +3574,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 +3644,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 +3667,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 +3836,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 +3877,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[];