rig-parts 2.9.1 → 2.11.0

package/docs/AUTHORING.md

@@ -708,8 +708,8 @@ renaming a supplied image does not establish that it was the donor's input.
 The target input is derived from the painting by the existing input model:
 `full` uses the exact centred white `squarePad`, and `head` the configured
 `head_box`. A nonsquare single-run file uses the painting at its original file
-size before the assembler's existing padding. Donor and target run canvases must
-have equal dimensions; donor and target input PNGs must also have equal
+size before the assembler's existing padding. Without a declared `crop`, donor
+and target run canvases must have equal dimensions; donor and target input PNGs must also have equal
 dimensions. Incompatible canvases or input sizes are refused, never resized to
 make the comparison pass.
 
@@ -768,6 +768,34 @@ 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.
 
+
+With a whole-layer donor made from a crop of the original painting, add
+`"crop": {"box": [left, top, right, bottom], "resample": "bilinear"}` to that
+entry. The box uses integer source-painting pixels with exclusive right/bottom
+bounds. Its input must be the white square-padded crop produced by the same
+`inputs` geometry. The crop must be inside the painting. Donor RGBA under the
+selected support and its existing margin must equal that reconstructed input.
+Containment covers alpha > 8 support only. That support must fit both the crop
+and the target canvas.
+
+The map derives from donor canvas, crop padding/origin and target input geometry.
+Unit scale with integer translation copies straight RGBA exactly. Every other map
+uses one premultiplied float32 bilinear affine pass. The derived map uses pixel
+corners. `warpAffine` samples by pixel index, as `layerToRig` does, with the
+existing cv2-compatible fixed-point sampling and transparent border. The receipt's optional `transport`
+records `crop`, `donor_canvas`, `target_canvas`, `scale`, `translate`, `filter`
+(`exact` or `bilinear`) and `input_rgba_sha256`, `before_rgba_sha256`,
+`after_rgba_sha256`. Hashes cover row-major straight RGBA over the entire named
+canvas, with the donor input dimensions derived from the square-padded crop.
+The production transport verifier checks canvas dimensions and the output hash
+before downstream assembly changes. It refuses a changed canvas as
+`PARTS_TAKEN_LAYERS`.
+Resampling establishes the declared output bytes. It does not establish equality
+between separately generated donor and target art. Omitting `crop` retains the
+existing geometry refusal and its message.
+
+Region take entries retain their existing geometry contract and refuse crop donors.
+
 ### Residual front/back edges (`edge_residuals.json`, issue #999)
 
 Under `assemble.project: "visible"`, assemble writes `edge_residuals.json` beside
