rig-parts 2.9.1 → 2.10.0

package/docs/AUTHORING.md

@@ -806,19 +806,45 @@ one seed pixel on the target run canvas (integer x right, y down).
   "run_dir": "runs/other",
   "st_input": "inputs/other_full.png",
   "part": "body",
-  "seed": [120, 240]
+  "seed": [120, 240],
+  "reference": { "painting": "inputs/painting.png", "sha256": "<SHA-256 of PNG bytes>" }
 }]
 ```
 
 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
+A missing tolerance declaration is refused. The optional `reference` declares
+exactly one of `"source": true` (the stage's `--source`) or
+`"painting": "path/to/reference.png"` (config-relative), and `sha256`, the
+lowercase SHA-256 of that PNG's file bytes. An absent `reference` preserves the
+shipped `source: true` semantics and prints one
+`ASSEMBLE_REGION_TAKE_REFERENCE_IMPLICIT` warning per build. It reads the same
+stage painting for the predicate. A declared but unreadable reference, or a
+hash or painting-dimension mismatch, is refused by name. Only an explicitly
+declared painting reference keeps the selected mask fixed when `--source`
+changes for projection. Its 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.
+For a declared reference, its hash, binding and painting-to-run transform are logged. For
+`scale` and `origin`, run coordinates are `(painting - origin) * scale`.
+The origin is the head crop's top-left or the negative full-input padding.
+The recorded filter is Lanczos3.
+
+A region take evaluates the pre-take assembly once as a counterfactual, retaining
+whole-layer takes. The target set includes cut pieces, limb segments and hybrid
+bands consuming a target, transitively. The same set permits empty pieces only
+in the internal counterfactual. Patches consume the painting directly and have
+no source-part relationship. Every non-target part keeps that assembly's complete image
+and record. This contains its changes to zero everywhere, including beyond the
+mapped region plus bicubic's 2 px support, through subsequent seam operations.
+Final recomposite and error measurements use those retained parts together with
+the taken targets. The counterfactual is never written. A take adds this extra
+assembly evaluation. Builds without region takes follow the existing single
+assembly path. Target filter halos are reported separately and have no bar.
 
 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]`
@@ -4536,7 +4562,8 @@ Limb source intersections use the final segmentation ownership map separately
 for each adjacent source; another limb's island is excluded before capture.
 
 To enforce a bend, add `cut_material` to the existing
