@rig-c/parts 1.36.0 → 1.38.0

package/src/build.ts

@@ -70,7 +70,7 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { besideIdleLine, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
 import { type Cut, type Extend, type Limb, loadConfig, loadConfigAndAnimations, loadEarlyConfig, type Patch, type PlanEntry } from './config.ts';
 import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
@@ -492,6 +492,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
         ...(Object.keys(altLimbs).length > 0 ? { limbs: altLimbs, bones: altBones } : {}),
         ...(fields.scene === undefined ? {} : { scene: fields.scene }),
         ...(fields.armSplit !== undefined && altPlan.some((e) => e[1] === 'full' && (e[2] === 'handwear-r' || e[2] === 'handwear-l')) ? { armSplit: fields.armSplit } : {}),
+        ...(fields.headFaceUnderfill === undefined ? {} : { headFaceUnderfill: fields.headFaceUnderfill }),
         seamRule: input.seam,
         projectRule: input.project,
       });
@@ -569,10 +570,11 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   const pad = result.parts.single_run_pad;
   if (pad !== undefined) log(singleRunPadLine(input.full, pad));
   for (const p of result.parts.parts) {
+    const underfillSuffix = p.from === 'head:face' && (result.headFaceUnderfillPx ?? 0) > 0 ? ` underfill=${result.headFaceUnderfillPx}px(full:face)` : '';
     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)} ${driftShare(p.refused_drift_px, p.projected_core_px)} 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}${underfillSuffix}`,
     );
   }
   // Issue #256: one line per part from an author-made layer, so it never reads as See-through's. None without one.
@@ -1483,6 +1485,27 @@ export function sweepCheckLines(line: SweepLine): string[] {
   ];
 }
 
+/**
+ * The seam over every animation (issue #493) as the console prints it: the status, what was read, the floor and that
+ * it is not a bar, then one WARN line per pair and animation with a frame over the floor, and a line per pair rigc
+ * read nothing of (its SKIP) or the line could not read. A SKIP with nothing declared prints its reason alone.
+ */
+export function motionSeamLines(line: MotionSeamLine, plant: MotionSeamPlant = {}): string[] {
+  if (line.status === 'SKIP' && line.rows.length === 0 && line.pairs.every((p) => p.unread === undefined)) return [`${MOTION_SEAM_LINE}: SKIP — ${String(line.reason)}`];
+  const read = `${line.pairs.length} declared pair(s) in ${line.animations.length} animation(s) (${line.animations.join(', ')}), read by rigc render --seam at ${line.fps} fps on the build as played`;
+  const head =
+    line.status === 'SKIP'
+      ? `${MOTION_SEAM_LINE}: SKIP — ${String(line.reason)}; ${read}`
+      : `${MOTION_SEAM_LINE}: ${line.status} — ${read}: ${line.warnings} warning(s), never a bar; ${line.floor}`;
+  return [
+    head,
+    ...line.pairs.filter((p) => p.unread !== undefined).map((p) => `seam "${p.pair}" (${p.declared.join('; ')}): not read — ${String(p.unread)}`),
+    ...line.rows.filter((r) => r.status === 'skip').map((r) => `seam "${r.pair}" in "${r.animation}": SKIP — rigc read no band on any of the ${r.drawn} frame(s) both slots draw, so there is no seam to read`),
+    ...(plant.silent === true ? [] : line.rows.filter((r) => r.opens.length > 0).map(motionSeamWarnText)),
+    ...line.rows.filter((r) => r.opens.length === 0 && r.under_floor.length > 0).map((r) => `seam "${r.pair}" in "${r.animation}": under the floor — rigc names ${r.under_floor.length} frame(s) open ${frameRuns(r.under_floor)}, each opening one cell thick`),
+  ];
+}
+
 /** A requirement's line as the console prints it: its name and status, the reason first when NOT MEASURABLE, then its figures as check.json holds them. */
 export function requirementText(name: string, line: RequirementLine): string {
   const rest = Object.entries(line).filter(([k]) => k !== 'status' && k !== 'reason');
@@ -1541,6 +1564,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (limbs !== undefined) for (const [i, l] of limbCheckLines(limbs).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   const sweep = fig[SWEEP_LINE];
   if (sweep !== undefined) for (const [i, l] of sweepCheckLines(sweep).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
+  for (const [i, l] of motionSeamLines(r.motionSeam).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const name of REPORTED_LINES) log(`  ${judgementLine(name, fig[name])}`);
   if (fig.sets !== undefined) {
     for (const [setName, setFig] of Object.entries(fig.sets)) {
@@ -1558,7 +1582,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   for (const p of r.problems) log(failLine(p));
   const reqNotPass = r.requirements === null ? 0 : r.requirements.summary.declared - r.requirements.summary.pass;
   const notMet = r.requirements === null ? `${r.problems.length} bar(s) not met` : `${r.problems.length - reqNotPass} bar(s) not met, ${reqNotPass} declared requirement(s) not PASS`;
-  log(`${fig.PASS ? 'check: PASS' : `check: FAIL — ${notMet}`}; ${barsSummary(r)}`);
+  log(`${fig.PASS ? 'check: PASS' : `check: FAIL — ${notMet}`}; ${barsSummary(r)}${r.motionSeam.status === 'SKIP' ? '' : `; ${r.motionSeam.warnings} warning(s) (${MOTION_SEAM_LINE}, not a bar)`}`);
   return r;
 }
 

package/src/check.ts

@@ -125,7 +125,7 @@ import {
   type Toward,
   type WorldBox,
 } from './instruments.ts';
-import { type AlternatePartsRecord, type PartRecord, type PartsFile, readParts } from './parts.ts';
+import { type AlternatePartsRecord, type LimbRecord, type PartRecord, type PartsFile, readParts } from './parts.ts';
 import { poseRigBonesForDrawn, type RigBone, SETS_FILE } from './rig.ts';
 import { turnTwin } from './turn.ts';
 import {
@@ -1863,6 +1863,7 @@ export interface CheckFigures {
   [LIMB_LINE]?: LimbLine;
   /** Written only where parts.json holds a limb record with a `range` (issue #360): {@link SweepLine}. */
   [SWEEP_LINE]?: SweepLine;
+  [MOTION_SEAM_LINE]?: MotionSeamLine;
   RECOMPOSITE_HOLES: ReportedLine;
   /** Written only under `--source` (issue #77): the setup pose against the painting, REPORTED. */
   SETUP_POSE_VS_SOURCE?: ReportedLine;
@@ -2125,6 +2126,8 @@ export interface CheckReport {
    * reads the idle. Empty when the idle is alone.
    */
   besideIdle: string[];
+  /** `SEAM_OVER_MOTION` (issue #493): a warning, never a bar — in `check.json` only when a pair is declared; its SKIP is printed either way. */
+  motionSeam: MotionSeamLine;
 }
 
 /**
@@ -3154,6 +3157,249 @@ export function sweepLine(
   };
 }
 
+// ---------------------------------------------------------------------------
+// the seam over every animation (issue #493; the line is {@link MOTION_SEAM_LINE}'s)
+// ---------------------------------------------------------------------------
+
+/**
+ * `SEAM_OVER_MOTION` (issue #493): every declared neighbour pair read in every
+ * animation `motion.json` holds, the idle included, by rig-c's seam reading
+ * (`rigc render --seam`, rig-c 2.60.0) — a **warning, never a bar**. The
+ * owner's ruling (2026-10-18): a seam opening in motion may be intentional, so
+ * the line names the pair, the animation, the frames and the cells, and moves
+ * neither the exit status nor `check: PASS`; the summary counts it apart from
+ * the bars.
+ *
+ * The pairs are the ones the inputs declare and nothing else: each limb's
+ * consecutive segments in `parts.json` (`config.limbs`, the upper and the
+ * segment below each joint) and, under `--requirements`, each `seam`
+ * requirement's part and neighbour. None declared, the line is a SKIP naming
+ * why, never a pass, and `check.json` carries no key for it.
+ *
+ * **The floor** ({@link openingOverFloor}): a frame's gap or ghost is reported
+ * when it holds more cells than its box is long — when it is thicker than one
+ * cell. rigc counts a cell drawn when the renderer paints its centre at half
+ * opacity or more, so a boundary that moves by less than a cell flips the
+ * cells along it in or out: a line of cells one deep, scattered or joined,
+ * holds at most as many cells as its box's longer side. A hole of any area
+ * holds more. The rule types no number; it is read off rigc's own cell and
+ * box, and measured, not chosen: on `examples/wind`'s idle rigc names 43
+ * openings over its six limb pairs (28 and 15 frames of the two elbows, 1 to
+ * 5 cells, boxes up to 17 cells long) and every one is one cell thick; on
+ * rig-c's `gallery/walk` its 13 joint cracks of 1 to 3 cells are too; the
+ * ghost rig-c's own reading names on a skirt swung clear of a leg (1564 cells
+ * in a box 92 long) is far over it.
+ */
+export const MOTION_SEAM_LINE = 'SEAM_OVER_MOTION';
+
+/** The seam reading's scratch build and renders, under `--out`; removed before the stage returns. */
+const MOTION_SEAM_SCRATCH = '_seam_motion';
+
+/** rig-c's seam reading: the file it writes in each set's directory, and its format tag. */
+export const SEAM_READING_FILE = 'seam.json';
+export const SEAM_READING_SPEC = 'rigc-seam/1';
+
+/** The floor as the console and `check.json` state it. */
+export const MOTION_SEAM_FLOOR = "a frame opens when its gap or its ghost holds more cells than its box is long (rig-c's cell, its box's longer side) — thicker than one cell; a crack one cell deep is the half-opacity cut moving by less than a cell, and is not reported";
+
+/** One declared pair: the two slots, and every declaration that names it. */
+export interface MotionSeamPair {
+  /** `"<a>|<b>"`, the two slots in the order declared first. */
+  pair: string;
+  a: string;
+  b: string;
+  declared: string[];
+  /** Why the pair is not read: a slot `rig.json` does not have. */
+  unread?: string;
+}
+
+/** One pair in one animation, as the floor reads rigc's file. */
+export interface MotionSeamRow {
+  pair: string;
+  animation: string;
+  /** rigc's: `skip` when no frame has a band to read — nothing measured, not a seam that held. */
+  status: 'read' | 'skip';
+  /** Frames both slots draw, and of those the frames read (rigc's `drawn`, `banded`). */
+  drawn: number;
+  banded: number;
+  /** The frames over the floor, ascending: the warning's frames. */
+  opens: number[];
+  /** Beside `opens`, frame by frame: the most cells of either kind on that frame. */
+  px: number[];
+  /** The most cells of either kind on any frame over the floor; 0 when none is. */
+  max_px: number;
+  /** The frames rigc names open whose every opening is one cell thick: under the floor, not reported. */
+  under_floor: number[];
+}
+
+/** The line: `WARN` with at least one warning, `CLEAR` with none, `SKIP` with nothing declared or nothing to read. */
+export interface MotionSeamLine {
+  status: 'WARN' | 'CLEAR' | 'SKIP';
+  reason?: string;
+  fps: number;
+  floor: string;
+  pairs: MotionSeamPair[];
+  animations: string[];
+  /** Rows with a frame over the floor: the WARN lines. */
+  warnings: number;
+  rows: MotionSeamRow[];
+}
+
+/**
+ * The neighbour pairs the inputs declare, in their order: each limb's
+ * consecutive segments (`parts.json`'s limb records, by segment), then each
+ * `seam` requirement's part and neighbour. A pair named twice, in either
+ * order, is one pair with both declarations.
+ */
+export function motionSeamPairs(parts: PartsFile, seams: ReadonlyArray<{ name: string; part: string; neighbour: string }>): MotionSeamPair[] {
+  const out: MotionSeamPair[] = [];
+  const add = (a: string, b: string, declared: string): void => {
+    const hit = out.find((p) => (p.a === a && p.b === b) || (p.a === b && p.b === a));
+    if (hit !== undefined) hit.declared.push(declared);
+    else out.push({ pair: `${a}|${b}`, a, b, declared: [declared] });
+  };
+  const limbs: string[] = [];
+  for (const p of parts.parts) if (p.limb !== undefined && !limbs.includes(p.limb.name)) limbs.push(p.limb.name);
+  for (const limb of limbs) {
+    const segs = parts.parts.filter((p) => p.limb?.name === limb).sort((x, y) => (x.limb as LimbRecord).segment - (y.limb as LimbRecord).segment);
+    for (let i = 1; i < segs.length; i++) {
+      const lower = segs[i].limb as LimbRecord;
+      add(segs[i - 1].name, segs[i].name, `config.limbs.${limb} segment ${lower.segment}${lower.joint === undefined ? '' : `, joint "${lower.joint}"`}`);
+    }
+  }
+  for (const r of seams) add(r.part, r.neighbour, `requirement "${r.name}" (seam)`);
+  return out;
+}
+
+/** A frame's opening of one kind over the floor ({@link MOTION_SEAM_FLOOR}): more cells than its box, in cells, is long. */
+export function openingOverFloor(hit: { px: number; cell: number; box: readonly [number, number, number, number] }): boolean {
+  const long = Math.round(Math.max(hit.box[2] - hit.box[0], hit.box[3] - hit.box[1]) / hit.cell);
+  return hit.px > long;
+}
+
+/** Frame indices as runs, `[0-6, 8, 13]`: the form rigc prints a frame list in. */
+export function frameRuns(frames: readonly number[]): string {
+  const runs: string[] = [];
+  for (let i = 0; i < frames.length; ) {
+    let j = i;
+    while (j + 1 < frames.length && frames[j + 1] === frames[j] + 1) j++;
+    runs.push(i === j ? String(frames[i]) : `${frames[i]}-${frames[j]}`);
+    i = j + 1;
+  }
+  return `[${runs.join(', ')}]`;
+}
+
+/**
+ * A planted defect, for the suite's mutants only (`SO` controls in `selftest.ts`). Every caller in `src/` passes none.
+ */
+export interface MotionSeamPlant {
+  /** Report every frame rigc names open, the one-cell cracks included: the floor removed. */
+  noFloor?: true;
+  /** Print the line's head and none of its WARN lines: the warning suppressed. */
+  silent?: true;
+}
+
+type SeamHitRead = { index: number; px: number; cell: number; box: [number, number, number, number] };
+
+/**
+ * The rows of one `rigc render --seam` run over every animation: `frames.json`
+ * names each set's directory, each `seam.json` (`rigc-seam/1`) its pairs in
+ * the flag's order. Refuses (`FRAMES_SIDECAR`), every problem at once, a set or
+ * file that is missing, a file that is not the animation's or not at the rate
+ * asked, a pair out of the flag's order, and a field of the wrong shape.
+ */
+export function readMotionSeams(dir: string, animations: readonly string[], fps: number, pairs: readonly MotionSeamPair[], plant: MotionSeamPlant = {}): MotionSeamRow[] {
+  const problems: Problem[] = [];
+  const bad = (object: string, detail: string): void => {
+    problems.push({ code: 'FRAMES_SIDECAR', object, detail });
+  };
+  const rows: MotionSeamRow[] = [];
+  const sidecar = readJson(join(dir, 'frames.json'), problems);
+  const sets = sidecar !== null && Array.isArray(sidecar.sets) ? sidecar.sets.filter(isRecord) : [];
+  const nums = (v: unknown): v is number[] => Array.isArray(v) && v.every((x) => typeof x === 'number');
+  const hitOf = (h: unknown): SeamHitRead | null =>
+    isRecord(h) && typeof h.index === 'number' && typeof h.px === 'number' && typeof h.cell === 'number' && h.cell > 0 && nums(h.box) && h.box.length === 4 ? { index: h.index, px: h.px, cell: h.cell, box: [h.box[0], h.box[1], h.box[2], h.box[3]] } : null;
+  for (const animation of animations) {
+    const set = sets.find((x) => x.animation === animation);
+    if (set === undefined || typeof set.dir !== 'string') {
+      bad(join(dir, 'frames.json'), `names no frame set for animation ${JSON.stringify(animation)}; \`rigc render --seam\` over the build writes one per animation`);
+      continue;
+    }
+    const path = join(dir, set.dir, SEAM_READING_FILE);
+    const file = readJson(path, problems);
+    if (file === null) continue;
+    if (file.spec !== SEAM_READING_SPEC) bad(path, `spec is ${JSON.stringify(file.spec)}; "${SEAM_READING_SPEC}" is required`);
+    if (file.animation !== animation) bad(path, `animation is ${JSON.stringify(file.animation)}; ${JSON.stringify(animation)} is required`);
+    if (file.fps !== fps) bad(path, `fps is ${JSON.stringify(file.fps)}; ${fps}, the rate asked for, is required`);
+    const read = Array.isArray(file.pairs) ? file.pairs : [];
+    if (read.length !== pairs.length) bad(path, `holds ${read.length} pair(s); the ${pairs.length} asked for, in the flag's order, are required`);
+    pairs.forEach((want, i) => {
+      const p = read[i];
+      const at = `${path} pairs[${i}]`;
+      if (!isRecord(p) || p.a !== want.a || p.b !== want.b) {
+        bad(at, `is ${JSON.stringify(isRecord(p) ? `${String(p.a)}|${String(p.b)}` : p)}; "${want.pair}", the flag's entry ${i}, is required`);
+        return;
+      }
+      if ((p.status !== 'read' && p.status !== 'skip') || typeof p.drawn !== 'number' || typeof p.banded !== 'number' || !nums(p.opens)) {
+        bad(at, 'is not { a, b, drawn, banded, status, opens, maxPx, gap, ghost } as rigc-seam/1 writes it');
+        return;
+      }
+      const over = new Map<number, number>();
+      for (const kind of ['gap', 'ghost'] as const) {
+        const k = p[kind];
+        const frames = isRecord(k) && Array.isArray(k.frames) ? k.frames.map(hitOf) : null;
+        if (frames === null || frames.some((h) => h === null)) {
+          bad(`${at} ${kind}`, 'is not { frames: [{ index, px, cell, box }…], spans, worst } as rigc-seam/1 writes it');
+          return;
+        }
+        for (const h of frames as SeamHitRead[]) if (plant.noFloor === true || openingOverFloor(h)) over.set(h.index, Math.max(over.get(h.index) ?? 0, h.px));
+      }
+      const opens = [...over.keys()].sort((x, y) => x - y);
+      rows.push({
+        pair: want.pair,
+        animation,
+        status: p.status,
+        drawn: p.drawn,
+        banded: p.banded,
+        opens,
+        px: opens.map((f) => over.get(f) ?? 0),
+        max_px: opens.reduce((m, f) => Math.max(m, over.get(f) ?? 0), 0),
+        under_floor: p.opens.filter((f) => !over.has(f)),
+      });
+    });
+  }
+  refuseIfAny(problems);
+  return rows;
+}
+
+/** The line from its rows: WARN when a row has a frame over the floor, CLEAR when none has, SKIP when no row was read. */
+export function motionSeamLine(pairs: MotionSeamPair[], animations: string[], fps: number, rows: MotionSeamRow[], reason?: string): MotionSeamLine {
+  const warnings = rows.filter((r) => r.opens.length > 0).length;
+  const read = rows.some((r) => r.status === 'read');
+  const skipWhy =
+    reason ??
+    (read
+      ? undefined
+      : pairs.every((p) => p.unread !== undefined)
+        ? `no declared pair is read: ${pairs.map((p) => `"${p.pair}" ${String(p.unread)}`).join('; ')}`
+        : `rigc read no band on any frame of any declared pair in any animation — nothing measured, which is not a seam that held`);
+  return {
+    status: skipWhy !== undefined ? 'SKIP' : warnings > 0 ? 'WARN' : 'CLEAR',
+    ...(skipWhy === undefined ? {} : { reason: skipWhy }),
+    fps,
+    floor: MOTION_SEAM_FLOOR,
+    pairs,
+    animations,
+    warnings,
+    rows,
+  };
+}
+
+/** One warning as the console prints it (issue #493's form, the floor's clause after it). */
+export function motionSeamWarnText(r: MotionSeamRow): string {
+  return `WARN seam "${r.pair}" opens on ${r.opens.length} frame(s) ${frameRuns(r.opens)} max ${r.max_px} px in "${r.animation}" — over the one-cell floor${r.under_floor.length === 0 ? '' : `, ${r.under_floor.length} more frame(s) one cell thick not reported`}`;
+}
+
 /**
  * One `CHECK_RIGC_GREEN` per line that says why `rigc <what>` was not green:
  * its FAIL and compile-error lines, or, when there are none, {@link causeLines}.
@@ -3570,6 +3816,37 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     }
   }
 
+  // 3e. every declared neighbour pair read in every animation by rigc's seam reading (issue #493): a warning, never a
+  // bar — the build as played, at the idle's rate; SKIP, named, with no pair declared or no animation to read
+  let motionSeam: MotionSeamLine;
+  {
+    const fps = IDLE_FPS;
+    const seamReqs = reqFile === null || seams === null ? [] : reqFile.requirements.flatMap((r) => (r.kind === 'seam' && seams?.has(r.name) === true ? [{ name: r.name, part: r.part, neighbour: r.neighbour }] : []));
+    const pairs = inp.parts === null ? [] : motionSeamPairs(inp.parts, seamReqs);
+    const slotNames = new Set((Array.isArray(inp.rig.slots) ? inp.rig.slots : []).filter(isRecord).map((sl) => String(sl.name)));
+    for (const p of pairs) {
+      const missing = [p.a, p.b].filter((n) => !slotNames.has(n));
+      if (missing.length > 0) p.unread = `names ${missing.map((n) => `slot "${n}"`).join(' and ')}, which rig.json does not have`;
+    }
+    const read = pairs.filter((p) => p.unread === undefined);
+    if (inp.parts === null) motionSeam = motionSeamLine([], animationNames, fps, [], inp.noParts ?? 'no parts.json');
+    else if (pairs.length === 0) motionSeam = motionSeamLine([], animationNames, fps, [], 'no neighbour pair is declared: parts.json holds no limb segment below a joint (config.limbs) and no --requirements seam names two parts');
+    else if (animationNames.length === 0) motionSeam = motionSeamLine(pairs, [], fps, [], 'motion.json holds no animation to read the declared pairs in');
+    else if (read.length === 0) motionSeam = motionSeamLine(pairs, animationNames, fps, []);
+    else {
+      const seamMotionDir = join(out, MOTION_SEAM_SCRATCH);
+      rmSync(seamMotionDir, { recursive: true, force: true });
+      try {
+        const list = read.map((p) => `${p.a}:${p.b}`).join(',');
+        const r = rigc(['render', '--candidate', buildDir, '--seam', list, '--fps', String(fps), '--max', String(FOLD_RENDER_MAX), '--out', seamMotionDir]);
+        if (r.status !== 0) refuseIfAny(rigcFailed(`render --seam ${list} --fps ${fps}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+        motionSeam = motionSeamLine(pairs, animationNames, fps, readMotionSeams(seamMotionDir, animationNames, fps, read));
+      } finally {
+        rmSync(seamMotionDir, { recursive: true, force: true });
+      }
+    }
+  }
+
   // 4. the setup pose as a one-key throwaway animation — the seam reads it against the parts, the source line against
   // the painting — and, beside it, the same pose with the eyes shut
   let seam: SeamFigures | null = null;
@@ -3749,6 +4026,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     ...(stress === null ? {} : { [STRESS_LINE]: stress }),
     ...(limbs === null ? {} : { [LIMB_LINE]: limbs }),
     ...(sweep === null ? {} : { [SWEEP_LINE]: sweep }),
+    ...(motionSeam.pairs.length === 0 ? {} : { [MOTION_SEAM_LINE]: motionSeam }),
     RECOMPOSITE_HOLES: inp.parts === null ? { status: 'SKIP', reason: inp.noParts ?? '' } : holesLine(inp.parts),
     ...(sourceRead === null ? {} : { [SOURCE_LINE]: sourceRead }),
     ...(Object.keys(skipped).length === 0 ? {} : { skipped }),
@@ -3832,6 +4110,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     written,
     requirements: reqBlock,
     besideIdle: named,
+    motionSeam,
   };
 }
 

package/src/config.ts

@@ -92,7 +92,7 @@ import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { edgeLength } from './length.ts';
-import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
+import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, scaledPoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
 import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
 import { EAR_DEPTH_RANGE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
 import { FLOOR_FORMS, type FloorForm, type MeshInfluences } from './weights.ts';
@@ -267,6 +267,8 @@ export interface Assemble {
   patches?: Patch[];
   cuts?: Cut[];
   alternates?: AlternateSetConfig[];
+  /** Issue #492: composite full:face under head:face on the head canvas to fill transparent holes inside the face silhouette. */
+  head_face_underfill?: boolean;
 }
 
 export interface SingleBone {
@@ -1140,7 +1142,7 @@ export interface PaintConfig {
 export interface EarlyConfig {
   key: string;
   seethrough: SeeThrough;
-  assemble: { rig_scale: number };
+  assemble: { rig_scale: number; head_face_underfill?: boolean };
 }
 
 /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
@@ -1199,8 +1201,13 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'layers') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     if ('assemble' in t) {
-      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates']);
-      if (a !== null && 'rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
+      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill']);
+      if (a !== null) {
+        if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
+        if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
+          c.fail('CONFIG_FIELD_TYPE', 'config.assemble.head_face_underfill', `is ${show(a.head_face_underfill)}; true or false is required`);
+        }
+      }
     }
   }
   if (door === 'assemble') {
@@ -1223,7 +1230,10 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if ('cloth' in t) checkCloth(c, t.cloth);
   const pose = base === null ? null : poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
-  return { config: raw as PaintConfig | EarlyConfig | AssembleConfig, pose };
+  const config = raw as PaintConfig | EarlyConfig | AssembleConfig;
+  const controlSkel = resolveControlSkeleton(t.generation, pose);
+  if (controlSkel !== undefined) controlSkeletons.set(config, controlSkel);
+  return { config, pose };
 }
 
 export function loadEarlyConfig(path: string, door: 'paint'): PaintConfig;