@@ -806,19 +834,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]`
@@ -832,6 +886,20 @@ 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.
 
+### Scene plate editor receipts (issue #966)
+
+Optional `scene.plate.editor_receipts` uses the assemble ledger shape
+`{receipts: [{file, sha256, from_sha256, editor}], required?}`. Paths resolve
+relative to the scene file. Every declared receipt is verified, and under
+`required: true` the plate must match a verified receipt by content before
+compose writes anything. The shared `trace_parts` boolean also requires a
+matching receipt when true, as in assemble. `from_sha256` and `editor` remain
+author declarations held to form and differing hashes. `provenance` remains
+required and describes pixel origin (`observed`, `generated`, `unknown`).
+A receipt verifies file identity and records an edit declaration. Neither
+field judges pixel content. Omitting the ledger preserves output bytes and
+accepted exit codes.
+
 ### Editor receipts (`assemble.editor_receipts`, issue #946)
 
 An image edited in code — a layer re-segmented by a script, a patch
@@ -4536,7 +4604,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 +5191,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 |
@@ -5129,7 +5202,8 @@ those settings. Changing a config seed alone cannot change a no-config run.
 | <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_CROP"></a>`ASSEMBLE_TAKE_CROP` | declared crop is outside the source, its square-padded input dimensions differ, or taken support would fall outside the crop or target | supply the original inside integer crop and its exact square-padded input, with explicit `resample: "bilinear"` |
+| <a id="ASSEMBLE_TAKE_GEOMETRY"></a>`ASSEMBLE_TAKE_GEOMETRY` | missing target head, unequal run canvases or unequal original input dimensions | supply matching geometry, or declare the whole-layer donor crop and resample explicitly |
 | <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 |
 | <a id="ASSEMBLE_TAKE_DEPTH_SHEET"></a>`ASSEMBLE_TAKE_DEPTH_SHEET` | taking layers with an active depth opt-in or bound scalar sheets has no declared mixed-run binding | keep scalar depth inactive; numeric ordering depth is retained, and a target sheet is never attached silently |
@@ -5557,7 +5631,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 |
@@ -5672,6 +5746,10 @@ and stay absent).
 | --- | --- | --- |
 | <a id="SCENE_FILE"></a><a id="SCENE_SPEC"></a><a id="SCENE_FIELD_PRESENT"></a><a id="SCENE_FIELD_TYPE"></a><a id="SCENE_KEY_KNOWN"></a>`SCENE_FILE`, `SCENE_SPEC`, `SCENE_FIELD_PRESENT`, `SCENE_FIELD_TYPE`, `SCENE_KEY_KNOWN` | the scene file is missing, not a JSON object, not `spine-parts-scene/1`, or a field is missing, of the wrong type or not one the format reads (`canvas` two positive integers; `characters` at least one, each `id`, `build`, `offset` — an offset is never assumed (0, 0) — and an optional `scale`, a positive finite number: 0, a negative number or a non-number is refused at `characters[i].scale`; `order` a list of strings). `note`, `*_note` (strings) and `x-…` (any value) are read by nothing | the field |
 | <a id="SCENE_ID_UNIQUE"></a><a id="SCENE_ID_FORM"></a>`SCENE_ID_UNIQUE`, `SCENE_ID_FORM` | an `id` repeated, empty, or holding `:` — the separator of a prefixed name — or `/`, `\` or a leading `.`, because an id begins every image file of its character | another id |
+| <a id="SCENE_EDITOR_RECEIPT"></a>`SCENE_EDITOR_RECEIPT` | `scene.plate.editor_receipts` has a malformed ledger or receipt (issue #966) | use `{receipts: [{file, sha256, from_sha256, editor}], required?}` with the same shape rules as assemble editor receipts |
+| <a id="SCENE_EDITOR_RECEIPT_FILE"></a>`SCENE_EDITOR_RECEIPT_FILE` | a plate receipt names a missing file | supply the edited image relative to the scene file |
+| <a id="SCENE_EDITOR_RECEIPT_SHA256"></a>`SCENE_EDITOR_RECEIPT_SHA256` | a plate receipt's file hashes differently from its declared `sha256` | record the current edited file's sha256 |
+| <a id="SCENE_EDITOR_RECEIPT_MISSING"></a>`SCENE_EDITOR_RECEIPT_MISSING` | `scene.plate.editor_receipts.required` is true and no verified receipt matches the plate's bytes | edit the plate in an image editor and record a matching receipt |
 | <a id="SCENE_PLATE_PROVENANCE"></a><a id="SCENE_PLATE_PRESENT"></a><a id="SCENE_PLATE_SIZE"></a>`SCENE_PLATE_PROVENANCE`, `SCENE_PLATE_PRESENT`, `SCENE_PLATE_SIZE` | the plate's `provenance` is not `observed`, `generated` or `unknown`; its image is missing or not a PNG; it is not the canvas's size (it is drawn at canvas (0, 0) and never scaled) | the plate |
 | <a id="SCENE_BUILD_PRESENT"></a>`SCENE_BUILD_PRESENT` | a build directory, or a file `build` writes in it (`parts.json`, `rig/rig.json`, `rig/motion.json` with an `idle`, an image its skin names, `check/check.json`), is missing | run `build` for that character |
 | <a id="SCENE_BUILD_GREEN"></a>`SCENE_BUILD_GREEN` | the build's own `check/check.json` does not say `PASS` and `gate_spine_html_green`; under an accept list (`--accept`, `characters[].accept`), it failed a bar the list does not name, its gate is red, a declared requirement is not PASS, or it names no failing bar — the bars not met and the ones accepted are listed | finish that character first: compose binds finished characters. To look at the scene meanwhile, name the failing bars (§7, *Composing several characters*) |
@@ -6415,7 +6493,7 @@ single-character path (§4, steps 0–9) on its own, already isolated input to a
 | field | what it is |
 | --- | --- |
 | `canvas` | the shared stage, canvas px, y down. The composed rig's stage is the canvas, `root` at its bottom centre, as a single character's is its own |
-| `plate` | optional. `image` (relative to the scene file) is a PNG of exactly the canvas's size; `provenance` is `observed` (the painting's own pixels), `generated` or `unknown` (a residual after the people were removed is `unknown` where they stood, and the author says so); `note` is free text. Both are copied into `scene.json` and **judged by nothing** |
+| `plate` | optional. `image` (relative to the scene file) is a PNG of exactly the canvas's size; `provenance` is `observed` (the painting's own pixels), `generated` or `unknown` (a residual after the people were removed is `unknown` where they stood, and the author says so); `note` is free text. `provenance` and `note` are copied into `scene.json` and **judged by nothing**. Optional `editor_receipts` uses the [editor receipt ledger](#scene-plate-editor-receipts-issue-966), with paths relative to the scene file and verified file hashes; `required: true` demands a matching plate receipt |
 | `characters[].id` | the prefix: every bone, slot, attachment (skin entry), constraint (its name, and every bone and path slot it names), `stops` entry (its `chain`, `links` and `against`, issue #431), `invariants.detached` bone, track, group and easing of that character is renamed `<id>:<name>`. `root` is the one shared root. A name resolves to exactly one character, and nothing resolves across characters without its prefix |
 | `characters[].build` | a `build --out` directory (relative to the scene file) whose own `check/check.json` is green |
 | `characters[].offset` | `[x, y]`, a translation from the build's rig px to canvas px. Every character is built at one `assemble.rig_scale`, so its rig px are canvas px at scale 1 |
@@ -6628,8 +6706,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 +6797,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 +6861,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,9 @@ 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`, `crop` (issues #866, #973, #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].crop** — required when present: `box`, `resample` (issue #973, additive, whole-layer entries only). `box` is an inside nonempty integer source-painting `[left, top, right, bottom]` with exclusive right/bottom. `resample: "bilinear"` is required explicitly. Donor input must match the square-padded crop under taken support plus its margin. Unit scale and integer translation copy RGBA exactly; other maps use the declared premultiplied float32 affine filter. Absent, the shipped geometry predicate and refusal message remain unchanged. Region entries reject this field
+- **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`
@@ -615,6 +617,20 @@ stale evidence rather than reconstructing original art from emitted siblings.
 Without the block the API reading is SKIP; CLI stdout and emitted bytes remain unchanged.
 See [Source before scissors](AUTHORING.md#source-before-scissors).
 
+### Scene plate editor receipts
+
+`scene.plate.editor_receipts` (issue #966, additive) is optional and uses the
+assemble receipt ledger shape, including `required` and `trace_parts`.
+Receipt file paths resolve against the scene file. Declared receipts are
+verified even without `required`; when required, the plate needs a verified
+receipt matching its bytes. Receipt refusals occur before compose writes new
+artifacts. As before, compose creates `--out` and clears its owned outputs,
+including an earlier `rig/` and `scene.json`, before input validation, so a
+refused re-run can remove earlier artifacts. Omitting the field preserves
+exit codes and `scene.json` bytes. The existing required
+`provenance` field is preserved. It declares pixel origin, while the receipt
+verifies file identity and records the author's edit declaration.
+
 ### Editor receipts
 
 The optional `assemble.editor_receipts` block (issue #946, additive) records
@@ -657,3 +673,22 @@ 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`.
+
+### Crop donor transport receipts (issue #973)
+
+Whole-layer `parts[].taken_layers[]` optionally adds `transport` when its config
+entry declares `crop`. The ordered fields are `crop`, `donor_canvas`,
+`target_canvas`, `scale`, `translate`, `filter`, `input_rgba_sha256`,
+`before_rgba_sha256` and `after_rgba_sha256`. Hashes bind whole-canvas row-major
+straight RGBA before and after transport, and the donor input reconstructed from
+the declared crop. `filter: "exact"` requires unit scale and integer translation.
+Other maps carry `"bilinear"`. The strict reader refuses incomplete or malformed
+transport records. Absent, the existing receipt fields and bytes are unchanged.
+The output hash describes transport before downstream assembly, independently of
+final part geometry. Existing no-take inputs emit no transport metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "2.9.1",
+  "version": "2.11.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', 'tags'], []);
+      ? c.object(p, v, ['run', 'run_dir', 'st_input', 'part', 'seed'], ['reference'])
+      : c.object(p, v, ['run', 'run_dir', 'st_input', 'tags'], ['crop']);
     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`);
       }
@@ -2518,6 +2526,14 @@ function checkTakeLayers(c: Check, value: Json, plan: string[] | null = null): v
       }
       return;
     }
+    if ('crop' in o) {
+      const crop = c.object(`${p}.crop`, o.crop, ['box', 'resample'], []);
+      if (crop !== null) {
+        const box = crop.box;
+        if (!(Array.isArray(box) && box.length === 4 && box.every(n => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0) && box[2] > box[0] && box[3] > box[1])) c.fail('CONFIG_FIELD_TYPE', `${p}.crop.box`, 'requires [left, top, right, bottom], nonnegative safe integers with positive width/height in source-painting pixels');
+        if (crop.resample !== 'bilinear') c.fail('CONFIG_FIELD_TYPE', `${p}.crop.resample`, '"bilinear" is required explicitly');
+      }
+    }
     if (!c.array(p + '.tags', o.tags, true)) return;
     (o.tags as Json[]).forEach((tag, j) => {
       const reading = typeof tag === 'string' ? readLayerTag(tag) : null;
@@ -2529,6 +2545,13 @@ function checkTakeLayers(c: Check, value: Json, plan: string[] | null = null): v
   });
 }
 
+/** Shared receipt shape validation for config and scene input doors. */
+export function editorReceiptProblems(value: unknown, at: string): Problem[] {
+  const c = new Check();
+  checkEditorReceipts(c, value, at);
+  return c.problems;
+}
+
 /**
  * `config.assemble.editor_receipts` (issue #946): `{receipts, required?, trace_parts?}` (`trace_parts`, issue #947).
  * Shape refusals are the loader's own; a receipt whose `from_sha256` equals
@@ -2536,8 +2559,7 @@ function checkTakeLayers(c: Check, value: Json, plan: string[] | null = null): v
  * Whether the file exists and hashes to `sha256` is read at assemble
  * (`src/editreceipt.ts`), where the file is.
  */
-function checkEditorReceipts(c: Check, value: Json): void {
-  const at = 'config.assemble.editor_receipts';
+function checkEditorReceipts(c: Check, value: Json, at = 'config.assemble.editor_receipts'): void {
   const o = c.object(at, value, ['receipts'], ['required', 'trace_parts']);
   if (o === null) return;
   for (const k of ['required', 'trace_parts'] as const) {

package/src/editreceipt.ts

@@ -89,6 +89,8 @@ export interface VerifiedReceipt extends EditorReceipt {
 /** The receipts read for one build: those that verified, keyed by sha256, and the refusals of those that did not. */
 export interface ReceiptLedger {
   required: boolean;
+  /** Input location, defaulting to the assemble ledger. */
+  at?: string;
   /** The field that made receipts required, as a refusal names it: `required`, else `trace_parts` (issue #947). */
   by: 'required' | 'trace_parts';
   bySha: ReadonlyMap<string, VerifiedReceipt>;
@@ -101,17 +103,17 @@ export interface ReceiptLedger {
  * `file`). A missing file is `ASSEMBLE_EDITOR_RECEIPT_FILE`; bytes that hash
  * to another value are `ASSEMBLE_EDITOR_RECEIPT_SHA256`, naming both values.
  */
-export function readEditorReceipts(spec: EditorReceipts | undefined, configPath: string): ReceiptLedger {
+export function readEditorReceipts(spec: EditorReceipts | undefined, configPath: string, at = AT, relativeTo: 'config' | 'scene file' = 'config'): ReceiptLedger {
   const problems: Problem[] = [];
   const bySha = new Map<string, VerifiedReceipt>();
   if (spec === undefined) return { required: false, by: 'required', bySha, problems };
   const base = dirname(resolve(configPath));
   spec.receipts.forEach((r, i) => {
-    const at = `${AT}.receipts[${i}]`;
+    const receiptAt = `${at}.receipts[${i}]`;
     const path = resolve(base, r.file);
-    const object = `${at} (file "${r.file}")`;
+    const object = `${receiptAt} (file "${r.file}")`;
     if (!existsSync(path) || !statSync(path).isFile()) {
-      problems.push({ code: 'ASSEMBLE_EDITOR_RECEIPT_FILE', object, detail: `names ${path}, which is no such file; the edited image, its path relative to the config's directory, is required` });
+      problems.push({ code: 'ASSEMBLE_EDITOR_RECEIPT_FILE', object, detail: `names ${path}, which is no such file; the edited image, its path relative to the ${relativeTo}'s directory, is required` });
       return;
     }
     const found = fileSha256(path);