-`spine-parts-requirements/1` file (the other fields remain required):
+`spine-parts-requirements/1` file. `requirements` remains required. `fps` is
+required only when a declared measurement reads the file's sampling rate.
 
 ```json
 {
@@ -5122,6 +5149,10 @@ those settings. Changing a config seed alone cannot change a no-config run.
 | <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="EDGE_PAIR_RESIDUAL"></a>`EDGE_PAIR_RESIDUAL` | report-only front/back residual candidates after visible edge composition, with pixel spans, boxes and coverage | read measured candidates and explicit skipped/unavailable reasons in `edge_residuals.json`. No pass/fail threshold is applied |
+| <a id="ASSEMBLE_REGION_TAKE_REFERENCE_IMPLICIT"></a>`ASSEMBLE_REGION_TAKE_REFERENCE_IMPLICIT` | warning, `reference` is absent and the predicate uses `--source` | declare a painting reference and its PNG hash to keep the mask independent of projection-source changes |
+| <a id="ASSEMBLE_REGION_TAKE_REFERENCE"></a>`ASSEMBLE_REGION_TAKE_REFERENCE` | a declared region reference is unreadable | supply the declared PNG, with `source: true` or `painting` and its byte hash |
+| <a id="ASSEMBLE_REGION_TAKE_REFERENCE_MATCH"></a>`ASSEMBLE_REGION_TAKE_REFERENCE_MATCH` | a reference hash or painting dimensions differ | supply the declared PNG and preserve the source geometry |
+| <a id="ASSEMBLE_REGION_TAKE_CONTAINMENT"></a>`ASSEMBLE_REGION_TAKE_CONTAINMENT` | a non-target part has no pre-take counterpart | retain the same neighbour part population before and after the take |
 | <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 |
@@ -5557,7 +5588,7 @@ documents do not ship). Each is an input this package built; none is an author's
 | <a id="BUILD_REQUIREMENTS_CONFLICT"></a>`BUILD_REQUIREMENTS_CONFLICT` | `build --requirements <file>` names a file with other bytes than the one `config.requirements` declares (issue #556): the detail names both, each resolved (the flag against the working directory, the declaration against the config's) with its sha256 — or `no such file`. Refused before assemble writes anything. The same file by both, or a copy of its bytes, is not refused: the declaration is read and recorded | drop the flag to build from the config's file, or point `config.requirements` at the flag's |
 | <a id="BUILD_STAGE_REQUEST"></a>`BUILD_STAGE_REQUEST` | an internal build worker was given a missing or malformed request, an unknown stage, or incomplete runner, input, output or scratch paths; the worker refuses before running a stage. This is the internal process protocol, not a public command or option | invoke `rig-parts build` with its documented flags; if that command produces this refusal, report the named request defect rather than constructing or modifying a worker request |
 | <a id="REQUIREMENTS_FILE"></a>`REQUIREMENTS_FILE` | `--requirements` names no file, or one that does not parse as a JSON object. Refused before anything is built (by `build`, before assemble) | the path of a `spine-parts-requirements/1` file |
-| <a id="REQUIREMENTS_FIELD"></a>`REQUIREMENTS_FIELD` | a field of the file is missing, of the wrong type, or not one the format reads: `spec`, `fps` (no default), `requirements`, each requirement's `name` (letters, digits, underscores; once each), `kind`, `animation` and its kind's fields — every bar among them (`within_px`, `fraction`, `tolerance`, `least_drive` above 0, `within_degrees` from 0 to 180, `lo_degrees` ≤ `hi_degrees`, `within_ratio` ≥ 1) — and each target's `bone`, `animation` and exactly one of `at` and `keys` (times strictly increasing), and `not_planted`, `not_swinging`, `rises` and `rests` when given (each a non-empty list of part names, each once; no part both in `not_swinging` and in `rises` or `rests`), and `may_fold` when given (a non-empty list of `{ "slot", "animation", "why" }`, every one a non-blank string, each pair once; issue #320), and `pinholes` when given (an object whose one field, `required`, is `true` or `false`; issue #944), `seam_over_motion` when given (the same shape; issue #941), and `boundary_colour` when given (an object whose one field, `max_step_excess`, is an integer from 0 through 255; issue #942). `note`, `*_note` (strings) and `x-…` (any value) are read by nothing, as in the config | write the field; the bar is yours. For a pair read only by `seam_over_motion.required`, declare `config.motion_seams` `[{part, neighbour}]` and omit a seam requirement. See the [carrier contract](#CONFIG_MOTION_SEAM) and [background over every frame](#background-over-every-frame-issue-941). |
+| <a id="REQUIREMENTS_FIELD"></a>`REQUIREMENTS_FIELD` | a field of the file is missing, of the wrong type, or not one the format reads: `spec`, `fps` (a positive number when supplied, required only when a declared measurement reads the file's sampling rate, with no default), `requirements`, each requirement's `name` (letters, digits, underscores; once each), `kind`, `animation` and its kind's fields — every bar among them (`within_px`, `fraction`, `tolerance`, `least_drive` above 0, `within_degrees` from 0 to 180, `lo_degrees` ≤ `hi_degrees`, `within_ratio` ≥ 1) — and each target's `bone`, `animation` and exactly one of `at` and `keys` (times strictly increasing), and `not_planted`, `not_swinging`, `rises` and `rests` when given (each a non-empty list of part names, each once; no part both in `not_swinging` and in `rises` or `rests`), and `may_fold` when given (a non-empty list of `{ "slot", "animation", "why" }`, every one a non-blank string, each pair once; issue #320), and `pinholes` when given (an object whose one field, `required`, is `true` or `false`; issue #944), `seam_over_motion` when given (the same shape; issue #941), and `boundary_colour` when given (an object whose one field, `max_step_excess`, is an integer from 0 through 255; issue #942). `note`, `*_note` (strings) and `x-…` (any value) are read by nothing, as in the config | write the field; the bar is yours. For a pair read only by `seam_over_motion.required`, declare `config.motion_seams` `[{part, neighbour}]` and omit a seam requirement. See the [carrier contract](#CONFIG_MOTION_SEAM) and [background over every frame](#background-over-every-frame-issue-941). |
 | <a id="REQUIREMENTS_RESOLVES"></a>`REQUIREMENTS_RESOLVES` | a bone, an `ik` or `transform` constraint (by name and `constraint_type`, as rig-c resolves it), a slot, a mesh attachment or an animation the file names is not in `rig.json` or `motion.json`, or a seam's part or a `not_planted`, `not_swinging`, `rises` or `rests` name is not in `parts.json` — the detail lists the ones that are; or an animation whose name cannot be a directory. Refused before anything is built | the name as the rig spells it |
 | <a id="REQUIREMENTS_CONSTRAINT_DRIVES"></a>`REQUIREMENTS_CONSTRAINT_DRIVES` | a `follow` names a bone its constraint does not constrain, or a property it does not drive: an `ik` drives `rotate` only; a `transform` drives `rotate` when a `to` names `rotate`, `translate` when one names `x` or `y` | the constraint's own bone and property |
 | <a id="REQUIREMENTS_TARGET_PARENT"></a>`REQUIREMENTS_TARGET_PARENT` | a scene target's bone is the root or is not parented to it, or the root is not at rest at the origin, or the animation keys the root — a stage point is a bone's position only under a root that stands still at the origin | a bone under the root for the scene to place |
@@ -6628,8 +6659,10 @@ and an entry whose slot does not fold in its animation fails the line
 (`CHECK_ANIMATIONS_DO_NOT_FOLD`, `declared_not_folding`) — an exception that excepts nothing
 is taken out of the file, as rig-c refuses one for `invariants.deformMayFold`.
 
-`fps` and `requirements` are required as always; a file that declares only exceptions
-is `{ "spec": "spine-parts-requirements/1", "fps": 12, "requirements": [], "not_planted": ["shoes"], "not_swinging": ["under"], "rises": ["arm"], "rests": ["hem"] }`.
+`requirements` is required. `fps` is required only when a declared measurement
+reads the file's sampling rate. Instruments using their own rate do not require it.
+A file that declares only exceptions
+is `{ "spec": "spine-parts-requirements/1", "requirements": [], "not_planted": ["shoes"], "not_swinging": ["under"], "rises": ["arm"], "rests": ["hem"] }`.
 
 **Four outcomes, never merged** (#87):
 
@@ -6717,8 +6750,9 @@ render each requirement on that animation reads: the rig under test's own build,
 copy with its scene targets placed), and, per follow, `requirements/released/<name>/`
 and `requirements/full/<name>/` — each a `rigc render` frame set with its
 `geometry.json`. The copies' specs and builds are scratch, removed before the stage
-returns. `check.json` gains `requirements` — `fps`, the summary and each line by name
-— before `PASS`, and `PASS` needs every declared requirement to PASS.
+returns. `check.json` gains `requirements` — the summary and each line by name,
+with `fps` only when the file supplies it — before `PASS`, and `PASS` needs every
+declared requirement to PASS.
 
 The selftest holds each kind and outcome to a hand value on a generated rig
 (`fixtures/reqrig.ts`): a two-bone ik that reaches its scene target holds its contact
@@ -6780,8 +6814,9 @@ Distance **greater than** the declared limit fails; equality passes. Without a
 limit, the block and every joint are **SKIP**, with the measured distances and
 `within_px: null`; this line is excluded from measured bars and contributes no
 PASS. Other independent checks may still pass. With no `fixed_skeleton` block,
-this measurement adds no output or render call. `fps` and `requirements` remain
-required by the enclosing file; they do not change this setup measurement.
+this measurement adds no output or render call. `requirements` remains required
+by the enclosing file. `fps` is required only when a declared measurement reads
+the file's sampling rate. Neither field changes this setup measurement.
 
 | rule | change |
 | --- | --- |

package/docs/STABILITY.md

@@ -156,7 +156,8 @@ part name, `[i]` an entry of a list):
 - **assemble.alternates[i]** — required: `name`; optional: `source`, `full`, `head`, `parts`, `hides`, `head_box`, `cuts`, `skeleton`, `anchor`, `base_anchor`, `drawn`, `tips`, `front`, `layers`, `focus` (issues #454, #465, #543, #652, #664, #666, #719, #780). `focus` is an authored finite `[x, y]` in painting pixels, within its canvas (edges included), refused as CONFIG_SET_FOCUS before assemble output when invalid; only when present, `parts.json` records it with focus_source_size and `sets.json` emits it in setup-world coordinates through the actual rig resize and `src/coords.ts`. Absent focus emits no field or inferred value; changing/removing it requires reassembly
 - **assemble.extend_below_crop[i]** — required: `part`, `run`, `tag`
 - **assemble.extend_painting[i]** — required: `part`, `band`, `max_distance`; optional: `min_held_alpha`, `order` (issues #848, #854, #855; explicit final layer-derived part, half-open rig band and positive four-neighbour path bound; base painting only). The optional integer floor 1–255 admits exact original alpha-over coverage strictly below it; absent or 1 blocks every nonzero holder. Only selected target samples below the floor may take painting RGBA; target samples at/above the floor and every non-target holder remain exact. By default overlapping reachable claims refuse. With `order` on every entry (unique nonnegative safe integers), lower values claim first and their gains block later candidates and paths; array order never breaks ties or supplies missing precedence
-- **assemble.take[i]** — required: `run`, `run_dir`, `st_input`, `tags` (issue #866)
+- **assemble.take[i]** — required: `run`, `run_dir`, `st_input`; optional: `tags`, `part`, `seed`, `reference` (issues #866, #1000, #1031). Whole-layer entries require `tags`; region entries require `part` and `seed`. An absent `reference` preserves the shipped `source: true` predicate and emits one named implicit-reference warning; only an explicitly declared painting reference makes the mask invariant to changes in `--source`
+- **assemble.take[i].reference** — required: `sha256`; optional: `source`, `painting` (issue #1031). Exactly one of `source: true` or a config-relative `painting` PNG is required
 - **assemble.editor_receipts** — required: `receipts`; optional: `required` (issue #946, additive), `trace_parts` (issue #947, additive)
 - **assemble.editor_receipts.receipts[i]** — required: `file`, `sha256`, `from_sha256`, `editor` (issue #946)
 - **assemble.patches[i]** — required: `name`, `box`, `alpha`, `draw`
@@ -657,3 +658,9 @@ changing a calibration requires preparing its recipe again. Compare the same
 provider maps and preserve their provenance. Each report row names the part,
 declared relief, group `zScale` and clipping over original alpha>=128 support;
 it remains a measurement rather than a shape-quality gate.
+
+The requirements file's `fps` becomes optional when no declared measurement
+reads that rate (issue #965, additive for readers). Measurements in
+`requirements` still require a positive `fps`, with no default. Declarations
+whose instruments use their own rate keep that rate.
+The output `check.json` omits `requirements.fps` when the file supplies no `fps`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "2.9.1",
+  "version": "2.10.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/assemble.ts

@@ -300,6 +300,8 @@ export function singleRunPadRecord(single: boolean, sourceW: number, sourceH: nu
 }
 
 export interface AssembleInput {
+  /** Counterfactual before seeded takes, with whole-layer takes already applied. */
+  regionTake?: { full: LayerSet; head: LayerSet; targets: string[] };
   /** Turn context for the exact part/carrier declarations, never an exemption flag. */
   turn?: TurnSpec;
   regions?: Record<string, RegionSpec>;
@@ -4052,6 +4054,7 @@ function cutLimbs(
   readHidden: (layer: string, by: string) => void = () => undefined,
   tips?: Record<string, [number, number]>,
   sourceGroups: ReadonlyMap<string, string> = new Map(),
+  emptyTargets?: ReadonlySet<string>,
 ): { parts: LimbPart[]; pieces: Built[]; counts: LimbCount[]; capFrom: Array<CapFrom | null>; material: MaterialRow[]; sources: MaterialSource[] } {
   const logical = (source: string): string => sourceGroups.get(source) ?? source;
   const names = Object.keys(limbs);
@@ -4110,7 +4113,7 @@ function cutLimbs(
     const on = names.filter((l) => limbs[l].segments.some((sg) => logical(sg.from) === logical(src)));
     const own = new Int32Array(W * H).fill(-1);
     const before = opaqueOf(b.r);
-    if (before === 0) {
+    if (before === 0 && !emptyTargets?.has(src)) {
       problems.push({ code: 'ASSEMBLE_LIMB_TAKES', object: `part "${src}" (config.limbs.${on[0]})`, detail: 'has no opaque pixel to cut; a part with art is required — the limb takes its pixels' });
       continue;
     }
@@ -4211,7 +4214,7 @@ function cutLimbs(
     for (const { q, i } of shares) {
       const writers = b.writers?.slice();
       pieces[i] = { ...b, writers, r: rasters[i], region: regions[i], merged: mergedIn(b, regions[i]) };
-      if (count(regions[i], regions[i]) === 0 && opaqueOf(rasters[i]) === 0) {
+      if (count(regions[i], regions[i]) === 0 && opaqueOf(rasters[i]) === 0 && !emptyTargets?.has(q.part)) {
         problems.push({
           code: 'ASSEMBLE_LIMB_PIXELS',
           object: `config.limbs.${q.limb}.segments[${q.segment}] (part "${q.part}")`,
@@ -4251,6 +4254,7 @@ function cutLimbs(
       const hasCoverSplit = names.some((other) => other !== l && limbs[other].split !== undefined && limbs[other].segments.some((osg) => osg.from === upFrom || osg.from === sg.from));
       const object = `config.limbs.${l}.segments[${k}] (joint "${String(sg.joint)}", part "${sg.part}")`;
       const run = limbRun(line, art, [0, 0, W - 1, H - 1]) ?? (hasCoverSplit ? limbRun(line, sharedArt, [0, 0, W - 1, H - 1]) : null);
+      if (run === null && emptyTargets?.has(sg.part)) return;
       if (run === null) {
         problems.push({
           code: 'ASSEMBLE_LIMB_JOINT_ON_ART',
@@ -4383,7 +4387,7 @@ function cutLimbs(
           }
         }
       }
-      if (img !== null && imagePx + lowerPx === 0 && hidden === null) {
+      if (img !== null && imagePx + lowerPx === 0 && hidden === null && !emptyTargets?.has(sg.part)) {
         problems.push({
           code: 'ASSEMBLE_LIMB_CAP_EMPTY',
           object: `${object}.cap`,
@@ -4477,6 +4481,7 @@ function cutLimbs(
       const li = names.indexOf(l), own = owners.get(sg.from) as Int32Array;
       const art = (x: number, y: number): boolean => x >= 0 && y >= 0 && x < W && y < H && own[y * W + x] === li && source.r.data[(y * W + x) * 4 + 3] > OPAQUE_ALPHA_ABOVE;
       const run = limbRun(line, art, [0, 0, W - 1, H - 1]);
+      if (run === null && emptyTargets?.has(sg.hybrid.part)) return;
       const width = sg.hybrid.width ?? (run === null ? 0 : 2 * halfWidthAbout(run));
       const upper = places.get(segs[k - 1].bone) as BonePlace;
       const lower = places.get(sg.bone) as BonePlace;
@@ -4799,12 +4804,56 @@ export function checkSingleRun(full: LayerSet, plan: readonly PlanEntry[] | null
   refuseIfAny(problems);
 }
 
+/** All output pieces that consume a taken source, including cut-to-limb paths.
+ * Painting patches have no source-part edge in the supported Patch schema. */
+export function regionTakeTargets(names: readonly string[], cuts: readonly Cut[], limbs: Readonly<Record<string, Limb>> = {}): ReadonlySet<string> {
+  const targets = new Set(names);
+  const edges = cuts.map(c => ({ from: c.from, into: c.into }));
+  for (const limb of Object.values(limbs)) for (const [index, segment] of limb.segments.entries()) {
+    edges.push({ from: segment.from, into: segment.part });
+    // A lower cap can copy the upper segment's source art.
+    if (index > 0) edges.push({ from: limb.segments[index - 1].from, into: segment.part });
+    if (segment.hybrid !== undefined) edges.push({ from: segment.from, into: segment.hybrid.part });
+  }
+  // Set iteration visits newly added descendants and terminates on cycles.
+  for (const source of targets) for (const edge of edges) if (edge.from === source) targets.add(edge.into);
+  return targets;
+}
+
+/** Retain neighbour pixels and their matching records after every coupled edit. */
+export function retainRegionNeighbours(placed: PlacedPart[], before: readonly PlacedPart[], targets: ReadonlySet<string>): void {
+  const originals = new Map(before.map(p => [p.record.name, p]));
+  for (let i = 0; i < placed.length; i++) {
+    if (targets.has(placed[i].record.name)) continue;
+    const original = originals.get(placed[i].record.name);
+    if (original === undefined) throw new PartsError([{
+      code: 'ASSEMBLE_REGION_TAKE_CONTAINMENT', object: `part "${placed[i].record.name}"`,
+      detail: 'has no pre-take counterpart; unchanged neighbour pixels and their measurements are required',
+    }]);
+    placed[i] = original;
+  }
+  if (before.some(p => !targets.has(p.record.name) && !placed.some(q => q.record.name === p.record.name))) throw new PartsError([{
+    code: 'ASSEMBLE_REGION_TAKE_CONTAINMENT', object: 'config.assemble.take',
+    detail: 'removed a non-target part; unchanged neighbour pixels and their measurements are required',
+  }]);
+}
+
 /**
  * Run the stage in memory. Everything that can be refused is refused before
  * this returns; nothing here writes a file, so a caller that writes only
  * after this returned writes only after green.
  */
 export function assemble(input: AssembleInput): AssembleResult {
+  if (input.regionTake === undefined) return assembleParts(input);
+  const targets = regionTakeTargets(input.regionTake.targets, input.cuts, input.limbs);
+  const before = assembleParts({ ...input, full: input.regionTake.full, head: input.regionTake.head, regionTake: undefined }, targets);
+  return assembleParts(input, targets, before);
+}
+
+/** The counterfactual is internal and is never emitted. Empty taken targets
+ * may be recovered by a take, so only that counterfactual permits them. */
+function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, beforeTake: AssembleResult | null = null): AssembleResult {
+  const emptyTargets = beforeTake === null ? targets : undefined;
   const { source, extend, patches, seamRule, projectRule } = input;
   const authoredDepths = input.depth === undefined ? new Map<string, AuthoredUnitDepth>() : authoredUnitDepths(input);
   if (input.paintingExtension !== undefined) refuseIfAny(paintingExtensionProblems(input.paintingExtension));
@@ -5130,7 +5179,7 @@ export function assemble(input: AssembleInput): AssembleResult {
       merged = mergeBelowCrop(r, extras, front, srcr, frame.headBottom, trace, (p, stage) => { writers[p] = AW[stage]; });
     }
     const { x1, opaque } = measureBox(r);
-    if (opaque === 0) {
+    if (opaque === 0 && !emptyTargets?.has(name)) {
       empty.push({
         code: 'ASSEMBLE_PART_OPAQUE',
         object: `part "${name}" (${key}, config.assemble.plan[${pi}])`,
@@ -5238,7 +5287,7 @@ export function assemble(input: AssembleInput): AssembleResult {
       if (whole !== parts) empty.push({ code: 'ASSEMBLE_COUNTS_ADD_UP', object, detail: `${what}: ${whole} before its cuts, ${parts} over the pieces; equal is required (a bug in the assembler, not in the inputs)` });
     }
     mine.forEach((i, k) => {
-      if (taken[k] === 0) {
+      if (taken[k] === 0 && !emptyTargets?.has(cuts[i].into)) {
         empty.push({
           code: 'ASSEMBLE_CUT_PIXELS',
           object: `config.assemble.cuts[${i}] (part "${cuts[i].into}")`,
@@ -5246,7 +5295,7 @@ export function assemble(input: AssembleInput): AssembleResult {
         });
       }
     });
-    if (kept === 0) {
+    if (kept === 0 && !emptyTargets?.has(name)) {
       empty.push({
         code: 'ASSEMBLE_CUT_PIXELS',
         object,
@@ -5271,7 +5320,7 @@ export function assemble(input: AssembleInput): AssembleResult {
       for (let p = 0; p < W * H; p++) if (cutMasks[i].data[p] === 1 && band.data[p] === 0 && (pieces[i] as Built).r.data[p * 4 + 3] > 0 && b.r.data[p * 4 + 3] > 0) { (b.writers as Int32Array)[p] = cutIds[i]; if (b.r.data[p * 4 + 3] > OPAQUE_ALPHA_ABOVE) opaqueFilled++; }
       // A hidden-art layer (issue #359) is the whole layer's covered art, read by every cut of its part: a cut it holds nothing
       // under fills 0, which the cut line counts, and is not refused as a file made for this one cut would be.
-      if (f.filled === 0 && input.cuts[i].under !== undefined) {
+      if (f.filled === 0 && input.cuts[i].under !== undefined && !emptyTargets?.has(cuts[i].into)) {
         empty.push({
           code: 'ASSEMBLE_UNDER_EMPTY',
           object: `config.assemble.cuts[${i}].under (part "${cuts[i].into}")`,
@@ -5300,7 +5349,7 @@ export function assemble(input: AssembleInput): AssembleResult {
     if (source === null) return;
     const m = cutMasks[i], r = newRaster(W, H);
     for (let p = 0; p < W * H; p++) if (m.data[p] === 1) r.data.set(source.r.data.subarray(p * 4, p * 4 + 4), p * 4);
-    if (opaqueOf(r) === 0) empty.push({ code: 'ASSEMBLE_CUT_PIXELS', object: `config.assemble.cuts[${i}] (part "${cuts[i].into}")`, detail: `takes 0 opaque pixels from selected ${source.key}; draw its polygon over that layer's art` });
+    if (opaqueOf(r) === 0 && !emptyTargets?.has(cuts[i].into)) empty.push({ code: 'ASSEMBLE_CUT_PIXELS', object: `config.assemble.cuts[${i}] (part "${cuts[i].into}")`, detail: `takes 0 opaque pixels from selected ${source.key}; draw its polygon over that layer's art` });
     const writers = (source.writers as Int32Array).slice();
     pieces[i] = { ...source, r, writers, region: m, merged: mergedIn(source, m) };
     for (let j = materialSources.length - 1; j >= 0; j--) if (materialSources[j].part === cuts[i].into) materialSources.splice(j, 1);