@@ -1243,6 +1253,40 @@ export function loadPaintConfig(path: string): { config: PaintConfig; pose: Cont
   return { config: config as PaintConfig, pose };
 }
 
+/**
+ * Issue #490: the control skeleton `config.generation.control.skeleton` names,
+ * with its points on the `generation.latent` canvas (`[w, h]`, x right, y down).
+ */
+export interface ControlSkeleton {
+  latent: readonly [number, number];
+  points: PosePoints;
+}
+
+const controlSkeletons = new WeakMap<object, ControlSkeleton>();
+
+function resolveControlSkeleton(gen: Json, pose: ControlPose | null): ControlSkeleton | undefined {
+  if (!isPlainObject(gen) || !isPlainObject(gen.control)) return undefined;
+  const l = gen.latent;
+  if (!(Array.isArray(l) && l.length === 2 && typeof l[0] === 'number' && typeof l[1] === 'number' && l[0] > 0 && l[1] > 0)) return undefined;
+  const latent: readonly [number, number] = [l[0], l[1]];
+  if (pose !== null) return { latent, points: pose.points };
+  const skel = gen.control.skeleton;
+  if (isSkeletonName(skel)) return { latent, points: scaledPoints(skel, latent[0], latent[1]) };
+  return undefined;
+}
+
+/**
+ * Return the {@link ControlSkeleton} resolved for a loaded or parsed config
+ * (`loadEarlyConfig`, `loadConfig`, `parseEarlyConfig`, `parseConfig`), or
+ * computed from an inline `generation.control.skeleton` built-in when present.
+ */
+export function controlSkeletonOf(cfg: object): ControlSkeleton | undefined {
+  const cached = controlSkeletons.get(cfg);
+  if (cached !== undefined) return cached;
+  const gen = (cfg as { generation?: unknown }).generation;
+  return resolveControlSkeleton(gen, null);
+}
+
 /** The pose file a checked `generation` block's control names, read relative to `base`; null for a built-in, an absent control, or a block already refused. */
 function poseBeside(c: Check, gen: Json, base: string): ControlPose | null {
   if (!isPlainObject(gen) || !isPlainObject(gen.control)) return null;
@@ -1388,9 +1432,12 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
     checkFaceAnimationBand(c, animations, hasAltFace, t.turn, attached);
     checkAnimationSetKeys(c, animations, t.assemble, new Set<string>([...parts, ...patches, ...cuts, ...(limbs?.parts.keys() ?? [])]));
   }
