rig-parts 2.3.0 → 2.4.0

package/src/build.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_SEAM_RULE } from './seamrule.ts';
 import { SETUP_PAINTING_LINE, setupPaintingLines } from './setuppainting.ts';
+import { boundaryColourLines } from './boundarycolour.ts';
 import { writeMaterialSources } from './cutmaterialio.ts';
 import { CUT_MATERIAL_LINE, CUT_MATERIAL_SOURCES, materialLines } from './cutmaterial.ts';
 import { ART_JOINT_LINE, artJointLines } from './artjoints.ts';
@@ -55,7 +56,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, type ExcludedCount, excludedLines, setExclusions, islandLines, setIslandSources, type IslandCount, hiddenLines, SINGLE_RUN_FACE_TAGS, singleRunHeadBox, softOcclusionLine, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeKindsLine, holeLines, measureRecomposite, type ProjectRule, recomposite, recompositeRecord, scenePhrase, type SeamRule, sourceInRig, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, type ExcludedCount, excludedLines, setExclusions, islandLines, setIslandSources, type IslandCount, hiddenLines, SINGLE_RUN_FACE_TAGS, singleRunHeadBox, softOcclusionLine, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeKindsLine, holeLines, measurePinholes, measureRecomposite, pinholeProblems, pinholesLine, type ProjectRule, recomposite, recompositeRecord, scenePhrase, type SeamRule, sourceInRig, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, prepareComparison, type ReplayCandidate, runComparison, runPreparedComparison, sourceSelfFailure, stimulusMotion, withStimulus } from './automotion.ts';
@@ -82,9 +83,11 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, checkSummaryLine, inputFileRecord, type InputFileRecord, CLOTH_LINE, type ClothLine, clothWarnText, figureOpeningLines, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamWarnText, motionJointContactLines, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, environmentLine, 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, readCheckEnvironment, readWindBand, 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, WIND_BAND_LINE, windBandLines } from './check.ts';
+import { besideIdleLine, checkSummaryLine, inputFileRecord, type InputFileRecord, CLOTH_LINE, type ClothLine, clothWarnText, figureOpeningLines, frameRuns, MOTION_SEAM_LINE, type MotionSeamLine, type MotionSeamPlant, motionSeamRequiredLine, motionSeamWarnText, motionJointContactLines, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, SWEEP_LINE, type SweepLine, buildGateLines, causeLines, environmentLine, 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, readCheckEnvironment, readWindBand, 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, WIND_BAND_LINE, windBandLines } from './check.ts';
 import { type Cut, type Extend, type Limb, loadConfigAndAnimations, loadConfigWithBytes, loadEarlyConfig, type Patch, type PlanEntry } from './config.ts';
 import { coreCompileGuideLine, failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
+import { editedConfigImages, editedRunImages, missingReceipts, readEditorReceipts } from './editreceipt.ts';
+import { untracedPartSources } from './partsource.ts';
 import type { MeshQualityReport, MotionSchedule } from '@rig-c/core/mesh';
 import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
@@ -98,7 +101,7 @@ import { type Mask, newMask } from './raster/types.ts';
 import { type OtherLimbs, splitLines, capOwnershipLines, type SplitCount } from './assemble.ts';
 import type { BoneEntry } from './config.ts';
 import { OPAQUE_ALPHA_ABOVE } from './layers.ts';
-import { readRequirements, type RequirementLine, summaryText } from './requirements.ts';
+import { pinholesRequired, readRequirements, type RequirementLine, summaryText } from './requirements.ts';
 import { type AutoMeshReport, buildRig, DEFAULT_IDLE_KEYS, type FaceAxis, type IdleKeys, type MeshReport, type RigCommand, rigJsonText, type RigOutput, type RigSpec, SETS_FILE, type StrayCleared, type TurnRow } from './rig.ts';
 import { KEYPOINT_NAMES, type KeypointName, type PosePoints } from './skeleton.ts';
 import { AUTHOR_NO_ROLE, isAuthorTag } from './tags.ts';
@@ -324,13 +327,21 @@ export function frontOrdered<T extends { record: { name: string } }>(items: read
 
 /** Read, assemble, and write only after every refusal has had its chance. Throws a PartsError on a refusal, having written nothing. */
 export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs, log: Log): AssembleResult {
-  const materialAsked = input.requirements === undefined ? false : readRequirements(input.requirements).cut_material !== undefined;
+  const requirementsFile = input.requirements === undefined ? null : readRequirements(input.requirements);
+  const materialAsked = requirementsFile?.cut_material !== undefined;
+  // Issue #944: the pinhole bar is measured only when the requirements file declares it required.
+  const pinholesAsked = requirementsFile !== null && pinholesRequired(requirementsFile);
   // The early door: assemble runs before propose has drafted bones, meshes,
   // regions and motion, so it requires only what it reads (issue #20).
   const cfg = loadEarlyConfig(input.config, 'assemble');
   const seam = input.seam ?? cfg.assemble.seam ?? DEFAULT_SEAM_RULE;
   const src = readSource(input.source);
-  const runs = applyTakenLayers(readRuns(input.full, input.head), src, cfg, input.config);
+  const read = readRuns(input.full, input.head);
+  // Issue #946: every declared receipt is held to its file, and under `required` every edited image needs one, before anything is assembled.
+  const receipts = readEditorReceipts(cfg.assemble.editor_receipts, input.config);
+  // Issue #947: under `trace_parts`, a shape drawn in the config through a part's pixels is refused with them.
+  refuseIfAny([...receipts.problems, ...missingReceipts(receipts, [...editedRunImages(read), ...editedConfigImages(input.config, cfg.assemble.cuts ?? [], cfg.limbs)]), ...untracedPartSources(cfg)]);
+  const runs = applyTakenLayers(read, src, cfg, input.config);
   for (const note of runs.notes) log(`note: ${note}`);
   const fields = stageFields(cfg, runs.single ? { w: src.width, h: src.height } : null);
   const under = readUnders(input.config, fields.cuts);
@@ -489,6 +500,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
       if (invalidFocus.length > 0) { altProblems.push(...invalidFocus); continue; }
     }
     const altRuns = readRuns(alt.full, alt.head ?? null);
+    altProblems.push(...missingReceipts(receipts, [...editedRunImages(altRuns, `alternate set "${alt.name}" `), ...editedConfigImages(input.config, alt.cuts ?? [], undefined, `${alt.at}.cuts`)]));
     const hidesSet = new Set(alt.hides ?? []);
     const declaredSlots = alt.parts !== undefined ? alt.parts.filter((p) => !hidesSet.has(p)) : baseSlots.filter((p) => !hidesSet.has(p));
     const coveredSet = new Set(declaredSlots);
@@ -759,6 +771,10 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
       assetIndices.set(file, index);
     }
   });