@@ -119,10 +121,10 @@ export function readEditorReceipts(spec: EditorReceipts | undefined, configPath:
       problems.push({ code: 'ASSEMBLE_EDITOR_RECEIPT_SHA256', object, detail: `the file's bytes hash to sha256 ${found}; the receipt's sha256 ${r.sha256} is required — the file changed after its receipt was written, or the receipt names another file` });
       return;
     }
-    if (!bySha.has(found)) bySha.set(found, { ...r, at, path });
+    if (!bySha.has(found)) bySha.set(found, { ...r, at: receiptAt, path });
   });
   const by = spec.required === true || spec.trace_parts !== true ? 'required' : 'trace_parts';
-  return { required: spec.required === true || spec.trace_parts === true, by, bySha, problems };
+  return { required: spec.required === true || spec.trace_parts === true, by, bySha, problems, at };
 }
 
 /** An image the input itself says was made or edited outside See-through. */
@@ -181,7 +183,7 @@ export function missingReceipts(ledger: ReceiptLedger, images: readonly EditedIm
     problems.push({
       code: 'ASSEMBLE_EDITOR_RECEIPT_MISSING',
       object: image.object,
-      detail: `${image.path} (sha256 ${found}) carries no editor receipt; ${AT}.${ledger.by} is true, so a receipt {file, sha256, from_sha256, editor} whose sha256 is this file's is required — edit the image in an image editor and record it, never generate or patch it in code`,
+      detail: `${image.path} (sha256 ${found}) carries no editor receipt; ${ledger.at ?? AT}.${ledger.by} is true, so a receipt {file, sha256, from_sha256, editor} whose sha256 is this file's is required — edit the image in an image editor and record it, never generate or patch it in code`,
     });
   }
   return problems;