@@ -5328,7 +5377,7 @@ export function assemble(input: AssembleInput): AssembleResult {
     const ci = cuts.findIndex((q) => q.into === name);
     return ci >= 0 ? pieces[ci] : null;
   };
-  const lim = cutLimbs(input.limbs ?? {}, input.bones ?? [], input.caps ?? new Map(), W, H, limbSource, opaqueOf, mergedIn, count, (name) => hiddenArt.get(name) ?? null, (layer, by) => hiddenUses.get(layer)?.push(by), input.boneTips, input.limbSourceGroups);
+  const lim = cutLimbs(input.limbs ?? {}, input.bones ?? [], input.caps ?? new Map(), W, H, limbSource, opaqueOf, mergedIn, count, (name) => hiddenArt.get(name) ?? null, (layer, by) => hiddenUses.get(layer)?.push(by), input.boneTips, input.limbSourceGroups, emptyTargets);
   // Issue #564: and the cap a run's own layer fills above its upper joint, read once the limbs are cut.
   if (bands !== null) refuseIfAny(limbBands(cuts, pieces, input.limbs ?? {}, input.bones ?? [], W, H, (l, k) => lim.parts.find((q) => q.limb === l && q.segment === k)?.record.cap, input.boneTips).problems);
   const limbPieces = lim.pieces;
