rig-parts 1.87.0 → 1.88.0

package/cli.ts

@@ -555,7 +555,8 @@ usage:
                     [--page-edges pot|free] [--pack-shape rect|polygon]
                     [--requirements <file.json>] [--seam-pairs] [--keep-stills]
                     [--set <name> | --all-sets] [--environment <schedule.json>]
-                    [--wind-band <spec.json>]
+                    [--wind-band <spec.json>] [--json]
+      --json prints the completed check.json object only, with unchanged exit codes.
       Build, gate, render and measure a rig through rig-c's CLI (the rigc at
       node_modules/.bin/rigc, or on PATH). --rig holds rig.json and motion.json:
       a rig spec, which rigc build compiles, not a compiled skeleton.json.
@@ -777,7 +778,7 @@ usage:
       extends below a crop (ASSEMBLE_SINGLE_RUN_PLAN), and the config sets no
       seethrough.head_box (ASSEMBLE_SINGLE_RUN_HEAD_BOX).
       Writes nothing unless every check passed.
-      --seam defaults to ${DEFAULT_SEAM_RULE}. --project says where a layer takes
+      --seam overrides config.assemble.seam, otherwise ${DEFAULT_SEAM_RULE}. --project says where a layer takes
       the painting's pixel: core (the reference's) erodes every layer's top-most
       opaque area by 5x5 first, so a part a few pixels wide takes none; visible
       erodes only along a rim where a later layer is in front. It defaults to
@@ -861,7 +862,7 @@ usage:
       green build ends with the pack line beside the spineboy yardstick and the
       three artifact paths — skeleton .json, .atlas and the packed page: the
       packed atlas is the result, the loose parts are the intermediate it was