package/src/parts.ts

@@ -507,9 +507,26 @@ function orderedProvenance(p: PixelProvenance): PixelProvenance {
     ...(p.depth === undefined ? {} : { depth: { kind: p.depth.kind, values: p.depth.values.map(v => ({ group: v.group, ...(v.bone === undefined ? {} : { bone: v.bone }), value: v.value })) } }) };
 }
 
+function orderedTakenSource(source: TakenLayerSource): TakenLayerSource {
+  const transport = source.transport;
+  return {
+    run: source.run, tag: source.tag, run_dir: source.run_dir, st_input: source.st_input,
+    prompt_id: source.prompt_id, seed: source.seed, support_px: source.support_px,
+    checked_px: source.checked_px, differing_px: source.differing_px,
+    ...(transport === undefined ? {} : { transport: {
+      crop: transport.crop, donor_canvas: transport.donor_canvas,
+      target_canvas: transport.target_canvas, scale: transport.scale,
+      translate: transport.translate, filter: transport.filter,
+      input_rgba_sha256: transport.input_rgba_sha256,
+      before_rgba_sha256: transport.before_rgba_sha256,
+      after_rgba_sha256: transport.after_rgba_sha256,
+    } }),
+  };
+}
+
 function serializePartList(parts: readonly PartRecord[]): Array<Record<string, unknown>> {
   return parts.map((p) =>
-    Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : k === 'taken_layers' ? p.taken_layers?.map(t => ({ run: t.run, tag: t.tag, run_dir: t.run_dir, st_input: t.st_input, prompt_id: t.prompt_id, seed: t.seed, support_px: t.support_px, checked_px: t.checked_px, differing_px: t.differing_px })) : k === 'provenance' ? orderedProvenance(p.provenance as PixelProvenance) : p[k]])),
+    Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : k === 'taken_layers' ? p.taken_layers?.map(orderedTakenSource) : k === 'provenance' ? orderedProvenance(p.provenance as PixelProvenance) : p[k]])),
   );
 }
 

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/scene.ts

@@ -96,9 +96,10 @@ import { dirname, join, resolve } from 'node:path';
 import type { RigStop } from '@rig-c/core/rig';
 import { checkStage, gateThroughRigc, type Log } from './build.ts';
 import { ACCEPTABLE_BARS, barsNotMet, type CheckReport, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, type PackMode, requirementsNotPass, type RigcRunner } from './check.ts';
-import { CONSTRAINT_BONE_FIELDS, ROOT_BONE } from './config.ts';
+import { CONSTRAINT_BONE_FIELDS, editorReceiptProblems, ROOT_BONE } from './config.ts';
 import { cropToSpineY } from './coords.ts';
 import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
+import { missingReceipts, readEditorReceipts, type EditorReceipts } from './editreceipt.ts';
 import type { MotionSpec } from './motion.ts';
 import { readPng } from './raster/png.ts';
 import { readRequirements, type RequirementsFile } from './requirements.ts';
@@ -161,6 +162,7 @@ export interface ScenePlate {
   image: string;
   imagePath: string;
   provenance: Provenance;
+  editor_receipts?: EditorReceipts;
   note: string | null;
 }
 