@@ -5736,6 +5785,18 @@ export function assemble(input: AssembleInput): AssembleResult {
       if (edged.get(name)?.data[p] !== 1 && paintingGains.get(name)?.data[p] !== 1 && retakeByName.get(name)?.data[p] !== 1 && yields.get(name)?.mask.data[p] !== 1 && trace.ring.data[p] === 0 && own.takenMask.data[p] === 1 && (region === null || region.data[p] === 1)) projected.data[p] = 1;
     }
     const { x0, y0, x1, y1, opaque } = measureBox(r);
+    if (opaque === 0 && emptyTargets?.has(name)) {
+      set({
+        record: {
+          name, from: key, x: 0, y: 0, w: 1, h: 1,
+          opaque_px: 0, visible_px: 0, occluded_px: 0, projected_core_px: 0,
+          source_px_taken: 0, visible_not_projected_px: 0, refused_drift_px: 0,
+          merged_px: 0, seam_override_px: 0,
+        },
+        image: newRaster(1, 1),
+      });
+      return;
+    }
     if (opaque === 0) {
       const pushed = pushedHere.reduce((a, q) => a + q.px, 0);
       empty.push({
@@ -5817,6 +5878,7 @@ export function assemble(input: AssembleInput): AssembleResult {
     const depth = authoredDepths.get(p.record.name);
     if (depth !== undefined) p.record.provenance.depth = depth;
   });
+  if (beforeTake !== null) retainRegionNeighbours(placed, beforeTake.images, targets!);
   // Provenance is now numbers/labels only. No later raster/figure operation
   // reads report buffers; release all aliases before recomposite/error work.
   valueBaselines.clear();

package/src/build.ts

@@ -351,12 +351,13 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   // 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 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 runs = applyTakenRegions(takenRuns, src, cfg, input.config, requirementsFile?.setup_painting, receipts, input.source);
+  for (const note of runs.notes) log(note.startsWith('WARN  ') ? note : `note: ${note}`);
   const fields = stageFields(cfg, runs.single ? { w: src.width, h: src.height } : null);
   const under = readUnders(input.config, fields.cuts);
   const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
-  const result = assemble({ source: src, full: runs.full, head: runs.head, depth: cfg.depth, depthBase: dirname(resolve(input.config)), ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: seam, projectRule: project });
+  const result = assemble({ source: src, full: runs.full, head: runs.head, depth: cfg.depth, depthBase: dirname(resolve(input.config)), ...fields, under,
+    ...((cfg.assemble.take ?? []).some(t => 'part' in t) ? { regionTake: { full: takenRuns.full, head: takenRuns.head, targets: (cfg.assemble.take ?? []).flatMap(t => 'part' in t ? [t.part] : []) } } : {}), ...(caps === undefined ? {} : { caps }), seamRule: seam, projectRule: project });
 
   // Issue #454: alternate painting sets, assembled before any file is written.
   const configDir = dirname(resolve(input.config));

package/src/check.ts

@@ -149,6 +149,7 @@ import { TURN_BONE, turnConstraintName, turnTwin } from './turn.ts';
 import { ROOT_BONE, loadConfigWithBytes, type Point } from './config.ts';
 import { influences, meshLimits, type Segment, type Influence, type InfluenceLimits } from './weights.ts';
 import {
+  requirementAnimations,
   aimLine,
   contactLine,
   declareConsumerDriven,
@@ -2767,7 +2768,7 @@ export interface SetCheckFigures {
 /** `check.json`'s `requirements` block: which file was read, the fps every named animation was sampled at, the summary, and each line by its name, in the file's order. */
 export interface RequirementsBlock {
   file: RequirementsFileRecord;
-  fps: number;
+  fps?: number;
   summary: RequirementsSummary;
   lines: Record<string, RequirementLine>;
 }
@@ -7489,12 +7490,11 @@ export function measureRequirements(inp: CheckInputs, file: RequirementsFile, bu
       return p;
     };
     const declared = new Map<string, { poses: Poses; geo: IdleGeometry; path: string }>();
-    for (const r of file.requirements) {
-      if (declared.has(r.animation)) continue;
-      const scene = file.targets.some((t) => t.animation === r.animation);
-      const label = scene ? `as declared, the scene targets of "${r.animation}" placed` : 'as declared';
-      const candidate = scene ? green(buildCopy(placedFor(r.animation).rig, placedFor(r.animation).motion), `the rig ${label}`) : buildDir;
-      declared.set(r.animation, posesOf(candidate, r.animation, join(reqDir, 'as-declared', r.animation), label));
+    for (const animation of requirementAnimations(file.requirements)) {
+      const scene = file.targets.some((t) => t.animation === animation);
+      const label = scene ? `as declared, the scene targets of "${animation}" placed` : 'as declared';
+      const candidate = scene ? green(buildCopy(placedFor(animation).rig, placedFor(animation).motion), `the rig ${label}`) : buildDir;
+      declared.set(animation, posesOf(candidate, animation, join(reqDir, 'as-declared', animation), label));
     }
     for (const r of file.requirements) {
       const d = declared.get(r.animation) as { poses: Poses; geo: IdleGeometry; path: string };

package/src/config.ts

@@ -2500,12 +2500,20 @@ function checkTakeLayers(c: Check, value: Json, plan: string[] | null = null): v
     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', 'part', 'seed'], ['reference'])
       : 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 (o.reference !== undefined) {
+        const r = c.object(`${p}.reference`, o.reference, ['sha256'], ['source', 'painting']);
+        if (r !== null) {
+          if (typeof r.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(r.sha256)) c.fail('CONFIG_FIELD_TYPE', `${p}.reference.sha256`, 'a lowercase SHA-256 of the reference PNG bytes is required');
+          if ((r.source === true) === (typeof r.painting === 'string') || ('source' in r && r.source !== true)) c.fail('CONFIG_FIELD_TYPE', `${p}.reference`, 'exactly one of source: true or painting is required');
+          if ('painting' in r) c.string(`${p}.reference.painting`, r.painting);
+        }
+      }
       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`);
       }

package/src/requirements.ts

@@ -133,6 +133,11 @@ export interface SeamRequirement extends RequirementCommon {
 
 export type Requirement = ContactRequirement | FollowRequirement | AimRequirement | RangeRequirement | StretchRequirement | SeamRequirement;
 
+/** Animations whose measurements consume the requirements file's sampling rate. */
+export function requirementAnimations(requirements: readonly { animation: string }[]): string[] {
+  return [...new Set(requirements.map((requirement) => requirement.animation))];
+}
+
 /** One stage point of a scene target, at a time in seconds (null for a fixed point). */
 export interface TargetPoint {
   t: number | null;
@@ -149,7 +154,7 @@ export interface SceneTarget {
 
 export interface RequirementsFile {
   path: string;
-  fps: number;
+  fps?: number;
   targets: SceneTarget[];
   requirements: Requirement[];
   /**
@@ -314,8 +319,8 @@ const EXCEPTION_ABSENT: Record<ExceptionList, string> = {
 
 /**
  * Read and shape-check a requirements file. Every problem is collected before
- * one refusal: the file, `spec`, `fps` (required, a positive number: no
- * default), `targets` (optional), `requirements` (required, possibly empty)
+ * one refusal: the file, `spec`, `fps` (a positive number required when a measurement reads
+ * the file's sampling rate, with no default), `targets` (optional), `requirements` (required, possibly empty)
  * and `not_planted`, `not_swinging`, `rises` and `rests` (each optional,
  * issues #231 and #245: a non-empty list of distinct part names, no part both
  * in `not_swinging` and in `rises` or `rests`;
@@ -355,9 +360,6 @@ export function readRequirements(path: string): RequirementsFile {
   if ('setup_painting' in raw) problems.push(...setupPaintingProblems(raw.setup_painting, `${at} setup_painting`));
   if ('cut_material' in raw) problems.push(...jointMaterialProblems(raw.cut_material, `${at} cut_material`));
   if ('fixed_skeleton' in raw) problems.push(...fixedSkeletonProblems(raw.fixed_skeleton, `${at} fixed_skeleton`));
-  let fps = NaN;
-  if (!(finite(raw.fps) && raw.fps > 0)) field(`${at} field "fps"`, `is ${JSON.stringify(raw.fps)}; a positive number of frames per second is required — every named animation is sampled at it, and there is no default`);
-  else fps = raw.fps;
 
   const requirements: Requirement[] = [];
   if (!Array.isArray(raw.requirements)) field(`${at} field "requirements"`, `is ${JSON.stringify(raw.requirements)}; an array of requirements is required (an empty one declares none)`);
@@ -537,6 +539,11 @@ export function readRequirements(path: string): RequirementsFile {
       });
     }
   }
+  const samplesAnimation = requirementAnimations(requirements).length > 0;
+  if ((raw.fps !== undefined || samplesAnimation) && !(finite(raw.fps) && raw.fps > 0)) {
+    field(`${at} field "fps"`, `is ${JSON.stringify(raw.fps)}; a positive number of frames per second is required — every named animation is sampled at it, and there is no default`);
+  }
+  const fps = finite(raw.fps) ? raw.fps : undefined;
   refuseIfAny(problems);
   return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold, ...(raw.fixed_skeleton === undefined ? {} : { fixed_skeleton: raw.fixed_skeleton as FixedSkeleton }), ...(raw.cut_material === undefined ? {} : { cut_material: raw.cut_material as JointMaterial[] }), ...(raw.setup_painting === undefined ? {} : { setup_painting: raw.setup_painting as SetupPainting }), ...(raw.pinholes === undefined ? {} : { pinholes: { required: (raw.pinholes as PinholesDeclaration).required } }), ...(raw.seam_over_motion === undefined ? {} : { seam_over_motion: { required: (raw.seam_over_motion as SeamOverMotionDeclaration).required } }), ...(raw.boundary_colour === undefined ? {} : { boundary_colour: { max_step_excess: (raw.boundary_colour as BoundaryColour).max_step_excess } }) };
 }

package/src/takeregion.ts

@@ -2,7 +2,7 @@
 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 { editedRunImages, fileSha256, 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';
@@ -19,6 +19,8 @@ export interface TakeRegion {
   part: string;
   /** One integer pixel on the target run canvas, x right and y down. */
   seed: [number, number];
+  /** PNG bytes, explicitly bound to the stage source or a separate painting. */
+  reference?: { source: true; sha256: string } | { painting: string; sha256: string };
 }
 export type TakeDeclaration = TakeLayers | TakeRegion;
 export interface RegionReading {
@@ -31,6 +33,8 @@ export interface RegionReading {
   painting_match_share: number;
   rgb_tolerance: number;
 }
+const IMPLICIT_REFERENCE_WARNING = 'ASSEMBLE_REGION_TAKE_REFERENCE_IMPLICIT';
+
 type Runs = { full: LayerSet; head: LayerSet; single: boolean; notes: string[] };
 
 function refuse(code: string, object: string, detail: string): never {
@@ -98,7 +102,7 @@ export function deriveTakenRegion(base: Layer, donor: Layer, painting: Raster, s
 }
 
 /** 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 {
+export function applyTakenRegions(runs: Runs, painting: Raster, cfg: AssembleConfig, configPath: string, setup: SetupPainting | undefined, receipts: ReceiptLedger, sourcePath?: string): 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;
@@ -108,9 +112,11 @@ export function applyTakenRegions(runs: Runs, painting: Raster, cfg: AssembleCon
   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];
+  if (declarations.some(item => item.reference === undefined)) {
+    notes.push(`WARN  ${IMPLICIT_REFERENCE_WARNING}: config.assemble.take — reference is absent; uses --source for the colour predicate; declare reference to bind its PNG sha256`);
+  }
   const seen = new Set<string>();
   for (const declaration of declarations) {
     const at = `config.assemble.take part "${declaration.part}" from "${declaration.run_dir}"`;
@@ -121,13 +127,28 @@ export function applyTakenRegions(runs: Runs, painting: Raster, cfg: AssembleCon
       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 reference = declaration.reference;
+    let referencePainting = painting;
+    let referenceHash: string | undefined;
+    if (reference !== undefined) {
+      const referencePath = 'source' in reference ? sourcePath : resolve(dirname(resolve(configPath)), reference.painting);
+      try {
+        if (referencePath === undefined) throw new Error('source path is absent');
+        referenceHash = fileSha256(referencePath);
+        referencePainting = readPng(referencePath);
+      } catch { return refuse('ASSEMBLE_REGION_TAKE_REFERENCE', at, 'reference must name a readable PNG with its declared sha256; a source binding requires the stage source path'); }
+      if (referenceHash !== reference.sha256 || referencePainting.width !== painting.width || referencePainting.height !== painting.height) {
+        return refuse('ASSEMBLE_REGION_TAKE_REFERENCE_MATCH', at, `reference sha256 ${referenceHash}, expected ${reference.sha256}; reference ${referencePainting.width}x${referencePainting.height}, source ${painting.width}x${painting.height}; matching hash and painting dimensions are required`);
+      }
+    }
+    const inputs = makeInputs(referencePainting, cfg, reference === undefined ? 'region take painting' : 'region take reference');
     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;
+    const target = declaration.run === 'head' ? inputs.head : runs.single && set.canvas.w !== set.canvas.h ? referencePainting : 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`); }
@@ -144,6 +165,9 @@ export function applyTakenRegions(runs: Runs, painting: Raster, cfg: AssembleCon
     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 };
+    const pad = target === referencePainting ? [0, 0] : declaration.run === 'head' ? inputs.headBox! : [-inputs.padLeft, -inputs.padTop];
+    const transform = { scale: [set.canvas.w / target.width, set.canvas.h / target.height], origin: [pad[0], pad[1]], filter: 'lanczos3' };
+    if (reference !== undefined) notes.push(`region reference ${reading.run}:${reading.part}: sha256 ${referenceHash}; binding ${'source' in reference ? 'source' : 'painting'}; painting-to-run ${JSON.stringify(transform)}`);
     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 };