-  if (base !== null) poseBeside(c, t.generation, base);
+  const pose = base === null ? null : poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
-  return { config: raw as CharacterConfig, animations };
+  const config = raw as CharacterConfig;
+  const controlSkel = resolveControlSkeleton(t.generation, pose);
+  if (controlSkel !== undefined) controlSkeletons.set(config, controlSkel);
+  return { config, animations };
 }
 
 /**
@@ -1791,13 +1838,16 @@ function checkRunTag(c: Check, path: string, run: Json, tag: Json): void {
  */
 function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
   const required = sectionRequired(door, 'assemble');
-  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates']);
+  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill']);
   if (a === null) return { parts: [], patches: [], cuts: [] };
   if (required.includes('plan') && !('plan' in a)) {
     c.fail('CONFIG_FIELD_PRESENT', 'config.assemble.plan', 'is absent and required; `assemble --propose-plan` prints one from the two runs — paste its plan and extend_below_crop into config.assemble');
   }
   const p = 'config.assemble';
   if ('rig_scale' in a) c.number(`${p}.rig_scale`, a.rig_scale, 'positive');
+  if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
+    c.fail('CONFIG_FIELD_TYPE', `${p}.head_face_underfill`, `is ${show(a.head_face_underfill)}; true or false is required`);
+  }
   const parts: string[] = [];
   if ('plan' in a && c.array(`${p}.plan`, a.plan, true)) {
     const seenPart = new Map<string, number>();