@rig-c/parts 1.11.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {
@@ -60,7 +60,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "rig-c": "^2.40.0"
+    "rig-c": "^2.47.1"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/skills/rig-parts/SKILL.md

@@ -82,10 +82,12 @@ stage writes are the whole interface.
    keeps under the piece's edge; 1 px closed the seam on scarf) — and give the piece its own
    `meshes` entry; the `cut:` line gives the split. At overlap 0 a cut through
    opaque art leaves a seam `check` reads (AUTHORING §5).
-   A seated or reclining figure: add `--keypoints <file>` (body-18 joints in
-   painting px, each observed, occluded or missing; AUTHORING §3, *A posed
-   figure*) so the neck, hip, chest and sleeves follow the pose and LINT reads
-   the joints, not screen y. Never write a joint you did not get from an
+   A figure whose joints are not where the screen-y rules put them — reclining,
+   an arm raised, seated in a skirt that does not start at the hip: add
+   `--keypoints <file>` (body-18 joints in painting px, each observed, occluded
+   or missing; AUTHORING §3, *A posed figure*) so the neck, hip, chest and
+   sleeves follow the pose and LINT reads the joints, not screen y. A clean
+   LINT does not show a seated hip is right; the overlay does. Never write a joint you did not get from an
    estimator or the painting: say `missing` and let the rule stand in.
 6. Correct against `render/landmarks.png` and `note:` lines; a
    `coverage … not checked` line is a bone no check read (the line says why),
@@ -109,7 +111,8 @@ stage writes are the whole interface.
 8. Read `out/check/check.json` — the six judgement lines the same way as the seam
    and the loop: a FAIL names the field to change (AUTHORING §6);
    `TEXTURE_STRETCH` names the worst mesh triangle (slot, triangle, vertices, edge,
-   frame), so quote it even on a PASS. Quote
+   frame), so quote it even on a PASS; its FAIL line also names the bones the
+   edge's two vertices are weighted to and the idle chains they hang on. Quote
    `RECOMPOSITE_HOLES` (uncovered px, hole count, the largest hole's box) in the
    report whatever `PASS` says. The artifact is the three paths the build prints
    last: `check/build/skeleton.json`, `skeleton.atlas` and the packed page. Report

package/src/assemble.ts

@@ -2654,6 +2654,14 @@ function fmt0(v: number): string {
  * no role. One both runs hold is proposed once, from the full run, and a note
  * says how to take the head run's too. No public example holds one, so no
  * proposal of theirs moves.
+ *
+ * ⚖️ This port's too (issue #308): every tag a layer of either run holds that
+ * no plan row or extend entry takes is named once, with why, run by run
+ * (`unplannedNotes`), after the uncovered bodies and before the plausibility
+ * drops. The plan is not changed. [observed] On the four public examples the
+ * plan, the extend entries and every earlier note are byte for byte as
+ * before; each gains one such note per tag left out (demo 6, scarf 9,
+ * reference-demo 7, reference-sample 9).
  */
 export function proposePlan(full: LayerSet, head: LayerSet, g: Geometry, minPx = PROPOSE_MIN_PX): PlanProposal {
   const frame = checkGeometry(g, { full, head });
@@ -2778,8 +2786,83 @@ export function proposePlan(full: LayerSet, head: LayerSet, g: Geometry, minPx =
           why,
         );
   const bodyNotes = left.map((u) => uncoveredNote(u, plan, minBody));
-  // The reference's notes, then the uncovered bodies, then the plausibility drops — a drop note is last, as it was.
-  return { plan, extend_below_crop: extend, notes: [...notes, ...bodyNotes, ...dropNotes] };
+  const unplanned = unplannedNotes(runs, plan, extend, noted, figures, minPx, (run, tag) => (find(run, tag)?.opaqueRunPx ?? 0) * (run === 'head' ? headArea : fullArea), new Set(left.map((u) => u.tag)));
+  // The reference's notes, then the uncovered bodies, then the layers in no row (issue #308), then the plausibility drops — a drop note is last, as it was.
+  return { plan, extend_below_crop: extend, notes: [...notes, ...bodyNotes, ...unplanned, ...dropNotes] };
+}
+
+/** What every `--propose-plan` note on a layer in no row says its pixel figures are. */
+export const UNPLANNED_PX = 'px: run pixels of alpha above 8 after ghost clean-up';
+
+/**
+ * One note per tag that a layer of either run holds and no plan row or
+ * extend entry takes (issue #308), in the full run's draw order and then the
+ * head run's, saying for each run why: it holds no such layer; the proposer
+ * takes the tag from the other run only (`PROPOSE_HEAD_TAGS`); its layer is
+ * empty, its opaque count below the floor (`PROPOSE_MIN_PX`); it crosses a
+ * plausibility rule (that layer's own note, which follows, names its figures);
+ * or, for a full-run `headwear` or `earwear`, the head run's was not below 0.8
+ * of it in rig px. A tag every holding run of which a plausibility note
+ * already names gets no second note. `nose`, which the proposer never plans
+ * (the reference's rule), gets a note of its own: the counts, and the row that
+ * lets `propose` read the head's pitch, the only reading in this package made
+ * off a part tagged `nose` (`headFrameNotes`, `src/propose.ts`). The plan is
+ * not changed.
+ */
+function unplannedNotes(
+  runs: Record<Run, RunLayer[]>,
+  plan: readonly PlanEntry[],
+  extend: readonly Extend[],
+  noted: ReadonlySet<string>,
+  figures: Record<Run, LayerFigures[]>,
+  minPx: number,
+  rigPx: (run: Run, tag: string) => number,
+  bodies: ReadonlySet<string>,
+): string[] {
+  const inRow = new Set<string>([...plan.map((p) => p[2]), ...extend.map((e) => e.tag)]);
+  const find = (run: Run, tag: string): RunLayer | undefined => runs[run].find((l) => l.tag === tag);
+  const floor = minPx === PROPOSE_MIN_PX ? `the proposer's floor of ${minPx} (PROPOSE_MIN_PX, src/assemble.ts)` : `the floor of ${minPx} this proposal was given`;
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const { tag } of [...runs.full, ...runs.head]) {
+    if (seen.has(tag) || inRow.has(tag)) continue;
+    seen.add(tag);
+    const held = (['full', 'head'] as const).filter((r) => find(r, tag) !== undefined);
+    const body = bodies.has(tag) ? "; the full run's layer holds a body no planned part covers, named in its note above" : '';
+    if (tag === 'nose') {
+      const counts = (['full', 'head'] as const).map((r) => `${r} run ${find(r, tag)?.opaqueRunPx ?? 'no layer'}${find(r, tag) === undefined ? '' : ' px'}`).join(', ');
+      const best = (['head', 'full'] as const).reduce((a, b) => ((find(b, tag)?.opaqueRunPx ?? 0) > (find(a, tag)?.opaqueRunPx ?? 0) ? b : a));
+      const most = find(best, tag)?.opaqueRunPx ?? 0;
+      const after = plan.some((p) => p[2] === 'face') ? ` after the row that takes "face"` : '';
+      const how =
+        most === 0
+          ? 'neither run\'s layer holds a pixel, so there is no nose part to add'
+          : `propose reads the head's pitch (where the nose sits between the eye midpoint and the mouth) only off a part tagged nose, and without one prints "not read: no part tagged nose"; to have it read, add ["nose", "${best}", "nose"] to assemble.plan${after} (the ${best} run's layer holds the more of it) and run assemble and propose again`;
+      out.push(`nose: in no plan row — the proposer never plans nose (the reference implementation's rule, which this port keeps); ${counts} (${UNPLANNED_PX}); ${how}${body}`);
+      continue;
+    }
+    if (held.every((r) => noted.has(`${r}:${tag}`))) continue;
+    const reason = (run: Run): string => {
+      const l = find(run, tag);
+      if (l === undefined) return `${run} run: no layer`;
+      const px = `${run} run: ${l.opaqueRunPx} px`;
+      const headTag = PROPOSE_HEAD_TAGS.includes(tag);
+      const fallback = tag === 'headwear' || tag === 'earwear';
+      if (run === 'full' && headTag && !fallback) return `${px}, but the proposer takes ${tag} from the head run only (PROPOSE_HEAD_TAGS, src/assemble.ts)`;
+      if (run === 'head' && !headTag && readAuthorTag(tag) === null) return `${px}, but the proposer takes ${tag} from the full run only (it is not one of PROPOSE_HEAD_TAGS, src/assemble.ts)`;
+      if (l.opaqueRunPx < minPx) return `${px}, empty: below ${floor}`;
+      if (noted.has(`${run}:${tag}`)) {
+        const f = figures[run].find((x) => x.name === tag) as LayerFigures;
+        return `${px}, crosses ${implausibleRules(f).join(', ')} (named with its figures in the note below)`;
+      }
+      if (run === 'full' && fallback) {
+        return `${px}, but the proposer takes ${tag} from the full run only when the head run's is below 0.8 of it in rig px (head run ${fmt0(rigPx('head', tag))}, full run ${fmt0(rigPx('full', tag))})`;
+      }
+      throw new Error(`unplannedNotes: no rule left ${run}:${tag} out of the plan, yet no row takes it`);
+    };
+    out.push(`${tag}: in no plan row — ${(['full', 'head'] as const).map(reason).join('; ')} (${UNPLANNED_PX})${body}`);
+  }
+  return out;
 }
 
 // ---------------------------------------------------------------------------

package/src/build.ts

@@ -227,7 +227,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
     log(
       `  ${p.name.padEnd(11)} ${p.from.padEnd(16)} ${`${p.w}x${p.h}`.padEnd(9)} @${String(p.x).padStart(4)},${String(p.y).padStart(4)} ` +
         `op=${String(p.opaque_px).padStart(6)} vis=${String(p.visible_px).padStart(6)} src=${String(p.source_px_taken).padStart(6)}/${String(p.projected_core_px).padStart(6)} ` +
-        `unproj=${String(p.visible_not_projected_px).padStart(5)} drift=${String(p.refused_drift_px).padStart(5)} merged=${p.merged_px} seam=${p.seam_override_px}`,
+        `unproj=${String(p.visible_not_projected_px).padStart(5)} drift=${String(p.refused_drift_px).padStart(5)} ${driftShare(p.refused_drift_px, p.projected_core_px)} merged=${p.merged_px} seam=${p.seam_override_px}`,
     );
   }
   // Issue #256: one line per part from an author-made layer, so it never reads as See-through's. None without one.
