rig-parts 1.84.0 → 1.85.0

package/cli.ts

@@ -723,6 +723,8 @@ usage:
   rig-parts assemble --source <painting.png> --full <dir|psd> [--head <dir|psd>]
                        --config <config.json> --out <dir> [--seam near-white|silhouette]
                        [--project core|visible] [--alt <name>=<source>:<full>[:<head>]]
+                       [--requirements <file.json>]
+      With cut_material declared, records original source edges bound to emitted parts for check.
       Merge the full-body and head-crop See-through runs into rig-space parts:
       <out>/rig/parts/<name>.png (each cropped to its alpha box), <out>/rig/parts.json,
       <out>/render/recomposite_rig.png and <out>/render/${ERROR_MAP_FILE} (the error
@@ -1082,7 +1084,7 @@ const TAKES = {
   compare: { valued: ['--left', '--right', '--map'], switches: [] },
   check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment', '--wind-band'], switches: ['--seam-pairs', '--keep-stills', '--all-sets', '--no-extremes'] },
   loop: { valued: ['--frames', '--out'], switches: ['--palette'] },
-  assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt', '--write-config'], switches: ['--propose-plan'] },
+  assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt', '--write-config', '--requirements'], switches: ['--propose-plan'] },
   'comfy seethrough': { valued: ['--image', '--out', '--resolution', '--steps', '--seed', '--prefix', '--host', '--wait', '--timeout', '--poll', '--config', '--depth-run'], switches: ['--offload', '--no-offload', '--lama', '--nf4'] },
   'comfy paint': { valued: ['--config', '--out', '--seeds', '--seed0', '--host', '--wait', '--timeout', '--poll'], switches: [] },
   inputs: { valued: ['--source', '--config', '--out'], switches: [] },
@@ -1707,6 +1709,7 @@ function cmdAssemble(args: string[]): number {
   }
   // --head is optional (issue #359): without it the full run is the one run, and it must hold the face.
   for (const f of ['--source', '--full', '--config']) if (!flags.has(f)) return usage(`assemble needs ${f}`);
+  if (propose && flags.has('--requirements')) return usage('--requirements belongs to assemble output, not --propose-plan');
   if (propose && (flags.has('--out') || flags.has('--seam') || flags.has('--project') || alts.length > 0)) return usage('--propose-plan prints to the console; it takes none of --out, --seam, --project, --alt');
   if (!propose && flags.has('--write-config')) return usage('--write-config belongs to assemble --propose-plan');
   if (!propose && !flags.has('--out')) return usage('assemble needs --out <dir>');
@@ -1739,7 +1742,7 @@ function cmdAssemble(args: string[]): number {
     }
     const out = flags.get('--out') as string;
     assembleStage(
-      { source, full, head, config, seam: seam as SeamRule, project: project as ProjectRule, ...(alts.length === 0 ? {} : { alts }) },
+      { source, full, head, config, ...(flags.has('--requirements') ? { requirements: flags.get('--requirements') as string } : {}), seam: seam as SeamRule, project: project as ProjectRule, ...(alts.length === 0 ? {} : { alts }) },
       { partsJson: join(out, 'rig', 'parts.json'), partsDir: join(out, 'rig', 'parts'), recomposite: join(out, 'render', 'recomposite_rig.png'), errorMap: join(out, 'render', ERROR_MAP_FILE) },
       console.log,
     );

package/docs/AUTHORING.md

@@ -4067,6 +4067,93 @@ consumer acceptance work; assembly provenance does not establish motion quality.
 
 <a id="source-before-scissors-issue-819"></a>
 
+A hand polygon ending at a joint supplies no material for that joint's turn
+(issue #888). An `overlap` keeps pixels on the **parent**; it does not grow
+the cut piece. No source for material past the joint means stop and name the
+tool gap, following the source ladder below; do not hide a tear with crops or
+under-pieces. With an explicit `cut_material` declaration, `assemble` prints
+each original polygon edge's length through
+opaque source art (`alpha > 8`) and contiguous material past it on the piece.
+The same reading covers a limb's original structural joint line and the
+lower segment together with its generated hybrid band, when present.
+Assembly readings are SKIP-class observations; only check judges the declared bend.
+Without a declaration the API reading is SKIP and the CLI keeps its existing output.
+Limb source intersections use the final segmentation ownership map separately
+for each adjacent source; another limb's island is excluded before capture.
+
+To enforce a bend, add `cut_material` to the existing
+`spine-parts-requirements/1` file (the other fields remain required):
+
+```json
+{
+  "spec": "spine-parts-requirements/1", "fps": 12, "requirements": [],
+  "cut_material": [{
+    "part": "hand", "joint": "wrist", "at": [8, 12], "axis": [0, 1],
+    "reach_px": 3, "bend_degrees": [-30, 30]
+  }]
+}
+```
+
+These are hand-computable fixture coordinates, not recommended rig values.
+`at` is an independently supplied joint centre in stage pixels (y down);
+`axis` identifies an original opaque cut inward within reach, checked against
+the source evidence. Every polygon edge retains its own canonical inward
+normal; a declaration matching none of the eligible edges is refused.
+Correspondence accepts exact perpendicularity to the original edge direction
+(zero dot product), or exact collinearity with its stored canonical inward
+(zero cross product); the inward cross-product sign must also agree.
+Positive scalar multiples such as `[1,1]` and `[2,2]` are equivalent; rounded
+unit components are never compared. Orientation arithmetic must be finite and
+the direction magnitude representable, otherwise the declaration is refused.
+`reach_px` is the author's explicit joint reach, and `bend_degrees` is the
+continuous interval in stage coordinates, positive clockwise, inside
+`[-180, 180]`. Nothing is inferred from a name or an animation. A limb's joint
+name and centre must match its recorded lower segment; segment0 and a
+standalone generated band have no lower structural cut to read.
+
+Run `assemble --requirements <file>` (or `build --requirements <file>`)
+first, then `check --requirements <file>` against that assembly. Only an
+explicit `cut_material` declaration writes `cut_material_sources.json`
+beside `parts.json`: original edge endpoints, inward direction, opaque
+source intervals split at pixel-cell boundaries (ordered, nonoverlapping
+`opaque_t` spans inside `[0,1]` on their actual edge), source labels and
+transformed RGBA digests including placement and size, bound to the emitted `parts.json` and every base PNG by SHA-256.
+`check` also verifies the complete source payload digest, the interval census
+and canonical perpendiculars. Listed source edges must contain positive
+opaque intervals; an empty array cannot hide an edge beside another one.
+`check` never reconstructs discarded source pixels or polygons from siblings.
+Missing or stale evidence is unavailable, not zero support. Assemble again to
+refresh it. Alternate-set source evidence is not interchangeable with the base
+assembly; this instrument currently reads the base parts only.
+
+The gate clips every original opaque edge interval to the declared reach.
+Let its tangent be `(-ny, nx)` for inward normal `n`. A point relative to the
+joint has **both** coordinates `(t, d)`, where `d` is the actual cut plane's
+normal offset. Inverse rotation gives `(t*cos(theta) - d*sin(theta),
+t*sin(theta) + d*cos(theta))`. Required outward material, measured from the
+actual cut plane, is `max(0, d*(1-cos(theta)) - t*sin(theta))`; the normal offset
+is never dropped or projected onto the joint plane.
+
+The entire actual line segment is tested against every relevant transparent
+pixel cell's outward normal shadow. Segment/polygon incidence can change only
+when a rotating endpoint crosses an edge, the rotating source line crosses a
+vertex, or edges become parallel. All critical angles are solved analytically;
+interval interiors and boundary angles cover the whole declared continuous
+range, including a fixed angle. A strict intersection supplies a witness and
+its contiguous depth, ending at the first transparent cell. Midpoint rays are
+additional diagnostics, never the coverage proof. No angular sampling rate or
+calibrated tolerance is used. Controls plant a between-ray hole and translated
+and oblique cut edges whose inverse rotations are computed by hand.
+
+`CHECK_CUT_JOINT_MATERIAL` names part, joint, original edge length, length
+within reach and found/required depth on the same deficient ray. The interval
+and pixel-cell geometry are measured; subpixel texture filtering, another
+motion, material outside the declared reach and consumer compositing remain
+outside this gate. An absent source crossing or unrepresentable arithmetic is
+`CHECK_CUT_MATERIAL_MEASURED`, never PASS. Without a declaration the API reading
+is SKIP; the CLI preserves its existing stdout and adds no sidecar, `parts.json` field,
+`check.json` field or counted bar to an undeclared build.
+
 **Scissors are for structure, never for repair.** `cuts`, `patches` and
 `author:<label>` layers separate something that must move independently and
 that See-through has no layer for: a joint, an accessory, or a rear piece that
@@ -4934,6 +5021,9 @@ documents do not ship). Each is an input this package built; none is an author's
 | <a id="CHECK_INPUT_PRESENT"></a><a id="CHECK_INPUT_IS_JSON"></a><a id="CHECK_PART_PNG_PRESENT"></a><a id="CHECK_PART_PNG_MATCHES_BOX"></a><a id="CHECK_PART_SLOT_PRESENT"></a><a id="CHECK_RIG_STAGE_PRESENT"></a><a id="CHECK_RIG_STAGE_IS_THE_CANVAS"></a><a id="CHECK_RIG_ROOT_BONE"></a><a id="CHECK_IDLE_PRESENT"></a>`CHECK_INPUT_PRESENT`, `CHECK_INPUT_IS_JSON`, `CHECK_PART_PNG_PRESENT`, `CHECK_PART_PNG_MATCHES_BOX`, `CHECK_PART_SLOT_PRESENT`, `CHECK_RIG_STAGE_PRESENT`, `CHECK_RIG_STAGE_IS_THE_CANVAS`, `CHECK_RIG_ROOT_BONE`, `CHECK_IDLE_PRESENT` | the rig directory is incomplete or disagrees with `parts.json` (`CHECK_PART_SLOT_PRESENT`: a part with no slot of its own name, which the judgement lines render it by; `CHECK_INPUT_PRESENT` on `--set` / `--all-sets`: no `parts.json`, no `alternates`, or the named set is not in `alternates`). `motion.json` is required even with no animation in it, because `rigc build` takes `--motion` (a spec with `"animations": {}` builds green); `CHECK_IDLE_PRESENT` is an `idle` that is there with no positive `duration` — an absent `idle` is measured around (§7). `CHECK_INPUT_PRESENT` on `…/parts.json`: `--parts` named a directory without `parts.json` — most often `parts/` itself — or, without `--parts`, the rig directory has none while the directory above it does (build's layout, `<out>/rig` under `<out>/parts.json`). The detail says it: "--parts names the directory holding parts.json and parts/, not parts/ itself (after build, that is build's --out, whose rig is <out>/rig); without --parts it is --rig", and names the parent when the parent holds `parts.json`. With neither (no `--parts`, and no `parts.json` beside `rig.json` or above it), the rig is measured without parts and nothing is refused (§7) | re-run rig (`build` does both); for `…/parts.json`, `--parts` — the directory above `parts/` |
 | <a id="CHECK_SOURCE_SIZE"></a>`CHECK_SOURCE_SIZE` | the painting `--source` names is not this rig's: no single `rig_scale` takes its width and height to the stage's (assemble makes the canvas `trunc(w × rig_scale)` x `trunc(h × rig_scale)`), or, with `parts.json` read, its `scale_rig_per_source` does not; or the stage is not whole pixels. Refused before anything is built | the painting the rig was made from — the stage's own size, or the painting `assemble` was given |
 | <a id="CHECK_SOURCE_PNG"></a>`CHECK_SOURCE_PNG` | `--source` names a file that does not read as a PNG | a PNG |
+| <a id="CHECK_SETUP_MATCHES_PAINTING"></a>`CHECK_SETUP_MATCHES_PAINTING` | region, slot, failing-pixel box, slot pixelcount, complete region pixelcount and declared limit | compare the source painting beside the actual setup; follow [Source before scissors](#source-before-scissors), then rerun with the same authored limit |
+| <a id="CHECK_SETUP_PAINTING_SOURCE"></a>`CHECK_SETUP_PAINTING_SOURCE` | a declaration without a source painting | supply `--source`; the assembled composite is not an independent reference |
+| <a id="CHECK_SETUP_PAINTING_MEASURED"></a>`CHECK_SETUP_PAINTING_MEASURED` | missing native setup/ownership or unsupported clipping | supply observable textured setup geometry; an unavailable instrument never passes |
 | <a id="CHECK_SOURCE_GRID"></a>`CHECK_SOURCE_GRID` | the setup-pose still and its black-tinted twin (the coverage `SETUP_POSE_VS_SOURCE` reads) did not come back on one grid over one opaque background | a rigc problem; report it |
 | <a id="CHECK_RIGC_VERSION"></a>`CHECK_RIGC_VERSION` | `rigc --version` is below 1.4.0, or prints no version: its `render` has no `--geometry`, which `TEXTURE_STRETCH` reads. Refused before anything is built | `bun install` (this package depends on rig-c ^2.20.4), or put a newer `rigc` first on `PATH` |
 | <a id="CHECK_RIGC_ENTRY"></a><a id="CHECK_RIGC_ENTRY_READS"></a>`CHECK_RIGC_ENTRY`, `CHECK_RIGC_ENTRY_READS` | `rigc --version` names no entry (a rigc below 2.0.0), or names one in neither launcher form (`entry: cli.ts — @esotericsoftware/spine-core <v> present`, `entry: cli_core.ts — @esotericsoftware/spine-core absent — …`); `check.json`'s `rigc_entry` records the one that gated the build | `bun install` |
@@ -4987,6 +5077,8 @@ documents do not ship). Each is an input this package built; none is an author's
 | <a id="REQUIREMENTS_TARGET"></a>`REQUIREMENTS_TARGET` | a scene target places one bone twice for one animation, places it for an animation no requirement measures, has a key outside the animation's `[0, duration]`, or sits in a group the animation translates | one placement per bone and animation, inside it, for an animation a requirement reads |
 | <a id="REQUIREMENTS_SELF_TARGET"></a>`REQUIREMENTS_SELF_TARGET` | a `contact` whose `target` is its own `bone` and `point` (0 apart by construction), or an `aim` whose `target` is a point of the aimed bone itself — its tip lies on its own axis (0 degrees by construction), its origin gives no line at all (issue #540): a PASS would say nothing. Refused before anything is built, beside the file's other refusals; a bone's tip against its own origin is a contact like any other (it reads the bone's length), and a stage target is never one | a different bone (or a stage point, for an aim), or for a contact the bone's other point |
 | <a id="CHECK_REQUIREMENTS_FRAMES"></a>`CHECK_REQUIREMENTS_FRAMES` | a requirement render did not write every frame rigc sampled, or the as-declared, released and full renders of a follow sampled different frames | a rigc problem; report it |
+| <a id="CHECK_CUT_JOINT_MATERIAL"></a>`CHECK_CUT_JOINT_MATERIAL` | A declared `cut_material` source ray within reach needs more depth during its continuous bend interval than its final piece supplies; the message names part, joint, original opaque edge length, found and required material | follow [Source before scissors](#source-before-scissors); obtain source material past the joint, or explicitly declare the consumer's smaller required bend; no crop or under-piece repair |
+| <a id="CHECK_CUT_MATERIAL_MEASURED"></a>`CHECK_CUT_MATERIAL_MEASURED` | Original source evidence is missing, malformed or stale, a part/joint correspondence is unresolved, the inward axis disagrees, or no opaque crossing lies within reach | rerun `assemble --requirements <file>` or `build --requirements <file>` to bind original source readings to the actual emitted parts; correct an independently declared correspondence/reach; never infer original art from emitted siblings |
 | <a id="CHECK_REQUIREMENT_MET"></a>`CHECK_REQUIREMENT_MET` | a declared requirement measured outside its bar; the figure, its frame and the bar are quoted | the rig or its motion (§7, *Declared requirements*) — or the bar, if the scene asks less |
 | <a id="CHECK_REQUIREMENT_MEASURABLE"></a>`CHECK_REQUIREMENT_MEASURABLE` | a declared requirement is NOT MEASURABLE: what it asks is undefined in the frames, and the reason is quoted. Not a pass | the declaration (a bone with a length, a target off the bone's origin, a least drive the constraint reaches) or the rig |
 | <a id="REQUIREMENTS_MAY_FOLD"></a>`REQUIREMENTS_MAY_FOLD` | a `may_fold` entry names a slot with no mesh attachment — a region is one quad and cannot fold (issue #320). Refused before anything is built. Before issue #333 an entry naming the idle was refused here too; the bar reads the idle now, and `idle` is an animation name like any other | a mesh slot |
@@ -5549,6 +5641,7 @@ Under `--source <painting.png>`, a second reported line, also never a FAIL
 | line | reports | bar | `reference-demo` | `reference-sample` | SKIP when |
 | --- | --- | --- | --- | --- | --- |
 | <a id="SETUP_POSE_VS_SOURCE"></a>`SETUP_POSE_VS_SOURCE` | the setup pose against the painting, by `assemble`'s own `measureRecomposite` over the stage's pixels — `mean_abs` and `within_share` (mean channel, within 8), `error_px` (max channel over 40), `uncovered_error_px` (of those, where the pose has alpha 128 or less), `hole_count` and the largest hole's box — with `painting_px`, `stage_px`, `render_px` and `render_scale` beside them. The painting is resampled onto the stage as assemble resamples it (lanczos3, alpha dropped). rigc renders onto an opaque grey, so the pose over white and its alpha are read off a second still of the same pose with every slot tinted black; both are carried onto the stage with the seam's map turned round (bilinear) | none — status `REPORTED`; assemble applies no bar to the figures it measures, so none is derived here | 3.146 / 93.43 % / 12,399 / 1,732, 518 holes, the largest 61 px at 351,157 6x20 (assemble's recomposite: 2.391 / 95.81 % / 11,050 / 1,564, 453) | 1.095 / 97.30 % / 5,348 / 1,239, 313 holes, the largest 88 px at 479,416 6x29 (assemble's: 0.835 / 97.95 % / 4,512 / 1,185, 259) | not written without `--source` |
+| <a id="SETUP_MATCHES_PAINTING"></a>`SETUP_MATCHES_PAINTING` | declared region count, native box, limit and actual top contributor rows | PASS/FAIL against authored limits; no limit is SKIP; undeclared regions are not judged |
 
 The figures are assemble's by construction, not a second definition beside them;
 what differs is what they are taken of — the pose rigc draws, not the flat stack —
@@ -6084,8 +6177,69 @@ Unknown fields are refused.
 
 | line | measures | bar | SKIP |
 | --- | --- | --- | --- |
+| <a id="CUT_JOINT_MATERIAL"></a>`CUT_JOINT_MATERIAL` | Original source edge intervals versus final opaque pixel-cell material over each explicit `cut_material` joint reach and continuous bend interval; full two-coordinate swept-segment coverage plus contiguous normal support | every required source interval has material through its inverse-rotation sweep; a hole between diagnostic rays also fails | no declaration: API SKIP, unchanged CLI stdout, no JSON key or counted bar; missing/stale source evidence or no crossing within reach: named unavailable refusal |
 | <a id="ART_JOINT_DISTANCE"></a>`ART_JOINT_DISTANCE` | Each independently measured art joint versus its explicitly named bone's renderer setup origin, in stage pixels; printed and recorded per joint | distance <= the declared `fixed_skeleton.within_px`, with no rounding slack | no limit declared: every row and the block retain their distances as SKIP, never a pass; no declaration: no line |
 
+### Setup against the painting
+
+`check --source <painting> --requirements <file>` can declare
+`setup_painting` in the existing `spine-parts-requirements/1` file:
+
+```json
+{
+  "spec": "spine-parts-requirements/1",
+  "fps": 12,
+  "requirements": [],
+  "setup_painting": {
+    "rgb_tolerance": 60,
+    "regions": [
+      { "name": "torso", "box": [10, 20, 40, 60], "max_pixels": 0 }
+    ]
+  }
+}
+```
+
+These are authored limits, not defaults or calibrated figures. A region's
+`box` is `[x, y, width, height]` in the declared stage's native pixel grid,
+x right and y down, with exclusive far edges. Regions must fit the stage.
+`rgb_tolerance` is an integer from 0 through 255. Count a pixel once when its
+maximum absolute RGB-channel difference is **strictly greater** than that
+value. The region passes when its total count is at most its authored
+nonnegative integer `max_pixels`. Without that limit the region reports
+**SKIP**, including a zero-count region. An undeclared region has no verdict.
+Without `setup_painting`, existing output bytes and rendering remain unchanged.
+
+The observation is the actual renderer's setup pose, without animation or
+physics advancement, from the already gated setup candidate. Its viewport is
+the declared stage, scale 1; no fitted alignment or flat part composite is
+substituted. Source PNG readers preserve straight RGBA. This optional check
+first composites the painting over opaque white at its **original source
+resolution**, rounding each RGB channel to RGBA8, then passes that opaque
+image through the existing `sourceInRig` Lanczos3 resampling onto the stage.
+The rendered setup is composited over white on the native stage grid. This
+ordering excludes hidden RGB from both resampling taps and figure detection;
+the global `sourceInRig` and legacy checks retain their existing RGB semantics.
+The figure domain is the union of rendered
+alpha above zero and the painting's existing `figureSilhouette`: border-median
+background difference, morphological opening and hole filling. This includes
+missing output over source figure and extra rendered support. It is not an
+independent segmentation oracle for arbitrary backgrounds.
+
+`SETUP_MATCHES_PAINTING` reports each region's box, pixel count and limit.
+Diagnostic slot rows partition that count and report their failing-pixel box.
+The slot is the **last actual textured drawing with sampled alpha above zero**
+at that pixel, measured by rig-c's rasterizer, or explicit `(uncovered)`.
+For translucent stacks this names the top contributor, not the exclusive
+material owner or the cause of the difference. Overlapping region declarations
+are measured independently. Clipped drawings whose ownership cannot be observed
+are refused rather than attributed by a part's bounding box.
+
+Invalid limits, repeated names, unknown fields and out-of-stage boxes use the existing `REQUIREMENTS_FIELD` refusal; no value is guessed.
+
+This optional declaration is independent of motion requirements and
+`fixed_skeleton`; it does not replace their schemas or validation. The named
+refusals are in the check/build rule table and the observation in the line table.
+
 ## 8. What one character costs
 
 | step | reference-sample | reference-demo | source |

package/docs/STABILITY.md

@@ -54,7 +54,7 @@ defaults are the help's too, and none is guessed from the art.
 | `inputs` | `--source`, `--config`, `--out` |
 | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
 | `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) |
+| `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`, `--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) |
@@ -501,3 +501,27 @@ no role or depth and changes no emitted file bytes.
 The unit-depth precedence and its primary-surface sampling are documented in
 [AUTHORING](AUTHORING.md#unit-depth-precedence).
 The separate ordering scalar is unchanged. No-image outputs retain legacy bytes.
+
+### Declared setup-painting regions
+
+The optional `setup_painting` key in `spine-parts-requirements/1` adds a
+`SETUP_MATCHES_PAINTING` observation only 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. Existing files without
+the key retain their output bytes and renderer calls. Other requirement fields
+remain independent. The [authoring contract](AUTHORING.md#setup-against-the-painting)
+defines white compositing, the figure domain, strict RGB comparison, top
+contributor attribution and named measurement refusals. The check observes the
+actual renderer setup at scale 1; it neither fits the art nor duplicates core
+validation. Only this declared check composites source RGBA over white at its
+original resolution **before** existing Lanczos3 stage resampling. Setup RGBA
+is composited on the native stage grid. Source readers preserve alpha; the
+global RGB-only source helper and checks without this declaration are unchanged.
+
+The optional `cut_material` block in `--requirements` declares a part, joint,
+independent stage-pixel centre, inward axis, reach and continuous bend interval.
+`assemble --requirements` and `build --requirements` write source-edge evidence
+only for that explicit block; `check --requirements` refuses unavailable or
+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).

package/package.json

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

package/src/assemble.ts

@@ -1,3 +1,5 @@
+import { edgeLength } from './length.ts';
+import { materialSource, type MaterialSource, materialRows, polygonMaterialEdges, type MaterialRow, type MaterialEdge, type PlacedArt } from './cutmaterial.ts';
 import { unionTakenSources } from './takesource.ts';
 import { authoredUnitDepths, type AuthoredUnitDepth } from './authoredunit.ts';
 import { paintingExtensionMasks, paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
@@ -3934,10 +3936,10 @@ function cutLimbs(
   readHidden: (layer: string, by: string) => void = () => undefined,
   tips?: Record<string, [number, number]>,
   sourceGroups: ReadonlyMap<string, string> = new Map(),
-): { parts: LimbPart[]; pieces: Built[]; counts: LimbCount[]; capFrom: Array<CapFrom | null> } {
+): { parts: LimbPart[]; pieces: Built[]; counts: LimbCount[]; capFrom: Array<CapFrom | null>; material: MaterialRow[]; sources: MaterialSource[] } {
   const logical = (source: string): string => sourceGroups.get(source) ?? source;
   const names = Object.keys(limbs);
-  if (names.length === 0) return { parts: [], pieces: [], counts: [], capFrom: [] };
+  if (names.length === 0) return { parts: [], pieces: [], counts: [], capFrom: [], material: [], sources: [] };
   const problems: Problem[] = [];
   const places = bonePlaces(bones, tips);
   const parts: LimbPart[] = [];
@@ -4413,7 +4415,30 @@ function cutLimbs(
     });
   }
   refuseIfAny(problems);
-  return { parts, pieces: pieces as Built[], counts, capFrom };
+  const material: MaterialRow[] = [];
+  const sourceReadings: MaterialSource[] = [];
+  for (const l of names) limbs[l].segments.forEach((sg, k) => {
+    if (k === 0) return;
+    const line = (lines.get(l) as Array<JointLine | null>)[k];
+    if (line === null) return;
+    const lo = parts.findIndex(p => p.part === sg.part);
+    const source = [...new Set([limbs[l].segments[k - 1].from, sg.from])].flatMap(name => {
+      const b = builtOf(name);
+      if (b === null) return [];
+      // Match segmentation and cap source ownership, after crossing/hand reassignment.
+      // Evidence must never borrow another limb's island or mutate its source raster.
+      const image = { ...b.r, data: b.r.data.slice() };
+      const owned = owners.get(name), li = names.indexOf(l);
+      for (let p = 0; p < W * H; p++) if (owned?.[p] !== li) image.data.fill(0, p * 4, p * 4 + 4);
+      return [{ x: 0, y: 0, image }];
+    });
+    const own = [lo, ...(sg.hybrid === undefined ? [] : [parts.findIndex(p => p.part === sg.hybrid?.part)])].filter(i => i >= 0).map(i => ({ x: 0, y: 0, image: (pieces[i] as Built).r }));
+    const t: [number, number] = [-line.axis[1], line.axis[0]], r = edgeLength(W, H);
+    const edge: MaterialEdge = { a: [line.at[0] - r * t[0], line.at[1] - r * t[1]], b: [line.at[0] + r * t[0], line.at[1] + r * t[1]], inward: line.axis };
+    sourceReadings.push(materialSource(sg.part, [...new Set([limbs[l].segments[k - 1].from, sg.from])], [edge], source));
+    material.push(...materialRows(sg.part, undefined, [edge], source, own).map(row => ({ ...row, joint: String(sg.joint) })));
+  });
+  return { parts, pieces: pieces as Built[], counts, capFrom, material, sources: sourceReadings };
 }
 
 // ---------------------------------------------------------------------------
@@ -4470,6 +4495,9 @@ export interface AssembleResult {
   figures: RecompositeFigures;
   /** What each `assemble.cuts` entry took, counted when it was made (`cutLines`); empty without cuts. */
   cuts: CutCount[];
+  /** Console-only source-edge support (#888); never serialized into parts.json. */
+  cutMaterial: MaterialRow[];
+  materialSources: MaterialSource[];
   /** 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. */
@@ -5016,11 +5044,14 @@ export function assemble(input: AssembleInput): AssembleResult {
   const mergedIn = (b: Built, region: Mask): number => count(b.trace.lastSel ?? null, region) + count(b.trace.lastRing ?? null, region);
   const pieces: Array<Built | null> = cuts.map(() => null);
   const cutCounts: CutCount[] = [];
+  const cutMaterial: MaterialRow[] = [];
+  const materialSources: MaterialSource[] = [];
   plan.forEach(([name], pi) => {
     const mine = cuts.map((q, i) => i).filter((i) => cuts[i].from === name);
     const b = built[pi];
     if (mine.length === 0 || b === null) return;
     const before = opaqueOf(b.r);
+    const sourceBeforeCuts: PlacedArt = { x: 0, y: 0, image: { ...b.r, data: b.r.data.slice() } };
     const rest = newMask(W, H);
     rest.data.fill(1);
     // The base's own pixels: `rest`, and every cut's band, which it keeps as well as the piece.
@@ -5120,6 +5151,8 @@ export function assemble(input: AssembleInput): AssembleResult {
         if (cuts[i].under_fill === 'colour') c.underFill = 'colour';
       }
       cutCounts.push(c);
+      const piece = pieces[i];
+      if (piece !== null) { materialSources.push(materialSource(cuts[i].into, [b.key], polygonMaterialEdges(cuts[i].polygon), [sourceBeforeCuts])); cutMaterial.push(...materialRows(cuts[i].into, undefined, polygonMaterialEdges(cuts[i].polygon), [sourceBeforeCuts], [{ x: 0, y: 0, image: piece.r }])); }
     });
   });
   // Parent partition counts and under use the removed parent art above. Only
@@ -5131,6 +5164,10 @@ export function assemble(input: AssembleInput): AssembleResult {
     if (opaqueOf(r) === 0) empty.push({ code: 'ASSEMBLE_CUT_PIXELS', object: `config.assemble.cuts[${i}] (part "${cuts[i].into}")`, detail: `takes 0 opaque pixels from selected ${source.key}; draw its polygon over that layer's art` });
     const writers = (source.writers as Int32Array).slice();
     pieces[i] = { ...source, r, writers, region: m, merged: mergedIn(source, m) };
+    for (let j = materialSources.length - 1; j >= 0; j--) if (materialSources[j].part === cuts[i].into) materialSources.splice(j, 1);
+    materialSources.push(materialSource(cuts[i].into, [source.key], polygonMaterialEdges(cuts[i].polygon), [{ x: 0, y: 0, image: source.r }]));
+    for (let j = cutMaterial.length - 1; j >= 0; j--) if (cutMaterial[j].part === cuts[i].into) cutMaterial.splice(j, 1);
+    cutMaterial.push(...materialRows(cuts[i].into, undefined, polygonMaterialEdges(cuts[i].polygon), [{ x: 0, y: 0, image: source.r }], [{ x: 0, y: 0, image: r }]));
   });
   refuseIfAny(empty);
   // In cut order, as the config lists them.
@@ -5638,6 +5675,8 @@ export function assemble(input: AssembleInput): AssembleResult {
     figure: inside === null ? null : figureImage(inside, W, H),
     figures,
     cuts: cutCounts,
+    cutMaterial: [...cutMaterial, ...lim.material],
+    materialSources: [...materialSources, ...lim.sources],
     limbs: lim.counts,
     uncovered,
     holeKinds: kinds,

package/src/build.ts

@@ -1,3 +1,6 @@
+import { SETUP_PAINTING_LINE, setupPaintingLines } from './setuppainting.ts';
+import { writeMaterialSources } from './cutmaterialio.ts';
+import { CUT_MATERIAL_LINE, CUT_MATERIAL_SOURCES, materialLines } from './cutmaterial.ts';
 import { ART_JOINT_LINE, artJointLines } from './artjoints.ts';
 import { applyTakenLayers } from './takelayers.ts';
 import { ownershipLines, provenanceLines } from './provenance.ts';
@@ -154,6 +157,8 @@ export interface AlternateCliInput {
 }
 
 export interface AssembleStageInput {
+  /** Write source-edge evidence only when cut_material is explicitly declared. */
+  requirements?: string;
   source: string;
   full: string;
   /** The head run, or null for one run that holds the face (issue #359). */
@@ -318,6 +323,7 @@ export function frontOrdered<T extends { record: { name: string } }>(items: read
 
 /** Read, assemble, and write only after every refusal has had its chance. Throws a PartsError on a refusal, having written nothing. */
 export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs, log: Log): AssembleResult {
+  const materialAsked = input.requirements === undefined ? false : readRequirements(input.requirements).cut_material !== undefined;
   // 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');
@@ -772,6 +778,8 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   for (const b of altBuilt) {
     for (const { name, image } of b.images) writePng(join(outs.partsDir, `${name}.png`), image);
   }
+  if (materialAsked) writeMaterialSources(outs.partsJson, outs.partsDir, result.parts, result.materialSources);
+  else rmSync(join(dirname(outs.partsJson), CUT_MATERIAL_SOURCES), { force: true });
   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.
@@ -799,6 +807,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   for (const l of authorPartLines(result.parts.parts)) log(l);
   // One line per plan part an assemble.cuts entry cut, before the fringe lines: the cut is made first. None without cuts.
   for (const l of cutLines(result.cuts)) log(l);
+  if (materialAsked) for (const line of materialLines({ status: 'SKIP', rows: result.cutMaterial, reason: 'assemble source readings only; check --requirements judges declared joint material' })) log(`  ${line}`);
   // Issue #349: one line per part a limb took, and one per joint with its cap's pixels. None without limbs.
   for (const l of limbLines(result.limbs)) log(l);
   for (const l of fringeLines(result.parts.parts)) log(l);
@@ -1942,8 +1951,12 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   if (vsSource !== undefined) log(`  ${judgementLine(SOURCE_LINE, vsSource)}`);
   const windBand = fig[WIND_BAND_LINE];
   if (windBand !== undefined) for (const l of windBandLines(windBand)) log(`  ${l}`);
+  const cutMaterial = fig[CUT_MATERIAL_LINE];
+  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 setupPainting = fig[SETUP_PAINTING_LINE];
+  if (setupPainting !== undefined) for (const line of setupPaintingLines(setupPainting)) log(`  ${line}`);
   if (r.requirements !== null) {
     for (const [name, line] of Object.entries(r.requirements.lines)) log(`  ${requirementText(name, line)}`);
     log(`  ${summaryText(r.requirements.summary)}`);
@@ -2388,6 +2401,8 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   const out = input.out;
   mkdirSync(out, { recursive: true });
   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 });
   // 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.
@@ -2413,7 +2428,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
     // And the steady-wind band spec (issue #590), as check reads it.
     if (input.windBand !== undefined) readWindBand(input.windBand);
     stages.assemble(
-      { source: input.source, full: input.full, head: input.head, config: input.config, seam: input.seam, project: input.project, ...(input.alts === undefined ? {} : { alts: input.alts }) },
+      { source: input.source, full: input.full, head: input.head, config: input.config, seam: input.seam, project: input.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'),
     );

package/src/check.ts

@@ -1,3 +1,6 @@
+import { SETUP_PAINTING_LINE, setupPaintingBounds, setupPaintingLine, type SetupPainting, type SetupPaintingLine } from './setuppainting.ts';
+import { readMaterialSources } from './cutmaterialio.ts';
+import { CUT_MATERIAL_LINE, checkJointMaterial, type MaterialLine } from './cutmaterial.ts';
 import { ART_JOINT_LINE, artJointLine, type ArtJointLine } from './artjoints.ts';
 import { baseAnchorMoves, type AnchorRegion } from './baseanchor.ts';
 /**
@@ -85,7 +88,7 @@ import { createRequire } from 'node:module';
 import type { Viewport as RootCoverageViewport } from '@rig-c/core/render-shared';
 import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig } from './assemble.ts';
+import { measureRecomposite, type RecompositeFigures, recompositeRecord, scenePhrase, sourceInRig, figureSilhouette } from './assemble.ts';
 import { type BoneTransform, computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toBoneLocal } from './coords.ts';
 import { capBox, inDisc } from './limbs.ts';
 import { motionSeamProblems } from './motionseams.ts';
@@ -1931,6 +1934,35 @@ function officialRenderer(): OfficialRenderer {
   return require('@rig-c/core/render-shared') as OfficialRenderer;
 }
 
+/** Observe the actual setup on the declared stage grid. No frame-zero motion,
+ * fitted alignment, flat recomposite or duplicate core validation. */
+export function measureSetupPainting(build: string, stage: StageBox, source: Raster, declared: SetupPainting, problems: Problem[]): SetupPaintingLine {
+  const api = officialRenderer();
+  const skeleton = join(build, 'skeleton.json'), atlas = join(build, 'skeleton.atlas');
+  const candidate = api.loadCandidate({ skeletonText: readFileSync(skeleton, 'utf8'), atlasText: readFileSync(atlas, 'utf8'), atlasDir: build, label: 'setup versus painting' }, { skeleton, atlas }, undefined);
+  const pose = api.throughPoser(candidate.choice, p => api.sampleSetupPose(p, { geometry: true, texture: true })).value[0];
+  if (pose === undefined || pose.pieces.some(p => 'source' in p)) {
+    refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_MEASURED', object: SETUP_PAINTING_LINE, detail: 'actual textured setup pieces are unavailable or include clipping; no guessed ownership is substituted' }]);
+  }
+  const W = stage.width, H = stage.height;
+  if (!Number.isSafeInteger(W) || !Number.isSafeInteger(H) || W <= 0 || H <= 0) refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_MEASURED', object: SETUP_PAINTING_LINE, detail: 'requires positive integer stage width/height for a native source-grid observation' }]);
+  const vp = { minX: stage.x, minY: stage.y, maxX: stage.x + W, maxY: stage.y + H, scale: 1, width: W, height: H };
+  const project = api.projector(vp), owners = new Int32Array(W * H).fill(-1);
+  pose.pieces.forEach((piece, i) => api.rasterisePiece(api.pageFor(candidate.pages, piece), piece, project, vp, (x, y, _r, _g, _b, a) => { if (a > 0) owners[y * W + x] = i; }));
+  // sourceInRig intentionally reads opaque RGB, discarding source alpha before
+  // resizing. This optional comparison declares source-over white instead:
+  // flatten at ORIGINAL source resolution first, so hidden RGB cannot reach
+  // Lanczos taps or the figure silhouette. Do not change the legacy helper.
+  const whiteSource = newRaster(source.width, source.height);
+  for (let p = 0; p < source.width * source.height; p++) {
+    for (let c = 0; c < 3; c++) whiteSource.data[p * 4 + c] = Math.round(source.data[p * 4 + c] * source.data[p * 4 + 3] / 255 + 255 * (1 - source.data[p * 4 + 3] / 255));
+    whiteSource.data[p * 4 + 3] = 255;
+  }
+  const painting = sourceInRig(whiteSource, W, H);
+  const setup = api.renderFrame(pose, candidate.pages, vp, [0, 0, 0, 0]);
+  return setupPaintingLine(declared, painting, { width: W, height: H, data: new Uint8ClampedArray(setup.data) }, figureSilhouette(painting).data, owners, pose.pieces.map(p => p.slot), problems);
+}
+
 /** One decoder/poser lifetime per state; retain only finite bounds and identities, never atlas pages or rasters. */
 export function seamStateBounds(build: string, state: string): SeamStateBounds {
   try {
@@ -2697,6 +2729,9 @@ export interface CheckFigures {
   requirements?: RequirementsBlock;
   /** Issue #880: only when requirements declares fixed_skeleton. */
   [ART_JOINT_LINE]?: ArtJointLine;
+  /** Only when setup_painting is explicitly declared. */
+  [SETUP_PAINTING_LINE]?: SetupPaintingLine;
+  [CUT_MATERIAL_LINE]?: MaterialLine;
   PASS: boolean;
 }
 
@@ -2943,7 +2978,7 @@ export function barsNotMet(fig: Readonly<Record<string, unknown>>): string[] {
     isRecord(fig.sets) &&
     Object.values(fig.sets).some((s) => isRecord(s) && typeof s.seam_mean === 'number' && typeof s.seam_px_over_40 === 'number' && seamFails(s.seam_mean, s.seam_px_over_40, typeof s.seam_frame_scale === 'number' ? s.seam_frame_scale : 1));
   if ((typeof fig.seam_mean === 'number' && typeof fig.seam_px_over_40 === 'number' && seamFails(fig.seam_mean, fig.seam_px_over_40, scale)) || setFailed) out.push('seam');
-  for (const n of [...JUDGEMENT_LINES, FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, ART_JOINT_LINE]) {
+  for (const n of [...JUDGEMENT_LINES, FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, ART_JOINT_LINE, CUT_MATERIAL_LINE]) {
     const l = fig[n];
     if (typeof l === 'object' && l !== null && (l as { status?: unknown }).status === 'FAIL') out.push(n);
   }
@@ -3052,7 +3087,7 @@ export function checkStatuses(fig: CheckFigures): Record<string, CheckStatus> {
   const bar = (name: string, measured: boolean): CheckStatus => (!measured ? 'SKIP' : notMet.includes(name) ? 'FAIL' : 'PASS');
   const out: Record<string, CheckStatus> = { gate: bar('gate', true), loop: bar('loop', fig.loop_max_diff !== null), seam: bar('seam', fig.seam_mean !== null) };
   for (const n of JUDGEMENT_LINES) out[n] = fig[n].status;
-  for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, SOURCE_LINE, WIND_BAND_LINE, ART_JOINT_LINE] as const) {
+  for (const n of [FOLD_LINE, LEVEL_LINE, STRESS_LINE, LIMB_LINE, SWEEP_LINE, MOTION_SEAM_LINE, CLOTH_LINE, ...REPORTED_LINES, SOURCE_LINE, WIND_BAND_LINE, ART_JOINT_LINE, CUT_MATERIAL_LINE, SETUP_PAINTING_LINE] as const) {
     const l = fig[n];
     if (l !== undefined) out[n] = l.status;
   }
@@ -5862,6 +5897,10 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     const file = reqFile as RequirementsFile;
     const ready = inp;
     take(() => resolveRequirements(file, ready.rig, ready.motion, ready.rootBone));
+    if (file.setup_painting !== undefined) take(() => {
+      refuseIfAny(setupPaintingBounds(file.setup_painting as SetupPainting, ready.stage.width, ready.stage.height));
+      if (ready.source === null) refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_SOURCE', object: 'requirements.setup_painting', detail: 'requires --source naming the painting; the assembled composite is not an independent source painting' }]);
+    });
     take(() => refuseIfAny(exceptionProblems(file, ready.parts, ready.noParts)));
     // A seam's pairs are read off parts.json's art (issue #111); both resolvers' problems are named in one refusal.
     if (file.requirements.some((r) => r.kind === 'seam')) {
@@ -5879,6 +5918,11 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   if (env !== null && !(isRecord(inp.motion.animations) && Object.keys(inp.motion.animations).length > 0)) {
     throw environmentRefused(env.path, `${inp.motionPath} holds no animation, so check renders no frame a schedule could pose — the setup-pose stills take none; rigc render reads a schedule only over an animation's frames`);
   }
+  // Read source support before rendering; no output/sidecar for undeclared builds.
+  if (reqFile?.cut_material !== undefined && (set !== undefined || allSets)) refuseIfAny([{code: 'CHECK_CUT_MATERIAL_MEASURED', object: 'cut_material', detail: 'source evidence binds base assembly only; run check on its base parts without --set/--all-sets; alternate-set coverage requires its own original source instrument'}]);
+  const cutMaterialProblems: Problem[] = [];
+  const cutMaterial = reqFile?.cut_material === undefined ? null : checkJointMaterial(reqFile.cut_material, inp.parts, name => readPng(join(inp.partsDir, `${name}.png`)), cutMaterialProblems, inp.parts === null ? undefined : readMaterialSources(dirname(inp.partsDir), inp.parts));
+  // A measured material failure is a check bar; unavailable data is a refusal.
   const rigcEntry = readRigcEntry(requireRigcVersion(rigc));
   /**
    * Issue #538: a render whose frames a bar or a warning reads, with the physics on — posed under the schedule when
@@ -6407,6 +6451,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const setHints = new Map<string, string>();
   const fixedSkeleton = reqFile?.fixed_skeleton;
   let artJoints: ArtJointLine | null = null;
+  let setupPainting: SetupPaintingLine | null = null;
   if (inp.parts !== null || inp.source !== null || fixedSkeleton !== undefined) {
     try {
       mkdirSync(stillDir, { recursive: true });
@@ -6434,6 +6479,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
       const sr = rigc(['render', '--candidate', join(stillDir, 'build'), '--animation', 'still', '--fps', String(STILL_FPS), '--max', String(maxSide), ...(fixedSkeleton === undefined ? [] : ['--geometry']), '--out', join(stillDir, 'render')]);
       if (sr.status !== 0) refuseIfAny(rigcFailed('render (the setup-pose still)', sr, sr.out.split('\n').filter((l) => l.includes('FAIL'))));
       const stillSet = readFrameSet(join(stillDir, 'render'));
+      if (reqFile?.setup_painting !== undefined && inp.source !== null) setupPainting = measureSetupPainting(join(stillDir, 'build'), inp.stage, inp.source.painting, reqFile.setup_painting, problems);
       if (fixedSkeleton !== undefined) {
         const geometryPath = join(stillSet.dir, GEOMETRY_FILE);
         const geometry = readGeometry(geometryPath, stillSet.written);
@@ -6636,6 +6682,8 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     ...(Object.keys(setsFigures).length === 0 ? {} : { sets: setsFigures }),
     ...(config === undefined ? {} : { config }),
     ...(artJoints === null ? {} : { [ART_JOINT_LINE]: artJoints }),
+    ...(setupPainting === null ? {} : { [SETUP_PAINTING_LINE]: setupPainting }),
+    ...(cutMaterial === null ? {} : { [CUT_MATERIAL_LINE]: cutMaterial }),
     ...(reqBlock === null ? {} : { requirements: reqBlock }),
     PASS: false,
   };
@@ -6679,7 +6727,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const rank = (q: Problem): number => JUDGEMENT_LINES.findIndex((n) => q.code === `CHECK_${n}`);
   problems.sort((a, b) => rank(a) - rank(b));
   problems.unshift(...barProblems);
-  problems.push(...foldProblems, ...levelProblems, ...stressProblems, ...limbProblems, ...sweepProblems, ...motionRootProblems, ...reqProblems);
+  problems.push(...cutMaterialProblems, ...foldProblems, ...levelProblems, ...stressProblems, ...limbProblems, ...sweepProblems, ...motionRootProblems, ...reqProblems);
   figures.PASS = problems.length === 0;
   const publishCheck = (): void => write('check.json', `${JSON.stringify(figures, null, 1)}\n`);
   if (motionSeam.worlds === undefined) publishCheck();
@@ -6699,7 +6747,9 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   }
   // Issues #320, #333: the fold bar is counted where it is written — on every rig whose motion holds an animation.
   if (folds !== null) tally(FOLD_LINE, null);
+  if (cutMaterial !== null) tally(CUT_MATERIAL_LINE, null);
   if (artJoints !== null) tally(ART_JOINT_LINE, artJoints.status === 'SKIP' ? (artJoints.reason ?? 'no declared limit') : null);
+  if (setupPainting !== null) tally(SETUP_PAINTING_LINE, setupPainting.status === 'SKIP' ? (setupPainting.reason ?? 'no declared limit') : null);
   // Issue #348: the level bar where it is written; a line whose every foot no frame posed says SKIP and is not measured.
   if (level !== null) tally(LEVEL_LINE, level.status === 'SKIP' ? (level.reason ?? '') : null);
   // Issue #347: the stress bar is counted where it is written — on every rig with a handwear part and an idle.

package/src/cutmaterial.ts

@@ -0,0 +1,285 @@
+import { edgeLength } from './length.ts';
+import { createHash } from 'node:crypto';
+/** Source support at declared joints (#888). Geometry is in stage pixels, y down.
+ * No scene, motion, material or threshold is inferred. This measures pixel-cell
+ * support on normal rays, not rendered seam visibility or a continuous surface.
+ */
+import { type Raster } from './raster/types.ts';
+import { OPAQUE_ALPHA_ABOVE } from './layers.ts';
+import { refuseIfAny, type Problem } from './errors.ts';
+import type { PartsFile } from './parts.ts';
+export type Point = [number, number];
+export interface JointMaterial {
+  part: string;
+  joint: string;
+  at: Point;
+  /** Points into the piece; need not be unit length. */
+  axis: Point;
+  reach_px: number;
+  /** Continuous interval in stage coordinates (positive clockwise). */
+  bend_degrees: Point;
+}
+export interface MaterialEdge { a: Point; b: Point; inward: Point; opaque_t?: Array<[number, number]>; opaque_length_px?: number; opaque_intervals?: number }
+export interface MaterialSource { part: string; from: string[]; source_sha256: string[]; edges: MaterialEdge[] }
+export const CUT_MATERIAL_SOURCES = 'cut_material_sources.json';
+export const CUT_MATERIAL_SPEC = 'rig-parts-cut-material-sources/1';
+export interface PlacedArt { x: number; y: number; image: Raster }
+export interface MaterialRow {
+  part: string; joint: string; edge: [Point, Point]; edge_length_px: number; within_reach_px: number;
+  found_px: number; required_px: number; rays: number;
+  status: 'PASS' | 'FAIL' | 'SKIP'; reason?: string;
+}
+export const CUT_MATERIAL_LINE = 'CUT_JOINT_MATERIAL';
+export interface MaterialLine { status: 'PASS' | 'FAIL' | 'SKIP'; rows: MaterialRow[]; reason?: string }
+const obj = (x: unknown): x is Record<string, unknown> => typeof x === 'object' && x !== null && !Array.isArray(x);
+const num = (x: unknown): x is number => typeof x === 'number' && Number.isFinite(x);
+const pair = (x: unknown): x is Point => Array.isArray(x) && x.length === 2 && x.every(num);
+export function jointMaterialProblems(raw: unknown, at: string): Problem[] {
+  const out: Problem[] = [];
+  const fail = (object: string, detail: string): void => { out.push({code:'REQUIREMENTS_FIELD', object, detail}); };
+  if (!Array.isArray(raw) || raw.length === 0) return [{code:'REQUIREMENTS_FIELD',object:at,detail:'requires a nonempty list of {part, joint, at, axis, reach_px, bend_degrees}; omit cut_material when undeclared'}];
+  const seen = new Set<string>();
+  raw.forEach((r, i) => {
+    const where = `${at}[${i}]`;
+    if (!obj(r)) { fail(where,'requires an object'); return; }
+    for (const k of Object.keys(r)) if (!['part','joint','at','axis','reach_px','bend_degrees'].includes(k)) fail(`${where}.${k}`,'is unknown; no guessed fields are read');
+    for (const k of ['part','joint']) if (typeof r[k] !== 'string' || r[k].trim() === '') fail(`${where}.${k}`,'requires a nonempty name');
+    for (const k of ['at','axis','bend_degrees']) if (!pair(r[k])) fail(`${where}.${k}`,'requires two finite numbers');
+    if (pair(r.axis) && (edgeLength(...r.axis) === 0 || !Number.isFinite(edgeLength(...r.axis)))) fail(`${where}.axis`,'requires a nonzero inward direction');
+    if (!num(r.reach_px) || r.reach_px <= 0) fail(`${where}.reach_px`,'requires a finite positive stage-pixel reach');
+    if (pair(r.bend_degrees) && (r.bend_degrees[0] > r.bend_degrees[1] || r.bend_degrees[0] < -180 || r.bend_degrees[1] > 180)) fail(`${where}.bend_degrees`,'requires an ordered interval inside [-180,180], in stage coordinates');
+    const key = JSON.stringify([r.part,r.joint]);
+    if (seen.has(key)) fail(where,'declares this part and joint twice');
+    seen.add(key);
+  });
+  return out;
+}
+const point = (a: Point, b: Point, t: number): Point => [a[0]+(b[0]-a[0])*t,a[1]+(b[1]-a[1])*t];
+const unit = (p: Point): Point => { const d = edgeLength(...p); return [p[0]/d,p[1]/d]; };
+const dot = (a: Point, b: Point): number => a[0]*b[0]+a[1]*b[1];
+export function opaqueAt(arts: readonly PlacedArt[], x: number, y: number): boolean {
+  return arts.some(a => { const ix = Math.floor(x-a.x), iy = Math.floor(y-a.y); return ix >= 0 && iy >= 0 && ix < a.image.width && iy < a.image.height && a.image.data[(iy*a.image.width+ix)*4+3] > OPAQUE_ALPHA_ABOVE; });
+}
+/** Exact parameter breaks at pixel-cell boundaries, no spatial step or epsilon. */
+function breaks(a: Point, b: Point, arts: readonly PlacedArt[]): number[] {
+  const ts = new Set([0,1]);
+  for (const r of arts) for (const k of [0,1] as const) {
+    const lo = k === 0 ? r.x : r.y, size = k === 0 ? r.image.width : r.image.height;
+    if (a[k] === b[k]) continue;
+    const start = Math.max(lo,Math.ceil(Math.min(a[k],b[k]))), end = Math.min(lo+size,Math.floor(Math.max(a[k],b[k])));
+    for (let v = start; v <= end; v++) { const t = (v-a[k])/(b[k]-a[k]); if (t > 0 && t < 1) ts.add(t); }
+  }
+  return [...ts].sort((x,y)=>x-y);
+}
+/** On a source pixel boundary the art must exist on both sides of the cut. */
+function across(arts: readonly PlacedArt[], p: Point, n: Point): boolean {
+  const cell = (direction: number, k: 0|1): number => Number.isInteger(p[k]) && direction < 0 ? p[k]-0.5 : p[k];
+  return opaqueAt(arts,cell(n[0],0),cell(n[1],1)) && opaqueAt(arts,cell(-n[0],0),cell(-n[1],1));
+}
+export function polygonMaterialEdges(poly: readonly Point[]): MaterialEdge[] {
+  const area = poly.reduce((s,a,i)=>{ const b=poly[(i+1)%poly.length]; return s+a[0]*b[1]-a[1]*b[0]; },0);
+  return poly.flatMap((a,i)=>{const b=poly[(i+1)%poly.length],d=edgeLength(b[0]-a[0],b[1]-a[1]);return d===0?[]:[{a,b,inward:area>0?[-(b[1]-a[1])/d,(b[0]-a[0])/d] as Point:[(b[1]-a[1])/d,-(b[0]-a[0])/d] as Point}];});
+}
+/** Contiguous opaque cells from the joint plane outward. A hole ends support. */
+function support(arts: readonly PlacedArt[], start: Point, n: Point): number {
+  const limit = arts.reduce((m,a)=>Math.max(m,edgeLength(a.x-start[0],a.y-start[1])+a.image.width+a.image.height),0);
+  if (limit === 0) return 0;
+  const end: Point = [start[0]-n[0]*limit,start[1]-n[1]*limit], ts=breaks(start,end,arts);
+  for(let i=0;i+1<ts.length;i++){ const p=point(start,end,(ts[i]+ts[i+1])/2);if(!opaqueAt(arts,...p))return ts[i]*limit; }
+  return limit;
+}
+/** max outward displacement of t*(-ny,nx), retained as a scalar instrument. */
+export function bendDepth(t: number, degrees: Point): number {
+  const angles = [...degrees];
+  for (const a of [-90,90]) if (a >= degrees[0] && a <= degrees[1]) angles.push(a);
+  return Math.max(0,...angles.map(a=>t*Math.sin(a*Math.PI/180)));
+}
+/** Exact quadrant values avoid inventing support for sin(pi)'s roundoff. */
+function trig(angle: number): [number, number] {
+  const q = angle / (Math.PI / 2);
+  if (Number.isInteger(q)) {
+    const k = ((q % 4) + 4) % 4;
+    return [[1,0],[0,1],[-1,0],[0,-1]][k] as [number, number];
+  }
+  return [Math.cos(angle), Math.sin(angle)];
+}
+/** Clip a convex polygon by a closed half-plane. No geometric tolerance. */
+function clip(poly:Point[],inside:(p:Point)=>number):Point[]{
+  const out:Point[]=[];
+  for(let i=0;i<poly.length;i++){
+    const a=poly[i],b=poly[(i+1)%poly.length],fa=inside(a),fb=inside(b);
+    if(fa>=0)out.push(a);
+    if((fa<0&&fb>0)||(fa>0&&fb<0))out.push(point(a,b,fa/(fa-fb)));
+  }
+  return out;
+}
+function polygonArea(poly:Point[]):number{return Math.abs(poly.reduce((s,a,i)=>{const b=poly[(i+1)%poly.length];return s+a[0]*b[1]-a[1]*b[0];},0))/2;}
+function convexHull(points:Point[]):Point[]{
+  const sorted=[...points].sort((a,b)=>a[0]-b[0]||a[1]-b[1]);
+  const turn=(a:Point,b:Point,c:Point):number=>(b[0]-a[0])*(c[1]-a[1])-(b[1]-a[1])*(c[0]-a[0]);
+  const half=(ps:Point[]):Point[]=>{const out:Point[]=[];for(const p of ps){while(out.length>=2&&turn(out[out.length-2],out[out.length-1],p)<=0)out.pop();out.push(p);}return out;};
+  return [...half(sorted).slice(0,-1),...half(sorted.reverse()).slice(0,-1)];
+}
+/** Empty exterior is four rectangles, so a distant declared joint never
+ * turns empty space into an unbounded pixel walk. Interior cells remain exact. */
+function emptyRectangles(at:Point,radius:number,arts:readonly PlacedArt[]):Array<[number,number,number,number]>{
+  const x0=Math.floor(at[0]-radius),x1=Math.ceil(at[0]+radius),y0=Math.floor(at[1]-radius),y1=Math.ceil(at[1]+radius);
+  if(arts.length===0)return [[x0,y0,x1,y1]];
+  const left=Math.max(x0,Math.min(...arts.map(a=>a.x))),right=Math.min(x1,Math.max(...arts.map(a=>a.x+a.image.width))),top=Math.max(y0,Math.min(...arts.map(a=>a.y))),bottom=Math.min(y1,Math.max(...arts.map(a=>a.y+a.image.height)));
+  if(left>=right||top>=bottom)return [[x0,y0,x1,y1]];
+  const out:Array<[number,number,number,number]>=[];
+  for(const rect of [[x0,y0,x1,top],[x0,bottom,x1,y1],[x0,top,left,bottom],[right,top,x1,bottom]] as Array<[number,number,number,number]>)if(rect[0]<rect[2]&&rect[1]<rect[3])out.push(rect);
+  for(let y=top;y<bottom;y++)for(let x=left;x<right;x++)if(!opaqueAt(arts,x+0.5,y+0.5))out.push([x,y,x+1,y+1]);
+  return out;
+}
+/** The inverse rotation of a full point, with no joint-plane projection. */
+function rotated(p:Point,angle:number):Point{const [c,s]=trig(angle);return [p[0]*c+p[1]*s,p[1]*c-p[0]*s];}
+const cross=(a:Point,b:Point):number=>a[0]*b[1]-a[1]*b[0];
+/**
+ * Segment-vs-convex-polygon intersection throughout an angle interval. Changes
+ * of incidence occur only when an endpoint crosses a polygon edge, the source
+ * line crosses a vertex, or an edge becomes parallel. All are sinusoid roots.
+ * One angle inside each resulting interval has the same intersection topology.
+ */
+function sweptSegmentWitness(a:Point,b:Point,poly:Point[],degrees:Point):Point|null{
+  if(poly.length<3||polygonArea(poly)===0)return null;
+  const lo=degrees[0]*Math.PI/180,hi=degrees[1]*Math.PI/180,angles=new Set<number>([lo,hi]);
+  const add=(angle:number):void=>{if(angle>=lo&&angle<=hi)angles.add(angle);};
+  const roots=(A:number,B:number,C:number):void=>{
+    const radius=edgeLength(A,B);if(radius===0||Math.abs(C)>radius)return;
+    const phase=Math.atan2(B,A),offset=Math.acos(C/radius);
+    for(const k of [-1,0,1]){add(phase+offset+k*2*Math.PI);add(phase-offset+k*2*Math.PI);}
+  };
+  const delta:Point=[b[0]-a[0],b[1]-a[1]];
+  for(let i=0;i<poly.length;i++){
+    const p=poly[i],q=poly[(i+1)%poly.length],edge:Point=[q[0]-p[0],q[1]-p[1]],normal:Point=[-edge[1],edge[0]],C=dot(normal,p);
+    for(const endpoint of [a,b])roots(dot(normal,endpoint),normal[0]*endpoint[1]-normal[1]*endpoint[0],C);
+    roots(cross(delta,p),dot(delta,p),cross(delta,a));
+    roots(cross(delta,edge),dot(delta,edge),0);
+  }
+  const sorted=[...angles].sort((a,b)=>a-b),tests=[...sorted,...sorted.slice(1).map((v,i)=>(v+sorted[i])/2)];
+  for(const angle of tests){
+    const x=rotated(a,angle),y=rotated(b,angle);let low=0,high=1;
+    for(let i=0;i<poly.length;i++){
+      const p=poly[i],q=poly[(i+1)%poly.length],edge:Point=[q[0]-p[0],q[1]-p[1]],fa=cross(edge,[x[0]-p[0],x[1]-p[1]]),fb=cross(edge,[y[0]-p[0],y[1]-p[1]]);
+      if(fa<0&&fb<0){low=1;high=0;break;}
+      if(fa<0)low=Math.max(low,fa/(fa-fb));
+      if(fb<0)high=Math.min(high,fa/(fa-fb));
+    }
+    if(high<=low)continue;
+    const witness=point(x,y,(low+high)/2);
+    if(poly.every((p,i)=>{const q=poly[(i+1)%poly.length];return cross([q[0]-p[0],q[1]-p[1]],[witness[0]-p[0],witness[1]-p[1]])>0;}))return witness;
+  }
+  return null;
+}
+/** Entire actual edge segment, including normal offset from the joint. */
+function sweptHole(a:Point,b:Point,n:Point,joint:JointMaterial,piece:readonly PlacedArt[]):{found:number;required:number;at:Point}|null{
+  const A:Point=[a[0]-joint.at[0],a[1]-joint.at[1]],B:Point=[b[0]-joint.at[0],b[1]-joint.at[1]],offset=dot(n,A),radius=Math.max(edgeLength(...A),edgeLength(...B));
+  // A normal ray starts on the actual edge plane, not the joint plane.
+  const bound=radius+Math.abs(offset);
+  for(const [x,y,right,bottom] of emptyRectangles(joint.at,bound,piece)){
+    const cell:Point[]=[[x-joint.at[0],y-joint.at[1]],[right-joint.at[0],y-joint.at[1]],[right-joint.at[0],bottom-joint.at[1]],[x-joint.at[0],bottom-joint.at[1]]];
+    const outward=clip(cell,p=>offset-dot(n,p));if(polygonArea(outward)===0)continue;
+    const distance=radius+Math.max(...outward.map(p=>edgeLength(...p)));
+    const shadow=convexHull([...outward,...outward.map<Point>(p=>[p[0]-n[0]*distance,p[1]-n[1]*distance])]);
+    const q=sweptSegmentWitness(A,B,shadow,joint.bend_degrees);if(q===null)continue;
+    const required=offset-dot(n,q);if(required<=0)continue;
+    const at:Point=[q[0]+joint.at[0],q[1]+joint.at[1]],start:Point=[at[0]+n[0]*required,at[1]+n[1]*required],found=support(piece,start,n);
+    if(found<required)return {found,required,at};
+    refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object:'swept source interval',detail:'a strict transparent-cell witness disagrees with its normal support reading; no PASS is inferred'}]);
+  }
+  return null;
+}
+export function materialRows(part: string, joint: JointMaterial | undefined, edges: readonly MaterialEdge[], source: readonly PlacedArt[], piece: readonly PlacedArt[]): MaterialRow[] {
+  return edges.map(edge=>{
+    const n=unit(edge.inward), d:Point=[edge.b[0]-edge.a[0],edge.b[1]-edge.a[1]], length=edgeLength(...d);
+    let lo=0,hi=1;
+    if(joint!==undefined){
+      const q:Point=[edge.a[0]-joint.at[0],edge.a[1]-joint.at[1]], A=dot(d,d), B=2*dot(q,d), C=dot(q,q)-joint.reach_px**2, disc=B*B-4*A*C;
+      if(A===0||disc<0){lo=1;hi=0;}else{lo=Math.max(0,(-B-Math.sqrt(disc))/(2*A));hi=Math.min(1,(-B+Math.sqrt(disc))/(2*A));}
+    }
+    if(!Number.isFinite(lo)||!Number.isFinite(hi)||!Number.isFinite(length))refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object:`part "${part}"`,detail:'joint/edge/reach arithmetic is not finite; supply representable measured stage coordinates and reach'}]);
+    let crossed=0,found=Infinity,required=0,rays=0,fail=false,margin=Infinity;
+    const spans=edge.opaque_t ?? opaqueParameters(edge,source);
+    const intervals=spans.map(([a,b]):[Point,Point]=>[point(edge.a,edge.b,a),point(edge.a,edge.b,b)]);
+    for(const interval of intervals){
+      // Preserve the source pixel-cell partition; clipping changes its endpoints only.
+      const param=(p:Point):number=>Math.abs(d[0])>=Math.abs(d[1])?(p[0]-edge.a[0])/d[0]:(p[1]-edge.a[1])/d[1];
+      const from=Math.max(lo,param(interval[0])),to=Math.min(hi,param(interval[1]));
+      if(to<=from)continue;
+      if(joint!==undefined){
+        const hole=sweptHole(point(edge.a,edge.b,from),point(edge.a,edge.b,to),n,joint,piece);
+        if(hole!==null){fail=true;if(hole.found-hole.required<margin){margin=hole.found-hole.required;found=hole.found;required=hole.required;}}
+      }
+      const p=point(edge.a,edge.b,(from+to)/2);
+      crossed+=(to-from)*length;rays++;
+      const at=joint?.at??p,tangent:Point=[-n[1],n[0]],t=dot([p[0]-at[0],p[1]-at[1]],tangent);
+      const offset=dot([p[0]-at[0],p[1]-at[1]],n);
+      const angles=joint===undefined?[0]:[...joint.bend_degrees].map(a=>a*Math.PI/180);
+      for(const angle of angles){
+        const [cos,sin]=trig(angle),s=t*cos-offset*sin,start:Point=[at[0]+s*tangent[0]+offset*n[0],at[1]+s*tangent[1]+offset*n[1]];
+        const r=joint===undefined?0:Math.max(0,offset*(1-cos)-t*sin),f=support(piece,start,n);
+        if(!Number.isFinite(f)||!Number.isFinite(r))refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object:`part "${part}"`,detail:'material support arithmetic is not finite; no PASS is inferred'}]);
+        if(f-r<margin || f-r===margin && r>required){margin=f-r;found=f;required=r;}
+        if(f<r)fail=true;
+      }
+    }
+    return {part,joint:joint?.joint??'(undeclared)',edge:[edge.a,edge.b],edge_length_px:intervals.reduce((s,[a,b])=>s+edgeLength(b[0]-a[0],b[1]-a[1]),0),within_reach_px:crossed,found_px:found===Infinity?0:found,required_px:required,rays,
+      status:joint===undefined||rays===0?'SKIP':fail?'FAIL':'PASS',...(joint===undefined?{reason:'no declared cut_material requirement; measured source support is not a pass'}:rays===0?{reason:'no opaque source crossing within declared joint reach'}:{})};
+  });
+}
+/** Original source intersections, represented as ordered bounded parameters. */
+function opaqueParameters(edge:MaterialEdge,source:readonly PlacedArt[]):Array<[number,number]>{
+  const ts=breaks(edge.a,edge.b,source),out:Array<[number,number]>=[];
+  for(let i=0;i+1<ts.length;i++)if(across(source,point(edge.a,edge.b,(ts[i]+ts[i+1])/2),edge.inward))out.push([ts[i],ts[i+1]]);
+  return out;
+}
+/** Canonical unit perpendicular; the sign is the explicitly captured inward side. */
+export function canonicalInward(a:Point,b:Point,inward:Point):Point{
+  const d:Point=[b[0]-a[0],b[1]-a[1]],length=edgeLength(...d),normal:Point=[-d[1]/length,d[0]/length];
+  return dot(normal,inward)>0?normal:[-normal[0],-normal[1]];
+}
+export function materialSource(part:string,from:string[],edges:readonly MaterialEdge[],source:readonly PlacedArt[]):MaterialSource{
+  return {part,from,source_sha256:source.map(s=>createHash('sha256').update(JSON.stringify([s.x,s.y,s.image.width,s.image.height])).update(s.image.data).digest('hex')),edges:edges.map(e=>{
+    const inward=canonicalInward(e.a,e.b,e.inward),opaque_t=opaqueParameters({...e,inward},source),length=edgeLength(e.b[0]-e.a[0],e.b[1]-e.a[1]);
+    return {a:e.a,b:e.b,inward,opaque_t,opaque_intervals:opaque_t.length,opaque_length_px:opaque_t.reduce((s,[a,b])=>s+(b-a)*length,0)};
+  }).filter(e=>e.opaque_t.length>0)};
+}
+export function checkJointMaterial(declarations: readonly JointMaterial[] | undefined, parts: PartsFile | null, image: (name:string)=>Raster, problems:Problem[],sources?:readonly MaterialSource[]): MaterialLine {
+  if(declarations===undefined)return {status:'SKIP',rows:[],reason:'no declared cut_material requirement'};
+  refuseIfAny(jointMaterialProblems(declarations,'cut_material'));
+  if(parts===null)refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object:'cut_material',detail:'requires parts.json and its emitted PNGs; missing art is not zero support'}]);
+  const rows:MaterialRow[]=[];
+  const records=(parts as PartsFile).parts;
+  const art=(name:string):PlacedArt=>{const p=records.find(p=>p.name===name);if(p===undefined)throw new Error(`missing resolved part ${name}`);return {x:p.x,y:p.y,image:image(name)};};
+  for(const req of declarations){
+    const p=records.find(p=>p.name===req.part),object=`part "${req.part}", joint "${req.joint}"`;
+    if(p===undefined||p.cut_from===undefined&&p.limb===undefined)refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object,detail:'requires a named cut_from or limb segment provenance; nearest parts and inferred joints are not read'}]);
+    const rec=p!,limb=rec.limb;
+    const original=sources?.find(s=>s.part===req.part);
+    if(original===undefined)refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object,detail:'original source edge readings are unavailable; emitted siblings cannot reconstruct discarded/overlapping source art — rerun assemble --requirements <file> (or build --requirements <file>) to write the source-bound sidecar'}]);
+    let piece=[art(rec.name)];
+    if(limb!==undefined){
+      if(limb.segment===0||limb.band!==undefined)refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object,detail:'requires a lower limb segment, not segment0 or the generated band'}]);
+      const geometry=limb.cap??limb.hybrid;
+      if(limb.joint!==req.joint||geometry===undefined||geometry.at[0]!==req.at[0]||geometry.at[1]!==req.at[1])refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object,detail:'declared joint name/at must equal the recorded lower joint centre; correct the explicit correspondence'}]);
+      if(limb.hybrid!==undefined)piece=[...piece,art(limb.hybrid.part)];
+    }
+    const candidates=(original as MaterialSource).edges.filter(e=>(e.opaque_t??[]).some(([lo,hi])=>{
+      const a=point(e.a,e.b,lo),b=point(e.a,e.b,hi),d:Point=[b[0]-a[0],b[1]-a[1]],q:Point=[req.at[0]-a[0],req.at[1]-a[1]],t=Math.max(0,Math.min(1,dot(q,d)/dot(d,d))),closest=point(a,b,t);return edgeLength(closest[0]-req.at[0],closest[1]-req.at[1])<=req.reach_px;
+    }));
+    if(candidates.length>0&&!candidates.some(e=>{
+      const d:Point=[e.b[0]-e.a[0],e.b[1]-e.a[1]],perpendicular=dot(d,req.axis),side=cross(d,req.axis),captured=cross(d,e.inward),sameCanonical=cross(e.inward,req.axis);
+      if(!Number.isFinite(perpendicular)||!Number.isFinite(side)||!Number.isFinite(captured)||!Number.isFinite(sameCanonical))refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object,detail:'edge/axis orientation arithmetic is not finite; supply a representable scalar multiple of the measured inward direction'}]);
+      return (perpendicular===0||sameCanonical===0)&&side!==0&&Math.sign(side)===Math.sign(captured);
+    }))refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object,detail:'declared axis matches no original opaque edge inward within reach; correct the explicit edge/joint correspondence'}]);
+    const read=materialRows(req.part,req,(original as MaterialSource).edges,[],piece);
+    if(read.every(r=>r.rays===0))refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object,detail:'no opaque cut interface within declared reach; correct the explicit joint correspondence/reach or supply source material; no PASS is invented'}]);
+    for(const r of read.filter(r=>r.rays>0)){
+      rows.push(r);
+      if(r.status==='FAIL')problems.push({code:'CHECK_CUT_JOINT_MATERIAL',object,detail:`edge [${r.edge.map(p=>p.join(',')).join(' -> ')}], opaque edge length ${r.edge_length_px} px (${r.within_reach_px} px within reach): material found ${r.found_px} px, required ${r.required_px} px by bend [${req.bend_degrees.join(', ')}] degrees within reach ${req.reach_px} px; source art past the joint is required — follow AUTHORING Source before scissors; no crop or under-piece repair`});
+    }
+  }
+  return {status:rows.some(r=>r.status==='FAIL')?'FAIL':'PASS',rows};
+}
+export function materialLines(line:MaterialLine):string[]{return [`${CUT_MATERIAL_LINE}: ${line.status}${line.reason===undefined?'':` — ${line.reason}`}`,...line.rows.map(r=>`${CUT_MATERIAL_LINE}: part "${r.part}", joint "${r.joint}", edge [${r.edge.map(p=>p.join(',')).join(' -> ')}]: ${r.status}; opaque edge length ${r.edge_length_px} px; material found ${r.found_px} px, required ${r.required_px} px (${r.rays} source rays; continuous inverse-rotation arc)`)];}

