@rig-c/parts 1.9.0 → 1.10.0

package/src/assemble.ts

@@ -95,7 +95,7 @@ import type { CharacterConfig, Cut, EarlyConfig, Extend, Patch, PlanEntry, Run,
 import { type Problem, refuseIfAny } from './errors.ts';
 import { figuresPhrase, implausibleRules, type Layer, type LayerFigures, layerFigures, type LayerSet, NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE, ruleSummary } from './layers.ts';
 import { squarePad } from './inputs.ts';
-import { PAINTING_RUN, type PartRecord, type PartsFile, type RecompositeRecord } from './parts.ts';
+import { PAINTING_RUN, type PartRecord, type PartsFile, type RecompositeRecord, type SceneRecord } from './parts.ts';
 import {
   alphaComposite,
   connectedComponents,
@@ -114,6 +114,7 @@ import {
   warpAffine,
 } from './raster/index.ts';
 import { pyRound } from './round.ts';
+import { AUTHOR_NO_ROLE, readAuthorTag } from './tags.ts';
 
 const f32 = Math.fround;
 
@@ -237,6 +238,8 @@ export interface AssembleInput {
   under?: ReadonlyArray<Raster | null>;
   seamRule: SeamRule;
   projectRule: ProjectRule;
+  /** `config.scene` (issue #242): the painting is a scene, so the recomposite is read inside the figure ({@link sceneFigure}). Absent or false: nothing changes. */
+  scene?: boolean;
 }
 
 /** The derived numbers of the two runs' geometry. */
@@ -1239,11 +1242,12 @@ function coveredMask(parts: PlacedPart[], W: number, H: number): Uint8Array {
   return covered;
 }
 
-/** Per rig pixel: 1 where the recomposite's max-channel difference from the painting is above `ERROR_LIMIT`. */
-function errorMask(can: Raster, srcr: Raster): Uint8Array {
+/** Per rig pixel: 1 where the recomposite's max-channel difference from the painting is above `ERROR_LIMIT` — and, with `inside` (a scene, issue #242), the pixel is the figure's. */
+function errorMask(can: Raster, srcr: Raster, inside: Uint8Array | null = null): Uint8Array {
   const n = srcr.width * srcr.height;
   const err = new Uint8Array(n);
   for (let p = 0; p < n; p++) {
+    if (inside !== null && inside[p] === 0) continue;
     let m = 0;
     for (let c = 0; c < 3; c++) m = Math.max(m, Math.abs(can.data[p * 4 + c] - srcr.data[p * 4 + c]));
     if (m > ERROR_LIMIT) err[p] = 1;
@@ -1270,10 +1274,10 @@ function errorMask(can: Raster, srcr: Raster): Uint8Array {
  * This is not in the reference, whose report stopped at the count. The count
  * cannot say where to look; a box and the parts round it can.
  */
-export function uncoveredHoles(can: Raster, srcr: Raster, parts: PlacedPart[]): { count: number; holes: RecompositeHole[] } {
+export function uncoveredHoles(can: Raster, srcr: Raster, parts: PlacedPart[], inside: Uint8Array | null = null): { count: number; holes: RecompositeHole[] } {
   const { width: W, height: H } = srcr;
   const covered = coveredMask(parts, W, H);
-  const err = errorMask(can, srcr);
+  const err = errorMask(can, srcr, inside);
   const mask = newMask(W, H);
   for (let p = 0; p < W * H; p++) if (err[p] === 1 && covered[p] === 0) mask.data[p] = 1;
   const cc = connectedComponents(mask, 8);
@@ -1312,14 +1316,23 @@ export function uncoveredHoles(can: Raster, srcr: Raster, parts: PlacedPart[]):
   return { count: all.length, holes };
 }
 
-export function measureRecomposite(can: Raster, srcr: Raster, parts: PlacedPart[]): RecompositeFigures {
+/**
+ * The recomposite's four figures and its holes. With `inside` (a scene, issue
+ * #242; {@link sceneFigure}) every one is read over the figure's pixels alone:
+ * the mean and the within share are over them, and a pixel outside is neither an
+ * error pixel nor a hole's. Without it, over the whole rig, as always.
+ */
+export function measureRecomposite(can: Raster, srcr: Raster, parts: PlacedPart[], inside: Uint8Array | null = null): RecompositeFigures {
   const { width: W, height: H } = srcr;
   const covered = coveredMask(parts, W, H);
   let sum = 0;
   let within = 0;
   let errorPx = 0;
   let uncoveredErrorPx = 0;
+  let read = 0;
   for (let p = 0; p < W * H; p++) {
+    if (inside !== null && inside[p] === 0) continue;
+    read++;
     let s = 0;
     let m = 0;
     for (let c = 0; c < 3; c++) {
@@ -1335,8 +1348,44 @@ export function measureRecomposite(can: Raster, srcr: Raster, parts: PlacedPart[
       if (covered[p] === 0) uncoveredErrorPx++;
     }
   }
-  const { count, holes } = uncoveredHoles(can, srcr, parts);
-  return { meanAbs: sum / (W * H), within: within / (W * H), errorPx, uncoveredErrorPx, holeCount: count, holes };
+  const { count, holes } = uncoveredHoles(can, srcr, parts, inside);
+  // Over the whole rig `read` is W * H, and the two quotients are the ones they always were.
+  return { meanAbs: inside === null ? sum / (W * H) : read === 0 ? 0 : sum / read, within: inside === null ? within / (W * H) : read === 0 ? 0 : within / read, errorPx, uncoveredErrorPx, holeCount: count, holes };
+}
+
+/** The figure mask's file name, beside the recomposite (issue #242): `recomposite_rig.png` -> `figure_rig.png`. */
+export const FIGURE_MASK_FILE = 'figure_rig.png';
+
+/**
+ * The figure of a scene painting (issue #242): per rig pixel, 1 where any
+ * full-run layer — See-through's decomposition of the whole figure, each layer
+ * placed on the rig as the stage places it — has alpha above
+ * `OPAQUE_ALPHA_ABOVE` (8), the cut this package already reads a layer's
+ * painted pixels by (ghost clean-up, the sheets, every part's opaque count).
+ * The threshold is that one, not a new one: a pixel no layer paints is the
+ * scene's, and a pixel any layer paints is the figure's, by the same rule that
+ * says what a layer holds. The head run is not read: it is a crop of the same
+ * figure, inside the full run's.
+ */
+export function sceneFigure(fullRig: readonly Raster[], W: number, H: number): Uint8Array {
+  const inside = new Uint8Array(W * H);
+  for (const r of fullRig) for (let p = 0; p < W * H; p++) if (r.data[p * 4 + 3] > OPAQUE_ALPHA_ABOVE) inside[p] = 1;
+  return inside;
+}
+
+/** The figure as an image, the mask `assemble` writes beside the recomposite: opaque white where the figure is, opaque black elsewhere. */
+export function figureImage(inside: Uint8Array, W: number, H: number): Raster {
+  const r = newRaster(W, H);
+  for (let p = 0; p < W * H; p++) {
+    const v = inside[p] === 1 ? 255 : 0;
+    r.data.set([v, v, v, 255], p * 4);
+  }
+  return r;
+}
+
+/** What a scene declaration says first on each recomposite line (issue #242): where it was read, and the figure's size against the rig's. */
+export function scenePhrase(s: SceneRecord, rigPx: number): string {
+  return `inside the figure (config.scene: the union of the full run's layers at alpha above ${s.figure_alpha_above}, ${s.figure_px} of ${rigPx} rig px)`;
 }
 
 /** The error map's colour for an uncovered error pixel: no part is there, so the page shows through. */
@@ -1359,10 +1408,10 @@ export const MAP_MISMATCHED: readonly [number, number, number] = [0, 0, 255];
  * both), so the two colours mean exactly the two masks. Integer arithmetic
  * only, so the bytes are deterministic.
  */
-export function recompositeErrorMap(can: Raster, srcr: Raster, parts: PlacedPart[]): Raster {
+export function recompositeErrorMap(can: Raster, srcr: Raster, parts: PlacedPart[], inside: Uint8Array | null = null): Raster {
   const { width: W, height: H } = srcr;
   const covered = coveredMask(parts, W, H);
-  const err = errorMask(can, srcr);
+  const err = errorMask(can, srcr, inside);
   const map = newRaster(W, H);
   for (let p = 0; p < W * H; p++) {
     const s = p * 4;
@@ -1381,9 +1430,9 @@ export function recompositeErrorMap(can: Raster, srcr: Raster, parts: PlacedPart
   return map;
 }
 
-export function figuresLine(f: RecompositeFigures): string {
+export function figuresLine(f: RecompositeFigures, scene: string | null = null): string {
   return (
-    `recomposite vs source: mean |d|=${f.meanAbs.toFixed(2)}, within ${WITHIN_LIMIT}: ${(100 * f.within).toFixed(1)}%, ` +
+    `${scene === null ? '' : `${scene}: `}recomposite vs source: mean |d|=${f.meanAbs.toFixed(2)}, within ${WITHIN_LIMIT}: ${(100 * f.within).toFixed(1)}%, ` +
     `error px > ${ERROR_LIMIT}: ${f.errorPx}, uncovered error px: ${f.uncoveredErrorPx}`
   );
 }
@@ -1398,8 +1447,8 @@ export function holeBox(h: RecompositeHole): string {
  * hole — `uncovered hole 1: 2340 px at 412,1088 30x78 (between "legwear_r"
  * 120 px, "legwear_l" 96 px)`, or `(borders no part)`.
  */
-export function holeLines(f: RecompositeFigures): string[] {
-  const head = `uncovered holes (8-connected): ${f.holeCount}${f.holeCount > f.holes.length ? `, the largest ${f.holes.length} listed` : ''}`;
+export function holeLines(f: RecompositeFigures, scene: string | null = null): string[] {
+  const head = `${scene === null ? '' : `${scene}: `}uncovered holes (8-connected): ${f.holeCount}${f.holeCount > f.holes.length ? `, the largest ${f.holes.length} listed` : ''}`;
   return [
     head,
     ...f.holes.map(
@@ -1665,6 +1714,8 @@ export interface AssembleResult {
   recomposite: Raster;
   /** `recompositeErrorMap`: uncovered error pixels red, covered ones blue, the painting dimmed grey. */
   errorMap: Raster;
+  /** Under `config.scene` (issue #242), the figure the recomposite was read inside ({@link figureImage}); null otherwise. */
+  figure: Raster | null;
   figures: RecompositeFigures;
   /** What each `assemble.cuts` entry took, counted when it was made (`cutLines`); empty without cuts. */
   cuts: CutCount[];
@@ -2113,12 +2164,15 @@ export function assemble(input: AssembleInput): AssembleResult {
 
   seamOverride(placed, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null);
   const can = recomposite(placed, W, H);
-  const figures = measureRecomposite(can, srcr, placed);
+  // Issue #242: on a scene painting the figure is read off the full run, and every recomposite figure inside it.
+  const inside = input.scene === true ? sceneFigure([...rig.entries()].filter(([k]) => k.startsWith('full:')).map(([, r]) => r), W, H) : null;
+  const sceneRecord: SceneRecord | null = inside === null ? null : { figure_alpha_above: OPAQUE_ALPHA_ABOVE, figure_px: inside.reduce((a, b) => a + b, 0), figure_mask: FIGURE_MASK_FILE };
+  const figures = measureRecomposite(can, srcr, placed, inside);
   const fullRig = fullTags.map((tag) => ({ tag, rig: rig.get(`full:${tag}`) as Raster }));
   const uncovered = uncoveredErrorLayers(
     fullRig,
     coveredMask(placed, W, H),
-    errorMask(can, srcr),
+    errorMask(can, srcr, inside),
     figures.uncoveredErrorPx,
     plan,
     extend,
@@ -2128,10 +2182,11 @@ export function assemble(input: AssembleInput): AssembleResult {
     bodyMinPx(frame),
   );
   return {
-    parts: { rig_size: [W, H], scale_rig_per_source: frame.S, parts: placed.map((p) => p.record), ghost_px: ghost, recomposite: recompositeRecord(figures) },
+    parts: { rig_size: [W, H], scale_rig_per_source: frame.S, parts: placed.map((p) => p.record), ghost_px: ghost, recomposite: recompositeRecord(figures), ...(sceneRecord === null ? {} : { scene: sceneRecord }) },
     images: placed,
     recomposite: can,
-    errorMap: recompositeErrorMap(can, srcr, placed),
+    errorMap: recompositeErrorMap(can, srcr, placed, inside),
+    figure: inside === null ? null : figureImage(inside, W, H),
     figures,
     cuts: cutCounts,
     uncovered,
@@ -2459,12 +2514,12 @@ export function uncoveredErrorLayers(
  * of the 240 uncovered error px lie on the full run's "back hair", in a body
  * of 240 px at 36,22 8x30; hair_back takes the head run's "back hair"; …`.
  */
-export function uncoveredLine(d: UncoveredErrorLayer): string {
+export function uncoveredLine(d: UncoveredErrorLayer, scene: string | null = null): string {
   const u = d.layer;
   const total = u.bodies.reduce((a, b) => a + b.px, 0);
   const big = u.bodies[0];
   const held = u.bodies.length > 1 ? `${u.bodies.length} bodies of ${total} px, the largest ${big.px} px at ${bodyBox(big)}` : `a body of ${big.px} px at ${bodyBox(big)}`;
-  return `uncovered: ${d.errorPx} of the ${d.of} uncovered error px lie on the full run's "${u.tag}", in ${held}; ${u.rule}`;
+  return `${scene === null ? '' : `${scene}: `}uncovered: ${d.errorPx} of the ${d.of} uncovered error px lie on the full run's "${u.tag}", in ${held}; ${u.rule}`;
 }
 
 /**
@@ -2534,7 +2589,10 @@ export const PROPOSE_ALIAS: Readonly<Record<string, string>> = {
   earwear: 'earring',
 };
 
+/** An author-made layer's part is named by its label as the author wrote it (issue #256): the label is already a part name (`authorLabelOk`). */
 function aliasOf(tag: string): string {
+  const author = readAuthorTag(tag);
+  if (author !== null) return author.label;
   return PROPOSE_ALIAS[tag] ?? tag.replaceAll(' ', '_').replaceAll('-', '_');
 }
 
@@ -2587,6 +2645,15 @@ function fmt0(v: number): string {
  * changed. [observed] reference-sample's proposal is the reference's byte for
  * byte; demo's, reference-demo's and scarf's each gain one note, on the hair
  * their configs had already corrected by hand.
+ *
+ * ⚖️ This port's too (issue #256): an author-made layer (`author:<label>`,
+ * `src/tags.ts`) is proposed from the run that holds it, at its place in that
+ * run's draw order, as the part named by its label, under the same floor and
+ * plausibility rules as any layer — its draw position is then the plan's,
+ * where the author moves it. A note per such part says it has no tag and so
+ * no role. One both runs hold is proposed once, from the full run, and a note
+ * says how to take the head run's too. No public example holds one, so no
+ * proposal of theirs moves.
  */
 export function proposePlan(full: LayerSet, head: LayerSet, g: Geometry, minPx = PROPOSE_MIN_PX): PlanProposal {
   const frame = checkGeometry(g, { full, head });
@@ -2611,7 +2678,10 @@ export function proposePlan(full: LayerSet, head: LayerSet, g: Geometry, minPx =
     return tag !== 'nose' && l !== undefined && l.opaqueRunPx >= minPx && !implausible(run, tag, 'not proposed');
   };
   const body = runs.full.filter((l) => !PROPOSE_HEAD_TAGS.includes(l.tag) && ok('full', l.tag)).map((l) => l.tag);
-  const heads = runs.head.filter((l) => PROPOSE_HEAD_TAGS.includes(l.tag) && ok('head', l.tag)).map((l) => l.tag);
+  // Issue #256: an author-made layer is proposed from the run that holds it, at its place in that run's draw order,
+  // like any layer; one both runs hold is proposed once, from the full run when the full run's is proposed, and the note says so.
+  const authorBoth = runs.head.filter((l) => readAuthorTag(l.tag) !== null && body.includes(l.tag)).map((l) => l.tag);
+  const heads = runs.head.filter((l) => (PROPOSE_HEAD_TAGS.includes(l.tag) || (readAuthorTag(l.tag) !== null && !authorBoth.includes(l.tag))) && ok('head', l.tag)).map((l) => l.tag);
   const hw = body.filter((t) => t.startsWith('handwear'));
   const plan: PlanEntry[] = [];
   const drop = (t: string): void => {
@@ -2647,6 +2717,12 @@ export function proposePlan(full: LayerSet, head: LayerSet, g: Geometry, minPx =
     }
   }
   for (const t of heads) plan.push([aliasOf(t), 'head', t]);
+  for (const [part, run, tag] of plan) {
+    if (readAuthorTag(tag) !== null) notes.push(`${tag}: ${AUTHOR_NO_ROLE}; proposed as "${part}" from the ${run} run, at its place in that run's draw order`);
+  }
+  for (const tag of authorBoth) {
+    notes.push(`${tag}: the head run holds a layer of this name too, and the proposer drafts one part per author-made layer, from the full run; to take the head run's as well, add ["<a part name>", "head", "${tag}"] to the plan`);
+  }
   const extend: Extend[] = [];
   /** A hair tag the proposer did not continue below the crop: how far its full-run layer reaches, rig px (null: no opaque row). */
   const reaches = new Map<string, number | null>();
@@ -2719,7 +2795,7 @@ export function proposePlan(full: LayerSet, head: LayerSet, g: Geometry, minPx =
  * the loader, because `inputs` runs before it exists; `seethrough` too, for a
  * full-loader config, where it is optional.
  */
-export function stageFields(cfg: Pick<CharacterConfig, 'seethrough' | 'assemble'>): {
+export function stageFields(cfg: Pick<CharacterConfig, 'seethrough' | 'assemble' | 'scene'>): {
   resolution: number;
   headBox: [number, number, number, number];
   rigScale: number;
@@ -2727,6 +2803,7 @@ export function stageFields(cfg: Pick<CharacterConfig, 'seethrough' | 'assemble'
   extend: Extend[];
   patches: Patch[];
   cuts: Cut[];
+  scene?: boolean;
 } {
   const problems: Problem[] = [];
   if (cfg.seethrough === undefined) {
@@ -2744,6 +2821,7 @@ export function stageFields(cfg: Pick<CharacterConfig, 'seethrough' | 'assemble'
     extend: cfg.assemble.extend_below_crop ?? [],
     patches: cfg.assemble.patches ?? [],
     cuts: cfg.assemble.cuts ?? [],
+    ...(cfg.scene === undefined ? {} : { scene: true }),
   };
 }
 

package/src/autoenvelope.ts

@@ -82,6 +82,7 @@
 import { type BoneMotionRange, type EnvelopeBoneRanges, MeshReductionError, type MeshQualityReport, type MeshReductionInput, type SkinningEnvelope, type SkinningEnvelopeBone, skinningEnvelopeBone } from 'rig-c/mesh';
 import type { ConfigConstraint } from './config.ts';
 import type { MotionKey, MotionSpec } from './motion.ts';
+import { edgeLength } from './length.ts';
 
 /** What the derivation reads off the rig besides the part: the bones (name, parent), each bone's setup joint in crop px, the idle as written, the constraints. */
 export interface EnvelopeBasis {
@@ -168,7 +169,7 @@ export function boneRange(basis: EnvelopeBasis, bone: string, origin: readonly [
     rotate,
     scaleX,
     scaleY,
-    translate: Math.hypot(tx, ty),
+    translate: edgeLength(tx, ty),
     setup: { ...SETUP },
   };
 }

package/src/automotion.ts

@@ -344,6 +344,47 @@ export function motionRowText(r: MeasureRow): string {
   return `${r.code}${region} ${r.state}: ${r.reason ?? ''}`;
 }
 
+/**
+ * Where a row of a comparison was read at its worst, in the words a reader can act on (issue #280), with its
+ * preposition: a declared stimulus by its animation's name (`at stimulus tail_l -10`, the frame rig-c ids
+ * `stimulus tail_l -10@explicit@0`), an idle frame as `at idle frame <id>`, a geometry row — read on the mesh, at
+ * no frame — as `in its geometry`, and a motion row that names no frame as `on the idle`.
+ */
+export function readingPlace(r: MeasureRow, stimulus: readonly StimulusPose[] | null, geometry: boolean): { text: string; stimulus: boolean } {
+  const id = r.worst?.frame?.id;
+  if (id === undefined) return { text: geometry ? 'in its geometry' : 'on the idle', stimulus: false };
+  const name = (stimulus ?? []).flatMap((st) => stimulusAnimationNames(st)).find((n) => explicitFrameId(n) === id);
+  return name === undefined ? { text: `at idle frame ${id}`, stimulus: false } : { text: `at ${name}`, stimulus: true };
+}
+
+/**
+ * Issue #280: the source compared with itself failed, so no replayed step can pass — the one sentence that says
+ * so (`the unreduced source itself fails <where> (<row> <value> against <bound>), so …`): where (a declared stimulus by name, or the idle frame), each failing row and its value against its bound,
+ * and the remedy, which is the source's (its spacing or outline), or the stimulus's when the failure is read at
+ * one. A row the source fails against itself is an absolute reading (`MQ_INVERSION` counts the source's own
+ * flipped triangles), which is why no reduction of it can pass. Null when the comparison has no failing row.
+ */
+export function sourceSelfFailure(self: MeshQualityReport, stimulus: readonly StimulusPose[] | null): { where: string; sentence: string } | null {
+  const rows = failingRows(self);
+  if (rows.length === 0) return null;
+  const geometryRows = new Set(self.candidates[0]?.geometry?.rows ?? []);
+  const places = rows.map((r) => readingPlace(r, stimulus, geometryRows.has(r)));
+  const distinct = [...new Set(places.map((p) => p.text))];
+  const where = distinct.join(', ');
+  // One place: the rows say only their values; several: each row says its own.
+  const read = rows
+    .map((r, i) => {
+      const at = distinct.length > 1 ? ` ${places[i].text}` : '';
+      return r.state === 'fail' || r.state === 'pass' || r.state === 'undeclared' ? `${r.code} ${r.value}${r.bound === null ? '' : ` against ${r.bound.op} ${r.bound.value}`}${at}` : `${r.code} ${r.state}${at}: ${r.reason ?? ''}`;
+    })
+    .join('; ');
+  const atStimulus = places.some((p) => p.stimulus);
+  return {
+    where,
+    sentence: `the unreduced source itself fails ${where} (${read}), so no replayed step can pass — change the source (its spacing or its outline)${atStimulus ? ' or lower the stimulus' : ''}`,
+  };
+}
+
 /** The candidate's rows with a declared bound that did not pass, geometry then motion. */
 export function failingRows(report: MeshQualityReport): MeasureRow[] {
   const c = report.candidates[0];

package/src/build.ts

@@ -43,10 +43,10 @@
 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, driftLine, figuresLine, holeLines, type ProjectRule, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, driftLine, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, 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, type ReplayCandidate, runComparison, stimulusMotion, withStimulus } from './automotion.ts';
+import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, sourceSelfFailure, stimulusMotion, withStimulus } from './automotion.ts';
 import {
   bisectAccepted,
   budgetProblem,
@@ -78,11 +78,12 @@ import { encodeGif } from './gif.ts';
 import { CONTROL_SUFFIX, withAnimations } from './motion.ts';
 import type { PaletteError } from './palette.ts';
 import { type LayerSet, readLayers } from './layers.ts';
-import { type PartRecord, readParts, writeParts } from './parts.ts';
+import { type PartRecord, readParts, tagOf, writeParts } from './parts.ts';
 import { encodePngBytes, readPng, writePng } from './raster/png.ts';
 import type { Raster } from './raster/types.ts';
 import { 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, type StrayCleared, type TurnRow } from './rig.ts';
+import { AUTHOR_NO_ROLE, isAuthorTag } from './tags.ts';
 import { TURN_BONE } from './turn.ts';
 import { pyRound } from './round.ts';
 
@@ -161,6 +162,16 @@ export function fringeLines(parts: readonly PartRecord[]): string[] {
     });
 }
 
+/**
+ * One line per part whose layer the author made (issue #256), in draw order:
+ * `  author-made: part "hand" (full:author:hand) — an author-made layer, …`.
+ * No line when no part came from one, so a plan of See-through layers prints
+ * what it printed before.
+ */
+export function authorPartLines(parts: readonly PartRecord[]): string[] {
+  return parts.filter((p) => isAuthorTag(tagOf(p.from) ?? '')).map((p) => `  author-made: part "${p.name}" (${p.from}) — ${AUTHOR_NO_ROLE}`);
+}
+
 /**
  * Each cut's `under` image (issue #193), read from its path relative to the
  * config's directory, null for a cut without one. Every cut is read before
@@ -207,6 +218,9 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   for (const { record, image } of result.images) writePng(join(outs.partsDir, `${record.name}.png`), image);
   writePng(outs.recomposite, result.recomposite);
   writePng(outs.errorMap, result.errorMap);
+  // Issue #242: under config.scene, the figure the recomposite was read inside, beside the recomposite.
+  const figurePath = result.figure === null ? null : join(dirname(outs.recomposite), FIGURE_MASK_FILE);
+  if (figurePath !== null) writePng(figurePath, result.figure as Raster);
   const [W, H] = result.parts.rig_size;
   log(`rig-parts assemble: ${result.images.length} part(s) on a ${W}x${H} rig (${result.parts.scale_rig_per_source} rig px per source px), seam rule ${result.seamRule}, projection rule ${result.projectRule}`);
   for (const p of result.parts.parts) {
@@ -216,6 +230,8 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
         `unproj=${String(p.visible_not_projected_px).padStart(5)} drift=${String(p.refused_drift_px).padStart(5)} merged=${p.merged_px} seam=${p.seam_override_px}`,
     );
   }
+  // Issue #256: one line per part from an author-made layer, so it never reads as See-through's. None without one.
+  for (const l of authorPartLines(result.parts.parts)) log(l);
   // One line per plan part an assemble.cuts entry cut, before the fringe lines: the cut is made first. None without cuts.
   for (const l of cutLines(result.cuts)) log(l);
   for (const l of fringeLines(result.parts.parts)) log(l);
@@ -228,11 +244,12 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   );
   const ghosts = Object.values(result.parts.ghost_px).reduce((a, b) => a + b, 0);
   log(`  ghost px removed: ${ghosts} over ${Object.keys(result.parts.ghost_px).length} layer(s)`);
-  log(figuresLine(result.figures));
-  for (const l of holeLines(result.figures)) log(l);
-  for (const u of result.uncovered) log(uncoveredLine(u));
+  const scene = result.parts.scene === undefined ? null : scenePhrase(result.parts.scene, W * H);
+  log(figuresLine(result.figures, scene));
+  for (const l of holeLines(result.figures, scene)) log(l);
+  for (const u of result.uncovered) log(uncoveredLine(u, scene));
   for (const d of result.drift) log(driftLine(d));
-  log(`wrote ${outs.partsJson}, ${result.images.length} PNG(s) in ${outs.partsDir}, ${outs.recomposite}, ${outs.errorMap} (uncovered error px red, covered error px blue, the painting grey)`);
+  log(`wrote ${outs.partsJson}, ${result.images.length} PNG(s) in ${outs.partsDir}, ${outs.recomposite}, ${outs.errorMap} (uncovered error px red, covered error px blue, the painting grey)${figurePath === null ? '' : `, ${figurePath} (the figure, white, the recomposite was read inside)`}`);
   return result;
 }
 
@@ -582,8 +599,12 @@ export function replaySearch(
   const self = runComparison(c.object, motionInput(c, motion, refModel, refModel, probeSchedule));
   if ('code' in self) return refuse(self);
   if (motionVerdict(c.object, self) !== null) {
-    lines.push(`replay "${c.part}": the unreduced source is not accepted against itself on the grid frames; no search runs`);
-    return { part: c.part, chosen: null, problems: run.problems, lines };
+    // Issue #280: the refusal says, in its own sentence, that the source fails itself — where, the row, the remedy;
+    // the reduction's reading follows it for the record. The line names the stimulus where it is read at one.
+    const why = sourceSelfFailure(self, c.stimulus);
+    lines.push(`replay "${c.part}": the unreduced source is not accepted against itself ${why === null ? 'on its selection frames' : why.where}; no search runs`);
+    const problems = why === null ? run.problems : run.problems.map((p) => (p.code === 'AUTO_MESH_MOTION' ? { ...p, detail: `${why.sentence}. The reduction's own reading, for the record: ${p.detail}` } : p));
+    return { part: c.part, chosen: null, problems, lines };
   }
   const selection = motion.selection;
   if (selection !== undefined && selection.maxProbes < maxReplays(N, I)) return refuse(budgetProblem(c.object, selection.maxProbes, N, I));
@@ -812,7 +833,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
       const c = m.contour;
       const stray = c.strayIslands === 0 ? '' : ` left out ${c.strayIslands} island(s), ${c.strayPixels} px`;
       const regions = m.regions.map((rg) => ` region ${rg.name}->${rg.bone} reaches ${rg.reached} (${rg.whole} whole)`).join('');
-      log(`${head}contour tol=${m.params.tolerance} margin=${m.params.margin} spacing=${m.params.spacing} ${infl} overshoot ${c.overshoot} min angle ${c.smallestAngle.value}${stray}${regions}`);
+      log(`${head}contour tol=${m.params.tolerance} margin=${m.params.margin} spacing=${m.params.spacing}${m.params.maxEdge === undefined ? '' : ` maxEdge=${m.params.maxEdge} (outline +${c.outlineCut ?? 0})`} ${infl} overshoot ${c.overshoot} min angle ${c.smallestAngle.value}${stray}${regions}`);
     } else log(`${head}grid=${m.grid} ${infl} loop passes ${rig.loopPasses[m.part]}`);
   }
   const regions = rig.rig.slots.length - rig.meshReport.length;
@@ -1024,7 +1045,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (r.seamViewport === null || fig.seam_mean === null) log(`  seam: SKIP — ${fig.skipped?.seam ?? ''}`);
   else {
     log(
-      `  seam: setup pose at ${r.seamViewport.pixelWidth}x${r.seamViewport.pixelHeight}, scale ${r.seamViewport.scale.toFixed(4)}: mean |d| ${fig.seam_mean} (<= ${SEAM_MEAN_BAR.toFixed(1)}), ` +
+      `  seam${fig.seam_border === undefined ? '' : ` (config.scene: ${fig.seam_border.frame_px_left_out} frame px on the painting's border rows and columns left out, ${fig.seam_border.px_over_40_left_out} of them over ${SEAM_PX_LEVEL})`}: setup pose at ${r.seamViewport.pixelWidth}x${r.seamViewport.pixelHeight}, scale ${r.seamViewport.scale.toFixed(4)}: mean |d| ${fig.seam_mean} (<= ${SEAM_MEAN_BAR.toFixed(1)}), ` +
         `${fig.seam_px_over_40} px over ${SEAM_PX_LEVEL}, ${fig.seam_frame_scale === null || fig.seam_px_over_40 === null ? '' : seamRigPxText(fig.seam_px_over_40, fig.seam_frame_scale)} rig px (the count / s²; <= ${SEAM_PX_BAR}), ${fig.seam_px_over_80} px over ${SEAM_PX_LEVEL_HIGH} (reported)`,
     );
     const pairs = fig.seam_pairs ?? [];
@@ -1274,6 +1295,40 @@ export interface BuildInput {
    * `check/idle_frames/`; absent, the loop is as before.
    */
   leadIn?: number;
+  /** `--seam-pairs`, forwarded to the check as `check` takes it (issue #257): the seam split by pair on a pass too; absent, nothing moves. */
+  seamPairs?: boolean;
+  /** `--keep-stills`, forwarded to the check as `check` takes it (issue #257): the setup-pose still under `check/setup_still/`; absent, nothing moves. */
+  keepStills?: boolean;
+}
+
+/** What `build` does with one flag `check` takes: hands it to its check stage, takes it as its own, or refuses it because build supplies the value itself. */
+export type CheckFlagInBuild =
+  | { as: 'forwarded' }
+  | { as: 'own'; why: string }
+  | { as: 'supplied'; why: string };
+
+/**
+ * Every flag `check` takes and what `build` does with it (issue #257). `cli.ts`
+ * refuses a `supplied` flag on `build` with its `why`; the selftest holds the
+ * table's keys to the flags `check`'s own refusal lists, so a flag added to
+ * `check` without a line here is a named failure, not a flag `build` drops.
+ */
+export const CHECK_FLAGS_IN_BUILD: Readonly<Record<string, CheckFlagInBuild>> = {
+  '--rig': { as: 'supplied', why: 'its check reads the rig its rig stage writes, <out>/rig; run check --rig to measure another rig' },
+  '--out': { as: 'own', why: 'build\'s own --out; its check writes under <out>/check' },
+  '--parts': { as: 'supplied', why: 'its check reads the parts its assemble stage writes, <out>; run check --parts to measure against others' },
+  '--source': { as: 'own', why: 'the painting assemble reads; it is not handed to the check, so check.json carries no SETUP_POSE_VS_SOURCE — run check --rig <out>/rig --parts <out> --source <painting> for that line' },
+  '--page-edges': { as: 'forwarded' },
+  '--pack-shape': { as: 'forwarded' },
+  '--requirements': { as: 'forwarded' },
+  '--seam-pairs': { as: 'forwarded' },
+  '--keep-stills': { as: 'forwarded' },
+};
+
+/** The `build` refusal of a `check` flag build supplies itself ({@link CHECK_FLAGS_IN_BUILD}), or null for any other flag. */
+export function suppliedCheckFlag(flag: string): string | null {
+  const row = Object.hasOwn(CHECK_FLAGS_IN_BUILD, flag) ? CHECK_FLAGS_IN_BUILD[flag] : undefined;
+  return row?.as === 'supplied' ? `build does not take "${flag}"; ${row.why}` : null;
 }
 
 /**
@@ -1347,6 +1402,8 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   const out = input.out;
   mkdirSync(out, { recursive: true });
   for (const p of BUILD_OWNS) rmSync(join(out, p), { recursive: true, force: true });
+  // Issue #242: the figure mask is written only under config.scene; one left by an earlier scene build is not this build's.
+  rmSync(join(out, FIGURE_MASK_FILE), { force: true });
   // The idle-keys value is named only when it is not the default, so a build without the flag, or with the default, prints the line it printed before issue #95.
   const idleKeys = input.idleKeys ?? DEFAULT_IDLE_KEYS;
   log(`rig-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? `, with the idle loop${input.leadIn === undefined ? '' : ` after a lead-in of ${input.leadIn} period(s)`}` : ''}`);
@@ -1376,7 +1433,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
 
   let report: CheckReport;
   try {
-    report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(input.requirements === undefined ? {} : { requirements: input.requirements }) }, run.check, run.checkBin, prefixed('check'));
+    report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(input.requirements === undefined ? {} : { requirements: input.requirements }), seamPairs: input.seamPairs === true, keepStills: input.keepStills === true }, run.check, run.checkBin, prefixed('check'));
   } catch (err) {
     return refused('check', err);
   }