@rig-c/parts 1.23.0 → 1.25.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
@@ -43,7 +46,12 @@
  *   layer with hanging strands ({@link Strand}) gets one pendulum chain per
  *   strand instead of the single pendant chain, and one note naming every
  *   strand and what became of it — a strand left without a chain is never
- *   silent (issue #24).
+ *   silent (issue #24). Under the `back hair` cloth recipe (issue #391) a
+ *   layer of either tag lying on a drafted tail rides the links it overlaps
+ *   instead: its pixels over the tail's art are each given to the nearest span
+ *   of the back hair's mesh (`tailOverlap`, `src/cloth.ts`), and when one is a
+ *   link the part's mesh takes those spans as its segments and no rule above
+ *   runs for it; a note names each span with its pixel count.
  * - anything no rule claims rides its nearest trunk bone as a region —
  *   including every part from an author-made layer (`<run>:author:<label>`,
  *   issue #256), which is no See-through tag and so has no role: no rule
@@ -138,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, 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';
 
 // ---------------------------------------------------------------------------
@@ -1364,6 +1373,8 @@ export function proposeWithBasis(
   const clothConstraints: ConfigConstraint[] = [];
   const clothUsed = new Set<ClothTarget>();
   const recipeOf = (tag: ClothTarget): ClothRecipe | null => cloth?.[tag] ?? null;
+  // Issue #391: the tails the back hair recipe drafts, each with its mesh's spans, which an accessory wrapped round one rides.
+  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))];
@@ -1547,7 +1558,14 @@ 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) {
+        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 }));
+      }
+      tails.push({ part: p.name, mask, spans });
     } else {
       const mask = P.alpha(p);
       const segs: Segment[] = [['head', rnd(head), rnd([axis, top + 13])]];
@@ -1714,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
@@ -1726,7 +1745,39 @@ export function proposeWithBasis(
     // gets the bone and chain, the rest ride the head rigidly. A stable sort,
     // as Python's `sorted` is.
     const cands = [...P.byTag(tag)].sort((a, b) => b.opaque_px - a.opaque_px);
+    // Issue #391: a layer of the tag lying on a tail the back hair recipe drafted rides the links it overlaps — the
+    // spans of the tail its pixels over the tail's art fall nearest — and not head: its mesh names those bones and no
+    // others, so every vertex weights by the rule the tail's own art does. The links are read off the overlap, never
+    // off the part's name. A layer over no link keeps its rule below. Only with the recipe: without it no tail moves
+    // by the world, and nothing here runs.
+    const rides = (q: PartRecord): boolean => {
+      const segments: Segment[] = [];
+      const links: string[] = [];
+      const said: string[] = [];
+      for (const tail of tails) {
+        const o = tailOverlap(tail, P.alpha(q), q);
+        if (!tail.spans.some((sp, k) => sp.link && o.counts[k] > 0)) continue;
+        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]}`);
+          // A link is named, so its segment is the link as the bones declare it; the head's span is written out, as the tail's mesh writes it.
+          segments.push(sp.link ? sp.bone : [sp.bone, sp.a, sp.b]);
+          if (sp.link) links.push(sp.bone);
+        });
+        said.push(`${o.over} of its ${o.total} px lie over ${tail.part}'s art, nearest ${tail.part}'s spans ${on.join(', ')} px`);
+      }
+      if (links.length === 0) return false;
+      const [g, r] = gridR(q);
+      delete regions[q.name];
+      meshes[q.name] = { grid: g, r, segments };
+      notes.push(
+        `${q.name} (${q.from}): wraps a tail config.cloth."back hair" drafts — ${said.join('; ')} — so its mesh's segments are those spans and it rides the links ${links.join(', ')} with the tail, not head; no ${tag} bone, pendant or strand chain is drafted for it (issue #391)`,
+      );
+      return true;
+    };
     for (const q of cands.slice(1)) {
+      if (rides(q)) continue;
       regions[q.name] = 'head';
       notes.push(`${q.name} (${q.from}): second ${tag} layer, rigid on head`);
       // A region cannot swing, so strands found on it are only said.
@@ -1735,6 +1786,7 @@ export function proposeWithBasis(
       if (strands.length > 0) notes.push(strandNote(q, strands, [], strands, 'it rides the head as a region'));
     }
     for (const p of cands.slice(0, 1)) {
+      if (rides(p)) continue;
       const [g, r] = gridR(p);
       const fullMask = dilate(P.alpha(p), 7);
       const onArt = (pts: ReadonlyArray<readonly [number, number]>): boolean => pts.every((q) => isOn(fullMask, q[0], q[1]));
@@ -2157,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])],
@@ -2184,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) {
@@ -2236,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 [
@@ -2261,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
@@ -3196,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 {
@@ -3216,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). */
@@ -3423,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);
@@ -3434,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. */
@@ -3456,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);
@@ -3623,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`;
   }
@@ -3657,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[];