package/src/cutmaterialio.ts

@@ -0,0 +1,63 @@
+/** Optional source-bound assembly evidence, absent on undeclared builds. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { edgeLength } from './length.ts';
+import { canonicalInward, CUT_MATERIAL_SOURCES, CUT_MATERIAL_SPEC, type MaterialSource, type Point } from './cutmaterial.ts';
+import type { PartsFile } from './parts.ts';
+import { refuseIfAny } from './errors.ts';
+const sha=(data:Uint8Array|string):string=>createHash('sha256').update(data).digest('hex');
+const hash=(path:string):string=>sha(readFileSync(path));
+const record=(v:unknown):v is Record<string,unknown>=>typeof v==='object'&&v!==null&&!Array.isArray(v);
+const digest=(v:unknown):v is string=>typeof v==='string'&&/^[a-f0-9]{64}$/.test(v);
+const point=(v:unknown):v is Point=>Array.isArray(v)&&v.length===2&&v.every(x=>typeof x==='number'&&Number.isFinite(x));
+export function writeMaterialSources(partsPath:string,partsDir:string,parts:PartsFile,sources:readonly MaterialSource[]):void{
+  const emitted=sources.filter(s=>parts.parts.some(p=>p.name===s.part));
+  writeFileSync(join(dirname(partsPath),CUT_MATERIAL_SOURCES),JSON.stringify({
+    spec:CUT_MATERIAL_SPEC,parts_sha256:hash(partsPath),
+    images:parts.parts.map(p=>({part:p.name,sha256:hash(join(partsDir,`${p.name}.png`))})),
+    sources_sha256:sha(JSON.stringify(emitted)),sources:emitted,
+  },null,2)+'\n');
+}
+export function readMaterialSources(home:string,parts:PartsFile):MaterialSource[]{
+  const path=join(home,CUT_MATERIAL_SOURCES);
+  const fail=(detail:string):never=>{refuseIfAny([{code:'CHECK_CUT_MATERIAL_MEASURED',object:path,detail:`${detail}; rerun assemble --requirements <file> or build --requirements <file>; emitted siblings are not original source evidence`}]);throw new Error('unreachable');};
+  if(!existsSync(path))return fail('original source-edge sidecar is unavailable');
+  let raw:unknown;
+  try{raw=JSON.parse(readFileSync(path,'utf8'));}catch{return fail('source-edge sidecar is not JSON');}
+  if(!record(raw)||raw.spec!==CUT_MATERIAL_SPEC||!Array.isArray(raw.images)||!Array.isArray(raw.sources))return fail(`requires ${CUT_MATERIAL_SPEC}, images and sources`);
+  if(Object.keys(raw).some(k=>!['spec','parts_sha256','images','sources_sha256','sources'].includes(k)))return fail('source sidecar has an unknown field');
+  if(raw.parts_sha256!==hash(join(home,'parts.json')))return fail('source-edge sidecar does not bind these parts.json bytes');
+  if(!digest(raw.sources_sha256)||raw.sources_sha256!==sha(JSON.stringify(raw.sources)))return fail('original source-edge payload digest differs; intervals/edges must not be removed or rewritten');
+  if(raw.images.length!==parts.parts.length)return fail('image bindings do not cover every emitted base part');
+  const seen=new Set<string>();
+  for(const binding of raw.images){
+    if(!record(binding)||typeof binding.part!=='string'||!digest(binding.sha256)||seen.has(binding.part)||!parts.parts.some(p=>p.name===binding.part))return fail('image bindings require each named base part exactly once and its SHA-256');
+    if(Object.keys(binding).some(k=>!['part','sha256'].includes(k)))return fail('image binding has an unknown field');
+    seen.add(binding.part);
+    const file=join(home,'parts',`${binding.part}.png`);
+    if(!existsSync(file)||hash(file)!==binding.sha256)return fail(`source-edge binding for part "${binding.part}" differs from its emitted PNG`);
+  }
+  const sources=new Set<string>();
+  for(const s of raw.sources){
+    if(!record(s)||typeof s.part!=='string'||sources.has(s.part)||!parts.parts.some(p=>p.name===s.part)||!Array.isArray(s.from)||s.from.length===0||!s.from.every(f=>typeof f==='string'&&f.length>0)||!Array.isArray(s.source_sha256)||s.source_sha256.length!==s.from.length||!s.source_sha256.every(digest)||!Array.isArray(s.edges))return fail('source readings require unique emitted parts, source labels/digests and edges');
+    if(Object.keys(s).some(k=>!['part','from','source_sha256','edges'].includes(k)))return fail('source reading has an unknown field');
+    sources.add(s.part);
+    for(const edge of s.edges){
+      if(!record(edge)||!point(edge.a)||!point(edge.b)||!point(edge.inward)||!Array.isArray(edge.opaque_t))return fail('edge readings require finite a, b, inward and bounded original opaque_t parameters');
+      if(Object.keys(edge).some(k=>!['a','b','inward','opaque_t','opaque_intervals','opaque_length_px'].includes(k)))return fail('edge reading has an unknown field; absolute opaque endpoints are not this format');
+      const a=edge.a,b=edge.b,n=edge.inward,length=edgeLength(b[0]-a[0],b[1]-a[1]);
+      if(!Number.isFinite(length)||length===0||edgeLength(...n)===0)return fail('source edge or its inward direction has zero/unrepresentable length');
+      const canonical=canonicalInward(a,b,n);
+      if(n[0]!==canonical[0]||n[1]!==canonical[1])return fail('inward must be the canonical unit perpendicular to the actual edge; no oblique inward is supported');
+      if(edge.opaque_t.length===0)return fail('listed source edges must have opaque intervals; an empty list may not hide an originally crossed edge');
+      let previous=0,total=0;
+      for(const span of edge.opaque_t){
+        if(!point(span)||span[0]<0||span[1]>1||span[0]>=span[1]||span[0]<previous)return fail('opaque_t intervals must be ordered, nonoverlapping, positive, and inside [0,1] on this actual edge');
+        previous=span[1];total+=(span[1]-span[0])*length;
+      }
+      if(edge.opaque_intervals!==edge.opaque_t.length||edge.opaque_length_px!==total)return fail('opaque interval count/length disagree with the original source-edge census');
+    }
+  }
+  return raw.sources as unknown as MaterialSource[];
+}

package/src/requirements.ts

@@ -1,3 +1,5 @@
+import { setupPaintingProblems, type SetupPainting } from './setuppainting.ts';
+import { jointMaterialProblems, type JointMaterial } from './cutmaterial.ts';
 import { fixedSkeletonProblems, type FixedSkeleton } from './artjoints.ts';
 /**
  * What a scene requires of a rig's motion, declared in a file `check` is given
@@ -193,6 +195,10 @@ export interface RequirementsFile {
   may_fold: MayFold[];
   /** Issue #880: an explicit fixed-skeleton art comparison, absent on other rigs. */
   fixed_skeleton?: FixedSkeleton;