@@ -253,6 +253,16 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   return result;
 }
 
+/**
+ * The scale the per-part line prints `drift=` with (issue #314): `refused_drift_px` counts the part's projection
+ * candidates (`projected_core_px`, the `src=` column's second figure) refused because See-through's colour sits more
+ * than the drift limit off the painting's, so it is read against them — `(<p>% of core)`, one decimal; a part with no
+ * candidate has nothing to refuse and says so. No bar reads either figure (AUTHORING §5, `assemble`).
+ */
+export function driftShare(refused: number, core: number): string {
+  return core === 0 ? '(no core)' : `(${((100 * refused) / core).toFixed(1)}% of core)`;
+}
+
 // ---------------------------------------------------------------------------
 // rig
 // ---------------------------------------------------------------------------
@@ -834,7 +844,11 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
       const stray = c.strayIslands === 0 ? '' : ` left out ${c.strayIslands} island(s), ${c.strayPixels} px`;
       const regions = m.regions.map((rg) => ` region ${rg.name}->${rg.bone} reaches ${rg.reached} (${rg.whole} whole)`).join('');
       log(`${head}contour tol=${m.params.tolerance} margin=${m.params.margin} spacing=${m.params.spacing}${m.params.maxEdge === undefined ? '' : ` maxEdge=${m.params.maxEdge} (outline +${c.outlineCut ?? 0})`} ${infl} overshoot ${c.overshoot} min angle ${c.smallestAngle.value}${stray}${regions}`);