-      made from. --seam defaults to ${DEFAULT_SEAM_RULE}, --project to
+      made from. --seam overrides config.assemble.seam, otherwise ${DEFAULT_SEAM_RULE}; --project to
       ${DEFAULT_PROJECT_RULE} (both as for assemble), --page-edges to ${DEFAULT_PAGE_EDGES} and
       --pack-shape to ${DEFAULT_PACK_SHAPE} (as for check; both packed builds, rig's gate
       and check's artifact, take them). --requirements is forwarded to check
@@ -1095,7 +1096,7 @@ const TAKES = {
   rig: { valued: ['--config', '--parts', '--out', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
   propose: { valued: ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--head', '--canvas', '--keypoints', '--person', '--wrist-snap', '--grid-rule', '--cloth', '--write-config', '--from'], switches: ['--head-box', '--no-back-hair', '--only-missing'] },
   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'] },
+  check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment', '--wind-band'], switches: ['--seam-pairs', '--keep-stills', '--all-sets', '--no-extremes', '--json'] },
   loop: { valued: ['--frames', '--out'], switches: ['--palette'] },
   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'] },
@@ -1338,6 +1339,8 @@ function flags(args: string[], command: Command, required: readonly string[]): M
 
 function cmdCheck(args: string[]): number {
   // The switches check takes (issues #202, #209, #454): they carry no value, so they are taken out before the valued flags are read.
+  const json = args.filter((a) => a === '--json').length;
+  if (json > 1) return usage('--json is given twice');
   const seamPairs = args.filter((a) => a === '--seam-pairs').length;
   if (seamPairs > 1) return usage('--seam-pairs is given twice');
   const keepStills = args.filter((a) => a === '--keep-stills').length;
@@ -1347,7 +1350,7 @@ function cmdCheck(args: string[]): number {
   const allSets = args.filter((a) => a === '--all-sets').length;
   if (allSets > 1) return usage('--all-sets is given twice');
   const f = flags(
-    args.filter((a) => a !== '--seam-pairs' && a !== '--keep-stills' && a !== '--all-sets' && a !== '--no-extremes'),
+    args.filter((a) => a !== '--seam-pairs' && a !== '--keep-stills' && a !== '--all-sets' && a !== '--no-extremes' && a !== '--json'),
     'check',
     ['--rig', '--out'],
   );
@@ -1365,8 +1368,9 @@ function cmdCheck(args: string[]): number {
       { rig, parts: f.get('--parts'), source: f.get('--source'), out, pageEdges: edges, packShape: shape, requirements: f.get('--requirements'), seamPairs: seamPairs === 1, keepStills: keepStills === 1, noExtremes: noExtremes === 1, ...(f.has('--set') ? { set: f.get('--set') as string } : {}), allSets: allSets === 1, ...(f.has('--environment') ? { environment: f.get('--environment') as string } : {}), ...(f.has('--wind-band') ? { windBand: f.get('--wind-band') as string } : {}) },
       rigcRunner(bin),
       bin,
-      console.log,
+      json === 1 ? () => {} : console.log,
     );
+    if (json === 1) process.stdout.write(`${JSON.stringify(r.figures, null, 1)}\n`);
     return r.figures.PASS ? EXIT_OK : EXIT_REFUSED;
   } catch (err) {
     return printRefusal(err);
@@ -1726,8 +1730,8 @@ function cmdAssemble(args: string[]): number {
   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>');
-  const seam = flags.get('--seam') ?? DEFAULT_SEAM_RULE;
-  if (!(SEAM_RULES as readonly string[]).includes(seam)) return usage(`--seam ${seam}; one of ${SEAM_RULES.join(', ')} is required`);
+  const seam = flags.get('--seam');
+  if (seam !== undefined && !(SEAM_RULES as readonly string[]).includes(seam)) return usage(`--seam ${seam}; one of ${SEAM_RULES.join(', ')} is required`);
   const project = flags.get('--project') ?? DEFAULT_PROJECT_RULE;
   if (!(PROJECT_RULES as readonly string[]).includes(project)) return usage(`--project ${project}; one of ${PROJECT_RULES.join(', ')} is required`);
   const [source, full, config] = ['--source', '--full', '--config'].map((f) => flags.get(f) as string);
@@ -1755,7 +1759,7 @@ function cmdAssemble(args: string[]): number {
     }
     const out = flags.get('--out') as string;
     assembleStage(
-      { 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 }) },
+      { source, full, head, config, ...(flags.has('--requirements') ? { requirements: flags.get('--requirements') as string } : {}), ...(seam === undefined ? {} : { 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,
     );
@@ -1946,8 +1950,8 @@ function cmdBuild(args: string[]): number {
   // --head is optional (issue #359), as for assemble.
   for (const f of ['--config', '--source', '--full', '--out']) if (!flags.has(f)) return usage(`build needs ${f}`);
   if (on.has('--all-sets') && flags.has('--set')) return usage('--set and --all-sets are two modes; give one');
-  const seam = flags.get('--seam') ?? DEFAULT_SEAM_RULE;
-  if (!(SEAM_RULES as readonly string[]).includes(seam)) return usage(`--seam ${seam}; one of ${SEAM_RULES.join(', ')} is required`);
+  const seam = flags.get('--seam');
+  if (seam !== undefined && !(SEAM_RULES as readonly string[]).includes(seam)) return usage(`--seam ${seam}; one of ${SEAM_RULES.join(', ')} is required`);
   const project = flags.get('--project') ?? DEFAULT_PROJECT_RULE;
   if (!(PROJECT_RULES as readonly string[]).includes(project)) return usage(`--project ${project}; one of ${PROJECT_RULES.join(', ')} is required`);
   const edges = pageEdgesOf(flags.get('--page-edges'));
@@ -1971,7 +1975,7 @@ function cmdBuild(args: string[]): number {
   const scratch = mkdtempSync(join(tmpdir(), 'rig-parts-build-'));
   try {
     const r = build(
-      { config, source, full, head, out, seam: seam as SeamRule, project: project as ProjectRule, loop, pageEdges: edges, packShape: shape, ...(flags.has('--requirements') ? { requirements: flags.get('--requirements') as string } : {}), idleKeys: keys, ...(leadText === undefined ? {} : { leadIn: Number(leadText) }), seamPairs: on.has('--seam-pairs'), keepStills: on.has('--keep-stills'), noExtremes: on.has('--no-extremes'), ...(alts.length === 0 ? {} : { alts }), ...(flags.has('--set') ? { set: flags.get('--set') as string } : {}), allSets: on.has('--all-sets'), ...(flags.has('--environment') ? { environment: flags.get('--environment') as string } : {}), ...(flags.has('--wind-band') ? { windBand: flags.get('--wind-band') as string } : {}) },
+      { config, source, full, head, out, ...(seam === undefined ? {} : { seam: seam as SeamRule }), project: project as ProjectRule, loop, pageEdges: edges, packShape: shape, ...(flags.has('--requirements') ? { requirements: flags.get('--requirements') as string } : {}), idleKeys: keys, ...(leadText === undefined ? {} : { leadIn: Number(leadText) }), seamPairs: on.has('--seam-pairs'), keepStills: on.has('--keep-stills'), noExtremes: on.has('--no-extremes'), ...(alts.length === 0 ? {} : { alts }), ...(flags.has('--set') ? { set: flags.get('--set') as string } : {}), allSets: on.has('--all-sets'), ...(flags.has('--environment') ? { environment: flags.get('--environment') as string } : {}), ...(flags.has('--wind-band') ? { windBand: flags.get('--wind-band') as string } : {}) },
       { rig: rigcRunner(bin), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'rig-gate'), stages: {
         assemble: (input, outputs) => runBuildProcess({ stage: 'assemble', bin, input, outputs }, join(scratch, 'workers')),
         rig: (input, _rigc, gateScratch) => runBuildProcess({ stage: 'rig', bin, input, scratch: gateScratch }, join(scratch, 'workers')),

package/docs/AUTHORING.md

@@ -147,6 +147,7 @@ read by no CPU stage).
 | `seethrough.steps`, `.seed`, `.offload` | `comfy seethrough --config` | run inputs when `--config <config.json>` is given; explicit CLI flags override them, including `--no-offload` for false |
 | `seethrough.head_box` | inputs (cuts the head image there; optional at the first call); assemble — where the head run sits on the painting | **proposed** by `propose --head-box` from the full run, square, source pixels, shifted inside the painting when needed; the head run must then be fed exactly that crop. With one run (no `--head`, issue #359: an artist's own file, §4 *For artists*) it is left out — there is no crop to place — and a config that sets it is refused (`ASSEMBLE_SINGLE_RUN_HEAD_BOX`) |
 | `seethrough.arm_split` | assemble, `assemble --propose-plan` — separates a single full-run `handwear-r` or `handwear-l` layer that holds both overlapping arms into both arm tags | **authored**, optional (issue #439): `{x?: number, line?: [[x, y], …], order: ["handwear-r", "handwear-l"] \| ["handwear-l", "handwear-r"]}` in `seethrough.resolution` full-run pixels. Exactly one of `x` (image column, `0 <= x <= resolution`) or `line` (a polyline of two or more `[x, y]` points in `[0, resolution]`, interpolated in x along y and clamped above/below its endpoints) is required (`CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE`), and `order` is `[back_tag, front_tag]`, the draw order of the two separated arm layers (`CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE`). Pixels at `< splitX(y)` go to `handwear-r` (image left, the subject's right arm) and pixels at `>= splitX(y)` go to `handwear-l` (image right, the subject's left arm). A split line that cuts a horizontal opaque run of the arm layer into more than two segments is refused (`ASSEMBLE_ARM_SPLIT_CUTS_ARM`). Without the declaration, when one arm layer's 8-connected component reaches both wrists under `propose --keypoints`, `propose` emits an `overlapping-arms` `LINT` naming the part, both wrists and `seethrough.arm_split`; absent, no byte of any output moves |
+| `assemble.seam` | assemble, build | **authored**, optional `"near-white"` or `"silhouette"` (issue #905). An explicit `--seam` overrides the config; otherwise this field overrides the existing `near-white` default. An invalid value is `CONFIG_FIELD_TYPE` at `config.assemble.seam`, including when a CLI override is given. Absent, existing build bytes are unchanged. |
 | `assemble.rig_scale` | assemble — the rig is `trunc(w × rig_scale)` x `trunc(h × rig_scale)`, and every rig-px value after it (`bones`, `meshes`, `motion`, `patches`, `cuts`) is in that rig's pixels; `check --source` (`CHECK_SOURCE_SIZE`) and `compose` (`SCENE_RIG_SCALE_AGREES`) read it back off `parts.json` | authored; rig pixels per source pixel. 0.5 in both examples (a 1664x2432 painting makes an 832x1216 rig). **Keep the figure about 1,100 to 1,200 rig px tall** — the `H` of `propose`'s `mesh spacing:` note, the height of the parts' boxes together — so for another painting, about 1,150 over the figure's height in painting px: that is the size the proposer's spacing divisor was calibrated at (H 1106–1185, the `mesh spacing` note says so) and the size of the two examples `check`'s bars are derived from, and the proposer and `check` also hold fixed rig-px values that do not scale with it (the fringe's 10 px step, the trunk segments' 18, 20, 30 and 100 px, the 15 px wrist tolerance, the 10-row pendant floor, the seam bar's 50 rig px over 40). What else it trades, measured on `demo` with the README loop from a fresh config at 0.25, 0.5 and 1 (issue #345, rig-c 2.47.1): the same plan and the same ten chains; every bar but the one the uncorrected `demo` always fails (`bottomwear` `TIP_OVER_ROOT`, the README loop's `RL01`) passing at all three; the atlas page 418x606, 832x1205 and 1825x2047; the figure's mesh spacing 16, 32 and 64, so 830, 868 and 932 triangles; the breath 2.5 % of a torso that scales with it; and the proposed bones, scaled to 0.5, off the 0.5 proposal's by up to 38 px at 0.25 and 22.5 px at 1 (the hairpin's origin; the skirt roots 20 and 10.5) — the fixed-px values above. `propose` records it on the proposal as `proposed_rig_scale` (issue #354), and changing `assemble.rig_scale` after the rig sections are written is refused (`CONFIG_PROPOSED_RIG_SCALE`): without that refusal `demo`'s tracked config built at 0.25 gated green and `check` failed only `TIP_OVER_ROOT` on both sleeves (`propose --from-config` named 54 `LINT` lines, links off the art) — re-run `assemble` and `propose` at the new scale. Absent: `CONFIG_FIELD_PRESENT`; 0, negative or not a number: `CONFIG_FIELD_TYPE`; a rig under 1x1: `ASSEMBLE_RIG_SIZE` |
 | `assemble.plan` | assemble; also the list every `meshes`/`regions` key must come from | **proposed** by `assemble --propose-plan`. `[part name, "full" \| "head", See-through tag]`, in draw order back to front. Names are free; roles come from the tag. A layer the author made and added to a run takes `author:<label>` in the tag's place, and has no role (§5, *A layer the author made*). When `generation.control.skeleton` is present and a full-run `handwear-r` or `handwear-l` layer merges sleeve, bare hand and overgarment drape into one layer — a skin-coloured hand cluster (`>= 40` run px, `GHOST_MIN_AREA`, measured `516..4,787` run px across the 9-standee corpus) lies within `0.35` forearm lengths of `<s>_wrist` and non-skin pixels reach more than `1.0x` the forearm length (`<s>_elbow -> <s>_wrist`) below `<s>_wrist` (issue #490; measured `-0.15x..0.45x` on the 6 clean standees vs `1.25x..2.02x` on the 3 merged standees, placing `1.0x` inside the `0.45x..1.25x` gap) — the layer is split into `drape-<s>`, `handwear-<s>` and `hand-<s>` (back to front) when the Euclidean RGB distance between the sleeve median colour above `<s>_wrist` and the drape median colour below `<s>_wrist` is at least `80` (`ARM_DRAPE_COLOR_DISTANCE`, measured `103.6..236.0` on the two distinct-colour merged standees vs `20.8..28.2` on the same-colour merged standee, placing `80` between `28.2` and `103.6`), or refused with `SEETHROUGH_ARM_RUN_MERGED` when the distance is under `80` |
 | `assemble.extend_below_crop` | assemble | **proposed** with the plan: `{part, run, tag}` — a head-run part that reaches the bottom of the head crop is continued from a full-run layer, whole connected components |
@@ -5233,6 +5234,7 @@ and stay absent).
 | <a id="RIG_TURN_SURFACE_MESH_BINDINGS"></a>`RIG_TURN_SURFACE_MESH_BINDINGS` | an authored surface mesh has unresolved/nonclosing weights or shares a frame moved by a unit/rear turn carrier; declared stop draw aliases resolve to their links for setup sampling | provide weighted bindings closing at 1 in the authored frame; `<link>_d` resolves only for links declared in `config.stops`; use independent chains for parts with different roles |
 | <a id="RIG_TURN_SURFACE_MESH_ATTACHMENT"></a>`RIG_TURN_SURFACE_MESH_ATTACHMENT` | a surface mesh has an alternate drawing without its own registered depth sampling frame | use the base attachment; explicit islands retain their own slot, attachment and bindings |
 | <a id="RIG_TURN_BODY_UNCOVERED"></a>`RIG_TURN_BODY_UNCOVERED` | **Warning:** a shown part without a body role overlaps a moved `turn.body` surface at setup alpha >= 128 and has different emitted endpoint displacement | declare the intended body role and inspect both endpoints; no role or depth is inferred |
+| <a id="RIG_TURN_HEAD_ROLL"></a>`RIG_TURN_HEAD_ROLL` | **Warning:** a declared head turn has an absolute authored-eye-origin roll above the empirical limit displayed as 18.485385 degrees; names the face/eye parts, both eye bones, signed roll and limit | inspect the neck at both extremes; this proxy does not detect the painting independently, correct tilt or change emitted bytes; see [Head roll before a declared turn](#head-roll-before-a-declared-turn) |
 | <a id="RIG_TURN_SURFACE_DEPTH_REQUIRED"></a>`RIG_TURN_SURFACE_DEPTH_REQUIRED` | a part with role `"surface"` in `config.turn.roles` or `config.turn.body.roles` carries no depth sheet in `parts.json` | run `assemble` with `config.depth` or provide `<part>_depth.png` in `parts.json` |
 | <a id="RIG_TURN_GRID_BUDGET"></a>`RIG_TURN_GRID_BUDGET` | a `"surface"` grid exceeds 2,400 triangles on one slot or 4,000 triangles across all `"surface"` slots | lower `config.turn.grid` / `config.turn.body.grid` `[cols, rows]` within the per-slot and total budgets |
 | <a id="RIG_TURN_HEAD_BONE"></a>`RIG_TURN_HEAD_BONE` | `buildRig` found no `"head"` (or body turn root) bone when emitting 2.5D turn carriers | declare `"head"` (or the body turn root bone) in `config.bones` |
@@ -5663,7 +5665,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 |
+| <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; with `--source`, no declaration is SKIP with its reason and declaration remedy; 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 —
@@ -6229,7 +6231,22 @@ 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.
+With `--source` but no `setup_painting` declaration, `SETUP_MATCHES_PAINTING`
+is explicitly **SKIP** in the console, `check.json`, the report's skipped-bar
+list and `check --json`. Its reason says the comparison was not measured and
+asks for `--requirements <file>` declaring `setup_painting.rgb_tolerance` and
+named `regions` with `box` and authored `max_pixels` limits. The SKIP changes
+no exit code and invents no metric, region or limit. This applies both without
+a requirements file and with one that omits the key. Without `--source` and
+without the declaration, the line stays absent. Declared observations retain
+their output bytes and renderer calls.
+
+`check --json` prints only the completed `check.json` object to stdout, with
+the same bytes as the file and the same exit code as ordinary `check` (0 or 1).
+Early input refusals and usage errors retain their named text and exits (1 or 2);
+they have no completed check object. `build --json` is refused by name: run
+`check --rig <out>/rig --parts <out> --out <dir> --json` after the build to read
+the completed check object.
 
 The observation is the actual renderer's setup pose, without animation or
 physics advancement, from the already gated setup candidate. Its viewport is
@@ -6566,6 +6583,47 @@ art. An authored `parts.json` depth reference remains an active standalone
 guards still apply. With binding inactive there is no added reference, file or
 legacy-byte change. #773 adds no image generation, geometry or motion model.
 
+### Head roll before a declared turn
+
+`rig` and `build` report `WARN RIG_TURN_HEAD_ROLL` when a declared head
+turn (`turn.depths` or `turn.roles`, including the depth-sampled producer)
+has an absolute setup eye-line roll above 18.485385 degrees (six-place display).
+The line names the face part (or the eye parts without a face), the signed
+roll, its absolute value, the limit, and both eye bones and parts. It reads
+the existing `eyeLineDegrees` on the authored `eye_r` and `eye_l` origins,
+image-left to image-right in Spine degrees, counter-clockwise; it does not
+detect the painting's tilt independently of those authored origins, estimate
+tilt from a bounding box, or invent a reading without both eye parts
+and bones or when their origins share a column.
+
+The limit is the midpoint between the maximum absolute roll of the measured
+public controls, 4.864514 degrees, and the tilted `three-quarter`
+input from issue #900, 32.106256 degrees. The comparison uses the unrounded
+midpoint. The controls are the five
+parts examples plus the published dancer config and head-turn demo's compiled
+setup eye origins. The named quiet controls read 3.239700 degrees
+(`reference-demo`), -1.941486 degrees (`dancer`), and
+0.520856 degrees (head-turn demo). This is an empirical separation
+of these inputs, not an anatomical limit or a visual-quality verdict.
+
+The parts configs were read at
+[`38e5f574`](https://github.com/rig-c/parts/tree/38e5f574a88b2e6753a982b0ee0952dbf273a12e/examples),
+the [dancer config](https://github.com/rig-c/examples/blob/564285414fccf7b47df32501c0b3c2968db77691/dancer/config.json)
+at `56428541`, and the
+[head-turn model](https://github.com/rig-c/rig-c.github.io/blob/989cebbd6733a58142923cec96fe2333da08194a/demos/head-turn/bundle/skeleton.model.json)
+at `989cebbd`. The [issue #900](https://github.com/rig-c/parts/issues/900)
+bootstrap used public `three-quarter` inputs at examples commit
+`ba99e403d4058fc1cfe40699bdcde8aaf00a90c0`; its authored crop-pixel eye origins
+are `[236, 136]` and `[287, 104]`. The compiled demo is a setup metric control,
+not a rebuild of its unavailable parts config.
+
+An already rolled head is turned about upright yaw/pitch axes; inspect its
+neck at both extremes before accepting that motion. This warning does not
+refuse the build, correct the tilt, add a roll axis, or change any pose or
+emitted file. With no head turn, including a body-only turn, it adds no warning.
+With an unreadable eye line the existing face-axis report retains its reason;
+silence is not a measured zero. The warning lives only in the stage report.
+
 ### Missing body-turn coverage
 
 `RIG_TURN_BODY_UNCOVERED` warns when a shown part without a
@@ -6682,6 +6740,26 @@ The trial's role relief/width ratios (face 0.1264803, front hair 0.1018772,
 back hair 0.0857722, ornament 0.0375868, garment 0.0990473) came from one
 head-turn demo's p5..p95 depth and part widths. They are measured starting
 points for declared proportions, not anatomical laws or default calibration.
+For a head-referenced calibration, declare
+`relief = referenceRoleRelief * targetFaceWidth / referenceFaceWidth`, using
+the assembled target face width and the same declared reference head measure
+for every role. This keeps head relief on one scale when a hair silhouette
+is much wider than the face. In contrast, `roleRatio * targetPartWidth`
+increases relief with that silhouette while the group's `zScale` stays fixed.
+An ornament narrower than its reference can gain relief under the head rule;
+inspect it as well as the widest part. The command derives neither rule:
+write the resulting rig-pixel `relief` explicitly in each recipe entry.
+
+Compare calibrations on identical prepared inputs and numeric maps, with the
+same medians, group pivot and `zScale`; only the declared relief changes.
+Read each named report row's `relief`, `zScale` and `clipFraction` before
+judging its render. The clipping denominator is every original part pixel
+with alpha >=128, including boundary support, never the padded input area.
+A low clipped fraction does not establish shape quality. Inspect setup,
+both yaw endpoints and their difference at native scale, then enlarge the
+same pixels with nearest-neighbour sampling. Neither clipping nor agreement
+with a reference map substitutes for that inspection.
+
 The owner's preference for per-part volume is subjective provenance, not an
 automated quality conclusion. Model licence posture remains the owner's choice.
 

package/docs/STABILITY.md

@@ -62,7 +62,7 @@ defaults are the help's too, and none is guessed from the art.
 | `propose` | `--parts`, `--source`, `--out`, `--full`, `--head`, `--write-config` together: the [neck draft](AUTHORING.md#a-neck-that-moves-on-its-own) for an existing config with `turn.body` and one neck plan row; reassembles under `<out>/rig`, preserves the sampled turn and drafts a rigid neck unit (issue #826) |
 | `compare` | `--left`, `--right`; optional `--map` |
 | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
-| `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills`, `--no-extremes` (issue #829), `--set` or `--all-sets` (issue #454), `--environment` (issue #538, additive), `--wind-band` (issue #590, additive) |
+| `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills`, `--no-extremes` (issue #829), `--set` or `--all-sets` (issue #454), `--environment` (issue #538, additive), `--wind-band` (issue #590, additive), `--json` (issue #904) |
 | `loop` | `--frames`, `--out`; optional `--palette` |
 | `build` | `--config`, `--source`, `--full`, `--out`; optional `--head` (as for `assemble`), `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--lead-in`, `--requirements`, `--idle-keys`, `--seam-pairs`, `--keep-stills`, `--no-extremes` (issue #829), `--alt` (as for `assemble`, issue #454), `--set` or `--all-sets` (as for `check`, issue #454), `--environment` (as for `check`, issue #538, additive), `--wind-band` (as for `check`, issue #590, additive) |
 | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
@@ -116,6 +116,18 @@ rules that make the contract:
 - **`turn`** (issue #251) adds a control bone `turn` under `root` that nothing
   keys, and carries each part in `depths` by `(pivot − depth) / (pivot − nearest
   depth)` of its x. Without the field no byte of any output moves.
+  A declared head turn (`depths` or `roles`) reports `RIG_TURN_HEAD_ROLL`
+  when the absolute setup eye-line roll exceeds the limit displayed as
+  18.485385 degrees
+  (issue #903). This empirical limit is the midpoint of the measured public
+  control maximum, 4.864514 degrees, and `three-quarter`,
+  32.106256 degrees (the comparison uses the unrounded midpoint). The warning
+  names the face/eye parts, the eye
+  bones, signed roll and limit. It is report-only: no refusal, field, pose or
+  emitted-byte change. No head turn, a body-only turn, or an unreadable eye
+  line adds no warning; unreadable retains the existing face-axis reason.
+  See [Head roll before a declared turn](AUTHORING.md#head-roll-before-a-declared-turn)
+  for the measurement scope and its limits.
 - **`scene`** (issue #242) declares the painting a scene — the figure and what
   is round it — and takes no field: `{}`. With it `assemble` reads the
   recomposite inside the figure (the union of the full run's layers at alpha
@@ -135,7 +147,7 @@ part name, `[i]` an entry of a list):
 - **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
 - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`, `arm_split`
 - **seethrough.arm_split** — required: `order`, and one of `x` or `line` (issue #439)
-- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `extend_painting`, `take`
+- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `extend_painting`, `take`
 - **assemble.alternates[i]** — required: `name`; optional: `source`, `full`, `head`, `parts`, `hides`, `head_box`, `cuts`, `skeleton`, `anchor`, `base_anchor`, `drawn`, `tips`, `front`, `layers`, `focus` (issues #454, #465, #543, #652, #664, #666, #719, #780). `focus` is an authored finite `[x, y]` in painting pixels, within its canvas (edges included), refused as CONFIG_SET_FOCUS before assemble output when invalid; only when present, `parts.json` records it with focus_source_size and `sets.json` emits it in setup-world coordinates through the actual rig resize and `src/coords.ts`. Absent focus emits no field or inferred value; changing/removing it requires reassembly
 - **assemble.extend_below_crop[i]** — required: `part`, `run`, `tag`
 - **assemble.extend_painting[i]** — required: `part`, `band`, `max_distance`; optional: `min_held_alpha`, `order` (issues #848, #854, #855; explicit final layer-derived part, half-open rig band and positive four-neighbour path bound; base painting only). The optional integer floor 1–255 admits exact original alpha-over coverage strictly below it; absent or 1 blocks every nonzero holder. Only selected target samples below the floor may take painting RGBA; target samples at/above the floor and every non-target holder remain exact. By default overlapping reachable claims refuse. With `order` on every entry (unique nonnegative safe integers), lower values claim first and their gains block later candidates and paths; array order never breaks ties or supplies missing precedence
@@ -206,6 +218,11 @@ part name, `[i]` an entry of a list):
 - **waist** — required: `top`, `bottom`, `upper`, `lower`, `bone`, `constraint` (#650; absent keeps the ordinary bindings and graph)
 <!-- /stable:config -->
 
+`assemble.seam` accepts `near-white` or `silhouette` (issue #905). CLI
+`--seam` overrides config, then the existing `near-white` default applies.
+Invalid values refuse as `CONFIG_FIELD_TYPE` at `config.assemble.seam`;
+an absent field preserves existing output bytes.
+
 `TY14` holds the set of field names in backticks above to the set of names the
 loader's object checks spell (every `c.object(…)` in `src/config.ts`, with the lists
 they name), in both directions, and refuses an object check whose key list it cannot
@@ -507,10 +524,17 @@ 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
+`SETUP_MATCHES_PAINTING` measurement when declared. It requires authored
 `rgb_tolerance` and named native-stage boxes. Each optional `max_pixels` is
-that whole region's limit; omission is SKIP, never PASS. Existing files without
-the key retain their output bytes and renderer calls. Other requirement fields
+that whole region's limit; omission is SKIP, never PASS. With `--source` but
+no declaration, the console, `check.json` and the report's skipped-bar list now
+say SKIP with the reason and the `--requirements` declaration remedy; exit
+codes stay unchanged. No metric, region or limit is invented. Without source
+and without the key, the line stays absent. Declared output bytes and renderer
+calls remain unchanged. `check --json` prints the completed `check.json` bytes
+to stdout and keeps the ordinary check's exit code; early input refusals and
+usage errors keep their existing named text and exits. `build --json` is refused
+with a `check --json` remedy; build keeps its multi-stage text report. 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
@@ -540,3 +564,9 @@ encoding, convexity sign and refusal remedies are in
 calls these stages; no-config builds retain their existing behavior and bytes.
 Group numbers and unit depths are explicit; no provider or absolute scale is
 inferred. A new depth stage never replaces Core's rig gate.
+`relief` is an explicit rig-pixel value, not an implicit width multiplier.
+Part-width and head-referenced calibrations are authored recipe choices;
+changing a calibration requires preparing its recipe again. Compare the same
+provider maps and preserve their provenance. Each report row names the part,
+declared relief, group `zScale` and clipping over original alpha>=128 support;
+it remains a measurement rather than a shape-quality gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.87.0",
+  "version": "1.88.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,4 @@
+import { type SeamRule } from './seamrule.ts';
 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';
@@ -188,16 +189,7 @@ export const SILHOUETTE_BORDER = 8;
 /** `figureSilhouette`: a pixel is figure where it differs from that median by more than this, max channel. */
 export const SILHOUETTE_LIMIT = 40;
 
-export type SeamRule = 'near-white' | 'silhouette';
-export const SEAM_RULES: readonly SeamRule[] = ['near-white', 'silhouette'];
-
-/**
- * The seam rule a run uses when none is named. Set by measurement, not taste:
- * the silhouette rule ships as the default only if it lowers the error pixel
- * count on every oracle character without raising mean |d| on any
- * (ORACLE_assemble.md, *faithful vs silhouette*).
- */
-export const DEFAULT_SEAM_RULE: SeamRule = 'near-white';
+export { DEFAULT_SEAM_RULE, SEAM_RULES, type SeamRule } from './seamrule.ts';
 
 /**
  * Where a layer may take the painting's pixel (`projectSource`). `core` is the

package/src/build.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_SEAM_RULE } from './seamrule.ts';
 import { SETUP_PAINTING_LINE, setupPaintingLines } from './setuppainting.ts';
 import { writeMaterialSources } from './cutmaterialio.ts';
 import { CUT_MATERIAL_LINE, CUT_MATERIAL_SOURCES, materialLines } from './cutmaterial.ts';
@@ -164,7 +165,7 @@ export interface AssembleStageInput {
   /** The head run, or null for one run that holds the face (issue #359). */
   head: string | null;
   config: string;
-  seam: SeamRule;
+  seam?: SeamRule;
   project: ProjectRule;
   /** `--alt` entries, merged with `config.assemble.alternates` by set name (issue #454). */
   alts?: readonly AlternateCliInput[];
@@ -327,13 +328,14 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   // The early door: assemble runs before propose has drafted bones, meshes,
   // regions and motion, so it requires only what it reads (issue #20).
   const cfg = loadEarlyConfig(input.config, 'assemble');
+  const seam = input.seam ?? cfg.assemble.seam ?? DEFAULT_SEAM_RULE;
   const src = readSource(input.source);
   const runs = applyTakenLayers(readRuns(input.full, input.head), src, cfg, input.config);
   for (const note of runs.notes) log(`note: ${note}`);
   const fields = stageFields(cfg, runs.single ? { w: src.width, h: src.height } : null);
   const under = readUnders(input.config, fields.cuts);
   const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
-  const result = assemble({ source: src, full: runs.full, head: runs.head, depth: cfg.depth, depthBase: dirname(resolve(input.config)), ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: input.seam, projectRule: input.project });
+  const result = assemble({ source: src, full: runs.full, head: runs.head, depth: cfg.depth, depthBase: dirname(resolve(input.config)), ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: seam, projectRule: input.project });
 
   // Issue #454: alternate painting sets, assembled before any file is written.
   const configDir = dirname(resolve(input.config));
@@ -673,7 +675,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
         ...(fields.yieldRefused === undefined ? {} : { yieldRefused: fields.yieldRefused }),
         ...(fields.turnMovingPair === undefined ? {} : { turnMovingPair: fields.turnMovingPair }),
         ...(fields.turn === undefined ? {} : { turn: fields.turn, regions: fields.regions, meshes: fields.meshes, motion: fields.motion }),
-        seamRule: input.seam,
+        seamRule: seam,
         projectRule: input.project,
         ...(altExclude.length === 0 ? {} : { exclude: altExclude }),
         ...(altIslands.length === 0 ? {} : { limbIslands: altIslands }),
@@ -2218,7 +2220,7 @@ export interface BuildInput {
   /** The head run, or null for one run that holds the face (issue #359). */
   head: string | null;
   out: string;
-  seam: SeamRule;
+  seam?: SeamRule;
   project: ProjectRule;
   loop: boolean;
   /** `--page-edges` for both packed builds, the rig stage's gate and the check's artifact. */
@@ -2253,7 +2255,7 @@ export interface BuildInput {
   windBand?: string;
 }
 
-/** What `build` does with one flag `check` takes: hands it to its check stage, takes it as its own, or refuses it because build supplies the value itself. */
+/** What `build` does with one flag `check` takes: hands it to its check stage, takes it as its own, or refuses it because build supplies the value or report itself. */
 export type CheckFlagInBuild =
   | { as: 'forwarded' }
   | { as: 'own'; why: string }
@@ -2280,6 +2282,7 @@ export const CHECK_FLAGS_IN_BUILD: Readonly<Record<string, CheckFlagInBuild>> =
   '--no-extremes': { as: 'forwarded' },
   '--environment': { as: 'forwarded' },
   '--wind-band': { as: 'forwarded' },
+  '--json': { as: 'supplied', why: 'build supplies its multi-stage text report; run check --rig <out>/rig --parts <out> --out <dir> --json for the completed check object' },
 };
 
 /** The requirements file build's check reads (issue #556): `read` is where it is opened, `recorded` what `check.json` names it by. */
@@ -2315,7 +2318,7 @@ export function buildRequirements(flag: string | undefined, declared: string | u
   ]);
 }
 
-/** The `build` refusal of a `check` flag build supplies itself ({@link CHECK_FLAGS_IN_BUILD}), or null for any other flag. */
+/** The `build` refusal of a `check` flag whose value or report build supplies itself ({@link CHECK_FLAGS_IN_BUILD}), or null for any other flag. */
 export function suppliedCheckFlag(flag: string): string | null {
   const row = Object.hasOwn(CHECK_FLAGS_IN_BUILD, flag) ? CHECK_FLAGS_IN_BUILD[flag] : undefined;
   return row?.as === 'supplied' ? `build does not take "${flag}"; ${row.why}` : null;
@@ -2408,7 +2411,6 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   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.
   const idleKeys = input.idleKeys ?? DEFAULT_IDLE_KEYS;
-  log(`rig-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? `, with the idle loop${input.leadIn === undefined ? '' : ` after a lead-in of ${input.leadIn} period(s)`}` : ''}`);
 
   let req: BuildRequirements | null = null;
   let configRecord: InputFileRecord | null = null;
@@ -2420,6 +2422,8 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
     // Issue #556: the flag, or the config's declaration when there is none; both naming other bytes is refused here.
     // Issue #607: the bytes this read parsed are the ones check.json's config record hashes, under the path as typed.
     const loaded = loadConfigWithBytes(input.config);
+    const seam = input.seam ?? loaded.config.assemble.seam ?? DEFAULT_SEAM_RULE;
+    log(`rig-parts build: ${input.config} -> ${out}, seam rule ${seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? `, with the idle loop${input.leadIn === undefined ? '' : ` after a lead-in of ${input.leadIn} period(s)`}` : ''}`);
     configRecord = inputFileRecord(loaded.bytes, input.config);
     req = buildRequirements(input.requirements, loaded.config.requirements, input.config);
     // The same for the requirements file's own shape; its names resolve against the rig, in the check, before it builds.
@@ -2429,7 +2433,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, ...(req === null ? {} : { requirements: req.read }), ...(input.alts === undefined ? {} : { alts: input.alts }) },
+      { source: input.source, full: input.full, head: input.head, config: input.config, 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,4 +1,4 @@
-import { SETUP_PAINTING_LINE, setupPaintingBounds, setupPaintingLine, type SetupPainting, type SetupPaintingLine } from './setuppainting.ts';
+import { SETUP_PAINTING_LINE, UNDECLARED_SETUP_PAINTING_REASON, setupPaintingBounds, setupPaintingLine, type SetupPainting, type SetupPaintingLine, type SetupPaintingObservation } 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';
@@ -2730,8 +2730,8 @@ 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;
+  /** Under --source: the declared observation, or an explicit undeclared SKIP. */
+  [SETUP_PAINTING_LINE]?: SetupPaintingObservation;
   [CUT_MATERIAL_LINE]?: MaterialLine;
   PASS: boolean;
 }
@@ -6476,7 +6476,8 @@ 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;
+  let setupPainting: SetupPaintingObservation | null = inp.source !== null && reqFile?.setup_painting === undefined
+    ? { status: 'SKIP', reason: UNDECLARED_SETUP_PAINTING_REASON } : null;
   if (inp.parts !== null || inp.source !== null || fixedSkeleton !== undefined) {
     try {
       mkdirSync(stillDir, { recursive: true });

package/src/config.ts

@@ -1,3 +1,4 @@
+import { SEAM_RULES, type SeamRule } from './seamrule.ts';
 import type { TakeLayers } from './takelayers.ts';
 import { paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
 import { baseAnchorProblems, type BaseAnchor } from './baseanchor.ts';
@@ -300,6 +301,8 @@ export interface AlternateSetConfig {
 }
 
 export interface Assemble {
+  /** Optional per-character seam rule; an explicit CLI flag wins. */
+  seam?: SeamRule;
   /** Verified named replacements from another See-through run (#866). */
   take?: TakeLayers[];
   /** Rig pixels per source pixel. */
@@ -1622,7 +1625,7 @@ export interface EarlyConfig {
   depth?: DepthConfig;
   key: string;
   seethrough: SeeThrough;
-  assemble: { rig_scale: number; take?: TakeLayers[]; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
+  assemble: { rig_scale: number; seam?: SeamRule; take?: TakeLayers[]; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
 }
 
 /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
@@ -1691,8 +1694,9 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'layers') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     if ('assemble' in t) {
-      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take']);
+      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam']);
       if (a !== null) {
+        checkSeam(c, a);
         if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
         if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
           c.fail('CONFIG_FIELD_TYPE', 'config.assemble.head_face_underfill', `is ${show(a.head_face_underfill)}; true or false is required`);
@@ -2457,10 +2461,17 @@ function checkTakeLayers(c: Check, value: Json): void {
   });
 }
 
+function checkSeam(c: Check, a: Record<string, Json>): void {
+  if ('seam' in a && !(SEAM_RULES as readonly unknown[]).includes(a.seam)) {
+    c.fail('CONFIG_FIELD_TYPE', 'config.assemble.seam', `is ${show(a.seam)}; one of ${SEAM_RULES.join(', ')} is required`);
+  }
+}
+
 function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
   const required = sectionRequired(door, 'assemble');
-  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take']);
+  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam']);
   if (a === null) return { parts: [], patches: [], cuts: [] };
+  checkSeam(c, a);
   if (required.includes('plan') && !('plan' in a)) {
     c.fail('CONFIG_FIELD_PRESENT', 'config.assemble.plan', 'is absent and required; `assemble --propose-plan` prints one from the two runs — paste its plan and extend_below_crop into config.assemble');
   }

package/src/rig.ts

@@ -309,6 +309,14 @@ function lineGap(a: number, b: number): number {
 /** The bones the face's line runs through: rigc's A51 draws its line through their origins, and the face bones are turned to that same line. */
 export const EYE_BONES: readonly [string, string] = ['eye_r', 'eye_l'];
 
+/**
+ * Issue #903: midpoint of absolute setup eye-line rolls measured on the public
+ * controls (maximum 4.864514437760526 degrees across the five parts examples,
+ * dancer and the head-turn demo) and three-quarter (32.106255955117845 degrees).
+ * This separates those inputs; it is not an anatomical or visual-quality bar.
+ */
+const HEAD_TURN_ROLL_LIMIT = (4.864514437760526 + 32.106255955117845) / 2;
+
 /**
  * The eye line (issue #239). It exists when parts.json holds an eye on each
  * side — the first part tagged `eyewhite-r` and the first tagged `eyewhite-l`
@@ -3656,6 +3664,15 @@ export function buildWaistPairSource(
     boneLandmarks.set(bName, [bEntry.x, bEntry.y]);
   }
   const turnWarnings: Problem[] = [];
+  if ((cfg.turn?.depths !== undefined || cfg.turn?.roles !== undefined) && line.degrees !== null && Math.abs(line.degrees) > HEAD_TURN_ROLL_LIMIT) {
+    const faces = parts.parts.filter(p => tagOf(p.from) === 'face' && p.cut_from === undefined).map(p => p.name);
+    const names = faces.length === 0 ? line.parts : faces;
+    turnWarnings.push({
+      code: 'RIG_TURN_HEAD_ROLL',
+      object: `${names.length === 1 ? 'part' : 'parts'} ${names.map(n => `"${n}"`).join(', ')}`,
+      detail: `setup eye-line roll ${pyRound(line.degrees, 6)} degrees (Spine, counter-clockwise), absolute ${pyRound(Math.abs(line.degrees), 6)} exceeds limit ${pyRound(HEAD_TURN_ROLL_LIMIT, 6)} degrees; read through authored ${EYE_BONES.join(' and ')} origins on ${line.parts.map(n => `"${n}"`).join(' and ')} (an eye-origin proxy, not painting detection); the declared head turn uses upright yaw/pitch axes on an already rolled head; inspect the neck at both turn extremes; warning only, no pose or output changed`,
+    });
+  }
   if (cfg.turn?.roles !== undefined || cfg.turn?.body !== undefined) {
     buildDepth25DTurn(rig, motion, {
       warnings: turnWarnings,

package/src/seamrule.ts

@@ -0,0 +1,11 @@
+/** Shared seam choices for the config reader and assembly. */
+export type SeamRule = 'near-white' | 'silhouette';
+export const SEAM_RULES: readonly SeamRule[] = ['near-white', 'silhouette'];
+
+/**
+ * The seam rule a run uses when none is named. Set by measurement, not taste:
+ * the silhouette rule ships as the default only if it lowers the error pixel
+ * count on every oracle character without raising mean |d| on any
+ * (ORACLE_assemble.md, *faithful vs silhouette*).
+ */
+export const DEFAULT_SEAM_RULE: SeamRule = 'near-white';

package/src/setuppainting.ts

@@ -74,6 +74,10 @@ export interface SetupPaintingLine {
   reason?: string;
 }
 
+/** An undeclared observation has no measured pixels, inferred regions or limit. */
+export type SetupPaintingObservation = SetupPaintingLine | { status: 'SKIP'; reason: string };
+export const UNDECLARED_SETUP_PAINTING_REASON = 'setup_painting is undeclared; setup-to-painting was not measured. To measure it, give --requirements <file> declaring setup_painting.rgb_tolerance and setup_painting.regions with name, box and authored max_pixels limits';
+
 /** 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.
@@ -119,7 +123,8 @@ export function setupPaintingLine(
     ...(noLimit ? { reason: 'a region has no declared max_pixels; it is measured as SKIP, never PASS' } : {}) };
 }
 
-export function setupPaintingLines(line: SetupPaintingLine): string[] {
+export function setupPaintingLines(line: SetupPaintingObservation): string[] {
+  if (!('regions' in line)) return [`${SETUP_PAINTING_LINE}: SKIP — ${line.reason}`];
   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)'}`)])];