+  // Issue #944: under pinholes.required, every pinhole of the base set's flat parts stack is refused by name, with the
+  // alternate sets' refusals, before anything is written.
+  const pinholes = pinholesAsked ? measurePinholes(sourceInRig(src, result.parts.rig_size[0], result.parts.rig_size[1]), result.images) : null;
+  if (pinholes !== null) altProblems.push(...pinholeProblems(pinholes, input.requirements as string));
   refuseIfAny(altProblems);
   if (altBuilt.length > 0) {
     result.parts.alternates = altBuilt.map((b) => b.record);
@@ -829,6 +845,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   for (const l of holeLines(result.figures, scene)) log(l);
   if (result.figures.uncoveredErrorPx > 0) log(holeKindsLine(result.holeKinds, scene));
   for (const u of result.uncovered) log(uncoveredLine(u, scene));
+  log(pinholesLine(pinholes, altBuilt.map((b) => b.record.name)));
   for (const d of result.drift) log(driftLine(d));
   for (const d of result.softOcclusion ?? []) log(softOcclusionLine(d));
   // Issue #588: per subset set, one line per limb part cut from a layer of more than one island, then (issue #587) one
@@ -1943,6 +1960,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   const sweep = fig[SWEEP_LINE];
   if (sweep !== undefined) for (const [i, l] of sweepCheckLines(sweep, r.sweepSteps).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const [i, l] of motionSeamLines(r.motionSeam).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
+  if (r.motionSeam.required !== undefined) log(`  ${motionSeamRequiredLine(r.motionSeam.required)}`);
   for (const [i, l] of figureOpeningLines(r.figureOpenings).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const [i, l] of clothLines(r.cloth).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const name of REPORTED_LINES) log(`  ${judgementLine(name, fig[name])}`);
@@ -1961,6 +1979,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (artJoints !== undefined) for (const line of artJointLines(artJoints)) log(`  ${line}`);
   const setupPainting = fig[SETUP_PAINTING_LINE];
   if (setupPainting !== undefined) for (const line of setupPaintingLines(setupPainting)) log(`  ${line}`);
+  for (const line of boundaryColourLines(r.boundaryColour)) log(`  ${line}`);
   if (r.requirements !== null) {
     for (const [name, line] of Object.entries(r.requirements.lines)) log(`  ${requirementText(name, line)}`);
     log(`  ${summaryText(r.requirements.summary)}`);

package/src/check.ts

@@ -2,6 +2,7 @@ import { SETUP_PAINTING_LINE, UNDECLARED_SETUP_PAINTING_REASON, setupPaintingBou
 import { readMaterialSources } from './cutmaterialio.ts';
 import { CUT_MATERIAL_LINE, checkJointMaterial, type MaterialLine } from './cutmaterial.ts';
 import { ART_JOINT_LINE, artJointLine, type ArtJointLine } from './artjoints.ts';
+import { BOUNDARY_COLOUR_LINE, BOUNDARY_COLOUR_UNMEASURED_CODE, measureBoundaryColour, type BoundaryColourMeasured } from './boundarycolour.ts';
 import { baseAnchorMoves, type AnchorRegion } from './baseanchor.ts';
 /**
  * The check stage: build a rig through rig-c, gate it under both
@@ -164,6 +165,7 @@ import {
   resolveRequirements,
   rigFacts,
   placedArt,
+  seamOverMotionRequired,
   type PosedAttachment,
   resolveSeams,
   type SeamFrame,
@@ -1927,7 +1929,7 @@ export interface SeamStateBounds {
  * different API. Importing check, or constructing a root-free reader, loads none.
  */
 type OfficialRenderer = typeof import('@rig-c/core/render-shared');
-function officialRenderer(): OfficialRenderer {
+export function officialRenderer(): OfficialRenderer {
   const require = createRequire(import.meta.url);
   const coreRoot = dirname(require.resolve('@rig-c/core/package.json'));
   let runtimePresent = false;
@@ -2736,6 +2738,8 @@ export interface CheckFigures {
   /** Under --source: the declared observation, or an explicit undeclared SKIP. */
   [SETUP_PAINTING_LINE]?: SetupPaintingObservation;
   [CUT_MATERIAL_LINE]?: MaterialLine;
+  /** Issue #942: only when requirements declares boundary_colour; undeclared writes no key and prints a SKIP. */
+  [BOUNDARY_COLOUR_LINE]?: BoundaryColourMeasured;
   PASS: boolean;
 }
 
@@ -2982,12 +2986,12 @@ export function barsNotMet(fig: Readonly<Record<string, unknown>>): string[] {
     isRecord(fig.sets) &&
     Object.values(fig.sets).some((s) => isRecord(s) && typeof s.seam_mean === 'number' && typeof s.seam_px_over_40 === 'number' && seamFails(s.seam_mean, s.seam_px_over_40, typeof s.seam_frame_scale === 'number' ? s.seam_frame_scale : 1));
   if ((typeof fig.seam_mean === 'number' && typeof fig.seam_px_over_40 === 'number' && seamFails(fig.seam_mean, fig.seam_px_over_40, scale)) || setFailed) out.push('seam');
-  for (const n of [...JUDGEMENT_LINES, FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, ART_JOINT_LINE, CUT_MATERIAL_LINE]) {
+  for (const n of [...JUDGEMENT_LINES, FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, ART_JOINT_LINE, CUT_MATERIAL_LINE, BOUNDARY_COLOUR_LINE]) {
     const l = fig[n];
     if (typeof l === 'object' && l !== null && (l as { status?: unknown }).status === 'FAIL') out.push(n);
   }
   const motion = fig[MOTION_SEAM_LINE];
-  if (isRecord(motion) && isRecord(motion.roots) && motion.roots.status === 'FAIL') out.push(MOTION_SEAM_LINE);
+  if (isRecord(motion) && ((isRecord(motion.roots) && motion.roots.status === 'FAIL') || (isRecord(motion.required) && motion.required.status === 'FAIL'))) out.push(MOTION_SEAM_LINE);
   return out;
 }
 
@@ -3033,6 +3037,8 @@ export interface CheckReport {
   motionSeam: MotionSeamLine;
   /** Issue #933: openings inside the figure over motion on undeclared setup-overlapping layer pairs — a warning, never a bar. */
   figureOpenings: FigureOpeningReading;
+  /** Issue #942: the boundary colour-step reading; null when undeclared (the SKIP line is printed, nothing written). */
+  boundaryColour: BoundaryColourMeasured | null;
   /** `CLOTH_SETTLES` (issue #501): a warning, never a bar — in `check.json` only when the rig declares a physics constraint and has an idle; its SKIP is printed either way. */
   cloth: ClothLine;
   /** `WIND_BAND` (issue #590): the steady-wind band each declared seam pair holds, written under `--wind-band` only. */
@@ -3093,7 +3099,7 @@ export function checkStatuses(fig: CheckFigures): Record<string, CheckStatus> {
   const bar = (name: string, measured: boolean): CheckStatus => (!measured ? 'SKIP' : notMet.includes(name) ? 'FAIL' : 'PASS');
   const out: Record<string, CheckStatus> = { gate: bar('gate', true), loop: bar('loop', fig.loop_max_diff !== null), seam: bar('seam', fig.seam_mean !== null) };
   for (const n of JUDGEMENT_LINES) out[n] = fig[n].status;
-  for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, 'figure_openings', SOURCE_LINE, WIND_BAND_LINE, ART_JOINT_LINE, CUT_MATERIAL_LINE, SETUP_PAINTING_LINE] as const) {
+  for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, 'figure_openings', SOURCE_LINE, WIND_BAND_LINE, ART_JOINT_LINE, CUT_MATERIAL_LINE, SETUP_PAINTING_LINE, BOUNDARY_COLOUR_LINE] as const) {
     const l = fig[n];
     if (l !== undefined) out[n] = l.status;
   }
@@ -4420,6 +4426,139 @@ export interface MotionSeamLine {
   worlds?: MotionSeamWorlds;
   /** Selected body-root pairs and named zero-band roots; existing internal seams remain warnings. */
   roots?: { status: 'PASS' | 'FAIL' | 'SKIP'; mode: 'gap-open+under-ghost'; ghost_owner: 'resolved-draw-order'; pairs: string[]; failed: number; reason?: string; unmeasured?: MotionUnmeasuredRoot[] };
+  /** Issue #941: written only under the requirements file's `seam_over_motion.required: true` ({@link motionSeamRequired}). */
+  required?: MotionSeamRequired;
+}
+
+/** Issue #941: the refusal's code — background on a frame of a declared pair, or a pair or line not measured, under `seam_over_motion.required`. */
+export const MOTION_SEAM_REQUIRED_CODE = 'CHECK_SEAM_OVER_MOTION_REQUIRED';
+
+/** The class a declared pair is named by in the required bar: a proven body root, a limb joint below segment 0, or a declaration (`seam` requirement, `motion_seams`). */
+export type MotionSeamClass = 'body-root' | 'internal-joint' | 'explicit';
+
+/** Issue #941: one pair in one animation as the background bar read it — every frame of the set, by rigc's `gapOpen`. */
+export interface MotionBackgroundRow {
+  pair: string;
+  animation: string;
+  /** Frames in the set: every frame `i / fps`, `i = 0..round(duration * fps)` (frames.json `sampled`, stride 1). */
+  frames: number;
+  status: 'read' | 'skip';
+  drawn: number;
+  banded: number;
+  /** rigc's `gapOpen` hits with a cell: background inside the carried setup-overlap band, alpha 0 in the whole skeleton composite. */
+  hits: Array<MotionSeamHit & { time: number }>;
+}
+
+/** Issue #941: `SEAM_OVER_MOTION`'s `required` block. The bar is 0 background cells on every frame read; it never SKIPs. */
+export interface MotionSeamRequired {
+  status: 'PASS' | 'FAIL';
+  mode: 'gap-open';
+  bar_px: 0;
+  /** Every declared pair, its class, and the frames read over every animation. */
+  pairs: Array<{ pair: string; class: MotionSeamClass; frames: number; background_frames: number; max_px: number }>;
+  /** How many refusals the bar added. */
+  failed: number;
+}
+
+/** A declared pair's class: a proven root first, then a limb joint, otherwise its explicit declaration. */
+export function motionSeamClass(p: MotionSeamPair): MotionSeamClass {
+  if (p.root !== undefined) return 'body-root';
+  return p.declared.some((d) => d.startsWith('config.limbs.')) ? 'internal-joint' : 'explicit';
+}
+
+/**
+ * Issue #941: every pair's `gapOpen` over every frame of one `rigc render --seam` run, beside {@link readMotionSeams}
+ * (which keeps its own reading). Refuses (`FRAMES_SIDECAR`), every problem at once, a set that is not every frame at
+ * the rate asked (stride 1, written = sampled), a file that is not the animation's or the rate's, a pair out of the
+ * flag's order, and a `gapOpen` of the wrong shape — unavailable is never a measured zero.
+ */
+export function readMotionSeamBackground(dir: string, animations: readonly string[], fps: number, pairs: readonly MotionSeamPair[]): MotionBackgroundRow[] {
+  const problems: Problem[] = [];
+  const bad = (object: string, detail: string): void => { problems.push({ code: 'FRAMES_SIDECAR', object, detail }); };
+  const sidecar = readJson(join(dir, 'frames.json'), problems);
+  const sets = sidecar !== null && Array.isArray(sidecar.sets) ? sidecar.sets.filter(isRecord) : [];
+  const rows: MotionBackgroundRow[] = [];
+  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; }
+    if (set.fps !== fps || set.stride !== 1 || typeof set.sampled !== 'number' || set.written !== set.sampled || !Number.isSafeInteger(set.sampled) || set.sampled < 1) {
+      bad(join(dir, 'frames.json') + ' set ' + JSON.stringify(animation), `is fps ${JSON.stringify(set.fps)}, sampled ${JSON.stringify(set.sampled)}, written ${JSON.stringify(set.written)}, stride ${JSON.stringify(set.stride)}; every frame at ${fps} fps (stride 1, written = sampled) is required — a sample is not every frame`);
+      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 || file.animation !== animation || file.fps !== fps) { bad(path, `is ${JSON.stringify(file.spec)} for ${JSON.stringify(file.animation)} at ${JSON.stringify(file.fps)} fps; "${SEAM_READING_SPEC}" for ${JSON.stringify(animation)} at ${fps} fps is required`); continue; }
+    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; }
+      const open = p.gapOpen;
+      const frames = isRecord(open) && Array.isArray(open.frames) ? open.frames : null;
+      const hits = frames === null ? [] : frames.flatMap((h) => isRecord(h) && Number.isSafeInteger(h.index) && typeof h.index === 'number' && h.index >= 0 && h.index < (set.sampled as number) &&
+        Number.isSafeInteger(h.px) && typeof h.px === 'number' && h.px > 0 && typeof h.cell === 'number' && h.cell > 0 && typeof h.time === 'number' && Number.isFinite(h.time) &&
+        Array.isArray(h.box) && h.box.length === 4 && h.box.every((v) => typeof v === 'number' && Number.isFinite(v))
+        ? [{ index: h.index, px: h.px, cell: h.cell, time: h.time, box: [h.box[0], h.box[1], h.box[2], h.box[3]] as [number, number, number, number] }] : []);
+      if ((p.status !== 'read' && p.status !== 'skip') || typeof p.drawn !== 'number' || typeof p.banded !== 'number' || frames === null || hits.length !== frames.length || new Set(hits.map((h) => h.index)).size !== hits.length) {
+        bad(`${at} gapOpen`, 'requires { frames: [{ index, time, px > 0, cell, box }…] } on every pair, one hit per frame, as rigc-seam/1 writes it from rig-c 2.69.0 — unavailable is not zero background');
+        return;
+      }
+      rows.push({ pair: want.pair, animation, frames: set.sampled as number, status: p.status, drawn: p.drawn, banded: p.banded, hits });
+    });
+  }
+  refuseIfAny(problems);
+  return rows;
+}
+
+/**
+ * Issue #941: the bar `seam_over_motion.required: true` declares — 0 background cells (rigc's `gapOpen`: gap cells
+ * inside the carried setup-overlap band where the whole skeleton composite has alpha 0) on every frame of every
+ * animation, for every declared pair: body-root, internal-joint and explicit. No floor, no sample. A line or a pair
+ * that measured nothing is refused too, since a SKIP is never a pass. Problems are pushed, one per pair and
+ * animation (with its worst frame) and one per pair or line not measured; the block is returned.
+ */
+export function motionSeamRequired(line: MotionSeamLine, rows: readonly MotionBackgroundRow[], requirements: string, problems: Problem[]): MotionSeamRequired {
+  const before = problems.length;
+  const why = `${requirements} declares seam_over_motion.required: true, so 0 background px is required on every frame of every declared seam pair`;
+  const refuse = (object: string, detail: string): void => { problems.push({ code: MOTION_SEAM_REQUIRED_CODE, object, detail }); };
+  if (line.status === 'SKIP' && line.rows.length === 0 && line.pairs.every((p) => p.unread === undefined)) {
+    refuse(MOTION_SEAM_LINE, `is SKIP — ${String(line.reason)}; nothing was measured, which is not a pass: ${why}. Declare the pairs (config.limbs, config.motion_seams, a --requirements seam) and an animation, or drop the declaration`);
+  }
+  const out: MotionSeamRequired['pairs'] = [];
+  for (const p of line.pairs) {
+    const cls = motionSeamClass(p);
+    const label = `${cls} seam "${p.pair}"`;
+    let frames = 0;
+    let open = 0;
+    let max = 0;
+    if (p.unread !== undefined) refuse(label, `is not read — ${p.unread}; ${why}`);
+    else for (const animation of line.animations) {
+      const r = rows.find((x) => x.pair === p.pair && x.animation === animation);
+      if (r === undefined || r.status !== 'read' || r.banded === 0) {
+        refuse(`${label} in "${animation}"`, `${r === undefined ? 'has no returned reading' : `rigc read no band on any of the ${r.drawn} frame(s) both slots draw (status ${r.status})`}; not measured is not a pass: ${why}`);
+        continue;
+      }
+      frames += r.frames;
+      open += r.hits.length;
+      if (r.hits.length === 0) continue;
+      const worst = r.hits.reduce((b, h) => (h.px > b.px || (h.px === b.px && h.index < b.index) ? h : b));
+      max = Math.max(max, worst.px);
+      refuse(`${label} in "${animation}" at frame ${worst.index} (t = ${worst.time}s)`,
+        `background on ${r.hits.length} of ${r.frames} frame(s) read ${frameRuns(r.hits.map((h) => h.index))}: found ${worst.px} px (rigc gapOpen cells of ${worst.cell} world units, world box [${worst.box.join(', ')}]) on the worst frame, 0 required; ${why}`);
+    }
+    out.push({ pair: p.pair, class: cls, frames, background_frames: open, max_px: max });
+  }
+  const failed = problems.length - before;
+  return { status: failed === 0 ? 'PASS' : 'FAIL', mode: 'gap-open', bar_px: 0, pairs: out, failed };
+}
+
+/** Issue #941: the console line for the required block. */
+export function motionSeamRequiredLine(r: MotionSeamRequired): string {
+  const frames = r.pairs.reduce((n, p) => n + p.frames, 0);
+  const classes = (['body-root', 'internal-joint', 'explicit'] as const).map((c) => `${r.pairs.filter((p) => p.class === c).length} ${c}`).join(', ');
+  return `${MOTION_SEAM_LINE} required: ${r.status} — ${r.pairs.length} declared pair(s) (${classes}), ${frames} pair-frame(s) read, every frame of every animation: ${r.failed === 0 ? '0 background px on every frame' : `${r.failed} refusal(s)`}, bar 0 px (rigc gapOpen, no floor; seam_over_motion.required: true)`;
 }
 
 /**
@@ -6285,6 +6424,11 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       refuseIfAny(setupPaintingBounds(file.setup_painting as SetupPainting, ready.stage.width, ready.stage.height));
       if (ready.source === null) refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_SOURCE', object: 'requirements.setup_painting', detail: 'requires --source naming the painting; the assembled composite is not an independent source painting' }]);
     });
+    // Issue #942: a declared boundary_colour reads parts.json's pieces and the idle; without either it cannot be taken.
+    if (file.boundary_colour !== undefined) take(() => refuseIfAny([
+      ...(ready.parts === null ? [{ code: BOUNDARY_COLOUR_UNMEASURED_CODE, object: 'requirements.boundary_colour', detail: `requires parts.json and its parts/ PNGs, the rig's own pieces the step is measured against: ${ready.noParts ?? 'none was read'}; an untaken reading is never a pass` }] : []),
+      ...(ready.idleDuration === null ? [{ code: BOUNDARY_COLOUR_UNMEASURED_CODE, object: 'requirements.boundary_colour', detail: `requires an idle animation, whose every frame is measured: ${ready.noIdle ?? 'none was read'}; an untaken reading is never a pass` }] : []),
+    ]));
     take(() => refuseIfAny(exceptionProblems(file, ready.parts, ready.noParts)));
     // A seam's pairs are read off parts.json's art (issue #111); both resolvers' problems are named in one refusal.
     if (file.requirements.some((r) => r.kind === 'seam')) {
@@ -6710,6 +6854,9 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   // Read the build as played at the idle's rate; unavailable data is named SKIP.
   let motionSeam: MotionSeamLine;
   const motionRootProblems: Problem[] = [];
+  // Issue #941: under seam_over_motion.required, the same render's gapOpen on every frame of every declared pair.
+  const seamRequired = seamOverMotionRequired(reqFile);
+  let backgroundRows: MotionBackgroundRow[] = [];
   {
     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 }] : []));
@@ -6773,6 +6920,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
         if (r.status !== 0) refuseIfAny(rigcFailed(`render --seam ${list} --fps ${fps}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
         const activeWorldRows: MotionSeamWorldRow[] = [];
         motionSeam = motionSeamLine(pairs, animationNames, fps, readMotionSeams(activeDest, animationNames, fps, read, {}, stripped !== null && env === null ? activeWorldRows : undefined, hasRoots ? motionRootDrawOrderReader(activeDest) : undefined), undefined, motionRootProblems, unmeasuredRoots);
+        if (seamRequired) backgroundRows = readMotionSeamBackground(activeDest, animationNames, fps, read);
         enrichMotionSeamPoses(activeDest, inp.rig, inp.parts, pairs, motionSeam.rows);
         if (stripped !== null) {
           const response = environmentResponse(readFileSync(join(buildDir, 'skeleton.json'), 'utf8'));
@@ -6800,6 +6948,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       }
     }
   }
+  if (seamRequired && reqFile !== null) motionSeam.required = motionSeamRequired(motionSeam, backgroundRows, reqFile.path, motionRootProblems);
   const declaredPairKeys = new Set(motionSeam.pairs.map((p) => [p.a, p.b].sort().join('|')));
   const figureOpenings: FigureOpeningReading =
     inp.parts === null
@@ -7031,6 +7180,11 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     }
   }
 
+  // Issue #942: the boundary colour step against the rig's own pieces, on the gated build, only when declared.
+  const boundaryDeclared = reqFile?.boundary_colour;
+  const boundaryColour = boundaryDeclared === undefined || inp.parts === null || inp.idleDuration === null ? null
+    : measureBoundaryColour(officialRenderer(), { build: buildDir, stage: inp.stage, parts: inp.parts, partsDir: inp.partsDir, imagesDir: typeof inp.rig.images === 'string' ? resolve(inp.rigDir, inp.rig.images) : join(inp.rigDir, 'images'), rig: inp.rig, fps: IDLE_FPS }, boundaryDeclared, problems);
+
   // 5. the scene's declared requirements (issue #93), only under --requirements
   const reqProblems: Problem[] = [];
   const reqBlock = reqFile === null || reqRecord === null ? null : { file: reqRecord, ...measureRequirements(inp, reqFile, buildDir, out, rigc, reqProblems, seams ?? new Map(), measured) };
@@ -7063,7 +7217,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 && motionSeam.roots === undefined ? {} : { [MOTION_SEAM_LINE]: motionSeam }),
+    ...(motionSeam.pairs.length === 0 && motionSeam.roots === undefined && motionSeam.required === undefined ? {} : { [MOTION_SEAM_LINE]: motionSeam }),
     ...(stripped === null || idle === null ? {} : { [CLOTH_LINE]: cloth }),
     RECOMPOSITE_HOLES: inp.parts === null ? { status: 'SKIP', reason: inp.noParts ?? '' } : holesLine(inp.parts),
     ...(figureOpenings.status === 'SKIP' ? {} : { figure_openings: figureOpenings }),
@@ -7074,6 +7228,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     ...(config === undefined ? {} : { config }),
     ...(artJoints === null ? {} : { [ART_JOINT_LINE]: artJoints }),
     ...(setupPainting === null ? {} : { [SETUP_PAINTING_LINE]: setupPainting }),
+    ...(boundaryColour === null ? {} : { [BOUNDARY_COLOUR_LINE]: boundaryColour }),
     ...(cutMaterial === null ? {} : { [CUT_MATERIAL_LINE]: cutMaterial }),
     ...(reqBlock === null ? {} : { requirements: reqBlock }),
     PASS: false,
@@ -7141,6 +7296,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   if (cutMaterial !== null) tally(CUT_MATERIAL_LINE, null);
   if (artJoints !== null) tally(ART_JOINT_LINE, artJoints.status === 'SKIP' ? (artJoints.reason ?? 'no declared limit') : null);
   if (setupPainting !== null) tally(SETUP_PAINTING_LINE, setupPainting.status === 'SKIP' ? (setupPainting.reason ?? 'no declared limit') : null);
+  if (boundaryColour !== null) tally(BOUNDARY_COLOUR_LINE, null);
   // Issue #348: the level bar where it is written; a line whose every foot no frame posed says SKIP and is not measured.
   if (level !== null) tally(LEVEL_LINE, level.status === 'SKIP' ? (level.reason ?? '') : null);
   // Issue #347: the stress bar is counted where it is written — on every rig with a handwear part and an idle.
@@ -7149,7 +7305,9 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   if (limbs !== null) tally(LIMB_LINE, null);
   // Issue #360: the range bar where it is written; a joint it cannot read fails, so it always measures.
   if (sweep !== null) tally(SWEEP_LINE, null);
-  if (motionSeam.roots !== undefined) tally(MOTION_SEAM_LINE, motionSeam.roots.status === 'SKIP' ? (motionSeam.roots.reason ?? 'no body-root reading') : null);
+  // Issue #941: the required bar never SKIPs (an unmeasured line or pair is its refusal), so it counts the line measured.
+  if (motionSeam.required !== undefined) tally(MOTION_SEAM_LINE, null);
+  else if (motionSeam.roots !== undefined) tally(MOTION_SEAM_LINE, motionSeam.roots.status === 'SKIP' ? (motionSeam.roots.reason ?? 'no body-root reading') : null);
   return {
     figures,
     gateHtml,
@@ -7167,6 +7325,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     motionSeam,
     figureOpenings,
     cloth,
+    boundaryColour,
     ...(sweepSteps.size === 0 ? {} : { sweepSteps }),
     ...(windBandRead === null ? {} : { windBand: windBandRead }),
   };

package/src/config.ts

@@ -100,6 +100,7 @@ import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { edgeLength } from './length.ts';
 import { setFocusProblems } from './setfocus.ts';
+import { type EditorReceipts, SHA256_PATTERN, SHA256_RULE } from './editreceipt.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 { BODYSHIFT_BONE, BODY_REAR_SHIFT_BONE, BODY_YAW_DIAL_BONE, EAR_DEPTH_RANGE, FACESHIFT_BONE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, type FaceDeformKey, PITCH_DIAL_BONE, REAR_SHIFT_BONE, TURN_BONE, TURN_ROLES, type TurnRole, type TurnSpec, YAW_DIAL_BONE, turnNearest, turnSurfaceBone, turnUnitBone } from './turn.ts';
@@ -305,6 +306,8 @@ export interface Assemble {
   seam?: SeamRule;
   /** Verified named replacements from another See-through run (#866). */
   take?: TakeLayers[];
+  /** Issue #946: receipts for images edited in an image editor; absent, no file is read and no byte moves. */
+  editor_receipts?: EditorReceipts;
   /** Rig pixels per source pixel. */
   rig_scale: number;
   plan: PlanEntry[];
@@ -1623,7 +1626,7 @@ export interface EarlyConfig {
   depth?: DepthConfig;
   key: string;
   seethrough: SeeThrough;
-  assemble: { rig_scale: number; seam?: SeamRule; take?: TakeLayers[]; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
+  assemble: { rig_scale: number; seam?: SeamRule; take?: TakeLayers[]; editor_receipts?: EditorReceipts; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
 }
 
 /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
@@ -1699,7 +1702,7 @@ 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', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam']);
+      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam', 'editor_receipts']);
       if (a !== null) {
         checkSeam(c, a);
         if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
@@ -1709,6 +1712,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
         checkKeepUnderOccluders(c, a, null);
         if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
         if ('take' in a) checkTakeLayers(c, a.take);
+        if ('editor_receipts' in a) checkEditorReceipts(c, a.editor_receipts);
         if ('yield_refused' in a && typeof a.yield_refused !== 'boolean') {
           c.fail('CONFIG_FIELD_TYPE', 'config.assemble.yield_refused', `is ${show(a.yield_refused)}; true or false is required`);
         }
@@ -2466,6 +2470,39 @@ function checkTakeLayers(c: Check, value: Json): void {
   });
 }
 
