rig-parts 2.7.0 → 2.8.0

package/cli.ts

@@ -1759,6 +1759,12 @@ function cmdAssemble(args: string[]): number {
       const target = writePath === undefined ? null : readConfigWriteTarget(writePath);
       const src = readSource(source);
       const cfg = loadEarlyConfig(config, 'layers');
+      if (cfg.assemble.take?.some(item => 'part' in item)) {
+        throw new PartsError([{
+          code: 'ASSEMBLE_REGION_TAKE_PLAN', object: 'config.assemble.take',
+          detail: 'region takes require a declared plan and setup_painting requirements at assemble/build; draft the plan before declaring a region take',
+        }]);
+      }
       const runs = applyTakenLayers(readRuns(full, head), src, { ...cfg, assemble: { ...cfg.assemble, plan: undefined } }, config);
       const g = proposeFields(cfg, runs.single ? { w: src.width, h: src.height } : null);
       const geometry = { sourceW: src.width, sourceH: src.height, ...g };

package/docs/AUTHORING.md

@@ -656,7 +656,7 @@ some layers, can supply those tags without editing either run directory:
 }]
 ```
 
-This array belongs in `assemble`. Every entry requires all four fields. `run`
+This array belongs in `assemble`. Every whole-layer entry requires all four fields. `run`
 is the **target** `full` or `head` run; `head` requires `--head`. `run_dir` and
 `st_input` resolve relative to the config, for assemble, build and
 `assemble --propose-plan` alike. Each target run/tag may be selected once. Empty
@@ -735,6 +735,43 @@ identity an executable check on supplied original inputs instead of trusting
 that claim or hand-editing `layers.json`. Seed and painting selection remain
 the author's decisions.
 
+### Taking a derived region (`assemble.take`, issue #1000)
+
+A region entry names one existing plan part, its target run, one donor run and
+one seed pixel on the target run canvas (integer x right, y down).
+
+```json
+"take": [{
+  "run": "full",
+  "run_dir": "runs/other",
+  "st_input": "inputs/other_full.png",
+  "part": "body",
+  "seed": [120, 240]
+}]
+```
+
+The region is derived from base alpha < 128, donor alpha >= 128, and the
+maximum RGB channel difference after rounding each pixel source-over white.
+The tolerance is exactly `--requirements`' `setup_painting.rgb_tolerance`.
+A missing declaration is refused. The target input is derived as for whole-layer
+take above. Both run canvases must agree, and the supplied original donor input
+must match the entire target input in RGBA and dimensions, establishing the same
+crop. Different crops await #973. Painting samples use the existing Lanczos3
+resize onto the run canvas. Only the 8-connected qualifying component containing
+the seed is copied. The base layer's depth and draw order stay in use.
+
+No polygon, rectangle or brush input is accepted. A drawn bound is scissors.
+The log reports the derived pixel count, run-grid `[left, top, width, height]`
+bounding box, painting-match share and tolerance. The share is 1 because every
+selected pixel passed the painting predicate. An empty region, seed outside its
+components or missing donor tag is refused before output. A target may have one
+region take or one whole-layer take. Hidden companions and active scalar depth
+sheets require separate bindings and are refused. Region donor runs use the same
+`editor_receipts` ledger as the base runs. Under `required` or `trace_parts`,
+every donor author/hidden image requires a valid receipt before pixels are
+copied. A receipted author-layer target is accepted. The plan proposal command
+refuses region entries because their part names depend on an existing plan.
+
 ### Editor receipts (`assemble.editor_receipts`, issue #946)
 
 An image edited in code — a layer re-segmented by a script, a patch
@@ -4982,6 +5019,13 @@ those settings. Changing a config seed alone cannot change a no-config run.
 | <a id="ASSEMBLE_TAKE_SUPPORT"></a>`ASSEMBLE_TAKE_SUPPORT` | selected layer has zero alpha > 8 pixels | choose a nonempty donor layer |
 | <a id="ASSEMBLE_TAKE_DEPTH_AMBIGUOUS"></a>`ASSEMBLE_TAKE_DEPTH_AMBIGUOUS` | different original runs have equal or null depths | use a run with distinct numeric depths; do not invent an inter-run tie order |
 | <a id="ASSEMBLE_TAKE_PLAN_ORDER"></a>`ASSEMBLE_TAKE_PLAN_ORDER` | supplied plan reverses an overlapping mixed-run pair: two-run full-layer head roles first, scalar depth within a role band (head-run and single-run rows use scalar depth); names the parts and support intersection | use the order drafted by `assemble --propose-plan`; fallback headwear follows the body and precedes the face, front hair follows the face; disjoint supports impose no plan-order constraint |
+| <a id="ASSEMBLE_REGION_TAKE_TOLERANCE"></a>`ASSEMBLE_REGION_TAKE_TOLERANCE` | a region take has no authored `setup_painting.rgb_tolerance` | supply the same requirements file to assemble/build and check |
+| <a id="ASSEMBLE_REGION_TAKE_GEOMETRY"></a>`ASSEMBLE_REGION_TAKE_GEOMETRY` | donor and target canvases or original input RGBA differ, or the target head run is absent | supply the same crop and original input PNG. Cropped donors await #973 |
+| <a id="ASSEMBLE_REGION_TAKE_PART"></a>`ASSEMBLE_REGION_TAKE_PART` | the named plan part/run or its base/donor tag is absent, or the target is taken twice | name an existing plan part and one donor holding its tag |
+| <a id="ASSEMBLE_REGION_TAKE_EMPTY"></a>`ASSEMBLE_REGION_TAKE_EMPTY` | the derived qualifying region has 0 pixels | supply material missing from the base that covers and matches the painting |
+| <a id="ASSEMBLE_REGION_TAKE_SEED"></a>`ASSEMBLE_REGION_TAKE_SEED` | the seed touches no qualifying component | name an integer pixel in the derived region on the target run canvas |
+| <a id="ASSEMBLE_REGION_TAKE_BINDING"></a>`ASSEMBLE_REGION_TAKE_BINDING` | active scalar depth or hidden companions have no region binding | supply a part without those companions |
+| <a id="ASSEMBLE_REGION_TAKE_PLAN"></a>`ASSEMBLE_REGION_TAKE_PLAN` | a region entry is present during plan proposal | draft the plan before declaring region takes, then use assemble/build with requirements |
 | <a id="ASSEMBLE_TAKE_GEOMETRY"></a>`ASSEMBLE_TAKE_GEOMETRY` | missing target head, unequal run canvases or unequal original input dimensions | supply matching geometry; the check does not resize inputs |
 | <a id="ASSEMBLE_TAKE_META"></a>`ASSEMBLE_TAKE_META` | donor `meta.json` lacks a readable prompt ID or seed | retain the original run metadata |
 | <a id="ASSEMBLE_TAKE_INPUT"></a>`ASSEMBLE_TAKE_INPUT` | declared donor input PNG cannot be read | name its original PNG relative to the config |
@@ -5353,6 +5397,7 @@ documents do not ship). Each is an input this package built; none is an author's
 | <a id="CHECK_SOURCE_SIZE"></a>`CHECK_SOURCE_SIZE` | the painting `--source` names is not this rig's: no single `rig_scale` takes its width and height to the stage's (assemble makes the canvas `trunc(w × rig_scale)` x `trunc(h × rig_scale)`), or, with `parts.json` read, its `scale_rig_per_source` does not; or the stage is not whole pixels. Refused before anything is built | the painting the rig was made from — the stage's own size, or the painting `assemble` was given |
 | <a id="CHECK_SOURCE_PNG"></a>`CHECK_SOURCE_PNG` | `--source` names a file that does not read as a PNG | a PNG |
 | <a id="CHECK_SETUP_MATCHES_PAINTING"></a>`CHECK_SETUP_MATCHES_PAINTING` | region, slot, failing-pixel box, slot pixelcount, complete region pixelcount and declared limit | compare the source painting beside the actual setup; follow [Source before scissors](#source-before-scissors), then rerun with the same authored limit |
+| <a id="CHECK_SETUP_PAINTING_BACKDROP"></a>`CHECK_SETUP_PAINTING_BACKDROP` | declared backdrop PNG cannot be read or decoded, its byte SHA-256 differs, its original painting grid differs, or any alpha is not 255 | supply an opaque plate with the declared lowercase SHA-256, aligned to the original painting; no fitting or white fallback |
 | <a id="CHECK_SETUP_PAINTING_SOURCE"></a>`CHECK_SETUP_PAINTING_SOURCE` | a declaration without a source painting | supply `--source`; the assembled composite is not an independent reference |
 | <a id="CHECK_SETUP_PAINTING_MEASURED"></a>`CHECK_SETUP_PAINTING_MEASURED` | missing native setup/ownership or unsupported clipping | supply observable textured setup geometry; an unavailable instrument never passes |
 | <a id="CHECK_BOUNDARY_COLOUR_STEP"></a>`CHECK_BOUNDARY_COLOUR_STEP` | the requirements file declares `boundary_colour.max_step_excess` and a part boundary's colour step in the rig's render exceeds the same boundary's step in the rig's own pieces by more than it; the part pair, the frame (`setup` or `idle frame <n> (t <s> s)`), the stage pixel, the excess, the declared allowance and both steps are quoted. Unlike [`CHECK_SETUP_MATCHES_PAINTING`](#CHECK_SETUP_MATCHES_PAINTING), which compares the painting per declared region at the setup pose, this compares against the rig's own flat pieces (`parts.json` placement at setup, each piece's rest colour through its art UVs on every idle frame), so a part drawn over its neighbour's line art is not a failure | the pair's rig image or mesh: `rig/images/<part>.png` (a texture stretched into its padded UVs, or a notch cut out of it), or that part's mesh in `config.json` `meshes` when the mesh cuts a corner off the art; see [Boundary colour step](#boundary-colour-step-issue-942) |
@@ -6065,7 +6110,7 @@ Under `--source <painting.png>`, a second reported line, also never a FAIL
 | line | reports | bar | `reference-demo` | `reference-sample` | SKIP when |
 | --- | --- | --- | --- | --- | --- |
 | <a id="SETUP_POSE_VS_SOURCE"></a>`SETUP_POSE_VS_SOURCE` | the setup pose against the painting, by `assemble`'s own `measureRecomposite` over the stage's pixels — `mean_abs` and `within_share` (mean channel, within 8), `error_px` (max channel over 40), `uncovered_error_px` (of those, where the pose has alpha 128 or less), `hole_count` and the largest hole's box — with `painting_px`, `stage_px`, `render_px` and `render_scale` beside them. The painting is resampled onto the stage as assemble resamples it (lanczos3, alpha dropped). rigc renders onto an opaque grey, so the pose over white and its alpha are read off a second still of the same pose with every slot tinted black; both are carried onto the stage with the seam's map turned round (bilinear) | none — status `REPORTED`; assemble applies no bar to the figures it measures, so none is derived here | 3.146 / 93.43 % / 12,399 / 1,732, 518 holes, the largest 61 px at 351,157 6x20 (assemble's recomposite: 2.391 / 95.81 % / 11,050 / 1,564, 453) | 1.095 / 97.30 % / 5,348 / 1,239, 313 holes, the largest 88 px at 479,416 6x29 (assemble's: 0.835 / 97.95 % / 4,512 / 1,185, 259) | not written without `--source` |
-| <a id="SETUP_MATCHES_PAINTING"></a>`SETUP_MATCHES_PAINTING` | declared region count, native box, limit and actual top contributor rows | PASS/FAIL against authored limits; no limit is SKIP, or the refusal `SETUP_PAINTING_REQUIRED_LIMIT` under `setup_painting.required: true`; with `--source`, no declaration is SKIP with its reason and declaration remedy; undeclared regions are not judged |
+| <a id="SETUP_MATCHES_PAINTING"></a>`SETUP_MATCHES_PAINTING` | declared region count, native box, limit and actual top contributor rows; observations source-over white unless `setup_painting.backdrop` declares the opaque plate behind a full-frame painting | PASS/FAIL against authored limits; no limit is SKIP, or the refusal `SETUP_PAINTING_REQUIRED_LIMIT` under `setup_painting.required: true`; with `--source`, no declaration is SKIP with its reason and declaration remedy; undeclared regions are not judged |
 | <a id="BOUNDARY_COLOUR_STEP"></a>`BOUNDARY_COLOUR_STEP` | the worst colour-step excess over the rig's own pieces at any part boundary of the setup and every idle frame, its part pair, frame and stage pixel, and the declared `max_step_excess` | PASS/FAIL against the declared allowance (FAIL is [`CHECK_BOUNDARY_COLOUR_STEP`](#CHECK_BOUNDARY_COLOUR_STEP), an unreadable piece [`CHECK_BOUNDARY_COLOUR_UNMEASURED`](#CHECK_BOUNDARY_COLOUR_UNMEASURED)); no `boundary_colour` in the requirements file is SKIP with its reason and the declaration to add, never a pass |
 
 The figures are assemble's by construction, not a second definition beside them;
@@ -6669,7 +6714,19 @@ substituted. Source PNG readers preserve straight RGBA. This optional check
 first composites the painting over opaque white at its **original source
 resolution**, rounding each RGB channel to RGBA8, then passes that opaque
 image through the existing `sourceInRig` Lanczos3 resampling onto the stage.
-The rendered setup is composited over white on the native stage grid. This
+The rendered setup is composited over white on the native stage grid.
+For a full-frame painting whose figure was painted over an opaque background,
+declare `setup_painting.backdrop: {"path": "backdrop.png", "sha256": "<64 lowercase hex digits>"}`.
+The PNG path resolves relative to the requirements file. The exact bytes read
+are hashed before decoding; the plate must be opaque everywhere and match the
+original painting dimensions. It is never fitted or inferred from the art.
+With the declaration, both observations use that plate instead of white:
+the painting is flattened over it before resampling, and the plate is
+resampled onto the stage before the rendered setup is composited over it.
+The report carries the declared path and verified hash. Pixels where painting
+RGB differs from the plate above the authored tolerance also enter the figure
+domain, even when no setup piece draws there. Missing material remains counted.
+Without the declaration, report bytes and the white comparator are unchanged. This
 ordering excludes hidden RGB from both resampling taps and figure detection;
 the global `sourceInRig` and legacy checks retain their existing RGB semantics.
 The figure domain is the union of rendered

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/build.ts

@@ -7,6 +7,7 @@ import { writeMaterialSources } from './cutmaterialio.ts';
 import { CUT_MATERIAL_LINE, CUT_MATERIAL_SOURCES, materialLines } from './cutmaterial.ts';
 import { ART_JOINT_LINE, artJointLines } from './artjoints.ts';
 import { applyTakenLayers } from './takelayers.ts';
+import { applyTakenRegions } from './takeregion.ts';
 import { ownershipLines, provenanceLines } from './provenance.ts';
 import { readSourceDepth } from './depthsheets.ts';
 import { orderedBaseAnchor } from './baseanchor.ts';
@@ -345,7 +346,8 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   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);
+  const takenRuns = applyTakenLayers(read, src, cfg, input.config);
+  const runs = applyTakenRegions(takenRuns, src, cfg, input.config, requirementsFile?.setup_painting, receipts);
   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);

package/src/check.ts

@@ -1,3 +1,4 @@
+import { readSetupBackdrop } from './setupbackdrop.ts';
 import { SETUP_PAINTING_LINE, UNDECLARED_SETUP_PAINTING_REASON, setupPaintingBounds, setupPaintingLine, type SetupPainting, type SetupPaintingLine, type SetupPaintingObservation } from './setuppainting.ts';
 import { readMaterialSources } from './cutmaterialio.ts';
 import { CUT_MATERIAL_LINE, checkJointMaterial, type MaterialLine } from './cutmaterial.ts';
@@ -1940,7 +1941,7 @@ export function officialRenderer(): OfficialRenderer {
 
 /** Observe the actual setup on the declared stage grid. No frame-zero motion,
  * fitted alignment, flat recomposite or duplicate core validation. */
-export function measureSetupPainting(build: string, stage: StageBox, source: Raster, declared: SetupPainting, problems: Problem[]): SetupPaintingLine {
+export function measureSetupPainting(build: string, stage: StageBox, source: Raster, declared: SetupPainting, problems: Problem[], backdrop?: Raster): SetupPaintingLine {
   const api = officialRenderer();
   const skeleton = join(build, 'skeleton.json'), atlas = join(build, 'skeleton.atlas');
   const candidate = api.loadCandidate({ skeletonText: readFileSync(skeleton, 'utf8'), atlasText: readFileSync(atlas, 'utf8'), atlasDir: build, label: 'setup versus painting' }, { skeleton, atlas }, undefined);
@@ -1954,17 +1955,17 @@ export function measureSetupPainting(build: string, stage: StageBox, source: Ras
   const project = api.projector(vp), owners = new Int32Array(W * H).fill(-1);
   pose.pieces.forEach((piece, i) => api.rasterisePiece(api.pageFor(candidate.pages, piece), piece, project, vp, (x, y, _r, _g, _b, a) => { if (a > 0) owners[y * W + x] = i; }));
   // sourceInRig intentionally reads opaque RGB, discarding source alpha before
-  // resizing. This optional comparison declares source-over white instead:
+  // resizing. This optional comparison declares source-over the plate or white:
   // flatten at ORIGINAL source resolution first, so hidden RGB cannot reach
   // Lanczos taps or the figure silhouette. Do not change the legacy helper.
   const whiteSource = newRaster(source.width, source.height);
   for (let p = 0; p < source.width * source.height; p++) {
-    for (let c = 0; c < 3; c++) whiteSource.data[p * 4 + c] = Math.round(source.data[p * 4 + c] * source.data[p * 4 + 3] / 255 + 255 * (1 - source.data[p * 4 + 3] / 255));
+    for (let c = 0; c < 3; c++) whiteSource.data[p * 4 + c] = Math.round(source.data[p * 4 + c] * source.data[p * 4 + 3] / 255 + (backdrop?.data[p * 4 + c] ?? 255) * (1 - source.data[p * 4 + 3] / 255));
     whiteSource.data[p * 4 + 3] = 255;
   }
   const painting = sourceInRig(whiteSource, W, H);
   const setup = api.renderFrame(pose, candidate.pages, vp, [0, 0, 0, 0]);
-  return setupPaintingLine(declared, painting, { width: W, height: H, data: new Uint8ClampedArray(setup.data) }, figureSilhouette(painting).data, owners, pose.pieces.map(p => p.slot), problems);
+  return setupPaintingLine(declared, painting, { width: W, height: H, data: new Uint8ClampedArray(setup.data) }, figureSilhouette(painting).data, owners, pose.pieces.map(p => p.slot), problems, backdrop === undefined ? undefined : sourceInRig(backdrop, W, H));
 }
 
 /** One decoder/poser lifetime per state; retain only finite bounds and identities, never atlas pages or rasters. */
@@ -6399,6 +6400,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       return null;
     }
   };
+  let setupBackdrop: Raster | undefined;
   // Issue #538: the schedule is read once, first, by rigc's own reader; refused, nothing is built or written.
   const env = environment === undefined ? null : take(() => readCheckEnvironment(environment));
   // Issue #590: the steady-wind band spec is read and resolved before anything is built or written.
@@ -6423,6 +6425,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     if (file.setup_painting !== undefined) take(() => {
       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' }]);
+      setupBackdrop = readSetupBackdrop(file.setup_painting as SetupPainting, requirements, ready.source?.painting ?? null);
     });
     // 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([
@@ -7018,7 +7021,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       const sr = rigc(['render', '--candidate', join(stillDir, 'build'), '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(maxSide), ...(fixedSkeleton === undefined ? [] : ['--geometry']), '--out', join(stillDir, 'render')]);
       if (sr.status !== 0) refuseIfAny(rigcFailed('render (the setup-pose still)', sr, sr.out.split('\n').filter((l) => l.includes('FAIL'))));
       const stillSet = readFrameSet(join(stillDir, 'render'));
-      if (reqFile?.setup_painting !== undefined && inp.source !== null) setupPainting = measureSetupPainting(join(stillDir, 'build'), inp.stage, inp.source.painting, reqFile.setup_painting, problems);
+      if (reqFile?.setup_painting !== undefined && inp.source !== null) setupPainting = measureSetupPainting(join(stillDir, 'build'), inp.stage, inp.source.painting, reqFile.setup_painting, problems, setupBackdrop);
       if (fixedSkeleton !== undefined) {
         const geometryPath = join(stillSet.dir, GEOMETRY_FILE);
         const geometry = readGeometry(geometryPath, stillSet.written);

package/src/config.ts

@@ -1,6 +1,6 @@
 import { SEAM_RULES, type SeamRule } from './seamrule.ts';
 import { GROUNDS, type Ground, PROJECT_RULES, type ProjectRule } from './projectrule.ts';
-import type { TakeLayers } from './takelayers.ts';
+import type { TakeDeclaration } from './takeregion.ts';
 import { paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
 import { baseAnchorProblems, type BaseAnchor } from './baseanchor.ts';
 import type { DepthConfig } from './depthsheets.ts';
@@ -309,8 +309,8 @@ export interface Assemble {
   project?: ProjectRule;
   /** Optional per-character painting ground (issue #996); absent, `plain`. Read by `visible` only. */
   ground?: Ground;
-  /** Verified named replacements from another See-through run (#866). */
-  take?: TakeLayers[];
+  /** Whole-layer replacements (#866) or seeded, painting-matched region takes (#1000). */
+  take?: TakeDeclaration[];
   /** 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. */
@@ -1631,7 +1631,7 @@ export interface EarlyConfig {
   depth?: DepthConfig;
   key: string;
   seethrough: SeeThrough;
-  assemble: { rig_scale: number; seam?: SeamRule; project?: ProjectRule; ground?: Ground; take?: TakeLayers[]; editor_receipts?: EditorReceipts; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
+  assemble: { rig_scale: number; seam?: SeamRule; project?: ProjectRule; ground?: Ground; take?: TakeDeclaration[]; 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. */
@@ -2455,15 +2455,32 @@ function checkKeepUnderOccluders(c: Check, a: Record<string, Json>, plan: readon
   });
 }
 
-function checkTakeLayers(c: Check, value: Json): void {
+function checkTakeLayers(c: Check, value: Json, plan: string[] | null = null): void {
   const at = 'config.assemble.take';
   if (!c.array(at, value, false)) return;
   const seen = new Set<string>();
   (value as Json[]).forEach((v, i) => {
-    const p = `${at}[${i}]`, o = c.object(p, v, ['run', 'run_dir', 'st_input', 'tags'], []);
+    const p = `${at}[${i}]`;
+    const region = isPlainObject(v) && ('part' in v || 'seed' in v);
+    const o = region
+      ? c.object(p, v, ['run', 'run_dir', 'st_input', 'part', 'seed'], [])
+      : c.object(p, v, ['run', 'run_dir', 'st_input', 'tags'], []);
     if (o === null) return;
     if (o.run !== 'full' && o.run !== 'head') c.fail('CONFIG_FIELD_TYPE', p + '.run', '"full" or "head" is required');
     for (const k of ['run_dir', 'st_input']) c.string(`${p}.${k}`, o[k]);
+    if (region) {
+      if (c.string(`${p}.part`, o.part) && plan !== null && !plan.includes(o.part)) {
+        c.fail('CONFIG_NAME_RESOLVES', `${p}.part`, `names "${o.part}"; a part named in assemble.plan is required`);
+      }
+      const key = `${String(o.run)}:part:${String(o.part)}`;
+      if (seen.has(key)) c.fail('CONFIG_TAKE_UNIQUE', `${p}.part`, `names ${key} again; one donor per target part is required`);
+      seen.add(key);
+      const seed = o.seed;
+      if (!(Array.isArray(seed) && seed.length === 2 && seed.every(n => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0))) {
+        c.fail('CONFIG_FIELD_TYPE', `${p}.seed`, 'requires [x, y], nonnegative safe integers in target-run canvas pixels');
+      }
+      return;
+    }
     if (!c.array(p + '.tags', o.tags, true)) return;
     (o.tags as Json[]).forEach((tag, j) => {
       const reading = typeof tag === 'string' ? readLayerTag(tag) : null;
@@ -2559,7 +2576,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 ('take' in a) checkTakeLayers(c, a.take, parts);
   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) => {

package/src/setupbackdrop.ts

@@ -0,0 +1,28 @@
+/** Declared setup plate: hash the same bytes that are decoded, before builds. */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { refuseIfAny } from './errors.ts';
+import { decodePngBytes } from './raster/png.ts';
+import type { Raster } from './raster/types.ts';
+import type { SetupPainting } from './setuppainting.ts';
+
+export function readSetupBackdrop(declared: SetupPainting, requirements: string, source: Raster | null): Raster | undefined {
+  const plate = declared.backdrop;
+  if (plate === undefined) return undefined;
+  const fail = (detail: string): never => {
+    refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_BACKDROP', object: 'setup_painting.backdrop', detail }]);
+    throw new Error('unreachable');
+  };
+  let bytes: Uint8Array;
+  try { bytes = new Uint8Array(readFileSync(resolve(dirname(requirements), plate.path))); }
+  catch { return fail(`cannot read declared PNG "${plate.path}"; requires the authored opaque backdrop, not a guessed colour`); }
+  const hash = createHash('sha256').update(bytes).digest('hex');
+  if (hash !== plate.sha256) return fail(`PNG "${plate.path}" has sha256 ${hash}; requires declared ${plate.sha256}`);
+  let raster: Raster;
+  try { raster = decodePngBytes(bytes, plate.path); }
+  catch { return fail(`"${plate.path}" is not a decodable PNG; requires an opaque backdrop on the original painting grid`); }
+  if (source === null || raster.width !== source.width || raster.height !== source.height) return fail(`PNG "${plate.path}" is ${raster.width}x${raster.height}; requires the original source painting grid ${source === null ? '(no source)' : `${source.width}x${source.height}`}, without fitting`);
+  if (raster.data.some((v, i) => i % 4 === 3 && v !== 255)) return fail(`PNG "${plate.path}" contains nonopaque pixels; requires alpha 255 throughout`);
+  return raster;
+}

package/src/setuppainting.ts

@@ -16,6 +16,8 @@ export interface SetupPainting {
    * refused by name (SETUP_PAINTING_REQUIRED_LIMIT) instead of reported as
    * SKIP. Absent or false: the pre-#943 reading, unchanged. */
   required?: boolean;
+  /** Opaque plate on the original painting grid; path relative to requirements. */
+  backdrop?: { path: string; sha256: string };
   /** A pixel counts when its maximum RGB difference is strictly greater. */
   rgb_tolerance: number;
   regions: SetupPaintingRegion[];
@@ -33,8 +35,17 @@ export function setupPaintingProblems(value: unknown, at: string): Problem[] {
     for (const k of Object.keys(v)) if (!allowed.includes(k) && !free(k, v[k])) fail(`${where}.${k}`, `is unknown; fields are ${allowed.join(', ')}`);
   };
   if (!object(value)) return [{ code: 'REQUIREMENTS_FIELD', object: at, detail: 'requires {rgb_tolerance, regions: [{name, box, max_pixels?}]}' }];
-  keys(value, ['required', 'rgb_tolerance', 'regions'], at);
+  keys(value, ['required', 'backdrop', 'rgb_tolerance', 'regions'], at);
   if ('required' in value && typeof value.required !== 'boolean') fail(`${at}.required`, `is ${JSON.stringify(value.required)}; requires true (the check may not SKIP: every limit must be declared) or false (the same as omitting it)`);
+  if ('backdrop' in value) {
+    const b = value.backdrop, where = `${at}.backdrop`;
+    if (!object(b)) fail(where, 'requires {path, sha256} for an opaque PNG on the original painting grid');
+    else {
+      keys(b, ['path', 'sha256'], where);
+      if (typeof b.path !== 'string' || b.path.trim() === '') fail(`${where}.path`, 'requires a nonempty PNG path relative to the requirements file');
+      if (typeof b.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(b.sha256)) fail(`${where}.sha256`, 'requires the lowercase SHA-256 of the PNG bytes');
+    }
+  }
   // Issue #943: under required: true an absent limit is not a SKIP to report but a refusal naming the field.
   const required = value.required === true;
   const missing = (where: string, needed: string): void => {
@@ -81,8 +92,9 @@ export interface SetupPaintingLine {
   status: 'PASS' | 'FAIL' | 'SKIP';
   instrument: 'rigc renderer setup textured pieces';
   registration: 'declared stage grid, scale 1, no fitting';
-  compositing: 'source-over white, RGBA8';
-  figure: 'source figureSilhouette union rendered alpha > 0';
+  compositing: 'source-over white, RGBA8' | 'source-over declared backdrop, RGBA8';
+  backdrop?: { path: string; sha256: string };
+  figure: 'source figureSilhouette union rendered alpha > 0' | 'source figureSilhouette union rendered alpha > 0 union source-backdrop RGB difference > tolerance';
   ownership: 'last actual drawn piece with sampled alpha > 0; uncovered explicit';
   rgb_tolerance: number;
   regions: SetupPaintingReading[];
@@ -95,12 +107,13 @@ export const UNDECLARED_SETUP_PAINTING_REASON = 'setup_painting is undeclared; s
 
 /** Pixel metric only. Caller supplies the actual renderer's textured setup and
  * its per-pixel drawn-piece owners on precisely the source grid. RGB under
- * zero alpha is ignored: both observations are source-over white first.
+ * zero alpha is ignored: both observations are source-over the declared opaque
+ * backdrop, or white when absent.
  * Region totals count each pixel once, even with translucent contributors.
  */
 export function setupPaintingLine(
   declared: SetupPainting, source: Raster, setup: Raster, figure: Uint8Array,
-  owners: Int32Array, slots: readonly string[], problems: Problem[],
+  owners: Int32Array, slots: readonly string[], problems: Problem[], backdrop?: Raster,
 ): SetupPaintingLine {
   refuseIfAny(setupPaintingProblems(declared, 'setup_painting'));
   refuseIfAny(setupPaintingBounds(declared, source.width, source.height));
@@ -108,15 +121,18 @@ export function setupPaintingLine(
   if (setup.width !== W || setup.height !== H || figure.length !== n || owners.length !== n || source.data.length !== n * 4 || setup.data.length !== n * 4 || owners.some(i => i < -1 || i >= slots.length)) {
     refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_MEASURED', object: SETUP_PAINTING_LINE, detail: 'requires actual setup pixels, figure domain and renderer owners on the declared native source grid; no fitted registration or guessed owner is substituted' }]);
   }
+  if ((declared.backdrop !== undefined) !== (backdrop !== undefined) || (backdrop !== undefined && (backdrop.width !== W || backdrop.height !== H || backdrop.data.length !== n * 4 || backdrop.data.some((v, i) => i % 4 === 3 && v !== 255)))) {
+    refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_BACKDROP', object: 'setup_painting.backdrop', detail: 'requires the declared opaque backdrop pixels on the native stage grid; an absent or mismatched plate is never replaced with white' }]);
+  }
   const regions = declared.regions.map<SetupPaintingReading>(r => {
     const rows = new Map<string, { pixels: number; x0: number; y0: number; x1: number; y1: number }>();
     let count = 0;
     for (let y = r.box[1]; y < r.box[1] + r.box[3]; y++) for (let x = r.box[0]; x < r.box[0] + r.box[2]; x++) {
       const p = y * W + x, q = p * 4;
-      if (figure[p] === 0 && setup.data[q + 3] === 0) continue;
+      if (figure[p] === 0 && setup.data[q + 3] === 0 && (backdrop === undefined || ![0, 1, 2].some(c => Math.abs(source.data[q + c] - backdrop.data[q + c]) > declared.rgb_tolerance))) continue;
       let delta = 0;
       for (let c = 0; c < 3; c++) {
-        const white = (image: Raster): number => Math.round(image.data[q + c] * image.data[q + 3] / 255 + 255 * (1 - image.data[q + 3] / 255));
+        const white = (image: Raster): number => Math.round(image.data[q + c] * image.data[q + 3] / 255 + (backdrop?.data[q + c] ?? 255) * (1 - image.data[q + 3] / 255));
         delta = Math.max(delta, Math.abs(white(source) - white(setup)));
       }
       if (delta <= declared.rgb_tolerance) continue;
@@ -134,7 +150,7 @@ export function setupPaintingLine(
     return result;
   });
   const noLimit = regions.some(r => r.status === 'SKIP');
-  return { status: regions.some(r => r.status === 'FAIL') ? 'FAIL' : noLimit ? 'SKIP' : 'PASS', instrument: 'rigc renderer setup textured pieces', registration: 'declared stage grid, scale 1, no fitting', compositing: 'source-over white, RGBA8', figure: 'source figureSilhouette union rendered alpha > 0', ownership: 'last actual drawn piece with sampled alpha > 0; uncovered explicit', rgb_tolerance: declared.rgb_tolerance, regions,
+  return { status: regions.some(r => r.status === 'FAIL') ? 'FAIL' : noLimit ? 'SKIP' : 'PASS', instrument: 'rigc renderer setup textured pieces', registration: 'declared stage grid, scale 1, no fitting', compositing: backdrop === undefined ? 'source-over white, RGBA8' : 'source-over declared backdrop, RGBA8', ...(declared.backdrop === undefined ? {} : { backdrop: { ...declared.backdrop } }), figure: backdrop === undefined ? 'source figureSilhouette union rendered alpha > 0' : 'source figureSilhouette union rendered alpha > 0 union source-backdrop RGB difference > tolerance', ownership: 'last actual drawn piece with sampled alpha > 0; uncovered explicit', rgb_tolerance: declared.rgb_tolerance, regions,
     ...(noLimit ? { reason: 'a region has no declared max_pixels; it is measured as SKIP, never PASS' } : {}) };
 }
 

package/src/takelayers.ts

@@ -9,6 +9,7 @@ import { PartsError, refuseIfAny, type Problem } from './errors.ts';
 import { dilate } from './raster/morph.ts';
 import { newMask, type Raster } from './raster/types.ts';
 import { readPng } from './raster/png.ts';
+import type { TakeDeclaration } from './takeregion.ts';
 import type { TakenLayerSource } from './takesource.ts';
 
 export interface TakeLayers {
@@ -62,8 +63,8 @@ function supportOverlap(a: Layer, b: Layer): number {
   return px;
 }
 /** Apply every declaration together, so replacing all tied layers from one run can retain its known order. */
-export function applyTakenLayers(runs: { full: LayerSet; head: LayerSet; single: boolean }, painting: Raster, cfg: Pick<EarlyConfig, 'seethrough' | 'depth'> & { assemble: { take?: TakeLayers[]; plan?: PlanEntry[] } }, configPath: string): { full: LayerSet; head: LayerSet; single: boolean; notes: string[] } {
-  const declarations = cfg.assemble.take ?? [];
+export function applyTakenLayers(runs: { full: LayerSet; head: LayerSet; single: boolean }, painting: Raster, cfg: Pick<EarlyConfig, 'seethrough' | 'depth'> & { assemble: { take?: TakeDeclaration[]; plan?: PlanEntry[] } }, configPath: string): { full: LayerSet; head: LayerSet; single: boolean; notes: string[] } {
+  const declarations = (cfg.assemble.take ?? []).filter((item): item is TakeLayers => 'tags' in item);
   if (declarations.length === 0) return { ...runs, notes: [] };
   if (cfg.depth !== undefined || [...runs.full.layers, ...runs.head.layers].some(l => l.depthSheet !== undefined)) return refuse('ASSEMBLE_TAKE_DEPTH_SHEET', 'config.assemble.take', 'active scalar depth sheets have no mixed-run binding; disable the depth opt-in or assemble a separately bound run before taking layers (numeric depth_median ordering is retained)');
   const inputs = makeInputs(painting, cfg, 'take target painting');

package/src/takeregion.ts

@@ -0,0 +1,151 @@
+/** Seeded, painting-matched additions to one planned part (#1000). */
+import { dirname, resolve } from 'node:path';
+import type { AssembleConfig, Run } from './config.ts';
+import { PartsError, refuseIfAny } from './errors.ts';
+import { editedRunImages, missingReceipts, type ReceiptLedger } from './editreceipt.ts';
+import { makeInputs } from './inputs.ts';
+import { OPAQUE_ALPHA_ABOVE, readLayers, type Layer, type LayerSet } from './layers.ts';
+import { connectedComponents } from './raster/components.ts';
+import { readPng } from './raster/png.ts';
+import { resize } from './raster/resize.ts';
+import { newMask, newRaster, type Raster } from './raster/types.ts';
+import type { SetupPainting } from './setuppainting.ts';
+import type { TakeLayers } from './takelayers.ts';
+
+export interface TakeRegion {
+  run: Run;
+  run_dir: string;
+  st_input: string;
+  part: string;
+  /** One integer pixel on the target run canvas, x right and y down. */
+  seed: [number, number];
+}
+export type TakeDeclaration = TakeLayers | TakeRegion;
+export interface RegionReading {
+  part: string;
+  run: Run;
+  run_dir: string;
+  pixels: number;
+  /** Run pixels, [left, top, width, height]. */
+  box: [number, number, number, number];
+  painting_match_share: number;
+  rgb_tolerance: number;
+}
+type Runs = { full: LayerSet; head: LayerSet; single: boolean; notes: string[] };
+
+function refuse(code: string, object: string, detail: string): never {
+  throw new PartsError([{ code, object, detail }]);
+}
+
+/** Mirrors setupPaintingLine, src/setuppainting.ts:117-122. Agreement is
+ * checked through that function's public signature, including alpha rounding. */
+export function regionPaintingDelta(source: Raster, donor: Raster, sourceOffset: number, donorOffset: number): number {
+  let delta = 0;
+  for (let channel = 0; channel < 3; channel++) {
+    const white = (image: Raster, offset: number): number => Math.round(
+      image.data[offset + channel] * image.data[offset + 3] / 255 + 255 * (1 - image.data[offset + 3] / 255),
+    );
+    delta = Math.max(delta, Math.abs(white(source, sourceOffset) - white(donor, donorOffset)));
+  }
+  return delta;
+}
+
+function offsetAt(layer: Layer, x: number, y: number): number | null {
+  if (x < layer.left || x >= layer.right || y < layer.top || y >= layer.bottom) return null;
+  return ((y - layer.top) * layer.pixels.width + x - layer.left) * 4;
+}
+
+/** Copy exactly the seed's 8-connected qualifying component. Inputs stay intact. */
+export function deriveTakenRegion(base: Layer, donor: Layer, painting: Raster, seed: readonly [number, number], tolerance: number, at: string): { layer: Layer; reading: Omit<RegionReading, 'part' | 'run' | 'run_dir'> } {
+  const { width, height } = painting;
+  const qualifying = newMask(width, height);
+  let candidates = 0;
+  for (let y = donor.top; y < donor.bottom; y++) for (let x = donor.left; x < donor.right; x++) {
+    const donorOffset = offsetAt(donor, x, y)!;
+    const baseOffset = offsetAt(base, x, y);
+    if (baseOffset !== null && base.pixels.data[baseOffset + 3] >= 128) continue;
+    if (donor.pixels.data[donorOffset + 3] < 128) continue;
+    if (regionPaintingDelta(painting, donor.pixels, (y * width + x) * 4, donorOffset) > tolerance) continue;
+    qualifying.data[y * width + x] = 1;
+    candidates++;
+  }
+  if (candidates === 0) return refuse('ASSEMBLE_REGION_TAKE_EMPTY', at, 'derived 0 qualifying run pixels; base alpha < 128, donor alpha >= 128 and painting match within the declared setup_painting.rgb_tolerance are required');
+  const [sx, sy] = seed;
+  if (!Number.isSafeInteger(sx) || !Number.isSafeInteger(sy) || sx < 0 || sy < 0 || sx >= width || sy >= height || qualifying.data[sy * width + sx] !== 1) {
+    return refuse('ASSEMBLE_REGION_TAKE_SEED', at, `seed [${seed.join(', ')}] touches no qualifying component on the ${width}x${height} run canvas; an integer qualifying pixel is required`);
+  }
+  const components = connectedComponents(qualifying, 8);
+  const label = components.labels[sy * width + sx];
+  const stats = components.stats[label];
+  const left = Math.min(base.left, stats.left), top = Math.min(base.top, stats.top);
+  const right = Math.max(base.right, stats.left + stats.width), bottom = Math.max(base.bottom, stats.top + stats.height);
+  const pixels = newRaster(right - left, bottom - top);
+  for (let y = base.top; y < base.bottom; y++) for (let x = base.left; x < base.right; x++) {
+    const from = offsetAt(base, x, y)!;
+    pixels.data.set(base.pixels.data.subarray(from, from + 4), ((y - top) * pixels.width + x - left) * 4);
+  }
+  for (let y = stats.top; y < stats.top + stats.height; y++) for (let x = stats.left; x < stats.left + stats.width; x++) {
+    if (components.labels[y * width + x] !== label) continue;
+    const from = offsetAt(donor, x, y)!;
+    pixels.data.set(donor.pixels.data.subarray(from, from + 4), ((y - top) * pixels.width + x - left) * 4);
+  }
+  let opaquePx = 0;
+  for (let i = 3; i < pixels.data.length; i += 4) if (pixels.data[i] > OPAQUE_ALPHA_ABOVE) opaquePx++;
+  return {
+    layer: { ...base, pixels, left, top, right, bottom, opaquePx },
+    reading: { pixels: stats.area, box: [stats.left, stats.top, stats.width, stats.height], painting_match_share: 1, rgb_tolerance: tolerance },
+  };
+}
+
+/** Called beside whole-layer take, before assembly or any output emission. */
+export function applyTakenRegions(runs: Runs, painting: Raster, cfg: AssembleConfig, configPath: string, setup: SetupPainting | undefined, receipts: ReceiptLedger): Runs {
+  const declarations = (cfg.assemble.take ?? []).filter((item): item is TakeRegion => 'part' in item);
+  if (declarations.length === 0) return runs;
+  const tolerance = setup?.rgb_tolerance;
+  if (typeof tolerance !== 'number' || !Number.isSafeInteger(tolerance) || tolerance < 0 || tolerance > 255) {
+    return refuse('ASSEMBLE_REGION_TAKE_TOLERANCE', 'config.assemble.take', 'a region take requires --requirements declaring setup_painting.rgb_tolerance, the same authored integer check reads; no default is supplied');
+  }
+  if (cfg.depth !== undefined || [...runs.full.layers, ...runs.head.layers].some(layer => layer.depthSheet !== undefined)) {
+    return refuse('ASSEMBLE_REGION_TAKE_BINDING', 'config.assemble.take', 'active scalar depth sheets have no region donor binding; a run without active scalar depth is required');
+  }
+  const inputs = makeInputs(painting, cfg, 'region take painting');
+  const lists = { full: [...runs.full.layers], head: [...runs.head.layers] };
+  const notes = [...runs.notes];
+  const seen = new Set<string>();
+  for (const declaration of declarations) {
+    const at = `config.assemble.take part "${declaration.part}" from "${declaration.run_dir}"`;
+    const plan = cfg.assemble.plan.find(entry => entry[0] === declaration.part && entry[1] === declaration.run);
+    if (plan === undefined) return refuse('ASSEMBLE_REGION_TAKE_PART', at, `requires a plan part named "${declaration.part}" in target run "${declaration.run}"`);
+    const key = `${plan[1]}:${plan[2]}`;
+    if (seen.has(key) || (cfg.assemble.take ?? []).some(item => 'tags' in item && item.run === plan[1] && item.tags.includes(plan[2]))) {
+      return refuse('ASSEMBLE_REGION_TAKE_PART', at, `target ${key} is taken more than once; one region donor or whole-layer donor per target is required`);
+    }
+    seen.add(key);
+    const set = runs[declaration.run];
+    const donor = readLayers(resolve(dirname(resolve(configPath)), declaration.run_dir));
+    refuseIfAny(missingReceipts(receipts, editedRunImages(
+      { full: donor, head: donor, single: true },
+      `region take "${declaration.run}:${declaration.part}" donor "${declaration.run_dir}" `,
+    )));
+    const target = declaration.run === 'head' ? inputs.head : runs.single && set.canvas.w !== set.canvas.h ? painting : inputs.full;
+    let supplied: Raster;
+    try { supplied = readPng(resolve(dirname(resolve(configPath)), declaration.st_input)); }
+    catch { return refuse('ASSEMBLE_REGION_TAKE_GEOMETRY', at, `st_input "${declaration.st_input}" must name the original readable donor input PNG so its geometry can be checked`); }
+    if ((declaration.run === 'head' && runs.single) || target === null || donor.canvas.w !== set.canvas.w || donor.canvas.h !== set.canvas.h || supplied.width !== target.width || supplied.height !== target.height || supplied.data.some((byte, i) => byte !== target.data[i])) {
+      return refuse('ASSEMBLE_REGION_TAKE_GEOMETRY', at, `donor canvas ${donor.canvas.w}x${donor.canvas.h}, target canvas ${set.canvas.w}x${set.canvas.h}, donor input ${supplied.width}x${supplied.height}; equal canvases and exact target input RGBA are required to establish one crop; cropped donors await #973`);
+    }
+    const base = lists[declaration.run].find(layer => layer.name === plan[2]);
+    const material = donor.layers.find(layer => layer.name === plan[2]);
+    if (base === undefined || material === undefined) return refuse('ASSEMBLE_REGION_TAKE_PART', at, `tag "${plan[2]}" is absent from ${base === undefined ? 'the base' : 'the donor'} run; both must hold the plan part's tag`);
+    if (base.depthSheet !== undefined || material.depthSheet !== undefined || [...set.hidden, ...donor.hidden].some(layer => layer.of === plan[2])) {
+      return refuse('ASSEMBLE_REGION_TAKE_BINDING', at, 'hidden companions or active depth sheets require independent region bindings; a part without those companions is required');
+    }
+    const source = resize(target, set.canvas.w, set.canvas.h, 'lanczos3');
+    const derived = deriveTakenRegion(base, material, source, declaration.seed, tolerance, at);
+    lists[declaration.run] = lists[declaration.run].map(layer => layer === base ? derived.layer : layer);
+    const reading: RegionReading = { part: declaration.part, run: declaration.run, run_dir: declaration.run_dir, ...derived.reading };
+    notes.push(`region take ${reading.run}:${reading.part} from ${reading.run_dir}: ${reading.pixels} run px; box [${reading.box.join(', ')}] (left, top, width, height); painting-match share ${reading.painting_match_share}; RGB tolerance ${reading.rgb_tolerance}; seed [${declaration.seed.join(', ')}], 8-connected`);
+  }
+  const full = { ...runs.full, layers: lists.full };
+  return { full, head: runs.single ? full : { ...runs.head, layers: lists.head }, single: runs.single, notes };
+}