+  /** Issue #887: authored source-painting limits over native renderer setup. */
+  setup_painting?: SetupPainting;
+  /** Explicit source-support declarations (#888), absent otherwise. */
+  cut_material?: JointMaterial[];
 }
 
 /** One declared fold (issue #320): a slot, a named animation, and why the fold is the art's. */
@@ -283,7 +289,9 @@ export function readRequirements(path: string): RequirementsFile {
     problems.push({ code: 'REQUIREMENTS_SELF_TARGET', object: `${label} field "target"`, detail });
   };
   if (raw.spec !== REQUIREMENTS_SPEC) field(`${at} field "spec"`, `is ${JSON.stringify(raw.spec)}; ${JSON.stringify(REQUIREMENTS_SPEC)} is required`);
-  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS, 'may_fold', 'fixed_skeleton'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests, may_fold, fixed_skeleton; note or *_note as a string; x-<name> as a record)');
+  for (const k of Object.keys(raw)) if (!['spec', 'fps', 'targets', 'requirements', ...EXCEPTION_LISTS, 'may_fold', 'fixed_skeleton', 'cut_material', 'setup_painting'].includes(k) && !freeKey(k, raw[k])) field(`${at} field "${k}"`, 'is not a field this format reads (spec, fps, targets, requirements, not_planted, not_swinging, rises, rests, may_fold, fixed_skeleton, cut_material, setup_painting; note or *_note as a string; x-<name> as a record)');
+  if ('setup_painting' in raw) problems.push(...setupPaintingProblems(raw.setup_painting, `${at} setup_painting`));
+  if ('cut_material' in raw) problems.push(...jointMaterialProblems(raw.cut_material, `${at} cut_material`));
   if ('fixed_skeleton' in raw) problems.push(...fixedSkeletonProblems(raw.fixed_skeleton, `${at} fixed_skeleton`));
   let fps = NaN;
   if (!(finite(raw.fps) && raw.fps > 0)) field(`${at} field "fps"`, `is ${JSON.stringify(raw.fps)}; a positive number of frames per second is required — every named animation is sampled at it, and there is no default`);