@@ -221,7 +223,8 @@ export function acceptProblems(names: readonly string[], where: string): Problem
 /**
  * Read and shape-check a scene file. Every problem is collected before one
  * refusal: the file, `spec`, `canvas` (two positive integers), `plate`
- * (optional: `image`, `provenance`, an optional `note`), `characters` (at
+ * (optional, with required `image` and `provenance` and optional `note`
+ * and `editor_receipts` with the shared ledger shape), `characters` (at
  * least one; each `id`, `build`, `offset`), `order` (a list of strings), and
  * any key the format does not read. Resolving the ids and slots `order`
  * names is {@link composeScene}'s, which has the builds.
@@ -270,7 +273,10 @@ export function loadScene(path: string): SceneFile {
     const p = o.plate;
     if (!isRecord(p)) fail('SCENE_FIELD_TYPE', 'scene.plate', `is ${show(p)}; {"image": "<png>", "provenance": ${PROVENANCES.map((x) => `"${x}"`).join(' | ')}} is required when the key is present`);
     else {
-      known(p, 'scene.plate', ['image', 'provenance', 'note']);
+      known(p, 'scene.plate', ['image', 'provenance', 'note', 'editor_receipts']);
+      if ('editor_receipts' in p) {
+        problems.push(...editorReceiptProblems(p.editor_receipts, 'scene.plate.editor_receipts').map((problem) => ({ ...problem, code: 'SCENE_EDITOR_RECEIPT' })));
+      }
       const image = p.image;
       const prov = p.provenance;
       if (!('image' in p)) fail('SCENE_FIELD_PRESENT', 'scene.plate.image', 'is absent and required; the plate PNG, relative to the scene file');
@@ -278,7 +284,7 @@ export function loadScene(path: string): SceneFile {
       if (!('provenance' in p)) fail('SCENE_FIELD_PRESENT', 'scene.plate.provenance', `is absent and required; one of ${PROVENANCES.join(', ')} — what the plate's pixels are, which the author states and nothing judges`);
       else if (typeof prov !== 'string' || !(PROVENANCES as readonly string[]).includes(prov)) fail('SCENE_PLATE_PROVENANCE', 'scene.plate.provenance', `is ${show(prov)}; one of ${PROVENANCES.join(', ')} is required`);
       if (typeof image === 'string' && image !== '' && typeof prov === 'string' && (PROVENANCES as readonly string[]).includes(prov)) {
-        plate = { image, imagePath: resolve(base, image), provenance: prov as Provenance, note: typeof p.note === 'string' ? p.note : null };
+        plate = { image, imagePath: resolve(base, image), provenance: prov as Provenance, ...('editor_receipts' in p ? { editor_receipts: p.editor_receipts as EditorReceipts } : {}), note: typeof p.note === 'string' ? p.note : null };
       }
     }
   }
@@ -1375,6 +1381,14 @@ export function composeFromFiles(scenePath: string, requirementsPath?: string, m
   const builds = scene.characters.map((c) => readCharacterBuild(c, problems, accept));
   let plate: PlateImage | null = null;
   if (scene.plate !== null) {
+    const ledger = readEditorReceipts(scene.plate.editor_receipts, scene.path, 'scene.plate.editor_receipts', 'scene file');
+    const receiptCodes: Readonly<Record<string, string>> = {
+      ASSEMBLE_EDITOR_RECEIPT_FILE: 'SCENE_EDITOR_RECEIPT_FILE',
+      ASSEMBLE_EDITOR_RECEIPT_SHA256: 'SCENE_EDITOR_RECEIPT_SHA256',
+      ASSEMBLE_EDITOR_RECEIPT_MISSING: 'SCENE_EDITOR_RECEIPT_MISSING',
+    };
+    const receiptProblems = [...ledger.problems, ...missingReceipts(ledger, [{ object: 'scene.plate.image', path: scene.plate.imagePath }])];
+    problems.push(...receiptProblems.map((problem) => ({ ...problem, code: receiptCodes[problem.code] ?? problem.code })));
     const where = `scene.plate.image (${scene.plate.image})`;
     if (!existsSync(scene.plate.imagePath)) problems.push({ code: 'SCENE_PLATE_PRESENT', object: where, detail: `${scene.plate.imagePath} does not exist; a PNG of the canvas's size is required` });
     else {

package/src/takelayers.ts

@@ -1,16 +1,19 @@
 /** Verified replacement in an existing full/head run; never writes or forges a run manifest. */
 import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname, resolve } from 'node:path';
 import type { EarlyConfig, PlanEntry, Run } from './config.ts';
 import { CORE_KERNEL, fullPlanBand } from './assemble.ts';
-import { makeInputs } from './inputs.ts';
+import { makeInputs, squarePad } from './inputs.ts';
 import { OPAQUE_ALPHA_ABOVE, readLayers, type Layer, type LayerSet } from './layers.ts';
 import { PartsError, refuseIfAny, type Problem } from './errors.ts';
 import { dilate } from './raster/morph.ts';
-import { newMask, type Raster } from './raster/types.ts';
+import { newMask, newRaster, newFloatImage, type Raster } from './raster/types.ts';
 import { readPng } from './raster/png.ts';
 import type { TakeDeclaration } from './takeregion.ts';