-    } else log(`${head}grid=${m.grid} ${infl} loop passes ${rig.loopPasses[m.part]}`);
+    } else {
+      // issue #303: only beside a declared stray, so a lattice line without one reads as it always did.
+      const stray = m.stray_cleared === undefined ? '' : ` stray ${m.stray} left out ${m.stray_cleared.islands} island(s), ${m.stray_cleared.pixels} of ${m.stray_cleared.art_pixels} art px`;
+      log(`${head}grid=${m.grid} ${infl} loop passes ${rig.loopPasses[m.part]}${stray}`);
+    }
   }
   const regions = rig.rig.slots.length - rig.meshReport.length;
   const tracks = rig.motion.animations.idle.tracks;

package/src/check.ts

@@ -1948,7 +1948,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     // One reader for the one geometry file: the stretch reads its meshes, the still regions every slot and the head bone.
     const geometryPath = join(idle.dir, GEOMETRY_FILE);
     const geometry = readGeometry(geometryPath, idle.written);
-    stretch = stretchLine(geometry, geometryPath, problems);
+    stretch = stretchLine(geometry, geometryPath, problems, inp);
     if (full !== null) still = stillLine(full, idle, geometry, geometryPath, problems, notPlanted);
   }
 
@@ -3300,15 +3300,76 @@ function stretchAtText(s: { triangle: number; vertices: readonly number[]; edge:
   return `triangle ${s.triangle} (vertices ${s.vertices.join(' ')}), edge ${s.edge.join('-')}, idle frame ${s.frame}`;
 }
 
+/**
+ * Issue #314: what a failing edge's two vertices hang on, read off rig.json and motion.json — so the cause reads off
+ * the line rather than off a hand decoding of the weight runs. Each vertex's bones from the default skin's weights,
+ * the largest two by weight (equal weights in rig.json's order), with how many it has; then every bone named, grouped
+ * by the idle chain it hangs on — the nearest link at or above it of a chain `CHAIN_LAG` reads
+ * ({@link chainFigures}: two or more rotate-keyed links at one period), each chain named once, by its first link — and
+ * the bones on none. A mesh with no weights rides its slot's bone, and an attachment the skin does not hold, or a
+ * vertex its weights do not reach, is said rather than guessed.
+ */
+export function edgeBonesText(rig: Record<string, unknown>, motion: Record<string, unknown>, slot: string, attachment: string, edge: readonly number[]): string {
+  const skins = isRecord(rig.skins) ? rig.skins : {};
+  const skin = isRecord(skins.default) ? skins.default : {};
+  const onSlot = isRecord(skin[slot]) ? skin[slot] : {};
+  const att = onSlot[attachment];
+  if (!isRecord(att)) return `its weights are not read: rig.json's default skin holds no attachment "${attachment}" on slot "${slot}"`;
+  if (!Array.isArray(att.weights)) {
+    const sl = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find((x) => x.name === slot);
+    return `the mesh carries no weights, so vertex ${edge.join(' and vertex ')} ride slot "${slot}"'s bone ${sl !== undefined && typeof sl.bone === 'string' ? `"${sl.bone}"` : '(rig.json names none)'}`;
+  }
+  const weights = att.weights;
+  const missing = edge.filter((v) => !Array.isArray(weights[v]));
+  if (missing.length > 0) return `its weights are not read: rig.json's mesh "${attachment}" weights ${weights.length} vertices, and vertex ${missing.join(' and ')} is not among them`;
+  const named: string[] = [];
+  const parts = edge.map((v, i) => {
+    const list = (weights[v] as unknown[]).filter(isRecord).filter((w) => typeof w.bone === 'string' && typeof w.weight === 'number') as Array<{ bone: string; weight: number }>;
+    const top = [...list].sort((a, b) => b.weight - a.weight).slice(0, 2);
+    for (const w of top) if (!named.includes(w.bone)) named.push(w.bone);
+    const shown = top.map((w) => `"${w.bone}" ${w.weight}`).join(', ');
+    return `${i === 0 ? `vertex ${v} is weighted to` : `vertex ${v} to`} ${shown}${list.length > 2 ? ` (the largest 2 of ${list.length})` : ''}`;
+  });
+  const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord);
+  const parent = new Map(bones.filter((b) => typeof b.name === 'string').map((b) => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
+  const firstLink = new Map<string, string>();
+  for (const c of chainFigures(rig, motion).chains) if (c.length >= 2) for (const l of c) firstLink.set(l.bone, c[0].bone);
+  const carries = new Map<string, string[]>();
+  const none: string[] = [];
+  for (const b of named) {
+    let chain: string | null = null;
+    const seen = new Set<string>();
+    for (let x: string | null = b; x !== null && !seen.has(x); x = parent.get(x) ?? null) {
+      const f = firstLink.get(x);
+      if (f !== undefined) {
+        chain = f;
+        break;
+      }
+      seen.add(x);
+    }
+    if (chain === null) none.push(b);
+    else carries.set(chain, [...(carries.get(chain) ?? []), b]);
+  }
+  const quoted = (l: readonly string[]): string => l.map((n) => `"${n}"`).join(', ');
+  const chains =
+    carries.size === 0
+      ? 'none of these bones hangs on a chain of the idle'
+      : `on the idle's chains, ${[...carries].map(([c, l]) => `the chain from "${c}" carries ${quoted(l)}`).join(' and ')}${none.length === 0 ? '' : `, and ${quoted(none)} ${none.length === 1 ? 'hangs' : 'hang'} on none`}`;
+  return `${parts.join(' and ')}; ${chains}`;
+}
+
 /**
  * (6) No visible texture stretch: for every mesh triangle, each edge's length
  * in each idle frame over its rest length (the setup pose's bones, no deform —
  * which on both examples is the art's own proportions, the attachment's `uvs`
  * times its size, to 2.4e-5). The figure is the rig's worst max(ratio,
  * 1/ratio); each mesh's largest and smallest ratio, and where, are the detail.
- * SKIP when the render wrote no geometry file or the rig draws no mesh.
+ * SKIP when the render wrote no geometry file or the rig draws no mesh. With
+ * `bound`, the rig and motion `check` read, a failing edge's line also names the
+ * bones its two vertices hang on and their chains ({@link edgeBonesText}, issue
+ * #314).
  */
-export function stretchLine(geo: IdleGeometry | null, path: string, problems: Problem[]): JudgementLine {
+export function stretchLine(geo: IdleGeometry | null, path: string, problems: Problem[], bound?: Pick<CheckInputs, 'rig' | 'motion'>): JudgementLine {
   if (geo === null) return skip(`${path} does not exist; \`rigc render --geometry\` (rig-c ${RIGC_GEOMETRY_VERSION} or later) writes it, and the skinned mesh vertices are read from it`);
   if (geo.meshes.length === 0) return skip('the rig draws no mesh attachment (every slot is a region), so there is no triangle to stretch');
   const figures = stretchFigures(geo.meshes, geo.frames);
@@ -3343,7 +3404,7 @@ export function stretchLine(geo: IdleGeometry | null, path: string, problems: Pr
       problems.push({
         code: 'CHECK_TEXTURE_STRETCH',
         object: `mesh "${m.slot}" ${stretchAtText(at)}`,
-        detail: `the edge is ${round3(at.ratio)} times its rest length (max(ratio, 1/ratio) ${severity}); <= ${TEXTURE_STRETCH_CEILING} is required — the texture on it is ${at.ratio >= 1 ? 'stretched' : 'squeezed'}: the bones this mesh is weighted to move apart (amplitudes too large down a chain), or a vertex blends bones that move against each other`,
+        detail: `the edge is ${round3(at.ratio)} times its rest length (max(ratio, 1/ratio) ${severity}); <= ${TEXTURE_STRETCH_CEILING} is required${bound === undefined ? '' : `; ${edgeBonesText(bound.rig, bound.motion, m.slot, m.attachment, at.edge)}`} — the texture on it is ${at.ratio >= 1 ? 'stretched' : 'squeezed'}: the bones this mesh is weighted to move apart (amplitudes too large down a chain), or a vertex blends bones that move against each other`,
       });
     }
   }

package/src/config.ts

@@ -278,6 +278,11 @@ export interface LatticeMeshSpec {
   rule?: WeightRule;
   /** The cap and the floor's form (issue #284); absent is 4 and the cut at 0.03, the rule as it always was. */
   influences?: MeshInfluences;
+  /**
+   * The largest island, in art pixels, that may be left out of the lattice (issue #303) — the contour mode's
+   * `contour.stray`, with the same meaning (`latticeStray`, `src/mesh.ts`); absent leaves none out.
+   */
+  stray?: number;
 }
 
 export interface ContourMeshSpec {
@@ -1665,7 +1670,7 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
     const at = `config.meshes.${part}`;
     // The known keys keep their old order (grid, r, segments) with contour after them, and `r` and `segments` are
     // required in the place and words the object check uses, so a lattice mesh's refusals read as they did.
-    const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto', 'exponent', 'rule', 'ribs', 'influences']);
+    const m = c.object(at, spec, [], ['grid', 'r', 'segments', 'contour', 'auto', 'exponent', 'rule', 'ribs', 'influences', 'stray']);
     if (m === null) continue;
     for (const key of ['r', 'segments']) if (!(key in m)) c.fail('CONFIG_FIELD_PRESENT', `${at}.${key}`, 'is absent and required');
     const modes = ['grid', 'contour', 'auto'].filter((k) => k in m);
@@ -1707,6 +1712,7 @@ function checkMeshes(c: Check, v: Json, bones: Set<string>, chains: Map<string,
     }
     if ('ribs' in m) checkRibs(c, `${at}.ribs`, m, chains);
     if ('influences' in m) checkMeshInfluences(c, `${at}.influences`, m);
+    if ('stray' in m) checkLatticeStray(c, `${at}.stray`, m);
     if ('auto' in m && typeof m.auto === 'object' && m.auto !== null && !Array.isArray(m.auto) && 'stimulus' in m.auto) {
       checkStimulus(c, `${at}.auto.stimulus`, (m.auto as Record<string, Json>).stimulus, m, chains);
     }
@@ -1775,6 +1781,21 @@ function checkMeshInfluences(c: Check, at: string, m: Record<string, Json>): voi
   }
 }
 
+/**
+ * `meshes.<part>.stray` (issue #303): the lattice's largest island, in art pixels, that may be left out — a whole
+ * number, 0 or more, as the contour mode's `contour.stray` is. The contour and automatic modes already state it in
+ * their own place (`contour.stray`, `auto.source.stray`), so beside either it is refused by name
+ * (`CONFIG_STRAY_MODE`) rather than read by nothing.
+ */
+function checkLatticeStray(c: Check, at: string, m: Record<string, Json>): void {
+  const elsewhere = 'contour' in m ? ['a contour mesh (contour)', 'contour.stray'] : 'auto' in m ? ['an automatic mesh (auto)', 'auto.source.stray'] : null;
+  if (elsewhere !== null && !('grid' in m)) {
+    c.fail('CONFIG_STRAY_MODE', at, `is ${show(m.stray)} on ${elsewhere[0]}; that mode states the largest island it may leave out in ${elsewhere[1]}, which its trace reads — declare it there, or remove stray`);
+    return;
+  }
+  c.int(at, m.stray, 0);
+}
+
 /**
  * `meshes.<part>.ribs` (issue #188): an object of chain name → `{ stations }`.
  * Each key must be a chain this mesh's `segments` name (a rib is placed along

package/src/heat.ts

@@ -44,10 +44,19 @@
  *   silhouette, or one whose every reached pixel is nearer another bone. A
  *   bone named in `segments` is a bone the author said may pull the layer;
  *   giving it 0 everywhere would be a silent answer to a question the
- *   config asked.
+ *   config asked. The rule is chosen per mesh (`meshes.<part>.rule`), so the
+ *   refusal names the third remedy too (issue #303): this part keeps the
+ *   distance rule — the one an author whose bone anchors the part from
+ *   outside its art (a torso bone on a neck) can take without moving a bone
+ *   another part placed or dropping the anchor.
  * - `RIG_HEAT_ISLAND_SOURCE`: a 4-connected island of the silhouette that no
  *   bone has a source in. With no fixed temperature the equation has no
- *   answer there; nothing nearest is borrowed.
+ *   answer there; nothing nearest is borrowed. When the caller can say the
+ *   island is dust that its `stray` would leave out ({@link HeatDust}: the
+ *   lattice, issue #303) the refusal names that field and the figure that
+ *   leaves the island out instead of a segment nobody would place on it; an
+ *   island above the dust line keeps the segment remedy, a real piece being
+ *   a real authoring question.
  * - `RIG_HEAT_CONVERGED`: above.
  *
  * Two runs on the same input write the same bytes: the claims, the sweep
@@ -55,6 +64,8 @@
  */
 import type { Point } from './config.ts';
 import { artMask, growSilhouette } from './contour.ts';
+import { DUST_MAX_PX, DUST_MAX_SHARE, isDust } from './mesh.ts';
+import { pyRound } from './round.ts';
 import type { Problem } from './errors.ts';
 import { connectedComponents, fillHoles, type Mask } from './raster/index.ts';
 import { capAndFloor, type Influence, type InfluenceLimits, type Segment, segmentDistance } from './weights.ts';
@@ -120,11 +131,34 @@ export interface HeatRow {
 
 const fmt = (v: number): string => String(Math.round(v * 1000) / 1000);
 
+/**
+ * What a mesh's `stray` can say about a silhouette island no bone reaches (issue #303), handed in by the mode that has
+ * the field (the lattice): the field's path, its declared figure (null when absent), and the part's art islands it
+ * reads — the art px (`isDust`'s share is of them) and the largest island's area, which `stray` never leaves out. It
+ * is read only when an island is refused, so a build that solves never computes it.
+ */
+export interface HeatDust {
+  field: string;
+  declared: number | null;
+  artPixels: number;
+  largest: number;
+}
+
+/** The refusal's remedy for an island of `area` px no bone reaches: the stray field when the island is dust it would leave out, else a segment. */
+function islandRemedy(area: number, dust: HeatDust | null): string {
+  if (dust !== null && isDust(area, dust.artPixels) && area < dust.largest) {
+    const now = dust.declared === null ? 'it is absent' : `it is ${dust.declared}`;
+    return `the island is dust — at most ${DUST_MAX_PX} px and at most ${pyRound(DUST_MAX_SHARE * 100, 6)} % of the part's ${dust.artPixels} art px, mesh-draft's dust line — which no bone is meant to sit on: declare ${dust.field} at ${area} or more (${now}), which leaves an island that small out of the mesh and the silhouette heat solves over`;
+  }
+  return `under rule "heat" every island needs a segment within ${HEAT_SOURCE_BAND} px of one of its pixel centres — nothing is borrowed from the nearest island`;
+}
+
 /**
  * Solve bone heat over `sil` (part-image pixels) for `segs` (rig px; the image is the rig less `(ox, oy)`).
- * `object` names the mesh in every refusal. Every problem found is returned at once.
+ * `object` names the mesh in every refusal. Every problem found is returned at once. `dust`, when the mesh's mode has
+ * a `stray` field, is read only to word an island refusal ({@link HeatDust}).
  */
-export function boneHeat(object: string, sil: Mask, segs: readonly Segment[], ox: number, oy: number, limits: HeatLimits = HEAT_LIMITS): HeatField | Problem[] {
+export function boneHeat(object: string, sil: Mask, segs: readonly Segment[], ox: number, oy: number, limits: HeatLimits = HEAT_LIMITS, dust: (() => HeatDust) | null = null): HeatField | Problem[] {
   const { width: w, height: h, data } = sil;
   const n = w * h;
   const bones: string[] = [];
@@ -166,19 +200,21 @@ export function boneHeat(object: string, sil: Mask, segs: readonly Segment[], ox
     problems.push({
       code: 'RIG_HEAT_BONE_SOURCE',
       object,
-      detail: `bone "${bone}" — its segment ${where} (rig px) ${why}, so it holds no source pixel; under rule "heat" every bound bone needs at least one: a silhouette pixel (${silPixels} px) whose centre lies within ${HEAT_SOURCE_BAND} px of the segment and nearer it than any other bound bone's. A bone with no source is not weighted 0 — move its segment onto the art, or take the bone out of segments`,
+      detail: `bone "${bone}" — its segment ${where} (rig px) ${why}, so it holds no source pixel; under rule "heat" every bound bone needs at least one: a silhouette pixel (${silPixels} px) whose centre lies within ${HEAT_SOURCE_BAND} px of the segment and nearer it than any other bound bone's. A bone with no source is not weighted 0 — move its segment onto the art, take the bone out of segments, or keep this part on the distance rule (rule "distance", or no rule, on this mesh: the rule is chosen per mesh)`,
     });
   });
   const cc = connectedComponents(sil, 4);
   const sourced = new Uint8Array(cc.count);
   for (let i = 0; i < n; i++) if (owner[i] >= 0) sourced[cc.labels[i]] = 1;
+  let dustRead: HeatDust | null = null;
   for (let c = 1; c < cc.count; c++) {
     if (sourced[c]) continue;
     const st = cc.stats[c];
+    if (dust !== null && dustRead === null) dustRead = dust();
     problems.push({
       code: 'RIG_HEAT_ISLAND_SOURCE',
       object,
-      detail: `the silhouette's 4-connected island of ${st.area} px at rig (${st.left + ox}, ${st.top + oy}) holds no bound bone's source pixel, so the heat equation has no fixed temperature there and no answer; under rule "heat" every island needs a segment within ${HEAT_SOURCE_BAND} px of one of its pixel centres — nothing is borrowed from the nearest island`,
+      detail: `the silhouette's 4-connected island of ${st.area} px at rig (${st.left + ox}, ${st.top + oy}) holds no bound bone's source pixel, so the heat equation has no fixed temperature there and no answer; ${islandRemedy(st.area, dustRead)}`,
     });
   }
   if (problems.length > 0) return problems;

package/src/mesh.ts

@@ -360,3 +360,64 @@ export function latticeMesh(part: string, art: Mask, grid: number, maxPasses: nu
   }
   return mesh;
 }
+
+/**
+ * Dust (issue #265, Stage B's rule; moved here from `src/meshdraft.ts` by issue #303, so the rig stage's heat refusal
+ * and `mesh-draft` read one line): an extra 4-connected island of the art of at most this many art px …
+ */
+export const DUST_MAX_PX = 4;
+
+/** … and at most this share of the part's art px. */
+export const DUST_MAX_SHARE = 0.001;
+
+/** Whether an island of `area` art px is dust in a part of `artPixels` art px ({@link DUST_MAX_PX}, {@link DUST_MAX_SHARE}). */
+export function isDust(area: number, artPixels: number): boolean {
+  return area <= DUST_MAX_PX && area <= DUST_MAX_SHARE * artPixels;
+}
+
+/** What a declared `meshes.<part>.stray` left out of a lattice's art (issue #303). */
+export interface LatticeStray {
+  /** The art the lattice is built over: `art` itself when nothing was left out. */
+  art: Mask;
+  /** Islands left out, and their art px. */
+  islands: number;
+  pixels: number;
+  /** The art px of the part before anything was left out. */
+  artPixels: number;
+  /** The area of the largest island; an island this large is never left out. */
+  largest: number;
+}
+
+/**
+ * The lattice's `stray` (issue #303), the contour mode's field with the same meaning — the largest island, in art
+ * pixels, that may be left out of the mesh — read over the same islands: the 4-connected islands of the art (alpha
+ * above {@link ART_ALPHA}). Every island of `stray` art px or fewer is cleared from the art the lattice and its heat
+ * silhouette are built over, except an island as large as the largest, which is never left out (two equal largest
+ * pieces both stay: leaving one would be a choice the declaration does not make). Unlike the contour mode, an island
+ * above the figure is not refused: the lattice bridges every island it keeps (step 2 above), so it is meshed as it
+ * always was. The part's image is not touched; `artCoverage` is read over all the art, the islands left out included.
+ */
+export function latticeStray(art: Mask, stray: number): LatticeStray {
+  const comp = connectedComponents(art, 4);
+  let largest = 0;
+  let artPixels = 0;
+  for (let l = 1; l < comp.count; l++) {
+    largest = Math.max(largest, comp.stats[l].area);
+    artPixels += comp.stats[l].area;
+  }
+  const out = new Uint8Array(comp.count);
+  let islands = 0;
+  let pixels = 0;
+  for (let l = 1; l < comp.count; l++) {
+    const a = comp.stats[l].area;
+    if (a <= stray && a < largest) {
+      out[l] = 1;
+      islands++;
+      pixels += a;
+    }
+  }
+  if (islands === 0) return { art, islands, pixels, artPixels, largest };
+  const data = new Uint8Array(art.data);
+  for (let i = 0; i < data.length; i++) if (out[comp.labels[i]] === 1) data[i] = 0;
+  return { art: { width: art.width, height: art.height, data }, islands, pixels, artPixels, largest };
+}

package/src/meshdraft.ts

@@ -68,7 +68,7 @@ import { BARS, type CheckReport, type PackShape, type PageEdges, type RigcRunner
 import { type CharacterConfig, type ContourMeshSpec, type LatticeMeshSpec, loadConfigAndAnimations, type Segment } from './config.ts';
 import { PartsError, type Problem, problemLine } from './errors.ts';
 import { IDLE_FPS } from './motion.ts';
-import { ART_ALPHA } from './mesh.ts';
+import { ART_ALPHA, DUST_MAX_PX, DUST_MAX_SHARE, isDust } from './mesh.ts';
 import { type PartsFile, readParts } from './parts.ts';
 import { alphaAbove, connectedComponents } from './raster/index.ts';
 import { readPng } from './raster/png.ts';
@@ -90,11 +90,11 @@ export const TOLERANCE_FIGURE_DIVISOR = 554;
 /** The heights of the three figures the two divisors were measured on, rig px (demo, the trailer, scarf). */
 export const CALIBRATION_HEIGHTS: readonly number[] = [1106, 1108, 1185];
 
-/** Dust: an extra island of at most this many art px (Stage B: 1–2 px dots were the measured case) … */
-export const DUST_MAX_PX = 4;
-
-/** … and at most this share of the part's art px. */
-export const DUST_MAX_SHARE = 0.001;
+/**
+ * Dust (Stage B: 1–2 px dots were the measured case): `src/mesh.ts` holds the line since issue #303, which the rig
+ * stage's heat refusal reads too; re-exported here, where it was first written.
+ */
+export { DUST_MAX_PX, DUST_MAX_SHARE } from './mesh.ts';
 
 /** The bend set's turn per link, degrees: the fallback Stage C stated, a physics constraint's reach not being derivable from it. */
 export const BEND_DEGREES = 15;
@@ -118,6 +118,33 @@ export const MORE_TRIANGLES_FLAG = '--more-triangles';
  */
 export const RELATIVE_SENTENCE = 'the gate is a judgment relative to this config\'s lattice, not an absolute quality: when the lattice coarsens, the reference moves with it';
 
+/**
+ * What `mesh-draft` says of a part whose config entry is not a lattice (`contour` or `auto`, issue #307): it drafts
+ * lattice entries only, so such a part was neither drafted nor compared. Said because the answer to "which mode comes
+ * out smaller" is not the one the names suggest: on one figure (rig-c/trailer 45becfb) an `auto` reduction held to a
+ * large declared bend kept two to three times the triangles of the outline this command drafts (AUTHORING §3, *Which
+ * mode comes out smaller*).
+ */
+export const NOT_COMPARED_SENTENCE = 'mesh-draft drafts lattice entries only, so it drafted nothing for this part and compared it with nothing; whether a lattice, or the outline mesh-draft drafts over one, comes out smaller is not known from this run — build the part once on a lattice, run mesh-draft, and compare the rig stage\'s mesh lines before keeping this entry';
+
+/** A config entry `mesh-draft` did not draft because it is not a lattice (issue #307), in config order. */
+export interface NotCompared {
+  part: string;
+  mode: 'contour' | 'auto';
+  note: string;
+}
+
+/** The entries of `meshes` that are not lattices, in config order, each with its note ({@link NOT_COMPARED_SENTENCE}). */
+export function notCompared(meshes: CharacterConfig['meshes']): NotCompared[] {
+  const out: NotCompared[] = [];
+  for (const [part, spec] of Object.entries(meshes)) {
+    if ('grid' in spec) continue;
+    const mode = 'auto' in spec ? 'auto' : 'contour';
+    out.push({ part, mode, note: `its entry is "${mode}", not a lattice: ${NOT_COMPARED_SENTENCE}` });
+  }
+  return out;
+}
+
 /** The five readings, in the order the gate reads them. */
 export const READINGS = ['bars', 'idle', 'bend inverted', 'bend worst', 'triangles'] as const;
 export type Reading = (typeof READINGS)[number];
@@ -182,7 +209,7 @@ export function dustOf(image: Raster): DustReading {
   if (islands.length === 0) return { keep: `its image has no pixel with alpha above ${ART_ALPHA}`, islands };
   if (islands.length > 1 && islands[0] === islands[1]) return { keep: `its art is ${islands.length} islands (${islands.join(', ')} px) of which two share the largest count, so no one island is the largest`, islands };
   const extra = islands.slice(1);
-  const pieces = extra.filter((n) => !(n <= DUST_MAX_PX && n <= DUST_MAX_SHARE * art));
+  const pieces = extra.filter((n) => !isDust(n, art));
   if (pieces.length > 0) {
     return {
       keep: `its art is ${islands.length} islands (${islands.join(', ')} px); ${pieces.length} beside the largest ${pieces.length === 1 ? 'is a real piece' : 'are real pieces'}, not dust (at most ${DUST_MAX_PX} px and at most ${pyRound(DUST_MAX_SHARE * 100, 6)} % of the part's ${art} art px), and the contour mode meshes one island`,
@@ -534,6 +561,8 @@ export interface PartRow {
 export interface MeshDraftResult {
   rules: FigureRules;
   rows: PartRow[];
+  /** The entries not drafted because they are not lattices (issue #307), in config order. */
+  notCompared: NotCompared[];
   written: string[];
 }
 
@@ -810,6 +839,7 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
   }
   const configText = splicedConfig(text, drafted);
   const rowsOut = [...rows.values()];
+  const others = notCompared(cfg.meshes);
   const report = {
     spec: MESH_DRAFT_SPEC,
     rules: {
@@ -834,6 +864,9 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
       gate: r.gate,
       note: r.note,
     })),
+    // Issue #307: present only when the config holds an entry that is not a lattice, so a config of lattices alone
+    // writes the bytes it wrote before the key existed.
+    ...(others.length === 0 ? {} : { not_compared: others }),
   };
   mkdirSync(input.out, { recursive: true });
   const written = [join(input.out, 'config.json'), join(input.out, MESH_DRAFT_REPORT)];
@@ -845,14 +878,15 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
     for (const g of r.gate) log(`    ${g.pass ? 'pass' : 'FAIL'}  ${g.reading}: ${g.text}`);
     if (r.mode === 'grid' && r.gate.length === 0) log(`    ${r.note}`);
   }
+  for (const o of others) log(`  NOT COMPARED  ${o.part}: ${o.note}`);
   const nDrafted = rowsOut.filter((r) => r.mode === 'contour').length;
   const tri = (pick: (r: PartRow) => number): number => rowsOut.reduce((a, r) => a + pick(r), 0);
-  log(`rig-parts mesh-draft: ${nDrafted} of ${rowsOut.length} lattice part(s) drafted; their triangles ${tri((r) => r.lattice.triangles)} -> ${tri((r) => (r.mode === 'contour' && r.candidate !== null ? r.candidate.triangles : r.lattice.triangles))}, the figure's overdraw over them ${report.figure_overdraw.lattice} -> ${report.figure_overdraw.written}${input.moreTriangles === true ? ` (${MORE_TRIANGLES_FLAG}: triangles reported, not a line)` : ''}; the drafted config's check: ${final.report.figures.PASS ? 'PASS' : 'FAIL'}`);
+  log(`rig-parts mesh-draft: ${nDrafted} of ${rowsOut.length} lattice part(s) drafted; their triangles ${tri((r) => r.lattice.triangles)} -> ${tri((r) => (r.mode === 'contour' && r.candidate !== null ? r.candidate.triangles : r.lattice.triangles))}, the figure's overdraw over them ${report.figure_overdraw.lattice} -> ${report.figure_overdraw.written}${input.moreTriangles === true ? ` (${MORE_TRIANGLES_FLAG}: triangles reported, not a line)` : ''}${others.length === 0 ? '' : `; ${others.length} part(s) not a lattice, not drafted and not compared: ${others.map((o) => `${o.part} (${o.mode})`).join(', ')}`}; the drafted config's check: ${final.report.figures.PASS ? 'PASS' : 'FAIL'}`);
   if (resolve(configDir) !== resolve(input.out)) {
     for (const r of relativePaths(raw)) log(`  note: ${r.at} is "${r.value}", relative to the config's directory; the written config keeps the text, so it resolves against ${input.out} — copy the file beside the written config, or the written config beside it`);
   }
   log(`rig-parts mesh-draft: wrote ${written.join(' and ')}`);
-  return { rules, rows: rowsOut, written };
+  return { rules, rows: rowsOut, notCompared: others, written };
 }
 
 /**