@@ -468,7 +476,7 @@ export function readRequirements(path: string): RequirementsFile {
     }
   }
   refuseIfAny(problems);
-  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold, ...(raw.fixed_skeleton === undefined ? {} : { fixed_skeleton: raw.fixed_skeleton as FixedSkeleton }) };
+  return { path: at, fps, targets, requirements, not_planted: lists.not_planted, not_swinging: lists.not_swinging, rises: lists.rises, rests: lists.rests, may_fold: mayFold, ...(raw.fixed_skeleton === undefined ? {} : { fixed_skeleton: raw.fixed_skeleton as FixedSkeleton }), ...(raw.cut_material === undefined ? {} : { cut_material: raw.cut_material as JointMaterial[] }), ...(raw.setup_painting === undefined ? {} : { setup_painting: raw.setup_painting as SetupPainting }) };
 }
 
 // ---------------------------------------------------------------------------

package/src/setuppainting.ts

@@ -0,0 +1,126 @@
+/** Authored source-painting limits over actual renderer setup pixels (#887). */
+import { refuseIfAny, type Problem } from './errors.ts';
+import type { Raster } from './raster/types.ts';
+
+export const SETUP_PAINTING_LINE = 'SETUP_MATCHES_PAINTING';
+export interface SetupPaintingRegion {
+  name: string;
+  /** Stage pixels, x right/y down: [x, y, width, height], exclusive far edge. */
+  box: [number, number, number, number];
+  /** Maximum count over the entire named region. Absent means SKIP. */
+  max_pixels?: number;
+}
+export interface SetupPainting {
+  /** A pixel counts when its maximum RGB difference is strictly greater. */
+  rgb_tolerance: number;
+  regions: SetupPaintingRegion[];
+}
+const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const integer = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v);
+const free = (k: string, v: unknown): boolean => (k.startsWith('x-') && k.length > 2) || ((k === 'note' || k.endsWith('_note')) && typeof v === 'string');
+
+/** Shape only: no default limit, inferred box, art alignment or slot name. */
+export function setupPaintingProblems(value: unknown, at: string): Problem[] {
+  const problems: Problem[] = [];
+  const fail = (where: string, detail: string): void => { problems.push({ code: 'REQUIREMENTS_FIELD', object: where, detail }); };
+  const keys = (v: Record<string, unknown>, allowed: string[], where: string): void => {
+    for (const k of Object.keys(v)) if (!allowed.includes(k) && !free(k, v[k])) fail(`${where}.${k}`, `is unknown; fields are ${allowed.join(', ')}`);
+  };
+  if (!object(value)) return [{ code: 'REQUIREMENTS_FIELD', object: at, detail: 'requires {rgb_tolerance, regions: [{name, box, max_pixels?}]}' }];
+  keys(value, ['rgb_tolerance', 'regions'], at);
+  if (!integer(value.rgb_tolerance) || value.rgb_tolerance < 0 || value.rgb_tolerance > 255) fail(`${at}.rgb_tolerance`, 'requires an authored integer from 0 through 255; difference strictly above it counts');
+  if (!Array.isArray(value.regions) || value.regions.length === 0) fail(`${at}.regions`, 'requires a nonempty list of named source-grid regions');
+  else {
+    const names = new Set<string>();
+    value.regions.forEach((r, i) => {
+      const where = `${at}.regions[${i}]`;
+      if (!object(r)) { fail(where, 'requires {name, box, max_pixels?}'); return; }
+      keys(r, ['name', 'box', 'max_pixels'], where);
+      if (typeof r.name !== 'string' || r.name.trim() === '') fail(`${where}.name`, 'requires a nonempty region name');
+      else { if (names.has(r.name)) fail(`${where}.name`, `declares region "${r.name}" twice`); names.add(r.name); }
+      if (!Array.isArray(r.box) || r.box.length !== 4 || !r.box.every(integer) || r.box[0] < 0 || r.box[1] < 0 || r.box[2] <= 0 || r.box[3] <= 0 || !Number.isSafeInteger(r.box[0] + r.box[2]) || !Number.isSafeInteger(r.box[1] + r.box[3])) fail(`${where}.box`, 'requires nonnegative integer x/y and positive integer width/height in stage pixels, with finite integer far edges');
+      if ('max_pixels' in r && (!integer(r.max_pixels) || r.max_pixels < 0)) fail(`${where}.max_pixels`, 'requires a nonnegative authored integer pixel count, or omission for SKIP');
+    });
+  }
+  return problems;
+}
+
+export function setupPaintingBounds(value: SetupPainting, width: number, height: number): Problem[] {
+  return value.regions.flatMap(r => r.box[0] + r.box[2] > width || r.box[1] + r.box[3] > height
+    ? [{ code: 'REQUIREMENTS_FIELD', object: `setup_painting region "${r.name}" box`, detail: `[${r.box.join(', ')}] exceeds the declared ${width}x${height} stage; regions use its native pixel grid, not a fitted render` }] : []);
+}
+
+export interface SetupPaintingSlot {
+  slot: string;
+  /** Bounding box of failing pixel centres, in stage-grid pixels. */
+  box: [number, number, number, number];
+  pixel_count: number;
+}
+export interface SetupPaintingReading extends SetupPaintingRegion {
+  status: 'PASS' | 'FAIL' | 'SKIP';
+  pixel_count: number;
+  limit: number | null;
+  slots: SetupPaintingSlot[];
+}
+export interface SetupPaintingLine {
+  status: 'PASS' | 'FAIL' | 'SKIP';
+  instrument: 'rigc renderer setup textured pieces';
+  registration: 'declared stage grid, scale 1, no fitting';
+  compositing: 'source-over white, RGBA8';
+  figure: 'source figureSilhouette union rendered alpha > 0';
+  ownership: 'last actual drawn piece with sampled alpha > 0; uncovered explicit';
+  rgb_tolerance: number;
+  regions: SetupPaintingReading[];
+  reason?: string;
+}
+
+/** Pixel metric only. Caller supplies the actual renderer's textured setup and
+ * its per-pixel drawn-piece owners on precisely the source grid. RGB under
+ * zero alpha is ignored: both observations are source-over white first.
+ * Region totals count each pixel once, even with translucent contributors.
+ */
+export function setupPaintingLine(
+  declared: SetupPainting, source: Raster, setup: Raster, figure: Uint8Array,
+  owners: Int32Array, slots: readonly string[], problems: Problem[],
+): SetupPaintingLine {
+  refuseIfAny(setupPaintingProblems(declared, 'setup_painting'));
+  refuseIfAny(setupPaintingBounds(declared, source.width, source.height));
+  const W = source.width, H = source.height, n = W * H;
+  if (setup.width !== W || setup.height !== H || figure.length !== n || owners.length !== n || source.data.length !== n * 4 || setup.data.length !== n * 4 || owners.some(i => i < -1 || i >= slots.length)) {
+    refuseIfAny([{ code: 'CHECK_SETUP_PAINTING_MEASURED', object: SETUP_PAINTING_LINE, detail: 'requires actual setup pixels, figure domain and renderer owners on the declared native source grid; no fitted registration or guessed owner is substituted' }]);
+  }
+  const regions = declared.regions.map<SetupPaintingReading>(r => {
+    const rows = new Map<string, { pixels: number; x0: number; y0: number; x1: number; y1: number }>();
+    let count = 0;
+    for (let y = r.box[1]; y < r.box[1] + r.box[3]; y++) for (let x = r.box[0]; x < r.box[0] + r.box[2]; x++) {
+      const p = y * W + x, q = p * 4;
+      if (figure[p] === 0 && setup.data[q + 3] === 0) continue;
+      let delta = 0;
+      for (let c = 0; c < 3; c++) {
+        const white = (image: Raster): number => Math.round(image.data[q + c] * image.data[q + 3] / 255 + 255 * (1 - image.data[q + 3] / 255));
+        delta = Math.max(delta, Math.abs(white(source) - white(setup)));
+      }
+      if (delta <= declared.rgb_tolerance) continue;
+      count++;
+      const slot = owners[p] < 0 ? '(uncovered)' : slots[owners[p]], row = rows.get(slot);
+      if (row === undefined) rows.set(slot, { pixels: 1, x0: x, y0: y, x1: x + 1, y1: y + 1 });
+      else { row.pixels++; row.x0 = Math.min(row.x0, x); row.y0 = Math.min(row.y0, y); row.x1 = Math.max(row.x1, x + 1); row.y1 = Math.max(row.y1, y + 1); }
+    }
+    const status = r.max_pixels === undefined ? 'SKIP' : count > r.max_pixels ? 'FAIL' : 'PASS';
+    const result: SetupPaintingReading = { ...r, status, pixel_count: count, limit: r.max_pixels ?? null,
+      slots: [...rows].map(([slot, row]) => ({ slot, box: [row.x0, row.y0, row.x1 - row.x0, row.y1 - row.y0], pixel_count: row.pixels })) };
+    if (status === 'FAIL') {
+      for (const row of result.slots) problems.push({ code: 'CHECK_SETUP_MATCHES_PAINTING', object: `region "${r.name}" slot "${row.slot}"`, detail: `box [${row.box.join(', ')}], pixelcount ${row.pixel_count}; region pixelcount ${count} > declared limit ${r.max_pixels}, RGB tolerance ${declared.rgb_tolerance}; compare the actual setup to the source painting on the declared stage grid` });
+    }
+    return result;
+  });
+  const noLimit = regions.some(r => r.status === 'SKIP');
+  return { status: regions.some(r => r.status === 'FAIL') ? 'FAIL' : noLimit ? 'SKIP' : 'PASS', instrument: 'rigc renderer setup textured pieces', registration: 'declared stage grid, scale 1, no fitting', compositing: 'source-over white, RGBA8', figure: 'source figureSilhouette union rendered alpha > 0', ownership: 'last actual drawn piece with sampled alpha > 0; uncovered explicit', rgb_tolerance: declared.rgb_tolerance, regions,
+    ...(noLimit ? { reason: 'a region has no declared max_pixels; it is measured as SKIP, never PASS' } : {}) };
+}
+
+export function setupPaintingLines(line: SetupPaintingLine): string[] {
+  return [`${SETUP_PAINTING_LINE}: ${line.status}${line.reason === undefined ? '' : ` — ${line.reason}`}; ${line.registration}; ${line.compositing}`,
+    ...line.regions.flatMap(r => [`${SETUP_PAINTING_LINE}: region "${r.name}" ${r.status} — box [${r.box.join(', ')}], pixelcount ${r.pixel_count}, limit ${r.limit ?? 'undeclared (SKIP)'}, RGB tolerance ${line.rgb_tolerance}`,
+      ...r.slots.map(s => `${SETUP_PAINTING_LINE}: slot "${s.slot}" region "${r.name}" — box [${s.box.join(', ')}], pixelcount ${s.pixel_count}; region total ${r.pixel_count}, limit ${r.limit ?? 'undeclared (SKIP)'}`)])];
+}