@rig-c/parts 1.13.1 → 1.15.0

package/src/meshdraft.ts

@@ -13,7 +13,9 @@
  * - the interior grid at spacing S = round(H / {@link FIGURE_GRID_DIVISOR});
  * - dust left out: an extra 4-connected island of the art (alpha above `ART_ALPHA`) of at most {@link DUST_MAX_PX} px
  *   and at most {@link DUST_MAX_SHARE} of the part's art is dust, and a `stray` equal to the largest such island leaves
- *   it out. A part with any other extra island holds a real piece, and keeps its lattice ({@link dustOf});
+ *   it out. A part with any other extra island holds a real piece ({@link dustOf}): issue #326 drafts it per island,
+ *   `bridges: true`, only when every island is carried by the same bones ({@link islandsJoin}: every vertex of the
+ *   part's lattice bound to one bone, the same one); otherwise it keeps its lattice, and the note names the bones;
  * - `r`, `segments`, `exponent`, `rule` and `influences` as the lattice entry states them.
  *
  * The constants are the ones issue #265's stages measured (Stage A passed every bar at c = 37 on three examples; T 2
@@ -68,6 +70,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 { type ContourBridges, FAINT_ALPHA } from './contour.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';
@@ -219,10 +222,13 @@ export function dustOf(image: Raster): DustReading {
   return { stray: extra.length === 0 ? undefined : extra[0], islands, dust: extra };
 }
 
-/** The candidate for one lattice entry: the outline mesh at the figure's numbers, its weights' fields as the lattice states them. */
-export function candidateMesh(lattice: LatticeMeshSpec, rules: Pick<FigureRules, 'tolerance' | 'spacing'>, stray: number | undefined): ContourMeshSpec {
+/**
+ * The candidate for one lattice entry: the outline mesh at the figure's numbers, its weights' fields as the lattice
+ * states them. `bridges` (issue #326): every real island meshed and joined by bridges ({@link islandsJoin}).
+ */
+export function candidateMesh(lattice: LatticeMeshSpec, rules: Pick<FigureRules, 'tolerance' | 'spacing'>, stray: number | undefined, bridges = false): ContourMeshSpec {
   return {
-    contour: { tolerance: rules.tolerance, margin: rules.tolerance, spacing: rules.spacing, maxEdge: rules.spacing, ...(stray === undefined ? {} : { stray }) },
+    contour: { tolerance: rules.tolerance, margin: rules.tolerance, spacing: rules.spacing, maxEdge: rules.spacing, ...(stray === undefined ? {} : { stray }), ...(bridges ? { bridges: true as const } : {}) },
     r: lattice.r,
     segments: lattice.segments,
     ...(lattice.exponent === undefined ? {} : { exponent: lattice.exponent }),
@@ -231,6 +237,52 @@ export function candidateMesh(lattice: LatticeMeshSpec, rules: Pick<FigureRules,
   };
 }
 
+/** What the same-bones test reads off a part's lattice as the rig stage weighted it (issue #326). */
+export interface CarriedBy {
+  /** Every bone a vertex is bound to, sorted. */
+  bones: string[];
+  /** The lattice's vertices, and how many are bound to more than one bone. */
+  vertices: number;
+  blended: number;
+}
+
+/** The bones a mesh attachment's vertices are bound to ({@link CarriedBy}). */
+export function carriedBy(att: Pick<MeshAttachment, 'weights'>): CarriedBy {
+  const bones = new Set<string>();
+  let blended = 0;
+  for (const w of att.weights) {
+    for (const e of w) bones.add(e.bone);
+    if (w.length > 1) blended++;
+  }
+  return { bones: [...bones].sort(), vertices: att.weights.length, blended };
+}
+
+/**
+ * Issue #326 (HQ's ruling on Stage A): a part whose art holds a second real island is drafted per island, joined by
+ * bridges, **only when every island is carried by the same bones**. The test, read off the part's lattice as the rig
+ * stage weighted it ({@link carriedBy}): every vertex is bound to one bone, and it is the same bone for every
+ * vertex. Then every point of the part — each island and every bridge between them — moves with that one bone, so no
+ * island moves against another and no bridge stretches. Anything else keeps the lattice, and the sentence says which
+ * bones; no two-bone join is drafted, measured or not (the ruling: nothing measured needs it).
+ *
+ * `islands` is {@link dustOf}'s reading of the same image. Returns the `stray` the candidate declares (the largest
+ * dust island: every real island is larger than any dust island on one part, since dust is at most
+ * {@link DUST_MAX_PX} px and a share of at most {@link DUST_MAX_SHARE}) and the real islands' px; or why the lattice
+ * is kept. A reading that is not a real piece or a tie for the largest — no art, or one island — is not this path's.
+ */
+export function islandsJoin(islands: readonly number[], lattice: Pick<MeshAttachment, 'weights'>): { stray: number | undefined; real: number[]; bone: string } | { keep: string } | null {
+  if (islands.length < 2) return null;
+  const art = islands.reduce((a, b) => a + b, 0);
+  const real = islands.filter((n, i) => i === 0 || n === islands[0] || !isDust(n, art));
+  const dust = islands.filter((n, i) => !(i === 0 || n === islands[0] || !isDust(n, art)));
+  if (real.length < 2) return null;
+  const c = carriedBy(lattice);
+  if (c.bones.length === 1 && c.blended === 0) return { stray: dust.length === 0 ? undefined : dust[0], real, bone: c.bones[0] };
+  return {
+    keep: `its ${real.length} real islands are carried by different bones — the lattice's ${c.vertices} vertices are bound to ${c.bones.map((b) => `"${b}"`).join(', ')}${c.blended > 0 ? `, ${c.blended} of them to more than one` : ''} — and mesh-draft joins islands by bridges only when every vertex is bound to one and the same bone, so that no island moves against another and no bridge between them stretches (issue #326)`,
+  };
+}
+
 /** The dense reference's lattice cell, px: Stage C's sample stride, the least whole number keeping a part's art at or under {@link DENSE_MAX_SAMPLES} samples. */
 export function denseGrid(artPx: number): number {
   return Math.max(1, Math.ceil(Math.sqrt(artPx / DENSE_MAX_SAMPLES)));
@@ -546,13 +598,30 @@ export interface MeshFigure {
   overdraw: number;
 }
 
+/** A bridged candidate's bridges (issue #326), off the rig stage's mesh report: the silhouettes, each join, and their area over the part's art. */
+export interface BridgeFigure {
+  /** The grown silhouettes, numbered by art px: each one's islands' art px. */
+  units: number[][];
+  joins: Array<{ span: [number, number]; area_px2: number }>;
+  /** Σ of the joins' area, px². */
+  area_px2: number;
+  /** That area over the part's art px: the share of the candidate's overdraw the bridges draw (4 decimals). */
+  overdraw: number;
+  /**
+   * Only when one was left out (HQ's ruling on #326): each faint island — every pixel's alpha under `FAINT_ALPHA`
+   * (`src/contour.ts`) — with its art px, its brightest pixel's alpha and its box in part-image px. Not meshed, so not
+   * drawn.
+   */
+  faint?: Array<{ art_px: number; max_alpha: number; box: [number, number, number, number] }>;
+}
+
 export interface PartRow {
   part: string;
   /** What the written config holds for the part. */
   mode: 'contour' | 'grid';
   lattice: MeshFigure & { grid: number; art_px: number };
   /** Null when no candidate was drafted for it (a real piece, or the stage refused it before any reading). */
-  candidate: (MeshFigure & { mesh: ContourMeshSpec }) | null;
+  candidate: (MeshFigure & { mesh: ContourMeshSpec; bridges?: BridgeFigure }) | null;
   readings: PartReadings | null;
   gate: GateLine[];
   note: string;
@@ -566,6 +635,23 @@ export interface MeshDraftResult {
   written: string[];
 }
 
+/** A bridged part's {@link BridgeFigure} off `<rigDir>/mesh_report.json`, or null when the report holds none for it. */
+export function bridgesOf(rigDir: string, part: string, art: number): BridgeFigure | null {
+  const path = join(rigDir, 'mesh_report.json');
+  if (!existsSync(path)) return null;
+  const rows = JSON.parse(readFileSync(path, 'utf8')) as Array<{ part: string; contour?: { bridges?: ContourBridges } }>;
+  const b = rows.find((r) => r.part === part)?.contour?.bridges;
+  if (b === undefined) return null;
+  const area = b.joins.reduce((t, j) => t + j.area, 0);
+  return {
+    units: b.units,
+    joins: b.joins.map((j) => ({ span: j.span, area_px2: j.area })),
+    area_px2: area,
+    overdraw: art === 0 ? 0 : pyRound(area / art, 4),
+    ...(b.faint === undefined ? {} : { faint: b.faint.map((f) => ({ art_px: f.art, max_alpha: f.maxAlpha, box: f.box })) }),
+  };
+}
+
 /** The mesh's area over the art's: the triangles' area in image px over the image's art px. */
 export function overdrawOf(att: MeshAttachment, art: number): number {
   let twice = 0;
@@ -660,6 +746,7 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
   // 2. Candidates for every lattice entry; a real piece keeps the lattice.
   const rows = new Map<string, PartRow>();
   const candidates = new Map<string, ContourMeshSpec>();
+  const joined = new Map<string, { stray: number | undefined; real: number[]; bone: string }>();
   for (const [part, spec] of Object.entries(cfg.meshes)) {
     if (!('grid' in spec)) continue;
     const img = images.get(part);
@@ -673,16 +760,45 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
     }
     const dust = dustOf(img);
     if ('keep' in dust) {
-      row.note = `keeps its lattice: ${dust.keep}`;
+      // Issue #326: islands carried by one bone are drafted per island and joined by bridges.
+      const join = islandsJoin(dust.islands, att);
+      if (join === null || 'keep' in join) {
+        row.note = `keeps its lattice: ${dust.keep}${join === null ? '' : `; ${join.keep}`}`;
+        continue;
+      }
+      joined.set(part, join);
+      candidates.set(part, candidateMesh(spec, rules, join.stray, true));
       continue;
     }
     candidates.set(part, candidateMesh(spec, rules, dust.stray));
   }
   const dustText = (part: string): string => {
+    const j = joined.get(part);
+    if (j !== undefined) {
+      const img = images.get(part) as Raster;
+      const dust = (dustOf(img) as { islands: number[] }).islands.slice(j.real.length);
+      return `${dust.length === 0 ? 'no dust' : `stray ${j.stray as number} leaves out ${dust.length} dust island(s) of ${dust.join(', ')} px`}; ${bridgeText(row(part))}`;
+    }
     const img = images.get(part);
     const d = img === undefined ? null : dustOf(img);
     return d === null || 'keep' in d || d.dust.length === 0 ? 'no dust' : `stray ${d.stray as number} leaves out ${d.dust.length} dust island(s) of ${d.dust.join(', ')} px`;
   };
+  const row = (part: string): PartRow => rows.get(part) as PartRow;
+  const faintText = (faint: NonNullable<BridgeFigure['faint']>): string =>
+    `LEFT OUT as faint, every pixel under alpha ${FAINT_ALPHA}: ${faint.map((f) => `${f.art_px} px (brightest alpha ${f.max_alpha}, at part-image px ${f.box[0]},${f.box[1]} ${f.box[2]}x${f.box[3]})`).join('; ')} — not meshed, so not drawn; if those pixels matter to you, keep the lattice for this part`;
+  const bridgeText = (r: PartRow): string => {
+    const j = joined.get(r.part) as { real: number[]; bone: string };
+    const b = r.candidate?.bridges;
+    const joins =
+      b === undefined
+        ? 'its bridges were not read'
+        : b.joins.length === 0
+          ? 'no bridge'
+          : `${b.joins.length} bridge(s) of ${b.joins.map((x) => `${x.span[0]} and ${x.span[1]} px`).join('; ')} span, ${b.area_px2} px² over no art (overdraw ${b.overdraw} of the candidate's ${r.candidate?.overdraw}; overdraw is reported, never a reason to leave art out)`;
+    const faint = b?.faint ?? [];
+    const visible = j.real.length - faint.length;
+    return `its ${j.real.length} real islands (${j.real.join(', ')} px)${faint.length === 0 ? '' : `: ${faintText(faint)}; the ${visible} visible`} traced as ${b === undefined ? 'its' : b.units.length} grown silhouette(s) and joined into one outline by ${joins}, every vertex bound to the one bone "${j.bone}" (issue #326)`;
+  };
 
   // 3. The drafted rig must build: a refusal laid on a part keeps that part's lattice.
   const keep = (part: string, reading: Reading, text: string): void => {
@@ -784,6 +900,10 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
       const att = attachmentOf(draftRig, part);
       const img = images.get(part) as Raster;
       row.candidate = { triangles: att.triangles.length / 3, overdraw: overdrawOf(att, artPixels(img)), mesh: candidates.get(part) as ContourMeshSpec };
+      if (joined.has(part)) {
+        const b = bridgesOf(draftedRig.rigDir, part, artPixels(img));
+        if (b !== null) row.candidate.bridges = b;
+      }
       const readings: PartReadings = { bars: null, idle: idleReading(idle, part), bend: read === null || typeof read === 'string' ? read : { links, ...read }, triangles: { lattice: row.lattice.triangles, candidate: row.candidate.triangles } };
       row.readings = readings;
       const v = gateVerdict({ ...readings, bars: [] }, input.moreTriangles === true);
@@ -834,7 +954,8 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
       drafted.set(row.part, { ...cand, note: row.note });
     } else if (row.note === '') {
       const failed = row.gate.filter((x) => !x.pass);
-      row.note = `keeps its lattice at grid ${row.lattice.grid}: ${failed.length === 0 ? 'no candidate was read' : failed.map((x) => `${x.reading} — ${x.text}`).join('; ')}`;
+      const faint = row.candidate?.bridges?.faint ?? [];
+      row.note = `keeps its lattice at grid ${row.lattice.grid}: ${failed.length === 0 ? 'no candidate was read' : failed.map((x) => `${x.reading} — ${x.text}`).join('; ')}${faint.length === 0 ? '' : `; on the bridged candidate those readings read: ${faintText(faint)}`}`;
     }
   }
   const configText = splicedConfig(text, drafted);
@@ -857,7 +978,7 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
       part: r.part,
       mode: r.mode,
       lattice: r.lattice,
-      candidate: r.candidate === null ? null : { triangles: r.candidate.triangles, overdraw: r.candidate.overdraw },
+      candidate: r.candidate === null ? null : { triangles: r.candidate.triangles, overdraw: r.candidate.overdraw, ...(r.candidate.bridges === undefined ? {} : { bridges: r.candidate.bridges }) },
       // Under --more-triangles only: what accepting a costlier candidate trades, triangles against overdraw.
       ...(input.moreTriangles === true && r.candidate !== null ? { delta: { triangles: r.candidate.triangles - r.lattice.triangles, overdraw: pyRound(r.candidate.overdraw - r.lattice.overdraw, 4) } } : {}),
       readings: r.readings,
@@ -873,7 +994,7 @@ export function meshDraftStage(input: MeshDraftInput, rigc: RigcRunner, checkBin
   writeFileSync(written[0], configText);
   writeFileSync(written[1], `${JSON.stringify(report, null, 2)}\n`);
   for (const r of rowsOut) {
-    const cand = r.candidate === null ? '' : `; candidate ${r.candidate.triangles} triangle(s), overdraw ${r.candidate.overdraw}`;
+    const cand = r.candidate === null ? '' : `; candidate ${r.candidate.triangles} triangle(s), overdraw ${r.candidate.overdraw}${r.candidate.bridges === undefined ? '' : ` (${r.candidate.bridges.joins.length} bridge(s), ${r.candidate.bridges.area_px2} px² over no art: overdraw ${r.candidate.bridges.overdraw} of it${(r.candidate.bridges.faint ?? []).map((f) => `; LEFT OUT faint ${f.art_px} px, brightest alpha ${f.max_alpha} < ${FAINT_ALPHA}`).join('')})`}`;
     log(`  ${r.mode === 'contour' ? 'DRAFTED' : 'LATTICE'}  ${r.part}: lattice grid ${r.lattice.grid} ${r.lattice.triangles} triangle(s), overdraw ${r.lattice.overdraw}${cand}`);
     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}`);

package/src/requirements.ts

@@ -179,6 +179,24 @@ export interface RequirementsFile {
    * Empty when not declared: every swinging part's tip swings.
    */
   rests: string[];
+  /**
+   * Issue #320: the folds the scene means — a slot whose mesh turns a triangle
+   * over in an animation, the idle included (issue #333), on purpose (a sleeve
+   * hidden behind the body as the arm crosses it), each by slot and animation
+   * with the author's why.
+   * `ANIMATIONS_DO_NOT_FOLD` names each such fold with its why and does not
+   * hold it to the bar, and fails an entry whose slot does not fold in that
+   * animation, as rig-c refuses an exemption that exempts nothing. Empty when
+   * not declared: no fold in a named animation is meant.
+   */
+  may_fold: MayFold[];
+}
+
+/** One declared fold (issue #320): a slot, a named animation, and why the fold is the art's. */
+export interface MayFold {
+  slot: string;
+  animation: string;
+  why: string;
 }
 
 /** What `check --requirements` and `build --requirements` name, said once for the help and the refusals. */
@@ -257,7 +275,7 @@ export function readRequirements(path: string): RequirementsFile {
     problems.push({ code: 'REQUIREMENTS_FIELD', object, detail });
   };
   if (raw.spec !== REQUIREMENTS_SPEC) field(`${at} field "spec"`, `is ${JSON.stringify(raw.spec)}; ${JSON.stringify(REQUIREMENTS_SPEC)} is required`);
-  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests; note or *_note as a string; x-<name> as a record)');
+  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS, 'may_fold'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests, may_fold; note or *_note as a string; x-<name> as a record)');
   let fps = NaN;
   if (!(finite(raw.fps) && raw.fps > 0)) field(`${at} field "fps"`, `is ${JSON.stringify(raw.fps)}; a positive number of frames per second is required — every named animation is sampled at it, and there is no default`);
   else fps = raw.fps;
@@ -407,8 +425,31 @@ export function readRequirements(path: string): RequirementsFile {
   lists.rests.forEach((n, i) => {
     if (lists.not_swinging.includes(n)) field(`${at} field "rests"[${i}]`, `names "${n}", which "not_swinging" names too; a part declared not swinging is not measured, so there is no tip to hold at rest — leave it in one list`);
   });
+  // Issue #320: may_fold, a non-empty list of { slot, animation, why }, each pair once; which slots and animations they are is read against the rig by resolveRequirements.
+  const mayFold: MayFold[] = [];
+  if (raw.may_fold !== undefined) {
+    if (!Array.isArray(raw.may_fold) || raw.may_fold.length === 0) field(`${at} field "may_fold"`, `is ${JSON.stringify(raw.may_fold)?.slice(0, 60)}; a non-empty list of { "slot", "animation", "why" } is required when the field is given — leave it out to declare that no fold in a named animation is meant`);
+    else {
+      raw.may_fold.forEach((e, i) => {
+        const where = `${at} field "may_fold"[${i}]`;
+        if (!isRecord(e)) {
+          field(where, `is ${JSON.stringify(e)?.slice(0, 40)}; { "slot": <name>, "animation": <name>, "why": <text> } is required`);
+          return;
+        }
+        const before = problems.length;
+        for (const k of Object.keys(e)) if (!['slot', 'animation', 'why'].includes(k) && !freeKey(k, e[k])) field(`${where} field "${k}"`, 'is not a field a may_fold entry reads (slot, animation, why)');
+        for (const k of ['slot', 'animation', 'why'] as const) {
+          if (typeof e[k] !== 'string' || (e[k] as string).trim().length === 0) field(`${where} field "${k}"`, `is ${JSON.stringify(e[k])}; ${k === 'why' ? 'the reason the fold is the art\'s, in words, is required — an exception without one is a silenced bar' : `a ${k} name is required`}`);
+        }
+        if (problems.length !== before) return;
+        const entry: MayFold = { slot: e.slot as string, animation: e.animation as string, why: e.why as string };
+        if (mayFold.some((m) => m.slot === entry.slot && m.animation === entry.animation)) field(where, `declares slot "${entry.slot}" in animation "${entry.animation}" a second time; each pair is declared once`);
+        else mayFold.push(entry);
+      });
+    }
+  }
   refuseIfAny(problems);
-  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests };
+  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold };
 }
 
 // ---------------------------------------------------------------------------
@@ -541,6 +582,21 @@ export function resolveRequirements(file: RequirementsFile, rig: Record<string,
     }
   }
 
+  // Issues #320, #333: each declared fold names a slot that holds a mesh and an animation motion.json declares — the idle
+  // included, since ANIMATIONS_DO_NOT_FOLD reads every animation.
+  file.may_fold.forEach((m, i) => {
+    const object = `may_fold[${i}] (slot "${m.slot}", animation "${m.animation}")`;
+    if (!(m.animation in anims)) unresolved(object, `names animation "${m.animation}", which motion.json does not declare; it declares ${listed(animNames)}`);
+    const slots = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).map((s) => s.name);
+    if (!slots.includes(m.slot)) {
+      unresolved(object, `names slot "${m.slot}", which rig.json does not declare`);
+      return;
+    }
+    const meshes = meshAttachmentsOf(rig, m.slot);
+    if (typeof meshes === 'string') problems.push({ code: 'REQUIREMENTS_RESOLVES', object, detail: meshes });
+    else if (meshes.length === 0) problems.push({ code: 'REQUIREMENTS_MAY_FOLD', object, detail: `names slot "${m.slot}", which no skin in rig.json gives a mesh attachment; a region is one quad and cannot fold, so declaring it excepts nothing` });
+  });
+
   const root = bones.find((b) => b.name === rootBone);
   const measured = new Set(file.requirements.map((r) => r.animation));
   const placed = new Set<string>();
@@ -1009,8 +1065,14 @@ export function followLine(r: FollowRequirement, declared: Poses, released: Pose
   };
 }
 
-/** `stretch`: `TEXTURE_STRETCH`'s per-mesh figure for one mesh over the named animation's frames — its worst max(ratio, 1/ratio) and where. */
-export function stretchRequirementLine(r: StretchRequirement, meshes: readonly MeshRest[], frames: readonly GeometryPose[], p: Poses): RequirementLine {
+/**
+ * `stretch`: `TEXTURE_STRETCH`'s per-mesh figure for one mesh over the named animation's frames — its worst
+ * max(ratio, 1/ratio) and where. With `heldBy`, the line also carries `held_by` (issue #321): what the worst edge's two
+ * vertices hang on. `check` passes `edgeBonesText` (`src/check.ts`), the function `CHECK_TEXTURE_STRETCH` names them
+ * with since #314, so the two lines cannot drift; it is handed in rather than imported because `src/check.ts` imports
+ * this module.
+ */
+export function stretchRequirementLine(r: StretchRequirement, meshes: readonly MeshRest[], frames: readonly GeometryPose[], p: Poses, heldBy?: (edge: readonly number[]) => string): RequirementLine {
   const mesh = meshes.find((m) => m.slot === r.slot && m.attachment === r.attachment);
   if (mesh === undefined) return notMeasurable('stretch', r.animation, `geometry.json's rest pose holds no mesh "${r.attachment}" on slot "${r.slot}", so no frame shows it`);
   const [m] = stretchFigures([mesh], frames);
@@ -1032,6 +1094,7 @@ export function stretchRequirementLine(r: StretchRequirement, meshes: readonly M
     triangles: m.triangles,
     severity: round6(severity),
     worst: `triangle ${at.triangle} (vertices ${at.vertices.join(' ')}), edge ${at.edge.join('-')}, ratio ${round6(at.ratio)}`,
+    ...(heldBy === undefined ? {} : { held_by: heldBy(at.edge) }),
     at: fi < 0 ? `frame ${at.frame}` : frameText(p, fi),
     max_ratio: round6(m.max.ratio),
     min_ratio: round6(m.min.ratio),
@@ -1274,7 +1337,7 @@ function failText(r: Requirement, l: RequirementLine): string {
   if (r.kind === 'contact') return `largest distance ${String(l.largest_px)} px at ${String(l.at)}, between ${String(l.of)} and ${String(l.against)}`;
   if (r.kind === 'aim') return `largest angle ${String(l.largest_degrees)} degrees at ${String(l.at)}, between ${String(l.of)} and the line to ${String(l.against)}`;
   if (r.kind === 'range') return `least ${String(l.least_degrees)} degrees at ${String(l.least_at)}, greatest ${String(l.greatest_degrees)} at ${String(l.greatest_at)}`;
-  if (r.kind === 'stretch') return `max(ratio, 1/ratio) ${String(l.severity)} at ${String(l.at)}, ${String(l.worst)}`;
+  if (r.kind === 'stretch') return `max(ratio, 1/ratio) ${String(l.severity)} at ${String(l.at)}, ${String(l.worst)}${typeof l.held_by === 'string' ? `; ${l.held_by}` : ''}`;
   if (r.kind === 'seam') return `largest opening ${String(l.largest_px)} px at ${String(l.at)}, ${String(l.pair)}`;
   return `measured fraction ${String(l.fraction_measured)} over ${String(l.frames_counted)} frame(s) that reach the least drive`;
 }

package/src/rig.ts

@@ -682,7 +682,7 @@ export interface ContourMeshReport {
   /** Only when the mesh declared ribs (issue #188): what it declared and what was placed. Absent otherwise, so a mesh without ribs writes the row it always wrote. */
   ribs?: RibsRow;
   /** `maxEdge` only when the mesh declared it (issue #265), so a mesh without it writes the row it always wrote. */
-  params: { tolerance: number; margin: number; spacing: number; maxEdge?: number; budget: number | null; stray: number | null };
+  params: { tolerance: number; margin: number; spacing: number; maxEdge?: number; budget: number | null; stray: number | null; bridges?: true };
   contour: ContourReport;
   regions: Array<{ name: string; bone: string; reached: number; whole: number }>;
   /** Only under `rule: "heat"` (issue #161), as the lattice row's. */
@@ -1381,7 +1381,7 @@ export function buildRig(
         : { name: rg.name, shape: 'polygon', points: rg.points.map(([x, y]) => [x - ox, y - oy] as [number, number]), spacing: rg.spacing, band: rg.band },
     );
     const ribs = chainRibs(ribSpec.segments, ribSpec.ribs, ox, oy);
-    const cm = contourMesh(p.name, { width: w, height: h, alpha }, { threshold: ART_ALPHA, tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget, stray: spec.stray, regions: inPart, ...(ribs.length === 0 ? {} : { ribs }) });
+    const cm = contourMesh(p.name, { width: w, height: h, alpha }, { threshold: ART_ALPHA, tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget, stray: spec.stray, ...(spec.bridges === undefined ? {} : { bridges: spec.bridges }), regions: inPart, ...(ribs.length === 0 ? {} : { ribs }) });
     if (Array.isArray(cm)) {
       out.push(...cm);
       return null;
@@ -1455,12 +1455,12 @@ export function buildRig(
         bones: [...bones].sort(),
         max_influences: maxInfl,
         mean_influences: pyRound(infl / cm.vertices.length, 2),
-        art_coverage: pyRound(rep.coveredArtPixels / (rep.artPixels + rep.strayPixels), 5),
+        art_coverage: pyRound(rep.coveredArtPixels / (rep.artPixels + rep.strayPixels + (rep.bridges?.faint ?? []).reduce((t, f) => t + f.art, 0)), 5),
         mode: 'contour',
         ...(exponent === undefined ? {} : { exponent }),
         ...(declared === undefined ? {} : { influences: declared }),
         ...(ribSpec.ribs === undefined ? {} : { ribs: ribsRow(ribSpec.ribs, cm.ribs ?? []) }),
-        params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget ?? null, stray: spec.stray ?? null },
+        params: { tolerance: spec.tolerance, margin: spec.margin, spacing: spec.spacing, ...(spec.maxEdge === undefined ? {} : { maxEdge: spec.maxEdge }), budget: spec.budget ?? null, stray: spec.stray ?? null, ...(spec.bridges === undefined ? {} : { bridges: spec.bridges }) },
         contour: rep,
         regions: regions.map((rg, k) => ({ name: rg.name, bone: rg.bone, reached: reached[k], whole: whole[k] })),
         ...(heat === null ? {} : { heat: heatRow(heat) }),

package/src/scene.ts

@@ -92,7 +92,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { checkStage, gateThroughRigc, type Log } from './build.ts';
-import { ACCEPTABLE_BARS, BARS, barsNotMet, type CheckReport, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, type PackMode, requirementsNotPass, type RigcRunner } from './check.ts';
+import { ACCEPTABLE_BARS, barsNotMet, type CheckReport, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, type PackMode, requirementsNotPass, type RigcRunner } from './check.ts';
 import { CONSTRAINT_BONE_FIELDS, ROOT_BONE } from './config.ts';
 import { cropToSpineY } from './coords.ts';
 import { PartsError, type Problem, problemLine, refuseIfAny } from './errors.ts';
@@ -1421,7 +1421,7 @@ export function composeStage(input: ComposeInput, run: ComposeRunners, log: Log)
     log(`compose: stopped at check; the composed rig's check is PASS${acceptedLine} (the composed rig and scene.json are written; the scene is for looking, not shipping)`);
     return { stoppedAt: 'check', composed, check: report };
   }
-  log(`compose: PASS — ${report.bars.measured.length} of ${BARS.length} bar(s) measured; the packed atlas under ${join(input.out, 'check', 'build')} is the artifact`);
+  log(`compose: PASS — ${report.bars.measured.length} of ${report.bars.measured.length + report.bars.skipped.length} bar(s) measured; the packed atlas under ${join(input.out, 'check', 'build')} is the artifact`);
   return { stoppedAt: null, composed, check: report };
 }