+/**
+ * `config.assemble.editor_receipts` (issue #946): `{receipts, required?, trace_parts?}` (`trace_parts`, issue #947).
+ * Shape refusals are the loader's own; a receipt whose `from_sha256` equals
+ * its `sha256` (no edit), or a `file` receipted twice, is `CONFIG_EDITOR_RECEIPT`.
+ * Whether the file exists and hashes to `sha256` is read at assemble
+ * (`src/editreceipt.ts`), where the file is.
+ */
+function checkEditorReceipts(c: Check, value: Json): void {
+  const at = 'config.assemble.editor_receipts';
+  const o = c.object(at, value, ['receipts'], ['required', 'trace_parts']);
+  if (o === null) return;
+  for (const k of ['required', 'trace_parts'] as const) {
+    if (k in o && typeof o[k] !== 'boolean') c.fail('CONFIG_FIELD_TYPE', `${at}.${k}`, `is ${show(o[k])}; true or false is required`);
+  }
+  if (!('receipts' in o) || !c.array(`${at}.receipts`, o.receipts, false)) return;
+  const seen = new Map<string, number>();
+  (o.receipts as Json[]).forEach((v, i) => {
+    const p = `${at}.receipts[${i}]`;
+    const r = c.object(p, v, ['file', 'sha256', 'from_sha256', 'editor'], []);
+    if (r === null) return;
+    if ('file' in r && c.string(`${p}.file`, r.file)) {
+      const file = r.file as string;
+      if (seen.has(file)) c.fail('CONFIG_EDITOR_RECEIPT', `${p}.file`, `names "${file}" again (first at receipts[${seen.get(file)}]); one receipt per file is required`);
+      else seen.set(file, i);
+    }
+    for (const k of ['sha256', 'from_sha256'] as const) {
+      if (k in r && (typeof r[k] !== 'string' || !SHA256_PATTERN.test(r[k] as string))) c.fail('CONFIG_FIELD_TYPE', `${p}.${k}`, `is ${show(r[k])}; ${SHA256_RULE} is required`);
+    }
+    if ('editor' in r) c.string(`${p}.editor`, r.editor);
+    if (typeof r.sha256 === 'string' && r.sha256 === r.from_sha256) c.fail('CONFIG_EDITOR_RECEIPT', `${p}.from_sha256`, `is ${r.from_sha256}, the receipt's own sha256; the bytes the edit started from are required, and an edit that left the bytes unchanged is not an edit`);
+  });
+}
+
 function checkSeam(c: Check, a: Record<string, Json>): void {
   if ('seam' in a && !(SEAM_RULES as readonly unknown[]).includes(a.seam)) {
     c.fail('CONFIG_FIELD_TYPE', 'config.assemble.seam', `is ${show(a.seam)}; one of ${SEAM_RULES.join(', ')} is required`);
@@ -2474,7 +2511,7 @@ function checkSeam(c: Check, a: Record<string, 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', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam']);
+  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam', 'editor_receipts']);
   if (a === null) return { parts: [], patches: [], cuts: [] };
   checkSeam(c, a);
   if (required.includes('plan') && !('plan' in a)) {
@@ -2512,6 +2549,7 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
   checkKeepUnderOccluders(c, a, parts);
   if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
   if ('take' in a) checkTakeLayers(c, a.take);
+  if ('editor_receipts' in a) checkEditorReceipts(c, a.editor_receipts);
   if ('extend_below_crop' in a && c.array(`${p}.extend_below_crop`, a.extend_below_crop, false)) {
     (a.extend_below_crop as Json[]).forEach((entry, i) => {
       const at = `${p}.extend_below_crop[${i}]`;