-import type { TakenLayerSource } from './takesource.ts';
+import { crop, pad } from './raster/composite.ts';
+import { warpAffine, type ScaleTranslate } from './raster/warp.ts';
+import { takenTransportProblems, type TakenLayerSource, type TakenLayerTransport } from './takesource.ts';
 
 export interface TakeLayers {
   run: Run;
@@ -18,6 +21,8 @@ export interface TakeLayers {
   /** The exact PNG supplied to See-through, resolved from the config directory. */
   st_input: string;
   tags: string[];
+  /** Original painting pixels, right/bottom exclusive; donor input is squarePad(crop). */
+  crop?: { box: [number, number, number, number]; resample: 'bilinear' };
 }
 function refuse(code: string, object: string, detail: string): never { throw new PartsError([{ code, object, detail }]); }
 function metadata(path: string): { prompt_id: string; seed: number } {
@@ -49,6 +54,92 @@ function identity(layer: Layer, canvas: LayerSet['canvas'], donor: Raster, targe
   if (differing > 0) return refuse('ASSEMBLE_TAKE_INPUT_IDENTITY', object, `${differing} differing pixel(s), bbox [${x0}, ${y0}, ${x1}, ${y1}] in st_input pixels (right/bottom exclusive); exact RGBA identity under alpha > ${OPAQUE_ALPHA_ABOVE}, grown by ${CORE_KERNEL}x${CORE_KERNEL}, is required`);
   return { support, checked };
 }
+/** Hash straight RGBA, with the dimensions carried separately in the transport receipt. */
+function rgbaHash(image: Raster): string {
+  return createHash('sha256').update(image.data).digest('hex');
+}
+
+function cropGeometry(d: TakeLayers, painting: Raster, target: Raster, donor: LayerSet, set: LayerSet, inputs: ReturnType<typeof makeInputs>, at: string): { expected: Raster; map: ScaleTranslate; exact: boolean } {
+  const declaration = d.crop!;
+  const [x0, y0, x1, y1] = declaration.box;
+  if (declaration.resample !== 'bilinear' || !declaration.box.every(Number.isSafeInteger) || x0 < 0 || y0 < 0 || x1 <= x0 || y1 <= y0 || x1 > painting.width || y1 > painting.height) {
+    return refuse('ASSEMBLE_TAKE_CROP', at, `crop [${declaration.box.join(', ')}] on painting ${painting.width}x${painting.height}; an inside nonempty integer box and resample "bilinear" are required`);
+  }
+  const w = x1 - x0, h = y1 - y0;
+  const donorPad = squarePad(w, h);
+  const expected = pad(crop(painting, x0, y0, w, h), donorPad.left, donorPad.top, donorPad.side - w - donorPad.left, donorPad.side - h - donorPad.top, [255, 255, 255, 255]);
+  const origin = target === painting ? [0, 0] : d.run === 'head' ? [-inputs.headBox![0], -inputs.headBox![1]] : [inputs.padLeft, inputs.padTop];
+  const scaleXUnit = BigInt(donorPad.side) * BigInt(set.canvas.w) === BigInt(donor.canvas.w) * BigInt(target.width);
+  const scaleYUnit = BigInt(donorPad.side) * BigInt(set.canvas.h) === BigInt(donor.canvas.h) * BigInt(target.height);
+  const offsetX = BigInt(x0 - donorPad.left + origin[0]) * BigInt(set.canvas.w);
+  const offsetY = BigInt(y0 - donorPad.top + origin[1]) * BigInt(set.canvas.h);
+  const integerX = offsetX % BigInt(target.width) === 0n;
+  const integerY = offsetY % BigInt(target.height) === 0n;
+  return { expected, exact: scaleXUnit && scaleYUnit && integerX && integerY, map: {
+    sx: scaleXUnit ? 1 : donorPad.side / donor.canvas.w * set.canvas.w / target.width,
+    sy: scaleYUnit ? 1 : donorPad.side / donor.canvas.h * set.canvas.h / target.height,
+    tx: integerX ? Number(offsetX / BigInt(target.width)) : (x0 - donorPad.left + origin[0]) * set.canvas.w / target.width,
+    ty: integerY ? Number(offsetY / BigInt(target.height)) : (y0 - donorPad.top + origin[1]) * set.canvas.h / target.height,
+  } };
+}
+
+/** One full-canvas affine pass, using the same premultiplied float32 convention as layerToRig. */
+function transportLayer(layer: Layer, donor: LayerSet, set: LayerSet, image: Raster, d: TakeLayers, map: ScaleTranslate, exact: boolean, at: string): { layer: Layer; transport: TakenLayerTransport } {
+  const canvas = newRaster(donor.canvas.w, donor.canvas.h);
+  for (let y = 0; y < layer.pixels.height; y++) {
+    canvas.data.set(layer.pixels.data.subarray(y * layer.pixels.width * 4, (y + 1) * layer.pixels.width * 4), ((y + layer.top) * canvas.width + layer.left) * 4);
+  }
+  const [x0, y0, x1, y1] = d.crop!.box;
+  const donorPad = squarePad(x1 - x0, y1 - y0);
+  for (let y = layer.top; y < layer.bottom; y++) for (let x = layer.left; x < layer.right; x++) {
+    if (canvas.data[(y * canvas.width + x) * 4 + 3] <= OPAQUE_ALPHA_ABOVE) continue;
+    const dx = x * donorPad.side / canvas.width - donorPad.left;
+    const dy = y * donorPad.side / canvas.height - donorPad.top;
+    const tx = map.sx * x + map.tx, ty = map.sy * y + map.ty;
+    if (dx < 0 || dy < 0 || (x + 1) * donorPad.side / canvas.width - donorPad.left > x1 - x0 || (y + 1) * donorPad.side / canvas.height - donorPad.top > y1 - y0 || tx < 0 || ty < 0 || tx + map.sx > set.canvas.w || ty + map.sy > set.canvas.h) {
+      return refuse('ASSEMBLE_TAKE_CROP', at, `supported donor cell [${x}, ${y}] falls outside the declared painting crop or target canvas; the whole taken support must be retained`);
+    }
+  }
+  const out = newRaster(set.canvas.w, set.canvas.h);
+  if (exact) {
+    for (let y = 0; y < canvas.height; y++) for (let x = 0; x < canvas.width; x++) {
+      const tx = x + map.tx, ty = y + map.ty;
+      if (tx >= 0 && ty >= 0 && tx < out.width && ty < out.height) out.data.set(canvas.data.subarray((y * canvas.width + x) * 4, (y * canvas.width + x + 1) * 4), (ty * out.width + tx) * 4);
+    }
+  } else {
+    const pre = newFloatImage(canvas.width, canvas.height, 4);
+    for (let p = 0; p < canvas.width * canvas.height; p++) {
+      const a = canvas.data[p * 4 + 3];
+      for (let c = 0; c < 3; c++) pre.data[p * 4 + c] = Math.fround(canvas.data[p * 4 + c] * Math.fround(a / 255));
+      pre.data[p * 4 + 3] = a;
+    }
+    const warped = warpAffine(pre, map, out.width, out.height, 'bilinear');
+    const clip = (v: number): number => Math.max(0, Math.min(255, v));
+    for (let p = 0; p < out.width * out.height; p++) {
+      const a = Math.fround(clip(warped.data[p * 4 + 3]));
+      for (let c = 0; c < 3; c++) {
+        const value = Math.fround(clip(warped.data[p * 4 + c]));
+        const straight = Math.fround(Math.fround(value * 255) / Math.max(a, Math.fround(1e-3)));
+        out.data[p * 4 + c] = a > 0 ? Math.trunc(clip(straight)) : 0;
+      }
+      out.data[p * 4 + 3] = Math.trunc(a);
+    }
+  }
+  let opaquePx = 0;
+  for (let p = 3; p < out.data.length; p += 4) if (out.data[p] > OPAQUE_ALPHA_ABOVE) opaquePx++;
+  if (opaquePx === 0) return refuse('ASSEMBLE_TAKE_SUPPORT', at, `has 0 pixels of alpha above ${OPAQUE_ALPHA_ABOVE} after the declared transport; a nonempty taken layer is required`);
+  const transport: TakenLayerTransport = {
+    crop: [...d.crop!.box], donor_canvas: [canvas.width, canvas.height], target_canvas: [out.width, out.height],
+    scale: [map.sx, map.sy], translate: [map.tx, map.ty], filter: exact ? 'exact' : 'bilinear',
+    input_rgba_sha256: rgbaHash(image), before_rgba_sha256: rgbaHash(canvas), after_rgba_sha256: rgbaHash(out),
+  };
+  refuseIfAny(takenTransportProblems(transport, out, at));
+  return {
+    layer: { ...layer, left: 0, top: 0, right: out.width, bottom: out.height, pixels: out, opaquePx },
+    transport,
+  };
+}
+
 export function takeLayerNote(source: TakenLayerSource): string {
   return `take ${source.run}:${source.tag} from ${source.run_dir}; prompt_id ${source.prompt_id}; seed ${source.seed}; st_input ${source.st_input}; support ${source.support_px} run px; checked ${source.checked_px} input px; differing ${source.differing_px}; alpha > ${OPAQUE_ALPHA_ABOVE}, ${CORE_KERNEL}x${CORE_KERNEL} margin`;
 }
@@ -81,7 +172,10 @@ export function applyTakenLayers(runs: { full: LayerSet; head: LayerSet; single:
     const meta = metadata(resolve(base, d.run_dir, 'meta.json'));
     let image: Raster;
     try { image = readPng(resolve(base, d.st_input)); } catch { return refuse('ASSEMBLE_TAKE_INPUT', at, `st_input "${d.st_input}" must name the original readable PNG supplied to the donor run`); }
-    if (target === null || donor.canvas.w !== set.canvas.w || donor.canvas.h !== set.canvas.h || image.width !== target.width || image.height !== target.height) return refuse('ASSEMBLE_TAKE_GEOMETRY', at, `donor canvas ${donor.canvas.w}x${donor.canvas.h}, target canvas ${set.canvas.w}x${set.canvas.h}, donor st_input ${image.width}x${image.height}, target st_input ${target?.width ?? 0}x${target?.height ?? 0}; equal canvases and equal input dimensions are required (full uses squarePad; head uses head_box)`);
+    if (d.crop === undefined && (target === null || donor.canvas.w !== set.canvas.w || donor.canvas.h !== set.canvas.h || image.width !== target.width || image.height !== target.height)) return refuse('ASSEMBLE_TAKE_GEOMETRY', at, `donor canvas ${donor.canvas.w}x${donor.canvas.h}, target canvas ${set.canvas.w}x${set.canvas.h}, donor st_input ${image.width}x${image.height}, target st_input ${target?.width ?? 0}x${target?.height ?? 0}; equal canvases and equal input dimensions are required (full uses squarePad; head uses head_box)`);
+    if (target === null) return refuse('ASSEMBLE_TAKE_CROP', at, 'a target input is required for a declared crop');
+    const geometry = d.crop === undefined ? undefined : cropGeometry(d, painting, target, donor, set, inputs, at);
+    if (geometry !== undefined && (image.width !== geometry.expected.width || image.height !== geometry.expected.height)) return refuse('ASSEMBLE_TAKE_CROP', at, `donor st_input ${image.width}x${image.height}; declared square-padded crop requires ${geometry.expected.width}x${geometry.expected.height}`);
     const union = new Uint8Array(image.width * image.height);
     for (const tag of d.tags) {
       const key = `${d.run}:${tag}`;
@@ -89,10 +183,12 @@ export function applyTakenLayers(runs: { full: LayerSet; head: LayerSet; single:
       seen.add(key);
       const layer = donor.layers.find(l => l.name === tag);
       if (layer === undefined) return refuse('ASSEMBLE_TAKE_TAG_IN_RUN', at, `tag "${tag}" is absent; a named See-through tag held by that donor is required`);
-      const checked = identity(layer, donor.canvas, image, target, `${at} tag "${tag}"`);
+      const checked = identity(layer, donor.canvas, image, geometry?.expected ?? target, `${at} tag "${tag}"`);
       for (let p = 0; p < union.length; p++) union[p] |= checked.checked[p];
       const source: TakenLayerSource = { run: d.run, tag, run_dir: d.run_dir, st_input: d.st_input, prompt_id: meta.prompt_id, seed: meta.seed, support_px: checked.support, checked_px: checked.checked.reduce((a, b) => a + b, 0), differing_px: 0 };
-      const replacement: Layer = { ...layer, takenLayers: [source] };
+      const transported = geometry === undefined ? undefined : transportLayer(layer, donor, set, image, d, geometry.map, geometry.exact, `${at} tag "${tag}"`);
+      if (transported !== undefined) source.transport = transported.transport;
+      const replacement: Layer = { ...(transported?.layer ?? layer), takenLayers: [source] };
       lists[d.run] = [...lists[d.run].filter(l => l.name !== tag), replacement];
       origins.set(replacement, resolve(base, d.run_dir));
       notes.push(takeLayerNote(source));

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 };

package/src/takesource.ts

@@ -1,6 +1,28 @@
 /** Layer identity receipts, retained independently of part names and derived geometry. */
+import { createHash } from 'node:crypto';
+import type { Raster } from './raster/types.ts';
 import type { Problem } from './errors.ts';
 import { readLayerTag } from './tags.ts';
+export interface TakenLayerTransport {
+  crop: [number, number, number, number];
+  donor_canvas: [number, number];
+  target_canvas: [number, number];
+  scale: [number, number];
+  translate: [number, number];
+  filter: 'exact' | 'bilinear';
+  input_rgba_sha256: string;
+  before_rgba_sha256: string;
+  after_rgba_sha256: string;
+}
+/** Verify a transported run canvas against its sealed receipt before downstream assembly. */
+export function takenTransportProblems(transport: TakenLayerTransport, image: Raster, at: string): Problem[] {
+  const actual = createHash('sha256').update(image.data).digest('hex');
+  if (image.width !== transport.target_canvas[0] || image.height !== transport.target_canvas[1] || actual !== transport.after_rgba_sha256) {
+    return [{ code: 'PARTS_TAKEN_LAYERS', object: at,
+      detail: `transported canvas ${image.width}x${image.height}, RGBA sha256 ${actual}; receipt requires ${transport.target_canvas.join('x')}, RGBA sha256 ${transport.after_rgba_sha256}` }];
+  }
+  return [];
+}
 export interface TakenLayerSource {
   run: 'full' | 'head';
   tag: string;
@@ -11,6 +33,7 @@ export interface TakenLayerSource {
   support_px: number;
   checked_px: number;
   differing_px: 0;
+  transport?: TakenLayerTransport;
 }
 export function unionTakenSources(lists: readonly (readonly TakenLayerSource[] | undefined)[]): TakenLayerSource[] {
   const out: TakenLayerSource[] = [];
@@ -28,13 +51,27 @@ export function takenSourceProblems(value: unknown, at: string): Problem[] {
     if (typeof item !== 'object' || item === null || Array.isArray(item)) { fail('each source must be a complete identity receipt'); continue; }
     const o = item as Record<string, unknown>;
     const tag = typeof o.tag === 'string' ? readLayerTag(o.tag) : null;
-    if (Object.keys(o).some(k => !keys.includes(k)) || keys.some(k => !(k in o)) ||
+    if (Object.keys(o).some(k => !keys.includes(k) && k !== 'transport') || keys.some(k => !(k in o)) ||
         (o.run !== 'full' && o.run !== 'head') || tag === null || tag.group === 'author' ||
         ['run_dir', 'st_input', 'prompt_id'].some(k => typeof o[k] !== 'string' || !(o[k] as string).trim()) ||
         !Number.isSafeInteger(o.seed) || (o.seed as number) < 0 ||
         ['support_px', 'checked_px'].some(k => !Number.isSafeInteger(o[k]) || (o[k] as number) <= 0) || o.differing_px !== 0) {
       fail('each source requires exactly run, See-through tag, run_dir, st_input, prompt_id, nonnegative safe integer seed, positive support_px/checked_px and differing_px 0'); continue;
     }
+    if (o.transport !== undefined) {
+      const t = o.transport as Record<string, unknown> | null;
+      const fields = ['crop', 'donor_canvas', 'target_canvas', 'scale', 'translate', 'filter', 'input_rgba_sha256', 'before_rgba_sha256', 'after_rgba_sha256'];
+      const pair = (v: unknown, positive: boolean, integer: boolean): v is number[] => Array.isArray(v) && v.length === 2 && v.every(n => typeof n === 'number' && Number.isFinite(n) && (!positive || n > 0) && (!integer || Number.isSafeInteger(n)));
+      if (typeof t !== 'object' || t === null || Array.isArray(t) || Object.keys(t).length !== fields.length || fields.some(k => !(k in t)) ||
+          !Array.isArray(t.crop) || t.crop.length !== 4 || !t.crop.every(n => Number.isSafeInteger(n) && n >= 0) || t.crop[2] <= t.crop[0] || t.crop[3] <= t.crop[1] ||
+          !pair(t.donor_canvas, true, true) || !pair(t.target_canvas, true, true) || !pair(t.scale, true, false) || !pair(t.translate, false, false) ||
+          (t.filter !== 'exact' && t.filter !== 'bilinear') ||
+          ['input_rgba_sha256', 'before_rgba_sha256', 'after_rgba_sha256'].some(k => typeof t[k] !== 'string' || !/^[0-9a-f]{64}$/.test(t[k] as string))) {
+        fail('transport requires exactly crop, donor_canvas, target_canvas, scale, translate, filter and three lowercase RGBA SHA-256 hashes');
+      } else if ((t.filter === 'exact') !== (t.scale[0] === 1 && t.scale[1] === 1 && t.translate.every(Number.isSafeInteger))) {
+        fail('transport filter exact requires unit scale and integer translation; every other map requires bilinear');
+      }
+    }
     const key = JSON.stringify([o.run, o.tag, o.run_dir]);
     if (seen.has(key)) fail(`duplicate source ${key}; each source must appear once`);
     seen.add(key);