rig-parts 2.3.0 → 2.4.0

package/docs/STABILITY.md

@@ -147,11 +147,13 @@ part name, `[i]` an entry of a list):
 - **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
 - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`, `arm_split`
 - **seethrough.arm_split** — required: `order`, and one of `x` or `line` (issue #439)
-- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `extend_painting`, `take`
+- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `extend_painting`, `take`, `editor_receipts`
 - **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.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`
 - **assemble.patches[i].draw**, when an object — required: `before`
 - **assemble.cuts[i]** — required: `from`, `into`, `polygon`, `draw`, `overlap`; optional: `under`, `under_fill`
@@ -240,7 +242,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), `excluded_px` after them only on a subset set's limb part whose cap the set exclusion took a pixel of (issue #603, additive: each pixel taken out of the count it was in, so the cap's counts are the written PNG's), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px` — on a subset set's limb part counted after the set exclusion, issue #603 — `seam_override_px`, and `fringe_pushed_back` when not empty); per-part `provenance` (`unchanged_layer_px`, `hand_px`, `automatic_px`, `edits`, `automatic`, additive, issue #823); optional top-level `motion_seams`, `alternates` and `cut_ownership` (one row per cut, independent of RGBA equality, issue #823); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
 | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
 | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones` (the sorted names the attachment's weights bind in the written `rig.json`, in every mode — since 1.49.1 (issue #536) a rig with `turn` or `stops` names the twins and `<link>_d` bones there, where the row named the segment bones they replace: a fix of a wrong name, not a format change; a rig with neither writes the bytes it wrote), `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); or `mode` "explicit" with `image_sha256` and `region_sha256` (the verified guards; counts and coverage are measured from the supplied mesh, no legacy generator report is adopted); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
-| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes. Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
+| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #941 adds optional `required` only under the requirements file's `seam_over_motion.required: true` — `status` (`PASS` or `FAIL`), `mode` `gap-open`, `bar_px` 0, `pairs` (each `pair`, `class` — `body-root`, `internal-joint` or `explicit` — `frames`, `background_frames`, `max_px`) and `failed` — and with it the key is written even when no pair is declared; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes. Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
 | `layers.json`, `<index>_<name>.png` | `layers --export` | the wrapper form `layers` reads (issue #359): `width`, `height`, then `layers` — each `name`, `filename`, `left`, `top`, `right`, `bottom`, `depth_median` (the input's own; `null` for a PSD, the manifest's order then being the draw order) — drawn layers in draw order, then the hidden-art layers; a PNG's name is its index and its layer's name, and the manifest, not the file name, says which layer it is |
 | the template `.psd` | `layers --template` | one empty layer per name `templateLayerNames` (`src/layers.ts`) holds, bottom first; the same canvas writes the same bytes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `constraints` with `--cloth` (issue #364: a physics constraint per tree link named `<bone>_physics`, a dangling end's `<bone>_translate`, and a skirt swing's transforms `<swing>_<tree>`), `turn` with `--full`/`--head`, `proposed_rig_scale` (issue #354), and `notes` |
@@ -534,7 +536,37 @@ The separate ordering scalar is unchanged. No-image outputs retain legacy bytes.
 The optional `setup_painting` key in `spine-parts-requirements/1` adds a
 `SETUP_MATCHES_PAINTING` measurement when declared. It requires authored
 `rgb_tolerance` and named native-stage boxes. Each optional `max_pixels` is
-that whole region's limit; omission is SKIP, never PASS. With `--source` but
+that whole region's limit; omission is SKIP, never PASS. The optional boolean
+`setup_painting.required` (issue #943, additive) is the author's declaration
+that the check may not SKIP: with `true`, an absent `rgb_tolerance`, `regions`
+or region `max_pixels` is refused by name as `SETUP_PAINTING_REQUIRED_LIMIT`
+when the file is read, before anything is built, and no limit is derived; a
+fully limited declaration measures, prints and writes the same bytes as
+without the field. Absent or `false`, every reading in this section is
+unchanged. The optional `pinholes` key (issue #944, additive) declares
+`assemble`'s pinhole bar: with `{"required": true}`, `assemble` (and `build`'s
+assemble) refuses every pinhole of the base set's flat parts stack by name as
+`ASSEMBLE_PINHOLES` before anything is written — the bar is 0 and takes no
+value. Absent or `false`, nothing is measured, the console's
+`ASSEMBLE_PINHOLES: SKIP` line says so, and no exit code, file or other line
+moves. The optional `seam_over_motion` key (issue #941, additive)
+declares `check`'s background bar: with `{"required": true}`, every declared
+`SEAM_OVER_MOTION` pair — body-root, internal-joint and explicit — is refused
+by name as `CHECK_SEAM_OVER_MOTION_REQUIRED` on any frame of any animation (12
+fps, every frame) with rigc `gapOpen` cells above 0, and a line or pair that
+measured nothing is refused too; `check.json`'s `SEAM_OVER_MOTION` gains
+`required`. The bar is 0 and takes no value. Absent or `false`, nothing is read
+and no exit code, line or byte moves; the existing warnings and the body-root
+bar are unchanged.
+The optional `boundary_colour` key (issue #942, additive) declares `check`'s
+`BOUNDARY_COLOUR_STEP` bar: with `{"max_step_excess": <0-255>}` (an authored
+integer; no default exists), `check` measures every part boundary of the setup
+and every idle frame against the rig's own pieces, writes the
+`BOUNDARY_COLOUR_STEP` block to `check.json`, and refuses each part pair over
+the allowance as `CHECK_BOUNDARY_COLOUR_STEP`, or a reading it cannot take as
+`CHECK_BOUNDARY_COLOUR_UNMEASURED`. Absent, nothing is measured or written,
+the console's `BOUNDARY_COLOUR_STEP: SKIP` line says so, and no exit code,
+file or other line moves. With `--source` but
 no declaration, the console, `check.json` and the report's skipped-bar list now
 say SKIP with the reason and the `--requirements` declaration remedy; exit
 codes stay unchanged. No metric, region or limit is invented. Without source
@@ -560,6 +592,30 @@ 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).
 
+### Editor receipts
+
+The optional `assemble.editor_receipts` block (issue #946, additive) records
+images edited in an image editor. Absent, no file is read and every output is
+byte-identical. Declared, every receipt's `file` must exist and hash to its
+`sha256` (`ASSEMBLE_EDITOR_RECEIPT_FILE`, `ASSEMBLE_EDITOR_RECEIPT_SHA256`);
+`from_sha256` and `editor` are the author's declaration, held to form and to
+`from_sha256` differing from `sha256` (`CONFIG_EDITOR_RECEIPT`). The optional
+boolean `required` is the author's declaration that no edited image may go
+without one: with `true`, every author-made layer, hidden-art layer, cut
+`under` and limb `cap` the build reads needs a receipt matching its bytes
+(`ASSEMBLE_EDITOR_RECEIPT_MISSING`), refused before anything is assembled.
+Absent or `false`, nothing is demanded; a build whose receipts all verify
+writes the same bytes as without the block. No input accepted before the block
+existed changes its exit code: the refusals fire only on a block that input
+could not have held. The optional boolean `trace_parts` (issue #947, additive)
+is the author's declaration that every part's pixels trace to a layer of the
+split or to a receipted image: with `true`, receipts are demanded as under
+`required`, and every shape the config draws through a part (a cut's
+`polygon`, `seethrough.arm_split`, a limb's `split.line`, a patch's `box`, a
+painting extension's `band`) is refused (`ASSEMBLE_PART_SOURCE`) before
+anything is assembled. Absent or `false`, nothing more is demanded and no byte
+moves.
+
 ## Provider-map depth stages (#897)
 
 The opt-in `depth-prepare` and `depth-apply` commands accept the separate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "2.3.0",
+  "version": "2.4.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": {
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "@rig-c/core": "3.1.0"
+    "@rig-c/core": "3.1.1"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/src/assemble.ts

@@ -2595,6 +2595,23 @@ export function visibilityCounts(object: string, part: Raster, visible: Mask, pr
  * This is NOT in the reference. It is the input of `seamRule: 'silhouette'`.
  */
 export function figureSilhouette(srcr: Raster): Mask {
+  const { width: W, height: H } = srcr;
+  const fig = newMask(W, H);
+  fig.data.set(paintedFigure(srcr));
+  const opened = dilate(dilate(erode(erode(fig, 3), 3), 3), 3);
+  return fillHoles(opened);
+}
+
+/**
+ * `figureSilhouette`'s own per-pixel test, before its opening and its hole
+ * fill: 1 where the painting (rig-sized) differs from the median colour of its
+ * outer `SILHOUETTE_BORDER`-pixel ring by more than `SILHOUETTE_LIMIT` (max
+ * channel). `figureSilhouette` opens and fills this mask; `measurePinholes`
+ * (issue #944) reads it as it is, so a pixel the painting shows as ground
+ * (between arm and body, between the legs, inside a hair loop) is never
+ * "painted".
+ */
+export function paintedFigure(srcr: Raster): Uint8Array {
   const { width: W, height: H } = srcr;
   const ring: number[][] = [[], [], []];
   for (let y = 0; y < H; y++) {
@@ -2608,13 +2625,12 @@ export function figureSilhouette(srcr: Raster): Mask {
     const n = s.length;
     return n % 2 === 1 ? s[(n - 1) / 2] : (s[n / 2 - 1] + s[n / 2]) / 2;
   });
-  const fig = newMask(W, H);
+  const painted = new Uint8Array(W * H);
   for (let p = 0; p < W * H; p++) {
     const d = Math.max(...[0, 1, 2].map((c) => Math.abs(srcr.data[p * 4 + c] - median[c])));
-    if (d > SILHOUETTE_LIMIT) fig.data[p] = 1;
+    if (d > SILHOUETTE_LIMIT) painted[p] = 1;
   }
-  const opened = dilate(dilate(erode(erode(fig, 3), 3), 3), 3);
-  return fillHoles(opened);
+  return painted;
 }
 
 export interface PlacedPart {
@@ -3071,36 +3087,80 @@ export function uncoveredHoles(can: Raster, srcr: Raster, parts: PlacedPart[], i
   const all = cc.stats.slice(1).filter((s) => s.area > 0);
   all.sort((a, b) => b.area - a.area || a.top - b.top || a.left - b.left);
   const listed = all.slice(0, HOLES_LISTED);
-  const holes = listed.map((s): RecompositeHole => {
-    const borders: HoleBorder[] = [];
-    parts.forEach(({ record: p, image }) => {
-      let n = 0;
-      // A part pixel can touch the hole only inside the hole's box grown by one.
-      const x0 = Math.max(p.x, s.left - 1);
-      const x1 = Math.min(p.x + p.w - 1, s.left + s.width);
-      const y0 = Math.max(p.y, s.top - 1);
-      const y1 = Math.min(p.y + p.h - 1, s.top + s.height);
-      for (let y = y0; y <= y1; y++) {
-        for (let x = x0; x <= x1; x++) {
-          if (image.data[((y - p.y) * p.w + (x - p.x)) * 4 + 3] <= COVERED_ALPHA) continue;
-          let touches = false;
-          for (let dy = -1; dy <= 1 && !touches; dy++) {
-            for (let dx = -1; dx <= 1 && !touches; dx++) {
-              const u = x + dx;
-              const v = y + dy;
-              if (u >= 0 && u < W && v >= 0 && v < H && cc.labels[v * W + u] === s.label) touches = true;
-            }
+  const holes = listed.map((s): RecompositeHole => ({ px: s.area, x: s.left, y: s.top, w: s.width, h: s.height, borders: holeBorders(parts, cc, s, W, H, COVERED_ALPHA) }));
+  return { count: all.length, holes };
+}
+
+/**
+ * The parts bordering one labelled component: every part with a pixel of
+ * alpha above `above` 8-adjacent to one of the component's pixels, each with
+ * the number of such pixels, most first and then in plan order (a pixel two
+ * parts hold counts for both). `uncoveredHoles` reads it at `COVERED_ALPHA`,
+ * `measurePinholes` (issue #944) at 0.
+ */
+function holeBorders(parts: readonly PlacedPart[], cc: Components, s: Components['stats'][number], W: number, H: number, above: number): HoleBorder[] {
+  const borders: HoleBorder[] = [];
+  parts.forEach(({ record: p, image }) => {
+    let n = 0;
+    // A part pixel can touch the hole only inside the hole's box grown by one.
+    const x0 = Math.max(p.x, s.left - 1);
+    const x1 = Math.min(p.x + p.w - 1, s.left + s.width);
+    const y0 = Math.max(p.y, s.top - 1);
+    const y1 = Math.min(p.y + p.h - 1, s.top + s.height);
+    for (let y = y0; y <= y1; y++) {
+      for (let x = x0; x <= x1; x++) {
+        if (image.data[((y - p.y) * p.w + (x - p.x)) * 4 + 3] <= above) continue;
+        let touches = false;
+        for (let dy = -1; dy <= 1 && !touches; dy++) {
+          for (let dx = -1; dx <= 1 && !touches; dx++) {
+            const u = x + dx;
+            const v = y + dy;
+            if (u >= 0 && u < W && v >= 0 && v < H && cc.labels[v * W + u] === s.label) touches = true;
           }
-          if (touches) n++;
         }
+        if (touches) n++;
       }
-      if (n > 0) borders.push({ part: p.name, px: n });
-    });
-    // Array.prototype.sort is stable, so equal counts keep plan order.
-    borders.sort((a, b) => b.px - a.px);
-    return { px: s.area, x: s.left, y: s.top, w: s.width, h: s.height, borders };
+    }
+    if (n > 0) borders.push({ part: p.name, px: n });
   });
-  return { count: all.length, holes };
+  // Array.prototype.sort is stable, so equal counts keep plan order.
+  borders.sort((a, b) => b.px - a.px);
+  return borders;
+}
+
+/**
+ * The pinholes of the flat parts stack at rest (issue #944): every 8-connected
+ * component of the stack's openings — the pixels no part has any alpha at
+ * (alpha 0 on every part) that the union of the parts' alpha above 0, its
+ * holes filled (`fillHoles`), encloses — of which every pixel is painted
+ * (`paintedFigure`: the painting differs from its border ring's median by more
+ * than `SILHOUETTE_LIMIT`, `figureSilhouette`'s test without its opening and
+ * hole fill). An opening with one pixel the painting shows as ground is a
+ * deliberate gap (between arm and body, between the legs, inside a hair loop)
+ * and is not a pinhole. No size threshold: one pixel is a pinhole.
+ *
+ * ⚖️ Invariant: each pinhole is a `RecompositeHole` — its box is its pixels'
+ * bounding box, its `borders` the parts with a pixel of alpha above 0
+ * 8-adjacent to it (`holeBorders`) — and the list is every pinhole, largest
+ * first, then by top row and left column, so the order is a function of the
+ * pixels. The painting is the rig-sized one assemble reads (`sourceInRig`).
+ */
+export function measurePinholes(srcr: Raster, parts: readonly PlacedPart[]): RecompositeHole[] {
+  const { width: W, height: H } = srcr;
+  const stack = newMask(W, H);
+  for (const { record: p, image } of parts) {
+    for (let y = 0; y < p.h; y++) for (let x = 0; x < p.w; x++) if (image.data[(y * p.w + x) * 4 + 3] > 0) stack.data[(p.y + y) * W + p.x + x] = 1;
+  }
+  const filled = fillHoles(stack);
+  const openings = newMask(W, H);
+  for (let p = 0; p < W * H; p++) if (filled.data[p] === 1 && stack.data[p] === 0) openings.data[p] = 1;
+  const cc = connectedComponents(openings, 8);
+  const painted = paintedFigure(srcr);
+  const allPainted = new Uint8Array(cc.stats.length).fill(1);
+  for (let p = 0; p < W * H; p++) if (cc.labels[p] > 0 && painted[p] === 0) allPainted[cc.labels[p]] = 0;
+  const pins = cc.stats.slice(1).filter((s) => s.area > 0 && allPainted[s.label] === 1);
+  pins.sort((a, b) => b.area - a.area || a.top - b.top || a.left - b.left);
+  return pins.map((s) => ({ px: s.area, x: s.left, y: s.top, w: s.width, h: s.height, borders: holeBorders(parts, cc, s, W, H, 0) }));
 }
 
 /**
@@ -3224,6 +3284,40 @@ export function figuresLine(f: RecompositeFigures, scene: string | null = null):
   );
 }
 
+/** Issue #944: the name of `assemble`'s pinhole bar — its console line and its refusal. */
+export const PINHOLES_RULE = 'ASSEMBLE_PINHOLES';
+
+/** Issue #944: what a pinhole is, said once for the line and the refusal. */
+const PINHOLE_IS = `an 8-connected opening of the flat parts stack — alpha 0 on every part, enclosed by the parts' alpha above 0 — whose every pixel the painting shows as figure, more than ${SILHOUETTE_LIMIT} off its border ring's median (max channel)`;
+
+/**
+ * Issue #944: one `ASSEMBLE_PINHOLES` refusal per pinhole, largest first — the
+ * pinhole's box, its pixel count and the parts bordering it, against the bar
+ * of 0 the requirements file `requirements` declares required.
+ */
+export function pinholeProblems(pinholes: readonly RecompositeHole[], requirements: string): Problem[] {
+  return pinholes.map((h, i) => ({
+    code: PINHOLES_RULE,
+    object: `pinhole ${i + 1} of ${pinholes.length} at ${holeBox(h)}`,
+    detail:
+      `is ${h.px} px ${h.borders.length === 0 ? 'bordering no part' : `between ${h.borders.map((b) => `"${b.part}" ${b.px} px`).join(', ')}`} — ${PINHOLE_IS}; ` +
+      `${requirements} declares pinholes.required: true, so 0 pinholes are required. Cover it from a layer that holds its pixels (AUTHORING, Source before scissors), or drop the declaration and the bar reports SKIP`,
+  }));
+}
+
+/**
+ * Issue #944: the `ASSEMBLE_PINHOLES` line under the hole lines. `null` is the
+ * bar not declared — SKIP with the reason and the declaration remedy, never a
+ * pass; an empty list is the declared bar met. A non-empty list never reaches
+ * here: it was refused (`pinholeProblems`). Alternate sets are not measured, and
+ * the PASS line names them.
+ */
+export function pinholesLine(pinholes: readonly RecompositeHole[] | null, alternates: readonly string[]): string {
+  if (pinholes === null) return `${PINHOLES_RULE}: SKIP — not measured, not a pass: no requirements file declares pinholes.required: true; declare {"pinholes": {"required": true}} in the --requirements file (config.requirements under build) to refuse every pinhole, ${PINHOLE_IS}`;
+  if (pinholes.length > 0) throw new Error(`pinholesLine: ${pinholes.length} pinhole(s) reached the PASS line; pinholeProblems refuses them`);
+  return `${PINHOLES_RULE}: PASS — 0 pinholes in the base set's flat parts stack, bar 0 (pinholes.required: true)${alternates.length === 0 ? '' : `; alternate set(s) ${alternates.map((a) => `"${a}"`).join(', ')} not measured`}; a pinhole is ${PINHOLE_IS}`;
+}
+
 /** A hole's box as the part lines and refusals print a box: `x,y wxh`. */
 export function holeBox(h: RecompositeHole): string {
   return `${h.x},${h.y} ${h.w}x${h.h}`;

package/src/boundarycolour.ts

@@ -0,0 +1,233 @@
+/**
+ * Issue #942: the colour step across part boundaries, against the rig's own pieces.
+ *
+ * The reference is never the painting: a part drawn on top legitimately shows its own colour over the neighbour's
+ * line art, so a painting-relative bar refuses correct overlaps (the #942 v1 reading). The reference is the rig's
+ * own parts, drawn by the SAME official rasteriser, so bilinear filtering is the same on both sides:
+ *
+ * - setup frame: each piece's `parts/<name>.png` as a flat quad at its parts.json rectangle (the layer stack
+ *   recomposited). A texture stretched into its padded UVs, or a notch the mesh or the texture cuts out of a
+ *   piece, makes the rig's render differ from that flat draw; a correct overlap does not, because both sides draw
+ *   the top piece.
+ * - every idle frame: the posed frame with each piece re-seated on its own parts PNG (padded as the rig image is)
+ *   through its own art UVs. A pixel then carries the colour its piece-local point has at rest, so a boundary
+ *   pair's step there is the same boundary's step at rest, tracked through the pieces' own UVs.
+ *
+ * The readout is, per 4-adjacent boundary pair (two different drawn owners, in either the render or the
+ * reference), the excess of the rendered step over the reference step: max(0, s_render - s_reference), with
+ * s = the largest RGB difference across the pair, both composited over white. The bar is the largest excess over
+ * every pair of every measured frame, against the rig's declared `boundary_colour.max_step_excess`. Nothing is
+ * derived from the art: no declaration, no measurement (SKIP, never a pass).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Plate } from '@rig-c/core/plate';
+import type { Frame, Piece } from '@rig-c/core/render-shared';
+import { seamSourceAttachment } from './check.ts';
+import { cropToSpineY } from './coords.ts';
+import type { Problem } from './errors.ts';
+import type { PartsFile } from './parts.ts';
+import { readPng } from './raster/png.ts';
+
+export const BOUNDARY_COLOUR_LINE = 'BOUNDARY_COLOUR_STEP';
+export const BOUNDARY_COLOUR_CODE = 'CHECK_BOUNDARY_COLOUR_STEP';
+export const BOUNDARY_COLOUR_UNMEASURED_CODE = 'CHECK_BOUNDARY_COLOUR_UNMEASURED';
+export const UNDECLARED_BOUNDARY_COLOUR_REASON = 'not measured, not a pass: no requirements file declares boundary_colour; declare {"boundary_colour": {"max_step_excess": <0-255>}} in the --requirements file (config.requirements under build) to hold every part boundary of the setup and every idle frame to the rig\'s own pieces';
+
+/** The one declaration: the largest step excess (0-255) the rig allows over its own pieces. No default exists. */
+export interface BoundaryColour {
+  max_step_excess: number;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const freeKey = (k: string, v: unknown): boolean => (k.startsWith('x-') && k.length > 2 && isObject(v)) || ((k === 'note' || k.endsWith('_note')) && typeof v === 'string');
+
+/** Shape only: an object holding exactly an authored integer `max_step_excess` from 0 through 255 (and notes). */
+export function boundaryColourProblems(value: unknown, at: string): Problem[] {
+  if (!isObject(value)) return [{ code: 'REQUIREMENTS_FIELD', object: at, detail: `is ${JSON.stringify(value)?.slice(0, 40)}; requires {"max_step_excess": <an authored integer 0-255>}` }];
+  const problems: Problem[] = [];
+  for (const k of Object.keys(value)) if (k !== 'max_step_excess' && !freeKey(k, value[k])) problems.push({ code: 'REQUIREMENTS_FIELD', object: `${at}.${k}`, detail: 'is not a field this block reads (max_step_excess; note or *_note as a string; x-<name> as a record)' });
+  const v = value.max_step_excess;
+  if (typeof v !== 'number' || !Number.isSafeInteger(v) || v < 0 || v > 255) problems.push({ code: 'REQUIREMENTS_FIELD', object: `${at}.max_step_excess`, detail: `is ${JSON.stringify(v)}; requires an authored integer from 0 through 255 — the largest RGB step a part boundary may add over the rig's own pieces; no default is derived from the art` });
+  return problems;
+}
+
+/** One boundary pair's worst reading: where, in which frame, and the two steps the excess is the difference of. */
+export interface BoundaryColourReading {
+  parts: [string, string];
+  frame: string;
+  at: [number, number];
+  excess: number;
+  rendered_step: number;
+  reference_step: number;
+}
+export interface BoundaryColourUnmeasured {
+  slot: string;
+  frame: string;
+  reason: string;
+}
+export interface BoundaryColourMeasured {
+  status: 'PASS' | 'FAIL';
+  instrument: 'rigc renderer, setup and every idle frame';
+  reference: 'setup: parts.json flat pieces; idle: each piece re-seated on its own parts PNG through its art UVs';
+  max_step_excess: number;
+  frames: number;
+  boundary_pairs: number;
+  worst: BoundaryColourReading | null;
+  /** Every part pair over the allowance, its worst reading each, in part-pair order. */
+  over: BoundaryColourReading[];
+  /** Pieces the reference could not be drawn for; any one makes the line FAIL (never a pass). */
+  unmeasured: BoundaryColourUnmeasured[];
+  alternates: 'not measured';
+}
+
+type Api = typeof import('@rig-c/core/render-shared');
+
+export interface BoundaryColourInput {
+  build: string;
+  stage: { x: number; y: number; width: number; height: number };
+  parts: PartsFile;
+  partsDir: string;
+  imagesDir: string;
+  rig: Record<string, unknown>;
+  fps: number;
+}
+
+interface Source { flat: Plate; padded: Plate; rec: { x: number; y: number; w: number; h: number } }
+
+function plateOf(r: { width: number; height: number; data: ArrayLike<number> }, pad: number): Plate {
+  const p = new Plate(r.width + 2 * pad, r.height + 2 * pad);
+  for (let y = 0; y < r.height; y++) for (let x = 0; x < r.width; x++) for (let c = 0; c < 4; c++) p.data[((y + pad) * p.width + x + pad) * 4 + c] = r.data[(y * r.width + x) * 4 + c];
+  return p;
+}
+
+/**
+ * Measure the declared bar on a gated build. `problems` gains one CHECK_BOUNDARY_COLOUR_STEP per part pair over the
+ * allowance, and one CHECK_BOUNDARY_COLOUR_UNMEASURED per piece the reference cannot be drawn for.
+ */
+export function measureBoundaryColour(api: Api, input: BoundaryColourInput, declared: BoundaryColour, problems: Problem[]): BoundaryColourMeasured {
+  const skeleton = join(input.build, 'skeleton.json'), atlas = join(input.build, 'skeleton.atlas');
+  const candidate = api.loadCandidate({ skeletonText: readFileSync(skeleton, 'utf8'), atlasText: readFileSync(atlas, 'utf8'), atlasDir: input.build, label: 'boundary colour' }, { skeleton, atlas }, undefined);
+  const opts = { geometry: true, texture: true };
+  const setup = api.throughPoser(candidate.choice, (p) => api.sampleSetupPose(p, opts)).value[0];
+  const idle = api.throughPoser(candidate.choice, (p) => api.sampleAnimation(p, 'idle', input.fps, opts)).value;
+  const W = input.stage.width, H = input.stage.height;
+  const vp = { minX: input.stage.x, minY: input.stage.y, maxX: input.stage.x + W, maxY: input.stage.y + H, scale: 1, width: W, height: H };
+  const project = api.projector(vp);
+  const records = new Map(input.parts.parts.map((p) => [p.name, p]));
+  const sources = new Map<string, Source | string>();
+  const unmeasured: BoundaryColourUnmeasured[] = [];
+  const unmeasuredSeen = new Set<string>();
+  const sourceOf = (frame: Frame, piece: Piece, label: string): Source | null => {
+    const fail = (reason: string): null => {
+      const key = `${piece.slot}\u0000${reason}`;
+      if (!unmeasuredSeen.has(key)) { unmeasuredSeen.add(key); unmeasured.push({ slot: piece.slot, frame: label, reason }); }
+      return null;
+    };
+    if (piece.kind === 'mesh' && piece.source !== undefined) return fail('the piece is clipped; a clipped piece has no flat reference');
+    if (piece.texture === undefined) return fail('the renderer gave no art UVs for the piece');
+    const drawn = (frame.attachments ?? []).filter((a) => a.slot === piece.slot);
+    if (drawn.length !== 1) return fail(`the frame draws ${drawn.length} attachment(s) on the slot; one is required`);
+    // The drawn attachment is resolved by name the way the seam's source mapping is (an entry's explicit `name`, or
+    // else its key), so a skin entry renamed under another key still reads its own image.
+    let image: string;
+    try { image = String(seamSourceAttachment(input.rig, piece.slot, String(drawn[0].attachment)).image); }
+    catch (e) { return fail(`the skin resolves no single image drawing for attachment "${String(drawn[0].attachment)}" (${e instanceof Error ? e.message : String(e)})`); }
+    let got = sources.get(image);
+    if (got === undefined) {
+      const name = image.replace(/\.png$/, '');
+      const rec = records.get(name);
+      const partPng = join(input.partsDir, `${name}.png`), rigPng = join(input.imagesDir, image);
+      if (rec === undefined) got = `parts.json holds no record "${name}" for the image "${image}"`;
+      else if (!existsSync(partPng) || !existsSync(rigPng)) got = `${existsSync(partPng) ? `the rig image "${image}"` : `the parts image "${name}.png"`} is absent`;
+      else {
+        const src = readPng(partPng), rigImg = readPng(rigPng);
+        const dx = rigImg.width - src.width, dy = rigImg.height - src.height;
+        if (src.width !== rec.w || src.height !== rec.h) got = `parts/${name}.png is ${src.width}x${src.height}, its record ${rec.w}x${rec.h}`;
+        else if (dx !== dy || dx < 0 || dx % 2 !== 0) got = `the rig image "${image}" is ${rigImg.width}x${rigImg.height}, not parts/${name}.png's ${src.width}x${src.height} with one even pad on every side`;
+        else got = { flat: plateOf(src, 0), padded: plateOf(src, dx / 2), rec };
+      }
+      sources.set(image, got);
+    }
+    return typeof got === 'string' ? fail(got) : got;
+  };
+  const own = (frame: Frame, pages: Map<string, Plate>, pieces: Piece[]): { data: Uint8Array; owner: Int32Array } => {
+    const plate = api.renderFrame({ ...frame, pieces }, pages, vp, [255, 255, 255, 255]);
+    const owner = new Int32Array(W * H).fill(-1);
+    pieces.forEach((piece, i) => api.rasterisePiece(api.pageFor(pages, piece), piece, project, vp, (x, y, _r, _g, _b, a) => { if (a > 0) owner[y * W + x] = i; }));
+    return { data: plate.data, owner };
+  };
+  const pairsWorst = new Map<string, BoundaryColourReading>();
+  let worst: BoundaryColourReading | null = null;
+  let boundaryPairs = 0;
+  const readFrame = (frame: Frame, label: string, flat: boolean): void => {
+    const pages = new Map<string, Plate>(candidate.pages);
+    const ok: boolean[] = [];
+    const refPieces = frame.pieces.map((piece, i): Piece => {
+      const s = sourceOf(frame, piece, label);
+      ok.push(s !== null);
+      if (s === null) return piece;
+      const page = `boundary-colour:${i}`;
+      if (flat) {
+        const { x, y, w, h } = s.rec;
+        const wx = (rx: number): number => rx + vp.minX, wy = (ry: number): number => vp.minY + cropToSpineY(ry, H);
+        pages.set(page, s.flat);
+        // rasteriseQuad reads world/uv pairs 0, 1, 2 as (s=1,t=0), the origin, (s=0,t=1).
+        return { kind: 'region', slot: piece.slot, page, tint: piece.tint, ...(piece.dark === undefined ? {} : { dark: piece.dark }), world: [wx(x + w), wy(y), wx(x), wy(y), wx(x), wy(y + h), wx(x + w), wy(y + h)], uvs: [1, 0, 0, 0, 0, 1, 1, 1] };
+      }
+      pages.set(page, s.padded);
+      const { uvWindow: _window, ...rest } = piece;
+      return { ...rest, page, uvs: (piece.texture as { artUvs: number[] }).artUvs } as Piece;
+    });
+    if (ok.some((v) => !v)) return;
+    const r = own(frame, candidate.pages, frame.pieces), f = own(frame, pages, refPieces);
+    const slots = frame.pieces.map((p) => p.slot);
+    for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+      const p = y * W + x;
+      for (const d of [1, W]) {
+        if ((d === 1 && x + 1 >= W) || (d === W && y + 1 >= H)) continue;
+        const q = p + d;
+        let a = r.owner[p], b = r.owner[q];
+        if (a < 0 || b < 0 || a === b) { a = f.owner[p]; b = f.owner[q]; if (a < 0 || b < 0 || a === b) continue; }
+        boundaryPairs++;
+        let sr = 0, sf = 0;
+        for (let c = 0; c < 3; c++) { sr = Math.max(sr, Math.abs(r.data[p * 4 + c] - r.data[q * 4 + c])); sf = Math.max(sf, Math.abs(f.data[p * 4 + c] - f.data[q * 4 + c])); }
+        const excess = Math.max(0, sr - sf);
+        const pair: [string, string] = slots[a] < slots[b] ? [slots[a], slots[b]] : [slots[b], slots[a]];
+        const key = pair.join('|');
+        const reading: BoundaryColourReading = { parts: pair, frame: label, at: [x, y], excess, rendered_step: sr, reference_step: sf };
+        const prev = pairsWorst.get(key);
+        if (prev === undefined || excess > prev.excess) pairsWorst.set(key, reading);
+        if (worst === null || excess > worst.excess) worst = reading;
+      }
+    }
+  };
+  readFrame(setup, 'setup', true);
+  for (const frame of idle) readFrame(frame, `idle frame ${frame.index} (t ${+frame.time.toFixed(4)} s)`, false);
+  const over = [...pairsWorst.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)).map(([, v]) => v).filter((v) => v.excess > declared.max_step_excess);
+  for (const u of unmeasured) problems.push({ code: BOUNDARY_COLOUR_UNMEASURED_CODE, object: `slot "${u.slot}" (${u.frame})`, detail: `${u.reason}; the step against the rig's own pieces cannot be taken, and an untaken reading is never a pass — make the slot draw a parts.json piece, or drop boundary_colour from the requirements file and the bar reports SKIP` });
+  for (const o of over) problems.push({ code: BOUNDARY_COLOUR_CODE, object: `part pair "${o.parts[0]}|${o.parts[1]}"`, detail: `${o.frame}, stage pixel (${o.at[0]}, ${o.at[1]}): step excess ${o.excess} > declared max_step_excess ${declared.max_step_excess} (rendered step ${o.rendered_step}, the rig's own pieces ${o.reference_step}); a texture stretched into its padded UVs or a notch cut out of a piece shows here — fix the rig image or mesh of that pair (AUTHORING, failure map)` });
+  return {
+    status: over.length === 0 && unmeasured.length === 0 ? 'PASS' : 'FAIL',
+    instrument: 'rigc renderer, setup and every idle frame',
+    reference: 'setup: parts.json flat pieces; idle: each piece re-seated on its own parts PNG through its art UVs',
+    max_step_excess: declared.max_step_excess,
+    frames: 1 + idle.length,
+    boundary_pairs: boundaryPairs,
+    worst,
+    over,
+    unmeasured,
+    alternates: 'not measured',
+  };
+}
+
+/** The lines `check` prints: the undeclared SKIP, or the measured line and one per part pair over the allowance. */
+export function boundaryColourLines(line: BoundaryColourMeasured | null): string[] {
+  if (line === null) return [`${BOUNDARY_COLOUR_LINE}: SKIP — ${UNDECLARED_BOUNDARY_COLOUR_REASON}`];
+  const w = line.worst;
+  return [
+    `${BOUNDARY_COLOUR_LINE}: ${line.status} — ${line.boundary_pairs} boundary pair reading(s) over ${line.frames} frame(s) (setup and every idle frame), worst step excess ${w === null ? 'none (no boundary)' : `${w.excess} at part pair "${w.parts.join('|')}" ${w.frame} (${w.at.join(', ')})`}, declared max_step_excess ${line.max_step_excess}; ${line.reference}; alternate sets not measured`,
+    ...line.over.map((o) => `${BOUNDARY_COLOUR_LINE}: part pair "${o.parts.join('|')}" FAIL — ${o.frame} (${o.at.join(', ')}), step excess ${o.excess} > ${line.max_step_excess} (rendered ${o.rendered_step}, own pieces ${o.reference_step})`),
+    ...line.unmeasured.map((u) => `${BOUNDARY_COLOUR_LINE}: slot "${u.slot}" NOT MEASURED — ${u.frame}: ${u.reason}`),
+  ];
+}