rig-parts 1.87.0 → 2.0.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 |
@@ -172,7 +173,7 @@ read by no CPU stage).
 | `motion.blink.still` | rig | **proposed** only for a lash `propose` notes (below), then checked: `{<part>: {row, bone}}` — the rows of that region part above `row` (rig px, y down) are drawn by a second slot `<part>_still` on `bone` and do not blink; rows from `row` down keep the part's slot and blink. The part must be a region on a bone `eyes` names, `bone` one it does not (`CONFIG_STILL_OFF_THE_BLINK`), and `row` a row of the part with no art across its whole width (`RIG_STILL_ROW_CLEAR`) |
 | `motion.animations_from` | rig; check (named; read for folds) | optional, never proposed (issue #183): a path, relative to the config file's directory, to a file in rig-c's motion-spec shape, `{"spec": "rigc-motion/1", "animations": {"<name>": {"duration": …, "tracks": [...]}, …}}` — an expression, a gesture, anything beside the idle. On every `rig` and `build` each of its animations is written into `rig/motion.json` after `idle`, as read: nothing added, re-keyed or judged here (except `derive` keys on `turn`/`tilt`, issue #436, and `{"t": …, "set": "<name>" \| null}` keys on slot `"attachment"` tracks, issue #473, which expand to `"v": "<set>_<slot>"` or `"v": null` when the set hides the slot, or `"v": "<slot>"` for `null`, refused with `CONFIG_SET_COVERS_SLOT` when the set is undeclared or does not cover the track's slot), and each is rigc's to accept or refuse at the rig stage's gate, in rigc's words. It may name what `motion.json` already holds — the bones `bones` declares, the easings `shut` and `open`, the groups `eyes` and `brows` when the blink writes them — and nothing else from the file reaches it. The loader refuses, every problem at once: no such file or one that cannot be read (`CONFIG_FILE_PRESENT`), text that is not JSON (`CONFIG_IS_JSON`), a file that is not an object, a `spec` other than `"rigc-motion/1"`, an `animations` that is not a table of objects (`CONFIG_FIELD_TYPE`), any other key — rig-c's `easings`, `groups`, `setup`, `physics`, `mix`, `archetype` and `cut` included, which would be read and not written (`CONFIG_KEY_KNOWN`), an animation named `idle` (`CONFIG_ANIMATION_NAME_FREE`), and a key written twice in one object of the file, which JSON would fold into its last value without a word (`CONFIG_KEY_UNIQUE`). `check` names the others on one line (`beside the idle: …`) and reads each for folds, with the idle — `ANIMATIONS_DO_NOT_FOLD` (§7, issues #320, #333); every other bar reads the idle. Absent, `motion.json` holds the idle alone, byte for byte as before, and `check` reads that idle for folds |
 | `constraints` | rig (handed to rig-c as `rig.json`'s `constraints`); `compare` and the coverage lines (roles) | **authored**, optional; `propose` writes none, but with `--cloth` (issue #364), where it writes the recipe's physics and swing transforms (*Recipe: cloth and hair that answer the world*, below). A list of constraints in **rig-c's own rig-spec shape** (`RigConstraint`: `ik`, `transform`, `path`, `physics`, `slider` — rig-c's `src/rig.ts` documents every field), in the order rigc applies them. The loader checks only what this package owns: each entry is an object with a `type` rigc names (`CONFIG_CONSTRAINT_TYPE_KNOWN`) and a non-empty `name`, unique within its kind as rigc finds constraints (`CONFIG_CONSTRAINT_NAME_UNIQUE`; an ik and a transform may share one); every bone it names — `bones`, an ik's `target`, a transform's `source`, a physics or slider constraint's `bone` — is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`); the bone a constraint follows does not sit under a bone it drives (`CONFIG_CONSTRAINT_TARGET_DETACHED`). Every other field (`mix`, `softness`, `properties`, a path's `slot`, a slider's `animation`) and every value is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`) — an ik's `bones` as a shape too: from rig-c 2.15.0 rigc refuses an ik over more than two bones, or over a pair whose second bone is not the first's child (issue #103; this loader refused both itself until then). A note and an `x-` record may ride on an entry; the rig stage leaves them out of what it hands rigc. Under the default `--idle-keys ctl` a two-bone ik whose child link the idle keys is split by that link's control, and rigc refuses the pair: run `rig --idle-keys direct` or `build --idle-keys direct` (the rig stage adds that sentence, naming the flag on the command that ran, to rigc's line; `build` forwards it to its rig stage, issue #95). Each bone a constraint follows is declared to rigc as `invariants.detached` from every bone it drives, which rigc's gate rule `A25` checks |
-| `stops` | rig (handed to rig-c as `rig.json`'s `stops`, and moves slots, mesh weights and child bones on stopped links onto `<link>_d`); `propose --from-config` (`LINT stop on <chain> …`) | **authored**, optional (issues #404, #447): `[{chain, links?, against, at, inward, outward, lower?: {inward, outward}}]` — rig-c's leg stops (`RigStop`, rig-c 2.56.0, `@rig-c/core/src/stop.ts`). `chain` is a chain `bones` declares (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `links`, optional, is a non-empty list of links of that chain (`CONFIG_NAME_RESOLVES`, `CONFIG_FIELD_TYPE`), or absent for every link of `chain` in chain order; `against` is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `at` is `[x, y]` in `against`'s local space, as rig-c's stop takes it (`CONFIG_FIELD_TYPE`): since each chain link (`leg_r0`, `leg_r1`) is turned to point along its segment (`+x` from origin to next link or tip, `+y` 90° counter-clockwise in Spine world), `at: [d, n]` sits `d` px from `against`'s origin toward its end and `n` px perpendicular to it; `inward`, `outward` and `lower.inward`, `lower.outward` are finite numbers (`CONFIG_FIELD_TYPE`). Every other stop rule — non-negative bounds, each stopped link written by a constraint, `against` not under the stopped chain, the aim not degenerate, `\|rest\| + outward <= 180°` (`RIG_STOP_BOUNDS`) — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). **Rising-limb / prone geometry (issue #447):** rig-c's `expandStops` aims `<chain>_rest` from `links[0]`'s setup origin at `<chain>_touch` (`at` in `against`'s local frame) and clamps `<link>_d` inside `[rest − inward, rest + outward]`; Spine wraps rotation at `±180°`, so `\|rest\| + outward <= 180°` is required (`RIG_STOP_BOUNDS`). Whenever `<chain>_touch` lies **above** `links[0]`'s root in rig pixels (`ty < y0`, i.e. higher Spine `y` — e.g. stopping a hanging cloth chain against a rising shin `leg_<s1>` in a prone or kneeling pose where the knee sits below `links[0]` and the ankle above it, so positive `at[0]` walks upward along the shin past `links[0]`'s root), `rest` lands in the upper half-plane (`\|rest\| > 90°`) and `\|rest\| + outward` exceeds `180°`. Stop against the descending thigh (`leg_<s0>`), set `links` to start at a link whose root sits above `<chain>_touch`, or omit the stop when the rising shin sits outside the hanging chain's sweep; `propose --from-config` prints `LINT stop on <chain> …` with the exact coordinates and angles when `<chain>_touch` lies above `links[0]`'s root or `\|rest\| + outward > 180°`. For every stopped link `<link>`, the rig stage moves any slot on `<link>`, any mesh weight on `<link>`, and any bone whose parent is `<link>` (a branched cloth tree's branches hanging from `<trunk_last>`, before `--idle-keys ctl` adds `<bone>_ctl` and before `turn` adds `turn_<part>_<bone>`) onto `<link>_d`, the drawn link bone rig-c's `expandStops` creates at `<link>`'s setup frame to carry the clamped rotation. Absent, `rig.json` carries no `stops` and no byte of any output moves |
+| `stops` | rig (handed to rig-c as `rig.json`'s `stops`, and moves slots, mesh weights and child bones on stopped links onto `<link>_d`); `propose --from-config` (`LINT stop on <chain> …`) | **authored**, optional (issues #404, #447): `[{chain, links?, against, at, inward, outward, lower?: {inward, outward}}]` — rig-c's leg stops (`RigStop`, rig-c 2.56.0, `@rig-c/core/stop`). `chain` is a chain `bones` declares (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `links`, optional, is a non-empty list of links of that chain (`CONFIG_NAME_RESOLVES`, `CONFIG_FIELD_TYPE`), or absent for every link of `chain` in chain order; `against` is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `at` is `[x, y]` in `against`'s local space, as rig-c's stop takes it (`CONFIG_FIELD_TYPE`): since each chain link (`leg_r0`, `leg_r1`) is turned to point along its segment (`+x` from origin to next link or tip, `+y` 90° counter-clockwise in Spine world), `at: [d, n]` sits `d` px from `against`'s origin toward its end and `n` px perpendicular to it; `inward`, `outward` and `lower.inward`, `lower.outward` are finite numbers (`CONFIG_FIELD_TYPE`). Every other stop rule — non-negative bounds, each stopped link written by a constraint, `against` not under the stopped chain, the aim not degenerate, `\|rest\| + outward <= 180°` (`RIG_STOP_BOUNDS`) — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). **Rising-limb / prone geometry (issue #447):** rig-c's `expandStops` aims `<chain>_rest` from `links[0]`'s setup origin at `<chain>_touch` (`at` in `against`'s local frame) and clamps `<link>_d` inside `[rest − inward, rest + outward]`; Spine wraps rotation at `±180°`, so `\|rest\| + outward <= 180°` is required (`RIG_STOP_BOUNDS`). Whenever `<chain>_touch` lies **above** `links[0]`'s root in rig pixels (`ty < y0`, i.e. higher Spine `y` — e.g. stopping a hanging cloth chain against a rising shin `leg_<s1>` in a prone or kneeling pose where the knee sits below `links[0]` and the ankle above it, so positive `at[0]` walks upward along the shin past `links[0]`'s root), `rest` lands in the upper half-plane (`\|rest\| > 90°`) and `\|rest\| + outward` exceeds `180°`. Stop against the descending thigh (`leg_<s0>`), set `links` to start at a link whose root sits above `<chain>_touch`, or omit the stop when the rising shin sits outside the hanging chain's sweep; `propose --from-config` prints `LINT stop on <chain> …` with the exact coordinates and angles when `<chain>_touch` lies above `links[0]`'s root or `\|rest\| + outward > 180°`. For every stopped link `<link>`, the rig stage moves any slot on `<link>`, any mesh weight on `<link>`, and any bone whose parent is `<link>` (a branched cloth tree's branches hanging from `<trunk_last>`, before `--idle-keys ctl` adds `<bone>_ctl` and before `turn` adds `turn_<part>_<bone>`) onto `<link>_d`, the drawn link bone rig-c's `expandStops` creates at `<link>`'s setup frame to carry the clamped rotation. Absent, `rig.json` carries no `stops` and no byte of any output moves |
 | `turn` | rig (adds the turn control or 2.5D head-turn producer) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected, or **authored** for 2.5D depth-sampled head turns (issue #763): `{pivot?, depths?, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}, roles?, counter?, grid?, unitDepths?, body?}`. When `roles` is declared (`{<part>: "surface" \| "unit" \| "rear"}`, issue #763; `CONFIG_TURN_ROLE_UNKNOWN`, `CONFIG_TURN_SURFACE_REQUIRED`, `RIG_TURN_SURFACE_MESH_BINDINGS`, `CONFIG_TURN_UNIT_MESH_BONES`), the rig stage runs the 2.5D depth-sampled head-turn producer: it edge-extends each turn-bound part's depth sheet across its transparent border and semi-transparent fringe from the nearest fully opaque (`alpha === 255`) texel before `PAD = 4` clamping (`padTurnDepthSheet`, `DEPTH_SILHOUETTE_SIZE_MISMATCH`), keeps authored `"surface"` meshes and their skinning (#795), sampling each vertex at its weighted setup position on its own extended sheet and emitting one inverse-setup-bone offset per influence (`D = -(pivot + z - zRef) * sin(angle)`, on x for yaw and y for pitch, with no narrowing or 2D spin); shared frames moved by another turn role are refused (`RIG_TURN_SURFACE_MESH_BINDINGS`), as are alternate drawings without their own depth sampling frame (`RIG_TURN_SURFACE_MESH_ATTACHMENT`). It promotes `"surface"` regions to `generator: {kind: "grid", cols, rows, depth}` (`grid`: `[cols, rows]` or `{<part>: [cols, rows]}`, default `[13, 16]`, bounded at `<= 2,400` triangles per slot and `<= 4,000` total, `RIG_TURN_GRID_BUDGET`, `RIG_TURN_SURFACE_DEPTH_REQUIRED`, `RIG_TURN_SHARED_DEPTH_SCALE`), emits `faceshift` and `rear_shift` under `head` (`CONFIG_TURN_HEAD_BONE`, `RIG_TURN_HEAD_BONE`), `<part>_surface` and `<part>_unit` under `faceshift`, and `yaw_dial` and `pitch_dial` under `root` (`CONFIG_TURN_BONE_FREE`, `RIG_TURN_NAME_FREE`), re-parents `"unit"` region bones and `"rear"` bones and mesh weights to `faceshift` and `rear_shift` (while `"unit"` mesh parts receive their own `<part>_unit` carrier under `faceshift`, rebind direct `"head"` weights to `<part>_unit`, reparent bound chain roots to `<part>_unit` while keeping chain skinning weights intact, and key `<part>_unit` in `turn_units`, #790), samples each `"unit"` bone's depth from the `"surface"` depth sheet at its rest position (or reads `unitDepths.<part>`, `RIG_TURN_UNIT_DEPTH_REQUIRED`), enforces ear occlusion (`ear_r`/`ear_l` drawn before the `face` surface in `assemble.plan`, `CONFIG_TURN_EAR_DRAW_ORDER`, and behind the cheek surface, `RIG_TURN_EAR_DEPTH_BEHIND_CHEEK`), and writes `turn` and `tilt` `derive` tracks (`pivot` default `55` rig px, `counter` default `0.1` in `[0, 1]`, `CONFIG_TURN_COUNTER_RANGE`). `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median, unless it rides another part's bone. With no `face` part, or more than one, the riders keep their own and a note says so. A rider by bone (issue #535) — a part every *ownable* bone of which (a chain link, or a bone no other bone hangs from; `head`, `chest` and any bone with a child are shared and never count on their own) is *hosted* by another carried part, the host of a bone being the carried part that binds it (its region's bone; a mesh's `segments`, `contour` and `auto` regions' bones) with the most `opaque_px`, the earlier in parts.json on a tie, and which hosts no bone itself — is drafted at its host's depth, 0.001 nearer when drawn after the host and 0.001 further when before, and a note names the host, the bones and its own median: a pin, clip or ornament on the back hair's links travels with the back hair, not with its own layer's depth. `propose` reads the proposal's own `bones`, `meshes` and `regions`; the face riders are read by their tag first and never by their bones. A part bound to two hosts' bones rides neither and a note says so. In the rig stage, an authored depth on a rider by bone whose fraction differs from its host's by more than 0.1 of the dial (`TURN_RIDER_APART`, a share of `pivot − nearest`) is refused (`CONFIG_TURN_RIDER_DEPTH`); the host is read off `parts.json`'s `opaque_px`, so the config loader cannot see it. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it requires `config.turn` (`CONFIG_TURN_REQUIRED`, issue #478; `propose --full`/`--head` drafts it), promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening on the trailing side, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). On yaw (`issue #479`), `evalYawFaceSurface` evaluates a **cylinder projection** (`cylinderYawDx`: `Δx(x, θ, R) = R · (sin(clamp(arcsin(clamp(x / R, −1, 1)) − θ, −π/2, π/2)) − clamp(x / R, −1, 1))`) of radius `R` (`turnSurfaceRadius`: `turn.surface.radius ?? turn.radius ?? turn.head.radius`, positive rig px checked by `CONFIG_FIELD_TYPE`, defaulting to half the face plate's opaque width `W / 2`) tapered by a cubic Hermite outline weight (`wOutline = 1` for `\|ux\| <= 0.7`, reaching `0` at `\|ux\| = 1.0`) so features slide across a fixed outline (`iris` shift within `±2%` of `cylinderYawDx`), the trailing cheek strip widens (`>= 1.54×` at `±15°`), and the leading jaw edge holds fixed (`0 px` shift) unless explicit horizontal `turn.deform` overrides (`turn_mid_x`, `turn_lead_compress_x`, `turn_trail_shift_x`) request the flat yaw table. On yaw (`issue #478`), `applyFaceSurfaceDeform` also derives a **head-only pivot** (`headTurnPivot`: `turn.head.pivot` when authored, otherwise the `opaque_px`-weighted mean of `depths[part]` across the head parts `DEFAULT_HEAD_TURN_PARTS` — `face`, `hair_front`, `hair_back`, `ear_r`, `ear_l`, `hairpin` — from `parts.json`, falling back to `turn.pivot`) so a forward torso or arm in `turn.depths` does not pull the head's rotation axis in front of `face`: `hair_back` (`depth_median > headPivot`, negative `headTurnFraction`) and `hairpin` behind `headPivot` translate opposite to the face's turn (`dx = s · turn_face_center_x · W · (headPivot − depth) / (headPivot − nearestHeadDepth)`), emerging on the trailing side to compensate for the leading-cheek foreshortening and keeping the combined head silhouette width near-constant across `±15°` without any same-sign `turn_hair_back_cheek_x` term. Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); `pivot` and `head.pivot` must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
 | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite, and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
 | `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `meshes.<part>` and `regions.<part>`, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — and every other byte as read; `--from <previous config>` (issue #571) takes an entry equal to the previous recipe's draft as the recipe's (*The config written*, under the recipe below) |
@@ -5084,7 +5085,7 @@ documents do not ship). Each is an input this package built; none is an author's
 | <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 |
 | <a id="REQUIREMENTS_NOT_PLANTED"></a>`REQUIREMENTS_NOT_PLANTED` | a `not_planted` name is a part `check` does not read as a planted foot — it does not come from a See-through `footwear` layer — or there is no `parts.json` to choose the feet by (issue #231). Refused before anything is built | a `footwear` part's name |
 | <a id="REQUIREMENTS_TIP_EXCEPTION"></a>`REQUIREMENTS_TIP_EXCEPTION` | a `not_swinging`, `rises` or `rests` name is a part `TIP_OVER_ROOT` does not read — not from a See-through `handwear` or `bottomwear` layer — or there is no `parts.json` (refused before anything is built); or a `rises` part is not carried by a chain that rises: the chain's **last link**, at the setup pose, runs other than up — from its origin along its `length` (the extent the rig stage turns a link to), or, a last link with no length, from the link before's origin to its own — the detail giving the link read and the direction measured (refused after the idle is rendered, before `check.json` is written) (issues #231, #322; until #322 it read the chain's first link's origin to its last's, which refused a folded arm — a link that hangs, then a forearm raised) | a swinging part's name; for `rises`, a part whose chain does rise |
-| <a id="CHECK_ENVIRONMENT"></a>`CHECK_ENVIRONMENT` | `check --environment` (or `build --environment`, forwarded): the schedule is refused, the detail rigc's own sentence verbatim. Read once by rig-c's reader (`readEnvironmentSchedule`, `@rig-c/core/src/environment.ts`) before anything is built — nothing at the path, a file that is not JSON or not an object, a `spec` other than `rigc-environment/1`, a key besides `spec`, `steps` or a step's `t`, `wind`, `gravity`, no step, a `t` not finite, below 0 or not after the step before, a `wind` or `gravity` not a pair of finite numbers (JSON's `1e999` reads as `Infinity` and is refused), a step stating neither — and `--out` is not written (`build` refuses under `[assemble]`, before it assembles). After the build, what `rigc render --environment` refuses of a well-formed schedule on this rig, quoted from its `--environment <path>:` line: no physics constraint, a half no constraint answers, two steps on one frame at 12 fps, a step after the last frame of the animation rendered. Also refused before anything is built: a `motion.json` with no animation, where no render `check` makes could pose the schedule | the schedule — rigc's sentence names the entry, the field, the value found and the value required; for a rig with no physics constraint, drop the flag: no world moves it |
+| <a id="CHECK_ENVIRONMENT"></a>`CHECK_ENVIRONMENT` | `check --environment` (or `build --environment`, forwarded): the schedule is refused, the detail rigc's own sentence verbatim. Read once by rig-c's reader (`readEnvironmentSchedule`, `@rig-c/core/environment`) before anything is built — nothing at the path, a file that is not JSON or not an object, a `spec` other than `rigc-environment/1`, a key besides `spec`, `steps` or a step's `t`, `wind`, `gravity`, no step, a `t` not finite, below 0 or not after the step before, a `wind` or `gravity` not a pair of finite numbers (JSON's `1e999` reads as `Infinity` and is refused), a step stating neither — and `--out` is not written (`build` refuses under `[assemble]`, before it assembles). After the build, what `rigc render --environment` refuses of a well-formed schedule on this rig, quoted from its `--environment <path>:` line: no physics constraint, a half no constraint answers, two steps on one frame at 12 fps, a step after the last frame of the animation rendered. Also refused before anything is built: a `motion.json` with no animation, where no render `check` makes could pose the schedule | the schedule — rigc's sentence names the entry, the field, the value found and the value required; for a rig with no physics constraint, drop the flag: no world moves it |
 | <a id="CHECK_WIND_BAND"></a>`CHECK_WIND_BAND` | `check --wind-band` (or `build --wind-band`, forwarded, issue #590): the sweep file is refused before anything is built, or cannot be measured against the rig. Refused before the build (`build` refuses under `[assemble]` before it assembles, and `--out` is not written): nothing at the path, a file that is not a JSON object, an unknown key (besides `note`, `*_note` and `x-…`), a missing or malformed field (`spec` must be `"rig-parts-wind-band/1"`; `min`, `max`, `step` finite numbers with `min < max`, `step > 0`, and `(max - min) / step` within `1e-6` of an integer at most `64`; `fps` a positive integer; `max_gap` and `max_ghost` non-negative integers; `pairs` a non-empty array of unique `"<a>:<b>"` strings with `a !== b`). Refused against the rig before `rigc build`: a slot in `pairs` not in `rig.json`'s `slots`, `motion.json` with no animation, a rig with no physics constraint, or a rig where no physics constraint has a non-zero `wind`. Refused after the first sweep render (before `check.json` is written, with `--out` cleaned): a pair in `pairs` whose drawings share no overlap band at the setup pose (`status: "skip"` or `banded === 0` in `seam.json`) | the `--wind-band` file or the rig — every field in `"rig-parts-wind-band/1"` is required (nothing falls back to `SEAM_OVER_MOTION`), each `"<a>:<b>"` pair must name two distinct slots whose art overlaps at rest, and the rig must declare at least one physics constraint that answers `wind` |
 | <a id="REQUIREMENTS_SEAM"></a>`REQUIREMENTS_SEAM` | a `seam` cannot be read against the rig: there is no `parts.json` (a merged rig, §7 *Measuring a rig rig-parts did not assemble*), or the two parts' art does not meet at the setup pose (no 4-adjacent pair). Refused before anything is built | two parts whose art touches, on a rig with its `parts.json` |
 
@@ -5157,7 +5158,7 @@ Absent declaration retains existing output bytes except optional new evidence on
 
 **Body-root seam identity** (issue #686). A limb must have exactly one segment0 part. Its declared bone must have one named immediate parent; the root slot must bind that bone (or its declared turn child). Non-limb parts with `topwear` or `bottomwear` source provenance, a slot on that parent (directly or through its verified generated turn child) and a named default-skin drawing are candidates. The body-side child must match `applyTurn`'s exact generated name, unique identity bone and parent, control and per-part transform binding; a similarly named bone alone is not proof (issue #708). The original carrier and pair slot names do not change under turn; stock setup pose `render --seam` selects all matching drawings with `banded > 0` (its existing alpha-overlap band, without dilation), so one selects one pair and two select both pairs. When eligible candidates all return valid setup banded 0, that limb has no selected root pair: `unmeasuredRoots` retains its limb, bone, parent, segment0 part, candidates and named reason, reported as SKIP, not measured PASS. Part spelling, nearest geometry and shared mesh influences select nothing. On `wind` the pairs are `topwear|upperarm_r`, `topwear|upperarm_l`, `bottomwear|thigh_r` and `bottomwear|thigh_l`; “trunk” is not a part name. Existing pairs keep their order; a reversed explicit declaration deduplicates with the root pair and retains both declarations. An ambiguous/missing named binding, no eligible candidate, or unreadable/undrawn setup data is `CHECK_MOTION_SEAM_ROOT`, naming the part and candidates. Valid zero-band metadata is carried separately as optional `roots.unmeasured`, never as a fabricated measured pair. The all-zero root block remains present and its bar is skipped; measured FAIL takes precedence over SKIP, while measured PASS plus any unmeasured root stays SKIP. No body provenance leaves legacy pair selection unchanged and supplies no body-root coverage.
 
-Renderer metadata and exact raster reads use the promised `@rig-c/core/render-shared` entry (rig-c >=2.69.0 <3.0.0). It registers no Spine runtime; where that runtime resolves from rig-c's own package root, the existing `@rig-c/core/render` entry registers the official Spine side explicitly. An install without Spine keeps rig-c's own candidate chooser and gate; candidate or loader failures never select a guessed fallback.
+Renderer metadata and exact raster reads use the promised `@rig-c/core/render-shared` entry (from rig-c 2.69.0). It registers no Spine runtime; where that runtime resolves from rig-c's own package root, the existing `@rig-c/core/render` entry registers the official Spine side explicitly. An install without Spine keeps rig-c's own candidate chooser and gate; candidate or loader failures never select a guessed fallback.
 
 The body-root bar counts stock partitions `gapOpen` plus `ghostA` or `ghostB` owned by the pair's UNDER-owned drawing in resolved draw order on each active frame, comparing their summed cells against the unchanged strict floor `px > round(max(box width, box height) / cell)` on the original raw kind boxes (their union when both kinds contribute), never the narrowed partition boxes; `gapCovered` and OVER-owned ghost cells do not count (issue #711). The metric mode is `gap-open+under-ghost`; rows retain the exact partition counts, UNDER owner and counted total in `cells`, including excluded and under-floor readings. Missing partitions, inconsistent sums or unavailable ownership are named `FRAMES_SIDECAR` refusals, never inferred zero. An active rendered environment fails `CHECK_SEAM_OVER_MOTION` above that floor, setting overall PASS false and exits 1. Existing internal-joint and explicit-only pairs remain warnings: their PASS, exit status and bar count are unchanged; reference worlds remain informational. The root bar is counted once, and absence is not a zero or a PASS. No whole-box alpha exemption or consumer compositor is used. This gate samples the supplied animations at 12 fps, not another motion or player scene.
 
@@ -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
@@ -252,7 +269,7 @@ keeps complete canonical raw pair data (boxes/cut metadata included), omitting
 `picture` unless its image exists. Semantic signatures preserve original source
 attachment UVs/topology/weights, own image content and world vertices/colour,
 not atlas pages/UVs or global piece ordinals. Unknown/no-art support stays conservative.
-Renderer metadata and exact raster reads use the promised `@rig-c/core/render-shared` entry (rig-c >=2.69.0 <3.0.0). It registers no Spine runtime; where that runtime resolves from rig-c's own package root, the existing `@rig-c/core/render` entry registers the official Spine side explicitly. An install without Spine keeps rig-c's own candidate chooser and gate; candidate or loader failures never select a guessed fallback.
+Renderer metadata and exact raster reads use the promised `@rig-c/core/render-shared` entry (from rig-c 2.69.0). It registers no Spine runtime; where that runtime resolves from rig-c's own package root, the existing `@rig-c/core/render` entry registers the official Spine side explicitly. An install without Spine keeps rig-c's own candidate chooser and gate; candidate or loader failures never select a guessed fallback.
 
 An unavailable, nonfinite, unrepresentable or oversized union, or nonempty official pinned.outside, refuses `CHECK_SEAM_DOMAIN`. Geometry margins outside the authored canvas are included in U, not treated as opaque-clip evidence. State-by-state geometry reads retain bounds/identities rather than all decoded pages or poses. `--keep-stills` keeps
 canonical frames in `setup_still/` and fitted diagnostics in `setup_still_auto/`.
@@ -311,20 +328,28 @@ in the package.
 
 ## rig-c
 
-`dependencies` takes `@rig-c/core` `2.82.0` exactly. Bun 1.4 or later
+`dependencies` takes `@rig-c/core` `3.0.0` exactly. Bun 1.4 or later
 is the declared floor (`engines.bun` `>=1.4.0`; older 1.4 releases are not tested in
 CI, which runs `latest`, and compatibility with an older 1.4 release is handled when
 reported as an issue). What this package relies on in rig-c, every import
 read off `src/` and `cli.ts`:
 
-- the named entries `@rig-c/core/mesh` (the outline functions, `measureAuthoredMeshFit`,
-  `reduceMesh`, `skinningEnvelopeBone`, `writeMeshQualityReport` and their types)
-  and `@rig-c/core/meshcompare` (`compareMeshesInMotion`);
-- the deep paths its `exports` map carries: `@rig-c/core/src/rig.ts` (`parseRigSpec`,
-  `RIG_SPEC_VERSION`, the constraint keys), `@rig-c/core/src/errors.ts`,
-  `@rig-c/core/src/png.ts`, `@rig-c/core/src/transform.ts` (the y flip, through
-  `src/coords.ts` only), `@rig-c/core/tools/plate.ts` (the PNG codec) and
-  `@rig-c/core/tools/font5x7.ts`;
+- the named entries its `exports` map carries (from `@rig-c/core` 3.0.0 `./*.ts` deep
+  file paths are gone, and `TY39` refuses any in the tree):
+  `@rig-c/core/mesh` (the outline functions, `measureAuthoredMeshFit`, `reduceMesh`,
+  `skinningEnvelopeBone`, `writeMeshQualityReport` and their types),
+  `@rig-c/core/meshcompare` (`compareMeshesInMotion`, `comparePreparedMotion`,
+  `prepareMotionReference`), `@rig-c/core/compile` (`f32`), `@rig-c/core/core`
+  (`RUNTIME_PI`), `@rig-c/core/deformgen` (`evaluateDeformTransform`),
+  `@rig-c/core/environment` (`ENVIRONMENT_SPEC`, `EnvironmentError`,
+  `environmentResponse`, `readEnvironmentSchedule`), `@rig-c/core/errors`
+  (`CompileError`), `@rig-c/core/font5x7` (`GLYPH_H`, `drawText`),
+  `@rig-c/core/passthrough` (`DRAWN_ALPHA`), `@rig-c/core/plate` (the PNG codec),
+  `@rig-c/core/png` (`assertPng`), `@rig-c/core/render` (`GeometryFile`,
+  `GeometryFrame`), `@rig-c/core/render-shared` (`Viewport`), `@rig-c/core/rig`
+  (`parseRigSpec`, `RIG_SPEC_VERSION`, the constraint keys and types),
+  `@rig-c/core/stop` (`expandStops`) and `@rig-c/core/transform` (the y flip and
+  frame transforms, through `src/coords.ts` only);
 - the `rigc` command: `build` and `render`, and `--version`, whose `entry:` line
   says which validator gated a build (`check.json`'s `rigc_entry`).
 
@@ -507,10 +532,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 +572,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": "2.0.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": {
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "@rig-c/core": "2.84.0"
+    "@rig-c/core": "3.0.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/src/apng.ts

@@ -4,7 +4,7 @@
  *
  * Pure: bytes in, bytes out, no clock, no file system. The only thing it leans
  * on is `node:zlib` for DEFLATE, which is also all rig-c's own PNG codec
- * (`rig-c/tools/plate.ts`) leans on; the chunk framing and CRC are that
+ * (`@rig-c/core/plate`) leans on; the chunk framing and CRC are that
  * codec's `pngChunk`, so there is one PNG chunk writer in the dependency tree,
  * not two.
  *
@@ -34,7 +34,7 @@
  * bitstream encoder, and none ships here.
  */
 import { deflateSync } from 'node:zlib';
-import { PNG_SIGNATURE, pngChunk } from '@rig-c/core/tools/plate.ts';
+import { PNG_SIGNATURE, pngChunk } from '@rig-c/core/plate';
 import { histogram, mapToPalette, medianCut, type PaletteError, paletteError, type Rgba } from './palette.ts';
 import type { Raster } from './raster/types.ts';
 

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';
@@ -170,9 +170,9 @@ import {
   type SeamPair,
   stretchRequirementLine,
 } from './requirements.ts';
-import { RIG_BONE_INHERIT, type RigSpec as RigcRigSpec } from '@rig-c/core/src/rig.ts';
-import { expandStops } from '@rig-c/core/src/stop.ts';
-import { ENVIRONMENT_SPEC, EnvironmentError, environmentResponse, readEnvironmentSchedule } from '@rig-c/core/src/environment.ts';
+import { RIG_BONE_INHERIT, type RigSpec as RigcRigSpec } from '@rig-c/core/rig';
+import { expandStops } from '@rig-c/core/stop';
+import { ENVIRONMENT_SPEC, EnvironmentError, environmentResponse, readEnvironmentSchedule } from '@rig-c/core/environment';
 import { ART_ALPHA } from './mesh.ts';
 import { connectedComponents } from './raster/components.ts';
 import { alphaComposite } from './raster/composite.ts';
@@ -329,8 +329,8 @@ export const DEFAULT_PACK_MODE: PackMode = { pageEdges: DEFAULT_PAGE_EDGES, pack
 /**
  * The profile every rigc build this package runs is gated under. rig-c 2.50.0
  * renamed `spine-html` to `rig-play` and runs the same rules under it; the old
- * name is accepted only until a later minor release and prints a deprecation
- * line on stderr (selftest `CK20` holds every stage's build to the new name).
+ * name was removed in rig-c 3.0.0 (selftest `CK20` holds every stage's build to
+ * the new name and verifies the old one is refused).
  */
 export const GATE_PROFILE = 'rig-play';
 
@@ -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;
 }
@@ -5309,7 +5309,7 @@ function environmentRefused(given: string, sentence: string): PartsError {
 
 /**
  * `--environment <file>` read once, before anything is built (issue #538): the file's bytes hashed and handed to
- * rig-c's own reader, `readEnvironmentSchedule` (`rig-c/src/environment.ts`), which refuses every malformed schedule
+ * rig-c's own reader, `readEnvironmentSchedule` (`@rig-c/core/environment`), which refuses every malformed schedule
  * — a `spec` other than {@link ENVIRONMENT_SPEC}, a key it does not read, no step, a `t` that is not finite, at or
  * above 0 and after the step before, a `wind` or `gravity` that is not a pair of finite numbers, a step that changes
  * nothing — by entry, field, the value found and the value required. Nothing here reads the schedule's meaning: its
@@ -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';
@@ -40,7 +41,7 @@ import type { DepthConfig } from './depthsheets.ts';
  *
  * Coordinates in `bones`, `meshes` and `motion` are RIG pixels, y down, origin
  * top-left — the parts' own space. The y flip to Spine happens once, in
- * `rig-c/src/transform.ts` (see `src/coords.ts`), when the rig is built.
+ * `@rig-c/core/transform` (see `src/coords.ts`), when the rig is built.
  *
  * 🔗 **`constraints` is rig-c's, verbatim (issue #92).** An optional list
  * of constraint objects in rig-c's own rig-spec shape (`RigConstraint`:
@@ -90,7 +91,7 @@ import type { DepthConfig } from './depthsheets.ts';
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey, type RigStop } from '@rig-c/core/src/rig.ts';
+import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey, type RigStop } from '@rig-c/core/rig';
 import { pyRound } from './round.ts';
 import { motionSeamProblems, type MotionSeamDeclaration } from './motionseams.ts';
 import { REQUIREMENTS_SPEC } from './requirements.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/coords.ts

@@ -22,7 +22,7 @@
  * `flattenRig` goes back through `toWorld`. No rotation matrix is written out
  * by hand in this package.
  */
-import { cropToSpineY } from '@rig-c/core/src/transform.ts';
+import { cropToSpineY } from '@rig-c/core/transform';
 
 /** A painting point on the accepted integer rig canvas, in setup-world coordinates. */
 export function paintingToSetupPoint(point: readonly number[], sourceSize: readonly number[], rigSize: readonly number[]): [number, number] {
@@ -34,5 +34,5 @@ export function setupToPaintingPoint(point: readonly number[], sourceSize: reado
   return [(point[0] + rigSize[0] / 2) / (rigSize[0] / sourceSize[0]), cropToSpineY(point[1], rigSize[1]) / (rigSize[1] / sourceSize[1])];
 }
 
-export { computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toBoneLocalVector, toWorld } from '@rig-c/core/src/transform.ts';
-export type { BoneTransform } from '@rig-c/core/src/transform.ts';
+export { computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, toBoneLocal, toBoneLocalVector, toWorld } from '@rig-c/core/transform';
+export type { BoneTransform } from '@rig-c/core/transform';

package/src/instruments.ts

@@ -962,7 +962,7 @@ export function partWorldBox(p: PartRecord, rigH: number, stage: StageBox): Worl
 /**
  * How many floating-point roundings stand between the rig and one coordinate
  * of a displacement {@link stillReading} returns, on its longest path. Every
- * number on it is a double: rigc's core poser (`rig-c/src/core/vertices.ts`,
+ * number on it is a double: rigc's core poser (`@rig-c/core/core`,
  * rig-c 2.15.0) reads a vertex's local coordinates and weights through
  * `Math.fround` and does the arithmetic in doubles, and `geometry.json` carries
  * those doubles. The float32 inputs are the same numbers in the rest vertex and

package/src/propose.ts

@@ -131,7 +131,7 @@ import { explicitWeightRows, regionBone, type RegionSpec } from './config.ts';
  */
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { drawText, GLYPH_H } from '@rig-c/core/tools/font5x7.ts';
+import { drawText, GLYPH_H } from '@rig-c/core/font5x7';
 import { type BoneEntry, type CharacterConfig, type ConfigConstraint, type ConfigStop, contourRegionsOf, deriveBustRegions, type Limb, type MeshSpec, type PartBinding, parseConfig, type Point, type Segment, type SkeletonSections, turnRidersByBone } from './config.ts';
 export { contourRegionsOf, deriveBustRegions };
 import { computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toWorld } from './coords.ts';

package/src/raster/png.ts

@@ -12,14 +12,14 @@
  * refuses by name rather than misreading. So adding `pngjs` would have been a
  * second codec for the same bytes, and two codecs are two answers.
  *
- * 🔌 **The deep path is the interface.** rig-c's `exports` map carries
- * `./*.ts`, so `rig-c/tools/plate.ts` is how a consumer reaches the codec
- * and it is what the installed package resolves. If a rigc release narrows the
- * map to omit these paths, this import is what breaks, by name, and
- * `bun run smoke` is where that is seen first.
+ * 🔌 **The named entries are the interface.** `@rig-c/core/plate` and
+ * `@rig-c/core/png` are how a consumer reaches the codec and what the
+ * installed package resolves. If a rigc release moves or drops these entries,
+ * this import is what breaks, by name, and `bun run smoke` is where that is
+ * seen first.
  */
-import { assertPng } from '@rig-c/core/src/png.ts';
-import { decodePng, encodePng } from '@rig-c/core/tools/plate.ts';
+import { assertPng } from '@rig-c/core/png';
+import { decodePng, encodePng } from '@rig-c/core/plate';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { type FloatImage, newFloatImage, newRaster, type Raster, RasterError } from './types.ts';
 

package/src/raster/types.ts

@@ -11,7 +11,7 @@
  *   feathered blend weight).
  *
  * Nothing here knows about Spine's y-up world. The only conversion between the
- * two lives in `rig-c/src/transform.ts`, re-exported by `src/coords.ts`.
+ * two lives in `@rig-c/core/transform`, re-exported by `src/coords.ts`.
  */
 export interface Raster {
   readonly width: number;

package/src/remesh.ts

@@ -75,8 +75,8 @@ import { applyMeshEdit, type DeltaApplied, type DeltaPlant, deltaSourceProblems,
 import { DEFAULT_IDLE_KEYS, type IdleKeys, type MeshAttachment, meshBoundBones, rigJsonText, type RigSpec } from './rig.ts';
 import { readRequirements } from './requirements.ts';
 import { pyRound } from './round.ts';
-import { type RigSpec as RigcRigSpec } from '@rig-c/core/src/rig.ts';
-import { expandStops } from '@rig-c/core/src/stop.ts';
+import { type RigSpec as RigcRigSpec } from '@rig-c/core/rig';
+import { expandStops } from '@rig-c/core/stop';
 
 /** The provenance file's spec. */
 export const REMESH_SPEC = 'rig-parts-remesh/1';

package/src/requirements.ts

@@ -50,8 +50,8 @@ import { fixedSkeletonProblems, type FixedSkeleton } from './artjoints.ts';
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { CompileError } from '@rig-c/core/src/errors.ts';
-import { splitRigSkin, type RigSkin } from '@rig-c/core/src/rig.ts';
+import { CompileError } from '@rig-c/core/errors';
+import { splitRigSkin, type RigSkin } from '@rig-c/core/rig';
 import { cropToSpineY } from './coords.ts';
 import type { Problem } from './errors.ts';
 import { refuseIfAny } from './errors.ts';

package/src/rig.ts

@@ -138,12 +138,12 @@ import { explicitAttachment, type ExplicitMeshReport } from './explicitmesh.ts';
  * order the objects are built in, and every number is rounded by `pyRound`).
  */
 import { type AutoSpec, type BoneEntry, type InfluenceMeshSpec, type WeightRule, type CharacterConfig, type ConfigConstraint, type ConfigStop, CONSTRAINT_FOLLOWS, constraintForRig, contourRegionsOf, type ContourSpec, DEFAULT_BUST_BONE_L, DEFAULT_BUST_BONE_R, type Point, type RibsSpec, ROOT_BONE, stopForRig, turnRidersByBone, weightsABone } from './config.ts';
-import { RUNTIME_PI } from '@rig-c/core/src/core/world.ts';
+import { RUNTIME_PI } from '@rig-c/core/core';
 import { type BoneTransform, computeExactFrameTransforms, computeWorldTransforms, cropToSpineY, normaliseDegrees, paintingToSetupPoint, setupToPaintingPoint, toBoneLocal, toWorld } from './coords.ts';
 import { type Problem, refuseIfAny, PartsError } from './errors.ts';
 import { recordedFocusProblems } from './setfocus.ts';
 import { eyeLineDegrees } from './headframe.ts';
-import type { RigBoneInherit, RigStop } from '@rig-c/core/src/rig.ts';
+import type { RigBoneInherit, RigStop } from '@rig-c/core/rig';
 import { f32 } from '@rig-c/core/compile';
 import type { MeshCounts, MeshQualityReport, MeshReductionInput, MotionAmplitude, ReducedMesh, Termination } from '@rig-c/core/mesh';
 import { bindWeightedVertices, buildGridMesh, buildSegmentsLattice, type EntrySegment, influenceShares, segmentDistance as rigcSegmentDistance, type SegmentsLattice, type SegmentsLatticeReport } from '@rig-c/core/mesh';
@@ -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/scene.ts

@@ -93,7 +93,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import type { RigStop } from '@rig-c/core/src/rig.ts';
+import type { RigStop } from '@rig-c/core/rig';
 import { checkStage, gateThroughRigc, type Log } from './build.ts';
 import { ACCEPTABLE_BARS, barsNotMet, type CheckReport, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, type PackMode, requirementsNotPass, type RigcRunner } from './check.ts';
 import { CONSTRAINT_BONE_FIELDS, ROOT_BONE } from './config.ts';

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)'}`)])];

package/src/sheet.ts

@@ -18,7 +18,7 @@
  */
 import { existsSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { drawText, GLYPH_H } from '@rig-c/core/tools/font5x7.ts';
+import { drawText, GLYPH_H } from '@rig-c/core/font5x7';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { type LayerSet, OPAQUE_ALPHA_ABOVE, readLayers } from './layers.ts';
 import { readParts } from './parts.ts';

package/src/structure.ts

@@ -71,8 +71,8 @@ import { explicitWeightRows, regionBone } from './config.ts';
  * Pure but for reading the three files it is handed.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { CompileError } from '@rig-c/core/src/errors.ts';
-import { parseRigSpec, RIG_SPEC_VERSION, type RigBone as RigcBone, type RigSpec as RigcSpec, splitRigSkin } from '@rig-c/core/src/rig.ts';
+import { CompileError } from '@rig-c/core/errors';
+import { parseRigSpec, RIG_SPEC_VERSION, type RigBone as RigcBone, type RigSpec as RigcSpec, splitRigSkin } from '@rig-c/core/rig';
 import { type ConfigConstraint, CONSTRAINT_FOLLOWS, contourRegionsOf, parseConfig, parseProposalSections, type Point, ROOT_BONE, type SkeletonSections, weightsABone } from './config.ts';
 import { computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toWorld } from './coords.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';

package/src/turn.ts

@@ -38,7 +38,7 @@ import { sampleTurnTriangleField, turnTriangleCoordinates } from './turnfield.ts
 import { PartsError } from './errors.ts';
 import { f32 } from '@rig-c/core/compile';
 import { warnUncoveredBodyTurn } from './turncoverage.ts';
-import { evaluateDeformTransform } from '@rig-c/core/src/deformgen.ts';
+import { evaluateDeformTransform } from '@rig-c/core/deformgen';
 
 /**
  * The layers that ride on the face (issue #271): See-through makes no depth

package/src/turncoverage.ts

@@ -1,7 +1,7 @@
 /** Report missing body-turn declarations from shown setup alpha and emitted fields. */
 import { f32 } from '@rig-c/core/compile';
-import { DRAWN_ALPHA } from '@rig-c/core/src/passthrough.ts';
-import { evaluateDeformTransform, type DeformTransform } from '@rig-c/core/src/deformgen.ts';
+import { DRAWN_ALPHA } from '@rig-c/core/passthrough';
+import { evaluateDeformTransform, type DeformTransform } from '@rig-c/core/deformgen';
 import { computeWorldTransforms, paintingToSetupPoint, toWorld } from './coords.ts';
 import { extendDepthSilhouette, sampleDepthFloat } from './depthsheets.ts';
 import { edgeLength } from './length.ts';

package/src/turnoverlap.ts

@@ -1,5 +1,5 @@
 /** Source-alpha overlap selects turn fields, never skin bindings. */
-import { DRAWN_ALPHA } from '@rig-c/core/src/passthrough.ts';
+import { DRAWN_ALPHA } from '@rig-c/core/passthrough';
 import { computeWorldTransforms, setupToPaintingPoint, toWorld } from './coords.ts';
 import type { Depth25DTurnOptions } from './turn.ts';
 import type { Problem } from './errors.ts';