rig-parts 2.8.1 → 2.9.0

package/docs/MIGRATION.md

@@ -382,7 +382,7 @@ What to do, keeping every entry you tuned — one command, after `assemble` has
 the split parts:
 
 ```
-rig-parts propose --parts <work/rig> --source <painting> --out <dir> --write-config config.json --only-missing
+rig-parts propose --parts <work/rig> --bust-landmarks bust-landmarks.json --source <painting> --out <dir> --write-config config.json --only-missing
 ```
 
 For each part the config attaches by neither `meshes` nor `regions`, it adds what is
@@ -481,3 +481,22 @@ cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
 including unselected frames, before reading the worst pose. Identical static
 ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
 never described as no declared range.
+
+## Contour torso drafts (#986)
+
+Fresh `propose` runs draft the chest-holding topwear as a contour mesh, including
+`trunk_chest` when the figure layer is split into limbs. The drafted `proposal.json`
+changes that mesh's mode and its explanatory notes. A torso on chains also declares
+uncapped continuous influences (#991). Non-torso meshes retain their existing modes.
+
+`--bust-landmarks <file>` declares `apex_r`, `apex_l` and optional `cleavage` in rig
+pixels. With these landmarks, `proposal.json` also adds `contour.bust` and the two
+chest-parented bones, `basis.json` records those bones, and the landmark overlays
+show them. A chest-holding torso now refuses with `PROPOSE_BUST_INPUT` when neither
+`--bust-landmarks` nor `--no-bust` is supplied. Runs that previously succeeded with
+a missing-landmarks note must now declare the landmarks or give an explicit
+`--no-bust "<reason>"`. Blank omission reasons are refused.
+
+A config receiving these newly drafted sections, and builds made from it, have
+changed mesh bytes. `--from-config` continues to read authored meshes unchanged.
+See [AUTHORING.md](AUTHORING.md#drafting-the-chest-carrier) for the input contract.

package/docs/STABILITY.md

@@ -49,6 +49,7 @@ defaults are the help's too, and none is guessed from the art.
 <!-- stable:commands -->
 | command | flags |
 | --- | --- |
+| `diff-components` | `--stack`, `--painting`, `--parts`, `--floor`; optional `--threshold`, `--figure`; exactly one of `--out`, `--verify` (issue #1005; exhaustive native error inventory, with byte-bound reader) |
 | `depth-prepare` | `--parts`, `--config`, `--out` (issue #897; separate numeric-depth recipe) |
 | `depth-apply` | `--parts`, `--manifest`, `--config`, `--rig-config`, `--out` (issue #897; original character config is read-only) |
 | `layers` | one positional path: a wrapper directory, a `layers.json` or a `.psd`; with it, optional `--export` (a directory to write the wrapper form into, issue #359); or `--template` with `--canvas` and no path; or a positional head run with `--full`, `--source`, `--config` together for `PLAN_HEAD_GARMENT_OVERLAP` (issue #826) |
@@ -58,7 +59,7 @@ defaults are the help's too, and none is guessed from the art.
 | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--no-offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll`, `--config` (See-through settings and optional depth block), `--depth-run` (`full` or `head`, required with the block) |
 | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`, `--write-config` (must name `--config` itself, issue #356); or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454), `--requirements` (source-bound cut-material evidence only when the file declares `cut_material`, issue #888) |
 | `propose` | `--head-box` with `--full`, `--canvas`; optional `--no-back-hair`, `--write-config` (existing config, issue #356) |
-| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (existing config for an ordinary proposal, issue #356; a new file with `--cloth`, issue #537; not with `--from-config` — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` writes changes), `--only-missing` (only with `--parts` and `--write-config`, not with `--cloth` or `--from-config`, issue #671 — additive: without it nothing `--write-config` writes changes) |
+| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (existing config for an ordinary proposal, issue #356; a new file with `--cloth`, issue #537; not with `--from-config` — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` writes changes), `--only-missing` (only with `--parts` and `--write-config`, not with `--cloth` or `--from-config`, issue #671 — additive: without it nothing `--write-config` writes changes)  `--bust-landmarks` (rig-pixel apex_r/apex_l and optional cleavage), or `--no-bust` (non-blank omission reason), one required when drafting a chest-holding torso, both incompatible with `--from-config` |
 | `propose` | `--parts`, `--source`, `--out`, `--full`, `--head`, `--write-config` together: the [neck draft](AUTHORING.md#a-neck-that-moves-on-its-own) for an existing config with `turn.body` and one neck plan row; reassembles under `<out>/rig`, preserves the sampled turn and drafts a rigid neck unit (issue #826) |
 | `compare` | `--left`, `--right`; optional `--map` |
 | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
@@ -86,6 +87,10 @@ The [command reference](AUTHORING.md#command-reference) describes each mode;
 [writing proposed config fields](AUTHORING.md#writing-proposed-config-fields)
 records the existing-file and fresh-file destinations and byte-preservation rules.
 
+`assemble --project visible` adds optional `edge_residuals.json` beside
+`parts.json` (issue #999), a report-only front/back residual candidate sidecar.
+Its observations add no acceptance bar to the existing outputs.
+
 ## The config contract
 
 `src/config.ts` is the schema and the loader, and
@@ -256,6 +261,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | `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 #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. |
+| `part_support_domains.json` | `assemble`, `build` | optional `rig-parts-support-domains/1` independent cut masks and unavailable reasons, with per-domain config-entry provenance and parts/PNG/payload digests; additive beside parts.json, whose bytes and PNGs are unchanged. Legacy output may omit it. `PART_SUPPORT_REPORT` reads pairs in the assembly placement frame and Unowned in actual setup, never as an acceptance gate. |
 | `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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "2.8.1",
+  "version": "2.9.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/skills/rig-parts/SKILL.md

@@ -86,7 +86,7 @@ under that.
 5. `rig-parts assemble … --out work` — read the `uncovered hole` lines and look at
    `work/render/recomposite_error_rig.png`; a large red hole between two parts is a
    gap See-through left (a skirt split into two legs), fixed in the plan or the layers,
-   not in the rig. Then `rig-parts propose --parts work/rig
+   not in the rig. Then `rig-parts propose --parts work/rig --bust-landmarks bust-landmarks.json
    --source <painting> --out work` → copy `bones`, `meshes`, `regions`, `limbs`,
    `motion`, `constraints`, `turn`, `motion_seams`, `proposed_rig_scale` from `proposal.json` into the config, each it
    wrote (`limbs` only with `--keypoints`, `constraints` only with `--cloth`, `turn`

package/src/assemble.ts

@@ -1,3 +1,5 @@
+import { edgePairResiduals, type EdgeResidualReport } from './edgeresidual.ts';
+import type { SupportDomain } from './coincide.ts';
 import { type SeamRule } from './seamrule.ts';
 import { DEFAULT_GROUND, DEFAULT_PROJECT_RULE, type Ground, type ProjectRule } from './projectrule.ts';
 import { paintingEdges, type PaintingEdgeSkips } from './paintingedges.ts';
@@ -2582,10 +2584,10 @@ 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 {
+export function figureSilhouette(srcr: Raster, painted = paintedFigure(srcr)): Mask {
   const { width: W, height: H } = srcr;
   const fig = newMask(W, H);
-  fig.data.set(paintedFigure(srcr));
+  fig.data.set(painted);
   const opened = dilate(dilate(erode(erode(fig, 3), 3), 3), 3);
   return fillHoles(opened);
 }
@@ -2628,9 +2630,8 @@ export function paintedFigure(srcr: Raster): Uint8Array {
  * ground reads near 0; a ground of many colours, or a figure crossing the
  * border, reads more.
  */
-export function groundRingShare(srcr: Raster): number {
+export function groundRingShare(srcr: Raster, painted = paintedFigure(srcr)): number {
   const { width: W, height: H } = srcr;
-  const painted = paintedFigure(srcr);
   let ring = 0;
   let figure = 0;
   for (let y = 0; y < H; y++) {
@@ -3066,7 +3067,7 @@ export function recomposite(parts: PlacedPart[], W: number, H: number): Raster {
 }
 
 /** Per rig pixel: 1 where some part has alpha above `COVERED_ALPHA`. */
-function coveredMask(parts: PlacedPart[], W: number, H: number): Uint8Array {
+export function coveredMask(parts: PlacedPart[], W: number, H: number): Uint8Array {
   const covered = new Uint8Array(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] > COVERED_ALPHA) covered[(p.y + y) * W + p.x + x] = 1;
@@ -3075,14 +3076,14 @@ function coveredMask(parts: PlacedPart[], W: number, H: number): Uint8Array {
 }
 
 /** Per rig pixel: 1 where the recomposite's max-channel difference from the painting is above `ERROR_LIMIT` — and, with `inside` (a scene, issue #242), the pixel is the figure's. */
-function errorMask(can: Raster, srcr: Raster, inside: Uint8Array | null = null): Uint8Array {
+export function errorMask(can: Raster, srcr: Raster, inside: Uint8Array | null = null, threshold = ERROR_LIMIT): Uint8Array {
   const n = srcr.width * srcr.height;
   const err = new Uint8Array(n);
   for (let p = 0; p < n; p++) {
     if (inside !== null && inside[p] === 0) continue;
     let m = 0;
     for (let c = 0; c < 3; c++) m = Math.max(m, Math.abs(can.data[p * 4 + c] - srcr.data[p * 4 + c]));
-    if (m > ERROR_LIMIT) err[p] = 1;
+    if (m > threshold) err[p] = 1;
   }
   return err;
 }
@@ -3127,7 +3128,7 @@ export function uncoveredHoles(can: Raster, srcr: Raster, parts: PlacedPart[], i
  * 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[] {
+export 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;
@@ -4597,6 +4598,8 @@ export function softOcclusionLine(r: SoftOcclusionReading): string {
 }
 
 export interface AssembleResult {
+  /** Report-only residual candidates, present after the visible edge pass. */
+  edgeResiduals?: EdgeResidualReport;
   /** Report-only source re-take under actual soft front support (#825). */
   softOcclusion?: SoftOcclusionReading[];
   parts: PartsFile;
@@ -4613,6 +4616,10 @@ export interface AssembleResult {
   /** Console-only source-edge support (#888); never serialized into parts.json. */
   cutMaterial: MaterialRow[];
   materialSources: MaterialSource[];
+  /** Independent authored masks frozen before any art-dependent partition. */
+  supportDomains: SupportDomain[];
+  /** Transient native source observation reused by build, never serialized. */
+  supportFigure?: Mask;
   /** What each `config.limbs` limb cut, per part it took and per joint (`limbLines`); empty without limbs (issue #349). */
   limbs: LimbCount[];
   /** The full-run layers the plan does not take from the full run whose uncovered error holds a body (`uncoveredErrorLayers`); empty otherwise. */
@@ -4846,7 +4853,8 @@ export function assemble(input: AssembleInput): AssembleResult {
   checkPlanAgainstRuns(sourcePlan, extend, full, head);
   const { W, H } = frame;
   const srcr = sourceInRig(source, W, H);
-  const groundShare = groundRingShare(srcr);
+  const supportPainted = paintedFigure(srcr);
+  const groundShare = groundRingShare(srcr, supportPainted);
   // Issue #359: a part's hidden-art layer is the under of a cut that names none — and, with one named, a refusal, since
   // reading either would be a guess. Its uses are counted for `hiddenLines`.
   const hiddenArt = hiddenArtByPart(plan, input.cuts, { full, head }, frame, input.resolution);
@@ -5002,6 +5010,9 @@ export function assemble(input: AssembleInput): AssembleResult {
   // most likely), and two cuts of one part that share a pixel would give it
   // to both. Every pair is named.
   const cutMasks = cuts.map((q) => pixelsInPolygon(q.polygon, W, H));
+  const supportDomains: SupportDomain[] = cuts.map((cut, i) => ({ part: cut.into,
+    mask: { width: W, height: H, data: cutMasks[i].data.slice() },
+    provenance: { kind: 'cut-polygon', entry: `config.assemble.cuts[${i}].polygon` } }));
   cuts.forEach((q, i) => {
     const out = q.polygon.filter(([x, y]) => x > W || y > H);
     if (out.length > 0) {
@@ -5139,7 +5150,7 @@ export function assemble(input: AssembleInput): AssembleResult {
   // Every Built owns its writer slice. No source-map lookup follows this
   // last cut-layer build; drop originals before cut/limb working sets grow.
   layerWriters.clear();
-  const silhouette = seamRule === 'silhouette' || patches.some((q) => q.alpha === 'silhouette') ? figureSilhouette(srcr) : null;
+  const silhouette = seamRule === 'silhouette' || patches.some((q) => q.alpha === 'silhouette') ? figureSilhouette(srcr, supportPainted) : null;
   const cut = patches.map((q, i) => {
     const c = cutPatch(q, srcr, silhouette);
     if (c === null) {
@@ -5653,7 +5664,7 @@ export function assemble(input: AssembleInput): AssembleResult {
       return whole;
     };
     const e = paintingEdges(stack.map(onRig), srcr, {
-      painted: paintedFigure(srcr),
+      painted: supportPainted,
       ...(input.ground === undefined ? {} : { ground: input.ground }),
       editable: order.map((d) => !('patch' in d)),
       keep: keepInOrder,
@@ -5835,6 +5846,13 @@ export function assemble(input: AssembleInput): AssembleResult {
     frame.headBottom,
     bodyMinPx(frame),
   );
+  // This observation belongs to the source painting. Reuse the mask already
+  // read for ground coverage without changing the assembly silhouette.
+  let opaqueSource = true;
+  for (let p = 3; p < source.data.length; p += 4) if (source.data[p] !== 255) { opaqueSource = false; break; }
+  const supportSilhouette = opaqueSource ? silhouette ?? figureSilhouette(srcr, supportPainted) : null;
+  const supportFigure = supportSilhouette === null ? undefined : newMask(W, H);
+  if (supportFigure !== undefined && supportSilhouette !== null) for (let p = 0; p < supportPainted.length; p++) supportFigure.data[p] = supportSilhouette.data[p] & supportPainted[p];
   return {
     ...(softOcclusion.length === 0 ? {} : { softOcclusion }),
     parts: {
@@ -5851,6 +5869,7 @@ export function assemble(input: AssembleInput): AssembleResult {
       ...(padRecord === null ? {} : { single_run_pad: padRecord }),
     },
     images: placed,
+    ...(projectRule === 'visible' ? { edgeResiduals: edgePairResiduals(placed.map(p => ({ name: p.record.name, x: p.record.x, y: p.record.y, image: p.image })), srcr, can, ERROR_LIMIT) } : {}),
     ...(registeredDepth.size === 0 ? {} : { depthReadings: ([['full', depthFullInput], ...(single ? [] : [['head', depthHeadInput]])] as Array<['full' | 'head', LayerSet]>).flatMap(([run, set]) => set.layers.flatMap(layer => layer.depthSheet === undefined ? [] : [{ from: `${run}:${layer.name}`, reading: layer.depthSheet.reading }])) }),
     ...(depthClamps.length === 0 ? {} : { depthClamps }),
     recomposite: can,
@@ -5860,6 +5879,8 @@ export function assemble(input: AssembleInput): AssembleResult {
     cuts: cutCounts,
     cutMaterial: [...cutMaterial, ...lim.material],
     materialSources: [...materialSources, ...lim.sources],
+    supportDomains,
+    ...(supportFigure === undefined ? {} : { supportFigure }),
     limbs: lim.counts,
     uncovered,
     holeKinds: kinds,

package/src/build.ts

@@ -1,3 +1,6 @@
+import { EDGE_RESIDUAL_FILE, edgeResidualLines } from './edgeresidual.ts';
+import { SUPPORT_DOMAINS_FILE, writeSupportDomains } from './supportdomains.ts';
+import { COINCIDE_LINE, supportLines } from './coincide.ts';
 import { DEFAULT_SEAM_RULE } from './seamrule.ts';
 import { DEFAULT_PROJECT_RULE } from './projectrule.ts';
 import { EDGE_CONTRAST } from './paintingedges.ts';
@@ -338,6 +341,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   // The early door: assemble runs before propose has drafted bones, meshes,
   // regions and motion, so it requires only what it reads (issue #20).
   const cfg = loadEarlyConfig(input.config, 'assemble');
+  const supportDeclarations = JSON.stringify(cfg.assemble.cuts ?? []);
   const seam = input.seam ?? cfg.assemble.seam ?? DEFAULT_SEAM_RULE;
   const project = input.project ?? cfg.assemble.project ?? DEFAULT_PROJECT_RULE;
   const src = readSource(input.source);
@@ -793,6 +797,9 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   mkdirSync(dirname(outs.recomposite), { recursive: true });
   mkdirSync(dirname(outs.errorMap), { recursive: true });
   writeParts(outs.partsJson, result.parts);
+  const residualPath = join(dirname(outs.partsJson), EDGE_RESIDUAL_FILE);
+  if (result.edgeResiduals === undefined) rmSync(residualPath, { force: true });
+  else writeFileSync(residualPath, JSON.stringify(result.edgeResiduals, null, 2) + '\n');
   for (const { record, image, depthImage } of result.images) {
     writePng(join(outs.partsDir, `${record.name}.png`), image);
     if (depthImage !== undefined && record.depth !== undefined) writePng(join(outs.partsDir, record.depth.image), depthImage);
@@ -805,6 +812,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   }
   if (materialAsked) writeMaterialSources(outs.partsJson, outs.partsDir, result.parts, result.materialSources);
   else rmSync(join(dirname(outs.partsJson), CUT_MATERIAL_SOURCES), { force: true });
+  writeSupportDomains(outs.partsJson, outs.partsDir, result.parts, result.supportDomains, supportDeclarations);
   writePng(outs.recomposite, result.recomposite);
   writePng(outs.errorMap, result.errorMap);
   // Issue #242: under config.scene, the figure the recomposite was read inside, beside the recomposite.
@@ -822,6 +830,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
     // Issue #996: under a declared busy ground, what the two ground rules left.
     if (fields.ground === 'busy') log(`  busy ground (assemble.ground): ${e.skipped.mix} behind-side px left that are not a mix of the two reference colours, ${e.skipped.support} part px not raised outside the part's own support`);
   }
+  if (result.edgeResiduals !== undefined) for (const line of edgeResidualLines(result.edgeResiduals)) log(line);
   // Issue #359: one run, said, so a reader of the lines knows no head run was placed.
   if (runs.single) log(`  one run: ${input.full} holds the face (${SINGLE_RUN_FACE_TAGS.join(', ')}), so no head run is read; every part comes from the full run`);
   // Issue #366: a file that is not the resolution square was padded to it; said, with where parts.json records it. None for a square file.
@@ -1665,6 +1674,10 @@ export interface CheckStageInput {
   out: string;
   /** The painting `--source` names (issue #77): adds the setup pose against it. */
   source?: string;
+  /** Internal build painting for the report only; does not enable source gates. */
+  supportSource?: string;
+  /** Transient source observation passed by assembly, never a public output. */
+  supportFigure?: Mask;
   /** The packed build's `--page-edges`; {@link DEFAULT_PAGE_EDGES} when absent. */
   pageEdges?: PageEdges;
   /** The packed build's `--pack-shape`; {@link DEFAULT_PACK_SHAPE} when absent. */
@@ -1826,9 +1839,12 @@ export function levelLines(line: LevelLine): string[] {
  * own — its limb, its bone, and on a FAIL every other bone it is bound to.
  */
 export function limbCheckLines(line: LimbLine): string[] {
+  const carriers = line.parts.some(row => row.region_bones !== undefined)
+    ? 'its segment carrier or its declared contour region bones'
+    : 'its one bone with weight 1 (a region on it, or a mesh weighted to it alone)';
   return [
-    `${LIMB_LINE}: ${line.status} — ${line.parts.length} limb part(s), each bound in rig.json to its one bone with weight 1 (a region on it, or a mesh weighted to it alone)`,
-    ...line.parts.map((r) => `limb  "${r.part}" (${r.limb}) on "${r.bone}": ${r.status}${r.others.length === 0 ? '' : `, also weighted to ${r.others.map((b) => `"${b}"`).join(', ')}`}`),
+    `${LIMB_LINE}: ${line.status} — ${line.parts.length} limb part(s), each bound in rig.json to ${carriers}`,
+    ...line.parts.map((r) => `limb  "${r.part}" (${r.limb}) on "${r.bone}": ${r.status}${r.region_bones === undefined ? '' : `, declared contour region bones [${r.region_bones.join(', ')}]`}${r.others.length === 0 ? '' : `, also weighted to ${r.others.map((b) => `"${b}"`).join(', ')}`}`),
   ];
 }
 
@@ -1928,7 +1944,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   const entryLine = versionLines.find((l) => l.startsWith('entry:'));
   log(`  ${rigcIdentity(bin, v)}${entryLine === undefined ? '' : `; ${entryLine}`}`);
   const mode: PackMode = { pageEdges: input.pageEdges ?? DEFAULT_PAGE_EDGES, packShape: input.packShape ?? DEFAULT_PACK_SHAPE };
-  const r = runCheck(input.rig, input.out, rigc, input.parts, mode, input.source, input.requirements, input.seamPairs === true, input.keepStills === true, input.set, input.allSets === true, input.environment, input.requirementsAs, input.config, input.windBand, input.noExtremes === true);
+  const r = runCheck(input.rig, input.out, rigc, input.parts, mode, input.source, input.requirements, input.seamPairs === true, input.keepStills === true, input.set, input.allSets === true, input.environment, input.requirementsAs, input.config, input.windBand, input.noExtremes === true, input.supportSource, input.supportFigure);
   if (r.figures.environment !== undefined) log(`  ${environmentLine(r.figures.environment)}`);
   log(`  gate rig-play (rigc ${packedBuildLabel(mode)}), verbatim:`);
   for (const l of r.gateHtml) log(l);
@@ -1994,6 +2010,8 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (cutMaterial !== undefined) for (const line of materialLines(cutMaterial)) log(`  ${line}`);
   const artJoints = fig[ART_JOINT_LINE];
   if (artJoints !== undefined) for (const line of artJointLines(artJoints)) log(`  ${line}`);
+  const partSupport = fig[COINCIDE_LINE];
+  if (partSupport !== undefined) for (const line of supportLines(partSupport)) log(`  ${line}`);
   const setupPainting = fig[SETUP_PAINTING_LINE];
   if (setupPainting !== undefined) for (const line of setupPaintingLines(setupPainting)) log(`  ${line}`);
   for (const line of boundaryColourLines(r.boundaryColour)) log(`  ${line}`);
@@ -2368,9 +2386,9 @@ export function suppliedCheckFlag(flag: string): string | null {
  * rig-c's launcher answers for; they are two fields so a caller can tell
  * the stages' calls apart (the selftest counts them).
  */
-/** Stage implementations may run outside this process; only check has a returned value the driver reads. */
+/** Stage implementations may run outside this process; assembly may return its transient source observation; check returns its report. */
 export interface BuildStages {
-  assemble: (input: AssembleStageInput, outputs: AssembleOutputs, log: Log) => void;
+  assemble: (input: AssembleStageInput, outputs: AssembleOutputs, log: Log) => { supportFigure?: Mask } | void;
   rig: (input: RigStageInput, rigc: RigcRunner, scratch: string, log: Log) => void;
   check: typeof checkStage;
 }
@@ -2445,6 +2463,8 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   for (const p of BUILD_OWNS) rmSync(join(out, p), { recursive: true, force: true });
   // Optional source evidence is cleared separately; BUILD_OWNS is the legacy complete output tree.
   rmSync(join(out, CUT_MATERIAL_SOURCES), { force: true });
+  rmSync(join(out, EDGE_RESIDUAL_FILE), { force: true });
+  rmSync(join(out, SUPPORT_DOMAINS_FILE), { force: true });
   // Issue #242: the figure mask is written only under config.scene; one left by an earlier scene build is not this build's.
   rmSync(join(out, FIGURE_MASK_FILE), { force: true });
   // The idle-keys value is named only when it is not the default, so a build without the flag, or with the default, prints the line it printed before issue #95.
@@ -2455,6 +2475,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   // Issue #978: the painting is handed to the check only when the requirements file declares setup_painting, which
   // cannot be measured without it; a build without that declaration hands it nothing, as before, and writes the same bytes.
   let paintingForCheck: string | null = null;
+  let supportFigure: Mask | undefined;
   try {
     // build runs rig next, which needs the whole config, so the full loader is
     // asked first: a config rig would refuse is refused before assemble writes
@@ -2474,11 +2495,12 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
     if (input.environment !== undefined) readCheckEnvironment(input.environment);
     // And the steady-wind band spec (issue #590), as check reads it.
     if (input.windBand !== undefined) readWindBand(input.windBand);
-    stages.assemble(
+    const assembled = stages.assemble(
       { source: input.source, full: input.full, head: input.head, config: input.config, seam, project, ...(req === null ? {} : { requirements: req.read }), ...(input.alts === undefined ? {} : { alts: input.alts }) },
       { partsJson: join(out, 'parts.json'), partsDir: join(out, 'parts'), recomposite: join(out, 'recomposite_rig.png'), errorMap: join(out, ERROR_MAP_FILE) },
       prefixed('assemble'),
     );
+    supportFigure = assembled?.supportFigure;
   } catch (err) {
     return refused('assemble', err);
   }
@@ -2491,7 +2513,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
 
   let report: CheckReport;
   try {
-    report = stages.check({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(req === null ? {} : { requirements: req.read, requirementsAs: req.recorded }), ...(paintingForCheck === null ? {} : { source: paintingForCheck }), seamPairs: input.seamPairs === true, keepStills: input.keepStills === true, noExtremes: input.noExtremes === true, ...(input.set === undefined ? {} : { set: input.set }), allSets: input.allSets === true, ...(input.environment === undefined ? {} : { environment: input.environment }), ...(input.windBand === undefined ? {} : { windBand: input.windBand }), ...(configRecord === null ? {} : { config: configRecord }) }, run.check, run.checkBin, prefixed('check'));
+    report = stages.check({ rig: join(out, 'rig'), parts: out, supportSource: input.source, ...(supportFigure === undefined ? {} : { supportFigure }), out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape, ...(req === null ? {} : { requirements: req.read, requirementsAs: req.recorded }), ...(paintingForCheck === null ? {} : { source: paintingForCheck }), seamPairs: input.seamPairs === true, keepStills: input.keepStills === true, noExtremes: input.noExtremes === true, ...(input.set === undefined ? {} : { set: input.set }), allSets: input.allSets === true, ...(input.environment === undefined ? {} : { environment: input.environment }), ...(input.windBand === undefined ? {} : { windBand: input.windBand }), ...(configRecord === null ? {} : { config: configRecord }) }, run.check, run.checkBin, prefixed('check'));
   } catch (err) {
     return refused('check', err);
   }