@rig-c/parts 2.42.0 → 2.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/cli.ts CHANGED
@@ -51,7 +51,7 @@ import { REQUIREMENTS_SENTENCE } from './src/requirements.ts';
51
51
  import { composeStage, IMAGE_SEP, PLATE, PROVENANCES, SCENE_REPORT_FILE, SCENE_REPORT_SPEC, SCENE_SPEC } from './src/scene.ts';
52
52
  import { buildSheet, defaultCaption, type Tile, tilesFrom } from './src/sheet.ts';
53
53
  import { loadComparison, requiredProblems, structureLines } from './src/structure.ts';
54
- import { assembleOutputFiles, clearRunStamp, readPackageIdentity, rigOutputFiles, RUN_STAMP_FILE, RUN_STAMP_SPEC, writeRunStamp } from './src/runstamp.ts';
54
+ import { assembleOutputFiles, clearComposeRun, clearRunStamp, readPackageIdentity, rigOutputFiles, RUN_STAMP_FILE, RUN_STAMP_SPEC, writeRunStamp } from './src/runstamp.ts';
55
55
  import { authorLayerLine } from './src/tags.ts';
56
56
 
57
57
  const EXIT_OK = 0;
@@ -970,7 +970,7 @@ usage:
970
970
  rigc refuses the pair a control splits, and the RIG_RIGC_GREEN line
971
971
  names the flag on the command that ran.
972
972
 
973
- rig-parts compose --scene <scene.json> --out <dir> [--requirements <file.json>] [--accept <bar>[,<bar>...]]
973
+ rig-parts compose --scene <scene.json> --out <dir> [--requirements <file.json>] [--accept <bar>[,<bar>...]] [--page-size <px>]
974
974
  Bind several finished characters into one rig. The scene file (spec
975
975
  "${SCENE_SPEC}") states the canvas {width, height}, an optional plate
976
976
  {image, provenance: ${PROVENANCES.join(' | ')}, note?}, the characters
@@ -1210,7 +1210,7 @@ const TAKES = {
1210
1210
  'comfy plate': { valued: ['--mode', '--painting', '--mask-from', '--occluder', '--out', '--graph', '--model', '--checkpoint-sha256', '--seed', '--grow', '--steps', '--cfg', '--prompt', '--negative', '--host', '--wait', '--timeout', '--poll'], switches: ['--holes'] },
1211
1211
  inputs: { valued: ['--source', '--config', '--out'], switches: [] },
1212
1212
  build: { valued: ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape', '--page-size', '--requirements', '--idle-keys', '--lead-in', '--alt', '--set', '--environment', '--wind-band'], switches: ['--loop', '--seam-pairs', '--keep-stills', '--all-sets', '--no-extremes'] },
1213
- compose: { valued: ['--scene', '--out', '--requirements', '--accept'], switches: [] },
1213
+ compose: { valued: ['--scene', '--out', '--requirements', '--accept', '--page-size'], switches: [] },
1214
1214
  'mesh-draft': { valued: ['--config', '--parts', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape', '--page-size'], switches: ['--more-triangles'] },
1215
1215
  'mesh-stats': { valued: ['--config', '--parts'], switches: [] },
1216
1216
  remesh: { valued: ['--rig', '--config', '--parts', '--part', '--mesh', '--delta', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape', '--page-size', '--input-check'], switches: ['--record-input-check'] },
@@ -2295,6 +2295,14 @@ function cmdBuild(args: string[]): number {
2295
2295
  function cmdCompose(args: string[]): number {
2296
2296
  const f = flags(args, 'compose', ['--scene', '--out']);
2297
2297
  if (typeof f === 'string') return usage(f);
2298
+ const out = f.get('--out') as string;
2299
+ clearComposeRun(out);
2300
+ let size: number | undefined;
2301
+ try {
2302
+ size = parsePageSize(f.get('--page-size'));
2303
+ } catch (err) {
2304
+ return printRefusal(err);
2305
+ }
2298
2306
  let bin: string;
2299
2307
  try {
2300
2308
  bin = findRigc(import.meta.dir, process.env.PATH ?? '');
@@ -2306,7 +2314,7 @@ function cmdCompose(args: string[]): number {
2306
2314
  const req = f.get('--requirements');
2307
2315
  const accept = f.get('--accept');
2308
2316
  const r = composeStage(
2309
- { scene: f.get('--scene') as string, out: f.get('--out') as string, ...(req === undefined ? {} : { requirements: req }), ...(accept === undefined ? {} : { accept: accept.split(',') }) },
2317
+ { scene: f.get('--scene') as string, out, ...(size === undefined ? {} : { pageSize: size }), ...(req === undefined ? {} : { requirements: req }), ...(accept === undefined ? {} : { accept: accept.split(',') }) },
2310
2318
  { rig: rigcRunner(bin), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'gate') },
2311
2319
  console.log,
2312
2320
  );
package/docs/AUTHORING.md CHANGED
@@ -4443,7 +4443,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
4443
4443
  | `check --rig --out [--parts] [--source] [--requirements]` | build packed, gated under `rig-play`, render the idle, measure seam, loop and the six judgement lines (mesh texture stretch among them, from the idle's `render --geometry`), and report the recomposite's holes from `parts.json`; on a rig spec with no `parts.json` or no `idle` (a merged rig, issue #77) the gate still runs and every line that needs the missing input says SKIP by name; `--source <painting.png>` adds `SETUP_POSE_VS_SOURCE`, the setup pose against the painting by assemble's recomposite figures; `--requirements <scene.json>` measures what a scene declares of the motion — a contact, a follow fraction, an aim, a joint range, a mesh's stretch, the seam between two parts over the motion — each against the author's own bar, from rig-c's posed frames, one line each, PASS, FAIL or NOT MEASURABLE (AUTHORING §7, *Declared requirements*) |
4444
4444
  | `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
4445
4445
  | `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
4446
- | `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](AUTHORING.md), *Composing several characters*) |
4446
+ | `compose --scene <scene.json> --out [--requirements] [--accept] [--page-size]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](AUTHORING.md), *Composing several characters*) |
4447
4447
  | `mesh-draft --config <json> --parts <dir> --out <dir>` | draft contour meshes for configured lattices, keeping each only where it holds against its lattice through rig-c; write the revised config and measurement report |
4448
4448
  | `mesh-stats --config <json> --parts <dir>` | print each configured mesh's vertex and triangle counts and their total through the rig stage's construction; write nothing |
4449
4449
  | `painting --keypoints <json> [--person <id>] [--form standee\|illustration] <png>` | before See-through, read the painting against its declared joints (`standee` by default, or `illustration` for a framed illustration where standee border, 8-joint and gap rules report `SKIP`) and refuse named problems; write nothing |
@@ -6235,7 +6235,7 @@ outside the consumed inputs pending [#1177](https://github.com/rig-c/parts/issue
6235
6235
  | <a id="CHECK_SETUP_PAINTING_MEASURED"></a>`CHECK_SETUP_PAINTING_MEASURED` | missing native setup/ownership or unsupported clipping | supply observable textured setup geometry; an unavailable instrument never passes |
6236
6236
  | <a id="CHECK_BOUNDARY_COLOUR_STEP"></a>`CHECK_BOUNDARY_COLOUR_STEP` | the requirements file declares `boundary_colour.max_step_excess` and a part boundary's colour step in the rig's render exceeds the same boundary's step in the rig's own pieces by more than it; the part pair, the frame (`setup` or `idle frame <n> (t <s> s)`), the stage pixel, the excess, the declared allowance and both steps are quoted. Unlike [`CHECK_SETUP_MATCHES_PAINTING`](#CHECK_SETUP_MATCHES_PAINTING), which compares the painting per declared region at the setup pose, this compares against the rig's own flat pieces (`parts.json` placement at setup, each piece's rest colour through its art UVs on every idle frame), so a part drawn over its neighbour's line art is not a failure | the pair's rig image or mesh: `rig/images/<part>.png` (a texture stretched into its padded UVs, or a notch cut out of it), or that part's mesh in `config.json` `meshes` when the mesh cuts a corner off the art; see [Boundary colour step](#boundary-colour-step-issue-942) |
6237
6237
  | <a id="CHECK_BOUNDARY_COLOUR_UNMEASURED"></a>`CHECK_BOUNDARY_COLOUR_UNMEASURED` | `boundary_colour` is declared and the step cannot be taken: no `parts.json`, no `idle`, or a default-skin region or mesh image without a sequence, with a parts record, whose rig image is not its parts PNG with one even pad on every side (refused before anything is built); otherwise a drawn slot has no `parts.json` piece, is clipped, or its rig image is not its parts PNG with one even pad on every side (the slot and frame are named). Never a pass | make every drawn slot a `parts.json` piece, or drop `boundary_colour` from the requirements file (the bar then reports SKIP) |
6238
- | <a id="CHECK_BEHIND_PART_SEAMS"></a>`CHECK_BEHIND_PART_SEAMS` | `behind_seams` is declared and a selected pair exceeds its allowance in the independent motion-opened or standing reading at setup or on an idle frame; the pair, behind slots, reading, frame, counted seam cells and allowance are named | repair the declared seam or author its per-pair allowance; no WARN mode or rest-visible mask; see [Behind-part seams](#behind-part-seams-issue-1314) |
6238
+ | <a id="CHECK_BEHIND_PART_SEAMS"></a>`CHECK_BEHIND_PART_SEAMS` | `behind_seams` is declared and a selected pair exceeds its allowance in the independent motion-opened or standing reading at setup, on an idle frame or at an opted-in named turn pose; the pair, behind slots, reading, frame, counted seam cells and allowance are named | repair the declared seam or author its per-pair allowance; no WARN mode or rest-visible mask; see [Behind-part seams](#behind-part-seams-issue-1314) |
6239
6239
  | <a id="CHECK_BEHIND_PART_SEAMS_UNMEASURED"></a>`CHECK_BEHIND_PART_SEAMS_UNMEASURED` | a pair with an authored effective threshold cannot read a mandatory population: selected pair, eligible behind slots, idle, readable setup, motion support, boundary population, or verified render/grid/material evidence; mandatory unread evidence makes the combined line FAIL. A missing threshold alone is a nonrequired SKIP and HOLE without this refusal code | supply the named measurement evidence; an invalid selected-pair override also refuses by name, and existing renderer or sidecar refusals remain refusals |
6240
6240
  | <a id="SETUP_PAINTING_REQUIRED_LIMIT"></a>`SETUP_PAINTING_REQUIRED_LIMIT` | `setup_painting.required` is `true` and a limit the check needs is absent: `rgb_tolerance`, `regions`, or a region's `max_pixels` (the object names the region). Refused when the requirements file is read, before anything is built (issue #943) | author the named limit; none is derived from the art. Without `required` the same region reports SKIP |
6241
6241
  | <a id="CHECK_SOURCE_GRID"></a>`CHECK_SOURCE_GRID` | the setup-pose still and its black-tinted twin (the coverage `SETUP_POSE_VS_SOURCE` reads) did not come back on one grid over one opaque background | a rigc problem; report it |
@@ -6289,7 +6289,7 @@ outside the consumed inputs pending [#1177](https://github.com/rig-c/parts/issue
6289
6289
  | <a id="BUILD_REQUIREMENTS_CONFLICT"></a>`BUILD_REQUIREMENTS_CONFLICT` | `build --requirements <file>` names a file with other bytes than the one `config.requirements` declares (issue #556): the detail names both, each resolved (the flag against the working directory, the declaration against the config's) with its sha256 — or `no such file`. Refused before assemble writes anything. The same file by both, or a copy of its bytes, is not refused: the declaration is read and recorded | drop the flag to build from the config's file, or point `config.requirements` at the flag's |
6290
6290
  | <a id="BUILD_STAGE_REQUEST"></a>`BUILD_STAGE_REQUEST` | an internal build worker was given a missing or malformed request, an unknown stage, or incomplete runner, input, output or scratch paths; the worker refuses before running a stage. This is the internal process protocol, not a public command or option | invoke `rig-parts build` with its documented flags; if that command produces this refusal, report the named request defect rather than constructing or modifying a worker request |
6291
6291
  | <a id="REQUIREMENTS_FILE"></a>`REQUIREMENTS_FILE` | `--requirements` names no file, or one that does not parse as a JSON object. Refused before anything is built (by `build`, before assemble) | the path of a `spine-parts-requirements/1` file |
6292
- | <a id="REQUIREMENTS_FIELD"></a>`REQUIREMENTS_FIELD` | a field of the file is missing, of the wrong type, or not one the format reads: `spec`, `fps` (a positive number when supplied, required only when a declared measurement reads the file's sampling rate, with no default), `requirements`, each requirement's `name` (letters, digits, underscores; once each), `kind`, `animation` and its kind's fields — every bar among them (`within_px`, `fraction`, `tolerance`, `least_drive` above 0, `within_degrees` from 0 to 180, `lo_degrees` ≤ `hi_degrees`, `within_ratio` ≥ 1) — and each target's `bone`, `animation` and exactly one of `at` and `keys` (times strictly increasing), and `not_planted`, `not_swinging`, `rises` and `rests` when given (each a non-empty list of part names, each once; no part both in `not_swinging` and in `rises` or `rests`), and `may_fold` when given (a non-empty list of `{ "slot", "animation", "why" }`, every one a non-blank string, each pair once; issue #320), and `pinholes` when given (an object whose one field, `required`, is `true` or `false`; issue #944), `seam_over_motion` when given (the same shape; issue #941), and `boundary_colour` when given (an object whose one field, `max_step_excess`, is an integer from 0 through 255; issue #942), and `motion_seams` when given (an array of `{part, neighbour}`, each an unordered pair of distinct output part names, once per list; issue #1269), and `behind_seams` when given (optional `threshold`, `allowance`, `pairs`; each pair requires distinct nonempty `part` and `neighbour`, with optional `threshold` and `allowance`; thresholds are integers from 0 through 255, allowances are nonnegative safe integers, and reverse duplicates are invalid; issue #1314). `note`, `*_note` (strings) and `x-…` (any value) are read by nothing, as in the config | write the field; the bar is yours. For a pair read only by `seam_over_motion.required`, declare requirements-level `motion_seams` `[{part, neighbour}]` and omit a seam requirement; this leaves a frozen `parts.json` untouched. `config.motion_seams` remains an assemble-time carrier into `parts.json`. See the [carrier contract](#CONFIG_MOTION_SEAM) and [background over every frame](#background-over-every-frame-issue-941). |
6292
+ | <a id="REQUIREMENTS_FIELD"></a>`REQUIREMENTS_FIELD` | a field of the file is missing, of the wrong type, or not one the format reads: `spec`, `fps` (a positive number when supplied, required only when a declared measurement reads the file's sampling rate, with no default), `requirements`, each requirement's `name` (letters, digits, underscores; once each), `kind`, `animation` and its kind's fields — every bar among them (`within_px`, `fraction`, `tolerance`, `least_drive` above 0, `within_degrees` from 0 to 180, `lo_degrees` ≤ `hi_degrees`, `within_ratio` ≥ 1) — and each target's `bone`, `animation` and exactly one of `at` and `keys` (times strictly increasing), and `not_planted`, `not_swinging`, `rises` and `rests` when given (each a non-empty list of part names, each once; no part both in `not_swinging` and in `rises` or `rests`), and `may_fold` when given (a non-empty list of `{ "slot", "animation", "why" }`, every one a non-blank string, each pair once; issue #320), and `pinholes` when given (an object whose one field, `required`, is `true` or `false`; issue #944), `seam_over_motion` when given (the same shape; issue #941), and `boundary_colour` when given (an object whose one field, `max_step_excess`, is an integer from 0 through 255; issue #942), and `motion_seams` when given (an array of `{part, neighbour}`, each an unordered pair of distinct output part names, once per list; issue #1269), and `behind_seams` when given (optional `threshold`, `allowance`, `pairs`, `turn: true`; each pair requires distinct nonempty `part` and `neighbour`, with optional `threshold` and `allowance`; thresholds are integers from 0 through 255, allowances are nonnegative safe integers, and reverse duplicates are invalid; issue #1314). `note`, `*_note` (strings) and `x-…` (any value) are read by nothing, as in the config | write the field; the bar is yours. For a pair read only by `seam_over_motion.required`, declare requirements-level `motion_seams` `[{part, neighbour}]` and omit a seam requirement; this leaves a frozen `parts.json` untouched. `config.motion_seams` remains an assemble-time carrier into `parts.json`. See the [carrier contract](#CONFIG_MOTION_SEAM) and [background over every frame](#background-over-every-frame-issue-941). |
6293
6293
  | <a id="REQUIREMENTS_RESOLVES"></a>`REQUIREMENTS_RESOLVES` | a bone, an `ik` or `transform` constraint (by name and `constraint_type`, as rig-c resolves it), a slot, a mesh attachment or an animation the file names is not in `rig.json` or `motion.json`, or a seam's part, a requirements-level `motion_seams` part or neighbour, or a `not_planted`, `not_swinging`, `rises` or `rests` name is not in `parts.json` — the detail lists the ones that are; or an animation whose name cannot be a directory. Refused before anything is built | the name as the rig spells it |
6294
6294
  | <a id="REQUIREMENTS_CONSTRAINT_DRIVES"></a>`REQUIREMENTS_CONSTRAINT_DRIVES` | a `follow` names a bone its constraint does not constrain, or a property it does not drive: an `ik` drives `rotate` only; a `transform` drives `rotate` when a `to` names `rotate`, `translate` when one names `x` or `y` | the constraint's own bone and property |
6295
6295
  | <a id="REQUIREMENTS_TARGET_PARENT"></a>`REQUIREMENTS_TARGET_PARENT` | a scene target's bone is the root or is not parented to it, or the root is not at rest at the origin, or the animation keys the root — a stage point is a bone's position only under a root that stands still at the origin | a bone under the root for the scene to place |
@@ -6420,12 +6420,23 @@ and stay absent).
6420
6420
  | <a id="SCENE_EDITOR_RECEIPT_MISSING"></a>`SCENE_EDITOR_RECEIPT_MISSING` | `scene.plate.editor_receipts.required` is true and no verified receipt matches the plate's bytes | edit the plate in an image editor and record a matching receipt |
6421
6421
  | <a id="SCENE_PLATE_PROVENANCE"></a><a id="SCENE_PLATE_PRESENT"></a><a id="SCENE_PLATE_SIZE"></a>`SCENE_PLATE_PROVENANCE`, `SCENE_PLATE_PRESENT`, `SCENE_PLATE_SIZE` | the plate's `provenance` is not `observed`, `generated` or `unknown`; its image is missing or not a PNG; it is not the canvas's size (it is drawn at canvas (0, 0) and never scaled) | the plate |
6422
6422
  | <a id="SCENE_BUILD_PRESENT"></a>`SCENE_BUILD_PRESENT` | a build directory, or a file `build` writes in it (`parts.json`, `rig/rig.json`, `rig/motion.json` with an `idle`, an image its skin names, `check/check.json`), is missing | run `build` for that character |
6423
+ | <a id="SCENE_PLATE_AT"></a>`SCENE_PLATE_AT` | a named layer's `at` is missing or not two finite integers | declare the image top-left in canvas pixels, y down; negative/outside coordinates are allowed |
6424
+ | <a id="SCENE_PLATE_NAME_UNIQUE"></a><a id="SCENE_PLATE_NAME_FREE"></a>`SCENE_PLATE_NAME_UNIQUE`, `SCENE_PLATE_NAME_FREE` | duplicate plate name or a collision with root, legacy plate, character id, bone, slot or animation | a distinct name and its exact once-only order token |
6425
+ | <a id="SCENE_PLATE_BACKDROP_SIZE"></a>`SCENE_PLATE_BACKDROP_SIZE` | an opaque declared backdrop is smaller than the composed stage in either width or height; the refusal names the layer, found dimensions and both required dimensions | use alpha or a backdrop meeting both canvas dimensions, which equal the stage; positioning outside the canvas does not relax the size floor |
6426
+ | <a id="SCENE_PLATE_ALPHA"></a>`SCENE_PLATE_ALPHA` | a named layer is opaque in every decoded texel without its own `opaque_backdrop: true` declaration | export the intended transparency or explicitly declare that layer's backdrop role; rigc A19 is still enforced |
6423
6427
  | <a id="SCENE_BUILD_GREEN"></a>`SCENE_BUILD_GREEN` | the build's own `check/check.json` does not say `PASS` and `gate_spine_html_green`; under an accept list (`--accept`, `characters[].accept`), it failed a bar the list does not name, its gate is red, a declared requirement is not PASS, or it names no failing bar — the bars not met and the ones accepted are listed | finish that character first: compose binds finished characters. To look at the scene meanwhile, name the failing bars (§7, *Composing several characters*) |
6424
6428
  | <a id="SCENE_ACCEPT_KNOWN"></a>`SCENE_ACCEPT_KNOWN` | an `--accept` name, or one in a character's `accept`, is not a bar `check` holds a build to: a problem code (`CHECK_LOOP_CLOSES`) where the bar's name (`loop`) belongs, a misspelling, or `gate`, which is rig-c's and never accepted | one of the names the message lists |
6425
6429
  | <a id="SCENE_BUILD_FIELD_KNOWN"></a>`SCENE_BUILD_FIELD_KNOWN` | a build's `rig.json` or `motion.json` carries a key compose does not know how to prefix or place, or a root with a transform of its own | a rig `build` wrote; a rig written by something else is `check`'s to measure (§7, *Measuring a rig rig-parts did not assemble*), not compose's to merge |
6426
6430
  | <a id="SCENE_RIG_SCALE_AGREES"></a>`SCENE_RIG_SCALE_AGREES` | the characters' `parts.json` `scale_rig_per_source` differ (each named) | one `assemble.rig_scale` for every character; `characters[].scale` sizes a placed character, it does not make two `rig_scale`s one |
6427
6431
  | <a id="SCENE_SCALE_EXACT"></a>`SCENE_SCALE_EXACT` | a character at a `scale` other than 1 carries something no per-character value can scale: a physics constraint with a nonzero `wind` or `gravity` (Spine applies both through the skeleton's `referenceScale`, which the composed skeleton holds once for every character), a track whose `property` compose does not know to be a length or not, or a translate key whose `v` is neither a list of numbers nor a map of them | `scale` 1 for that character, or rebuild it at another `assemble.rig_scale` |
6428
- | <a id="SCENE_DURATION_AGREES"></a>`SCENE_DURATION_AGREES` | the characters' idles are of different durations (each named) | one `motion.duration` |
6432
+ | <a id="SCENE_DURATION_AGREES"></a>`SCENE_DURATION_AGREES` | the characters' idles are of different durations (each named), or `scene.animations.idle.duration` differs from the composed idle | declare the same duration; compose never stretches or retimes either side |
6433
+ | <a id="CE_COMPILE_ANIMATION_GROUP_UNKNOWN"></a>`CE_COMPILE_ANIMATION_GROUP_UNKNOWN` | a scene track names no own declared group, including inherited object names such as `constructor` | name an explicitly declared final group; prototype properties are not groups |
6434
+ | <a id="SCENE_ANIMATION_NAME_FREE"></a>`SCENE_ANIMATION_NAME_FREE` | a scene clip name already belongs to an imported character animation | choose a new name; only shared `idle` can be extended |
6435
+ | <a id="SCENE_DIAL_RANGE_DECLARED"></a>`SCENE_DIAL_RANGE_DECLARED` | a keyed slider has no readable explicit `from` and `max` bounds, or its bounds are reversed; the bone and slider are named | declare both finite bounds with `from <= max`; no limits are invented |
6436
+ | <a id="SCENE_DIAL_KEY_RANGE"></a>`SCENE_DIAL_KEY_RANGE` | a scene key on a slider input is outside that slider's declared range; the message names the bone, slider, key time, found value and range | author the value inside its own declared `[from, max]` bounds |
6437
+ | <a id="SCENE_DIAL_KEY_DECLARED"></a>`SCENE_DIAL_KEY_DECLARED` | a scene key uses `derive` on a slider's input property, including one that also carries a raw `v`; derived slider inputs are not a supported scene dial dialect | declare an explicit numeric `v` for the named dial, within the named slider's own range; group member values are checked separately |
6438
+ | <a id="SCENE_ANIMATION_LOOP_CLOSES"></a>`SCENE_ANIMATION_LOOP_CLOSES` | the gated posed samples at 0 and the scene clip's declared duration differ, for a new clip or an idle extension | close the posed bone, slot, geometry, alpha, clip and draw-order state; comparison omits physics simulation only and never wraps the endpoint to zero |
6439
+ | <a id="SCENE_ANIMATION_POSE_READABLE"></a>`SCENE_ANIMATION_POSE_READABLE` | Core cannot read or pose the compiled scene clip for its endpoint comparison | correct the construct named by Core; unreadable poses never count as closed and no scene is emitted |
6429
6440
  | <a id="SCENE_CHARACTER_INSIDE_CANVAS"></a>`SCENE_CHARACTER_INSIDE_CANVAS` | a character's part boxes, placed at its offset, leave the canvas (the boxes and the canvas px quoted) | the offset, or the canvas |
6430
6441
  | <a id="SCENE_ORDER_RESOLVES"></a>`SCENE_ORDER_RESOLVES` | an order entry names no character, or `<id>:<slot>` names a slot that character does not have (its slots listed) | the entry |
6431
6442
  | <a id="SCENE_ORDER_ONCE"></a><a id="SCENE_ORDER_COMPLETE"></a>`SCENE_ORDER_ONCE`, `SCENE_ORDER_COMPLETE` | a slot is drawn twice (a slot entry repeated, or an id listed twice), or never (the character's id is absent and some of its slots are named nowhere — they are listed) | name each slot once, or the id for the slots not named elsewhere |
@@ -7169,7 +7180,7 @@ rig directory, copied away from its `parts.json`, reads `5 of 10`: the gate, the
7169
7180
 
7170
7181
  ### Composing several characters (`compose`, issue #74)
7171
7182
 
7172
- `rig-parts compose --scene <scene.json> --out <dir> [--requirements <file.json>] [--accept <bar>[,<bar>…]]`
7183
+ `rig-parts compose --scene <scene.json> --out <dir> [--requirements <file.json>] [--accept <bar>[,<bar>…]] [--page-size <px>]`
7173
7184
  binds characters this package already built into one rig. Each character runs the
7174
7185
  single-character path (§4, steps 0–9) on its own, already isolated input to a green
7175
7186
  `build` first; compose reads what that build wrote and changes nothing in it.
@@ -7189,12 +7200,92 @@ single-character path (§4, steps 0–9) on its own, already isolated input to a
7189
7200
  | `canvas` | the shared stage, canvas px, y down. The composed rig's stage is the canvas, `root` at its bottom centre, as a single character's is its own |
7190
7201
  | `plate` | optional. `image` (relative to the scene file) is a PNG of exactly the canvas's size; `provenance` is `observed` (the painting's own pixels), `generated` or `unknown` (a residual after the people were removed is `unknown` where they stood, and the author says so); `note` is free text. `provenance` and `note` are copied into `scene.json` and **judged by nothing**. Optional `editor_receipts` uses the [editor receipt ledger](#scene-plate-editor-receipts-issue-966), with paths relative to the scene file and verified file hashes; `required: true` demands a matching plate receipt |
7191
7202
  | `characters[].id` | the prefix: every bone, slot, attachment (skin entry), constraint (its name, and every bone and path slot it names), `stops` entry (its `chain`, `links` and `against`, issue #431), `invariants.detached` bone, track, group and easing of that character is renamed `<id>:<name>`. `root` is the one shared root. A name resolves to exactly one character, and nothing resolves across characters without its prefix |
7192
- | `characters[].build` | a `build --out` directory (relative to the scene file) whose own `check/check.json` is green |
7203
+ | `characters[].build` | a `build --out` directory (relative to the scene file) whose own `check/check.json` is green. After `rig` plus `rigc build`, run `rig-parts check --rig <build>/rig --parts <assembled-inputs> --out <build>/check`; retain its named SKIPs |
7193
7204
  | `characters[].offset` | `[x, y]`, a translation from the build's rig px to canvas px. Every character is built at one `assemble.rig_scale`, so its rig px are canvas px at scale 1 |
7205
+ | `plates` | optional list of named layers (issue #1345); may coexist with legacy `plate`. Every layer requires `name`, `image`, `provenance` and `at: [x, y]`. `image` resolves against the scene file and keeps its native dimensions and PNG bytes, with no scale or canvas containment requirement. `at` is two finite integers locating the image **top-left in canvas pixels, y down, origin top-left**; negative/outside positions are allowed. Missing, fractional and nonfinite placement is `SCENE_PLATE_AT`. Optional `note` and `editor_receipts` have the legacy plate meanings; every ledger is verified independently. `opaque_backdrop: true` exempts only that declared layer from compose's alpha requirement; otherwise at least one decoded texel must have alpha below 255 (`SCENE_PLATE_ALPHA`), even for an oversized image. An opaque declared backdrop must also have width at least `canvas.width` **and** height at least `canvas.height`, the composed rig's stage dimensions, matching core 3.8.0 A19's rig-spec size inference. A smaller opaque backdrop is refused before output by `SCENE_PLATE_BACKDROP_SIZE`; a transparent layer has no size floor. rigc's A19 remains enabled |
7206
+ | `plates[].name` | the layer's bone, slot and attachment name and exact `order` token. Names must be unique, nonempty and distinct from `root`, legacy `plate`, shared `idle`, every character id and every prefixed character bone/slot/animation (`SCENE_PLATE_NAME_UNIQUE`, `SCENE_PLATE_NAME_FREE`). Images use `scene-plate.<declaration-index>.png`, separately from character images; any collision is `SCENE_IMAGE_NAME_FREE` |
7194
7207
  | `characters[].scale` | optional, a positive number; absent is 1, and 1 composes to the bytes a scene without the key writes. The character's size on the canvas, about its stage's top-left corner: a rig px `p` lands at canvas px `scale * p + offset` (issue #197). A character scaled up past its art is drawn soft — the art is not resampled; rebuild it at a higher `assemble.rig_scale` if that matters |
7195
7208
  | `characters[].accept` | optional, a list of bar names: the bars this character's own check may have failed and still be composed (issue #203). `compose --accept <bar>[,<bar>…]` is the same list for every character; the two are joined, so the command line applies to every character and a character's list adds to it. Each name is one of the bars `check`'s summary names, less the gate — `loop`, `seam`, `BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`, `ANIMATIONS_DO_NOT_FOLD` (issue #320), `STRESS_OFF_CHAIN` (issue #347), `SEAM_OVER_MOTION` (the body-root bar, issue #686); anything else is `SCENE_ACCEPT_KNOWN`. A build is taken when every bar its `check.json` failed is named; its gate red, a declared requirement not PASS, or a bar not named is `SCENE_BUILD_GREEN` as before. **It is for looking, not for shipping:** the `[compose]` line says which failing bars were accepted, `scene.json` records them as the character's `accepted`, the composed rig's own check measures them again and reports them as it finds them, and the run exits 1 even when that check is PASS (a composed rig has no `parts.json`, so the seam and four judgement lines say SKIP there). A list that accepts nothing — every build green — composes to the bytes a scene without one writes |
7209
+ | `animations` | optional map by scene clip name, each value a rigc `MotionAnimation` (`duration`, `tracks`, optional `loop`, `note`, and core timeline collections). Names resolve against the final scene without another prefix or unit conversion: `plate`, declared named plate bones and `<id>:<bone>`, including generated dials. A new name adds; `idle` appends tracks/timelines to the composed idle, preserving its metadata and every existing character track, deform and physics constraint. Its duration must exactly equal the composed idle (`SCENE_DURATION_AGREES`); no retiming. An imported animation name cannot be replaced (`SCENE_ANIMATION_NAME_FREE`). Absent declaration preserves legacy bytes and output paths (issue #1346) |
7196
7210
  | `order` | the draw order, back to front: a character id (its slots not named elsewhere, in its own order) or one `<id>:<slot>`. Every slot of every character is drawn exactly once. Interleaving is written by naming slots: `["a", "b:arm_l", "b"]` draws `b`'s left arm between `a` and the rest of `b` |
7197
7211
 
7212
+ Named plates join `order` exactly once, wherever their tokens occur: for example
7213
+ `["backdrop", "left", "middle", "right", "foreground"]`. Character tokens still
7214
+ expand only their slots not explicitly named elsewhere. Duplicate plate or slot
7215
+ tokens are `SCENE_ORDER_ONCE`; an omitted layer/slot is `SCENE_ORDER_COMPLETE`;
7216
+ an unknown token is `SCENE_ORDER_RESOLVES`. Declaration order does not draw a
7217
+ layer. The legacy `plate`, when present, remains first.
7218
+
7219
+ Each named plate's bone is under `root` at `(0, 0)`. Its attachment centre is
7220
+ `x = stage.x + at[0] + image.width / 2` and
7221
+ `y = cropToSpineY(at[1] + image.height / 2, canvas.height)` through `src/coords.ts`.
7222
+ Thus a canvas-sized named plate at `[0, 0]` has the same bone/attachment numbers
7223
+ as legacy `plate`. The optional report `plates` array records each name, source
7224
+ image, provenance, note, `at`, `opaque_backdrop`, bone, slot, native size and PNG
7225
+ SHA-256, with `judged_by: "nothing"` for the pixel-origin declaration. Absent
7226
+ `plates` adds no report key and preserves existing output bytes. Plate motion
7227
+ and depth-derived parallax are not introduced by this declaration.
7228
+
7229
+ Scene animation values use rigc's motion units: translations are offsets in the
7230
+ final bone's local frame (rig pixels, y up); rotations are degrees added to setup.
7231
+ Durations, key times and values are required declarations. Core parses the clip
7232
+ and resolves targets, groups and easings against the composed rig/motion, using
7233
+ its existing named refusals, including `CE_COMPILE_ANIMATION_BONE_UNKNOWN`,
7234
+ `CE_COMPILE_ANIMATION_TRACK_DUPLICATE`, `CE_COMPILE_KEY_AFTER_DURATION` and
7235
+ `CE_COMPILE_SLIDER_ANIMATION_UNKNOWN`. A missing prefixed bone also names its
7236
+ character ID; no alternate bone is selected. Groups/easings reference the final
7237
+ prefixed definitions already in the scene; this field adds no definitions.
7238
+
7239
+ Generated dial names are stable: `<id>:yaw_dial`, `<id>:pitch_dial`, and
7240
+ `<id>:<turn.body.slider>` (default `<id>:body_yaw_dial`); renaming these is a major
7241
+ change. They exist only when that character's producer generated them. Dial
7242
+ rotation keys must lie in their own slider's explicitly declared `[from, max]`
7243
+ range. `SCENE_DIAL_KEY_RANGE` names the bone, slider, time, found value and range;
7244
+ `SCENE_DIAL_RANGE_DECLARED` refuses unreadable bounds instead of inventing limits.
7245
+ Keys on a slider input must state numeric `v` values. `derive` there is refused
7246
+ by `SCENE_DIAL_KEY_DECLARED`, even alongside a raw `v`, because derived inputs
7247
+ are not a supported scene dial dialect. A group's explicit values are checked
7248
+ against each member dial's own declared range.
7249
+ Slider source properties resolve to their numeric timeline channels: `x/y` read
7250
+ `translatex/translatey` or the respective `translate` channel; `scaleX/scaleY`
7251
+ read `scalex/scaley` or the respective `scale` channel; `shearY` reads `sheary`
7252
+ or the second `shear` channel. Only the channel that drives that slider is
7253
+ compared to its bounds. Group names must be own declared keys; inherited object
7254
+ properties are refused with `CE_COMPILE_ANIMATION_GROUP_UNKNOWN`.
7255
+
7256
+ For example, this declaration adds a plate take independently of character idle:
7257
+
7258
+ ```json
7259
+ "animations": {
7260
+ "pan": {
7261
+ "duration": 4,
7262
+ "loop": true,
7263
+ "tracks": [{
7264
+ "bone": "plate", "property": "translate",
7265
+ "keys": [{"t": 0, "v": [-3, 0]}, {"t": 2, "v": [3, 0]}, {"t": 4, "v": [-3, 0]}]
7266
+ }]
7267
+ }
7268
+ }
7269
+ ```
7270
+
7271
+ Legacy same-path comparisons report raw file differences as well as stable-byte
7272
+ parity. Core's `check/build/run.json` carries fresh `started_at` and `finished_at`
7273
+ execution timestamps. Only those two valid clock fields may differ in the
7274
+ stable comparison: every other receipt field and every other output byte must
7275
+ match. Raw all-file equality is never reported when those clocks differ.
7276
+
7277
+ Every declared scene clip, including an `idle` extension, is sampled from the
7278
+ gated compiled model at `t=0` and its declared duration before any scene output
7279
+ is emitted. Bone transforms, drawn/deformed geometry, slots, alpha, clipping and
7280
+ draw order must be identical (`SCENE_ANIMATION_LOOP_CLOSES`). This observes posed
7281
+ samples, including interpolation and slider application, rather than comparing
7282
+ raw endpoint keys or wrapping the end back to zero. Physics simulation is left
7283
+ out of this keyed-closure observation, as in `check`'s loop bar; emitted physics
7284
+ constraints/tracks remain unchanged. Fired events are not pose state. `loop` is
7285
+ the core player hint; it does not waive this scene closure requirement. A new
7286
+ named clip does not layer character idle automatically; extend `idle` when its
7287
+ breathing/blink/deform/physics payload must remain in that take.
7288
+
7198
7289
  What is composed:
7199
7290
 
7200
7291
  - **Images are `<id>.<file>`, not `<id>:<file>`.** rig-c names an atlas region
@@ -7245,10 +7336,45 @@ What is composed:
7245
7336
  play. Each is read with the idle's own key lists, so a key compose does not know
7246
7337
  how to prefix is `SCENE_BUILD_FIELD_KNOWN`, as it is on the idle, and a track of
7247
7338
  one that keys `root` is `SCENE_ROOT_SHARED` (issue #183).
7339
+ - **Turn producer output** (issue #1344) is admitted explicitly: yaw/pitch
7340
+ `derive` keys (including per-bone depth maps and per-member values), weighted
7341
+ deform offsets and the producer's `depth: true` yaw/pitch deform transforms.
7342
+ Slots, attachments, map members and slider animation references are prefixed;
7343
+ the one `default` skin stays shared. Degrees, key times and grid counts stay;
7344
+ translate values, derive `depth`/`carried`/`about`, and weighted deform offsets
7345
+ scale with the character. Unknown nested models or fields are refused by name.
7346
+ - **Depth grids** carry only the rig producer's `generator: {kind: "grid",
7347
+ cols, rows, depth: {image, near, zScale}}`. The depth image is copied unchanged
7348
+ under the character's image prefix, and the generator names that copy; it is
7349
+ compile-time input, not another atlas region. A generated image-sized grid at
7350
+ character scale other than 1 is `SCENE_SCALE_EXACT`: moving its bone offsets
7351
+ and depth scale alone cannot resize its bind geometry. Rebuild it at another
7352
+ `assemble.rig_scale`; no image or geometry resampling is guessed.
7353
+ - **Producer invariants** carry `inherit` modes unchanged and prefix
7354
+ `deformMayFold` slots without changing their reasons. Declared `meshSlots`
7355
+ ceilings are summed for the composed skeleton; a member with no ceiling
7356
+ contributes its actual mesh-slot count. `meshTriangles` is the maximum of the
7357
+ declared per-mesh ceilings and actual maxima of members with none. These
7358
+ counts come from emitted weighted triangles or declared grid dimensions;
7359
+ scenes with no declared budget gain no budget field.
7360
+ - **A rig gate is not the character's check.** `rig-parts rig --out <build>/rig`
7361
+ followed by `rigc build` does not create `<build>/check/check.json` and remains
7362
+ `SCENE_BUILD_PRESENT`, even if the rigc gate is green. Keep `parts.json` beside
7363
+ `rig/`, then run `rig-parts check --rig <build>/rig --parts <build> --out <build>/check`
7364
+ before composing. Only a standalone rig with no manifest in its own or parent
7365
+ directory may omit `--parts`; its parts-dependent lines retain named SKIPs. The check must
7366
+ report both `PASS: true` and `gate_spine_html_green: true`; named accepted
7367
+ failing bars keep the existing preview-only semantics. No alternate gated-only
7368
+ admission is implied by the turn contract.
7248
7369
  - **Gated as `rig` gates its own:** `rigc build --profile rig-play --pack`, the
7249
7370
  compile and the packed pages on disk, in a scratch directory; `--out` receives
7250
7371
  `rig/` (`rig.json`, `motion.json`, `images/`) and `scene.json` only when it is
7251
- green. Then `check` runs over `rig/` into `check/`, as on any rig it did not
7372
+ green. `--page-size <px>` (a positive integer, refused as `PACK_PAGE_SIZE`
7373
+ otherwise; issue #1352) is forwarded to both packed builds and recorded as
7374
+ `pack_mode.page_size` in `scene.json` and `check/check.json` only when given;
7375
+ without it, rigc's default 2048 px page and padding 2 on each side bound any
7376
+ plate or region side to at most 2044 px before `CE_ATLAS_REGION_EXCEEDS_PAGE`
7377
+ (`COMPOSE_RIGC_GREEN`). Then `check` runs over `rig/` into `check/`, as on any rig it did not
7252
7378
  build: without a `parts.json` the seam, `BREATH_VISIBLE`, `BLINK_NO_HOLE`,
7253
7379
  `TIP_OVER_ROOT`, `STILL_REGIONS_DARK` and `RECOMPOSITE_HOLES` say SKIP and why,
7254
7380
  and the gate, the loop, `CHAIN_LAG` and `TEXTURE_STRETCH` measure.
@@ -7286,6 +7412,45 @@ character's input arrives isolated); a composed `parts.json`, so the bars that
7286
7412
  read See-through tags are measured per character by its own `build`, not over the
7287
7413
  scene; a rig `build` did not write.
7288
7414
 
7415
+
7416
+ #### Compose input record (issue #1348)
7417
+
7418
+ A fully green compose writes `compose-run.json` at the `--out` root, beside
7419
+ `scene.json`, with spec `rig-compose-run/1`. It removes a previous record before
7420
+ the stage begins, including before stage option validation; a refused input,
7421
+ rig-c gate, check or accepted failing character leaves no record. The existing
7422
+ rig, scene report and check keep their bytes and paths. Core's nested
7423
+ `check/build/run.json` retains its own clocks; it is a different record.
7424
+
7425
+ The fixed top-level key order is `spec`, `scene`, `characters`, `plate`, `plates`:
7426
+
7427
+ | entry | exact binding |
7428
+ | --- | --- |
7429
+ | `scene` | `{path, sha256}`: `path` as supplied to compose and SHA-256 of the raw scene JSON bytes parsed, including whitespace |
7430
+ | `characters` | sorted by `id` in code-unit order; each `{id, build, files}`, with `build` as declared in the scene, and `files` sorted by build-relative `path`; each file is `{path, sha256}` |
7431
+ | `plate` | legacy plate `{path, sha256}`, with its image path as declared relative to the scene file, or `null` when absent |
7432
+ | `plates` | every named plate `{name, path, sha256}`, sorted by `name` in code-unit order; image paths as declared relative to the scene file; `[]` when absent |
7433
+
7434
+ The character file inventory is exactly `check/check.json` (admission verdict),
7435
+ `parts.json` (rig dimensions, scale and art bounds), `rig/rig.json` (structure,
7436
+ skins and references), `rig/motion.json` (animation), and each distinct image
7437
+ named by the default skin under `rig/images/`, including a generator's depth
7438
+ image. These are the bytes compose parses or passes into the composed rig.
7439
+ It does not enumerate the build directory: unused images, packed pages,
7440
+ source configs and the character's own `run.json` are excluded. A declared
7441
+ `parts.json` painting binding and editor receipts keep their existing validation;
7442
+ their declarations are bound through the containing input bytes. This record
7443
+ inventories the listed compose inputs, not external requirements or CLI options.
7444
+
7445
+ Hashes are captured from the same byte buffers consumed before the gate, never
7446
+ by rereading inputs after it. Image hashes bind encoded file bytes, including
7447
+ any trailing bytes, rather than decoded pixels. Identical inputs at identical
7448
+ supplied paths give identical record bytes; there are no clocks. A changed byte
7449
+ changes its input entry's hash; if multiple entries reference one physical file,
7450
+ each reference changes. Missing scene, build and plate files retain their named
7451
+ `SCENE_FILE`, `SCENE_BUILD_PRESENT` and `SCENE_PLATE_PRESENT` refusals.
7452
+
7453
+
7289
7454
  ### Declared requirements (`--requirements`)
7290
7455
 
7291
7456
  The bars above are this package's. What a *scene* asks of the rig's motion — that
@@ -7922,11 +8087,41 @@ It cannot establish a behind-part PASS.
7922
8087
  | --- | --- |
7923
8088
  | `behind_seams.threshold` | Optional authored T, an integer from 0 through 255. There is no default. A pair override can supply it; a pair with neither value reports SKIP and a HOLE. |
7924
8089
  | `behind_seams.allowance` | Optional nonnegative safe integer counted-cell allowance for both independent halves. The explicit design ruling sets omission to 0. |
8090
+ | `behind_seams.turn` | Optional literal `true`: measure existing declared turn slider endpoints and full corners; no range is declared here. Omit for byte-identical setup/idle-only output. |
7925
8091
  | `behind_seams.pairs` | Optional array of selected-pair overrides; no adjacency is guessed. |
7926
8092
  | `behind_seams.pairs[i].part`, `behind_seams.pairs[i].neighbour` | Required distinct nonempty part names. They must resolve to known parts in the selected declaration population; repeating a pair in either order is invalid. |
7927
8093
  | `behind_seams.pairs[i].threshold` | Optional authored integer T from 0 through 255, overriding the rig value for this pair. No effective T means SKIP and a HOLE. |
7928
8094
  | `behind_seams.pairs[i].allowance` | Optional nonnegative safe integer, overriding the rig allowance for both halves of this pair. |
7929
8095
 
8096
+ With `turn: true`, `BEHIND_PART_SEAMS.turn` is separate from setup and idle.
8097
+ For each declared local dial, sample its `from` and `max` with all others at
8098
+ setup, followed by every full min/max corner; duplicate poses occur once.
8099
+ For yaw, pitch and body yaw this means six axis endpoints and eight corners.
8100
+ Each row names the planned and observed dial locals and observed slider mapped
8101
+ times, using independent t=0 reset samples rather than idle time. The turn block records selected pose names, per-pair native
8102
+ frames and sampled/read/unmeasured pose counts, and separate standing and
8103
+ motion-opened maxima. No sweep or temporal span is claimed. Its stock transported
8104
+ setup-overlap evidence is computed separately with the official seam reader;
8105
+ the idle's exact stock binding is unchanged. One throwaway rig-c build appends a
8106
+ duration-0 animation for each selected pose, retaining the accepted setup,
8107
+ sliders, existing animations, build profile and pack flags. Its public motion
8108
+ tracks use `rotate`, `translatex` or `translatey`, with planned local minus
8109
+ setup as the key offset. The official facade samples each animation at t=0;
8110
+ rig-c applies its timeline before constraints. Local channels and slider times
8111
+ are observations after constraints, not a pre-constraint hook. Planned locals
8112
+ must match the observed locals at float32 precision. No second poser, projection
8113
+ or skinning implementation is used. The copy must retain the actual poser,
8114
+ atlas text, decoded pages and setup geometry; any mismatch or build refusal is
8115
+ a named turn HOLE while unrelated readings continue. Turn limitations record
8116
+ the original accepted skeleton SHA-256 once. The scratch copy is removed even
8117
+ on refusal; without the turn opt-in no copy or extra build is created.
8118
+ A missing optional poser is a named HOLE. A missing dial persists turn SKIP and
8119
+ its HOLE; an effective T makes it a required-unmeasured failure. Legacy `turn.x`
8120
+ has no finite range declaration and stays unread. Unread corridors cannot become
8121
+ zero counts. Thresholds and per-pair allowances apply unchanged to turn. A pair
8122
+ without its own effective T stays SKIP with a HOLE; another pair's override
8123
+ does not make that optional reading fail the turn block.
8124
+
7930
8125
  Malformed shapes and fields are [`REQUIREMENTS_FIELD`](#REQUIREMENTS_FIELD).
7931
8126
  Pair names must resolve to known parts and the pair must already belong to
7932
8127
  the actual selected declarations; neither is inferred from tags or body roles. Existing limb-segment, proven body-root and explicit
@@ -8246,6 +8441,36 @@ parents and stops keep their emitted names; Core creates the draw bones later.
8246
8441
  A name ending in `_d` alone is not an alias: a missing non-stop bone still
8247
8442
  raises `RIG_TURN_SURFACE_MESH_BINDINGS`. No new config field is required.
8248
8443
 
8444
+ All surfaces in one turn group share the reference already used by its sampled
8445
+ units: the first surface's opaque-art depth median, with `face` preferred for
8446
+ the head. When both eye landmarks exist, the head uses their mean depth sampled
8447
+ on that primary surface instead. Generated grids and authored weighted meshes
8448
+ both move by `-(pivot + z - zRef) * sin(angle)` along the active axis. Each
8449
+ surface samples its own sheet for `z`; it does not subtract its own median or
8450
+ eye samples. The depth recipe's `median` is encoded upstream in that sheet,
8451
+ so relative placements between surfaces survive the turn. Each group keeps
8452
+ its own reference; a single surface keeps its existing motion bytes.
8453
+ Where boundary continuity is intended, adjust the declared `median` and `relief`
8454
+ so sampled depths meet there; choosing a different shared reference leaves the
8455
+ seam jump unchanged. See [DEPTH](DEPTH.md) for the boundary-depth equation.
8456
+
8457
+ Mixed depth and normals sources use this same coordinate space. Depth apply
8458
+ normalizes each raw field by its own median and percentile span, then encodes
8459
+ the declared `median + relief * u` in rig pixels. Raw model offsets and scales
8460
+ do not survive as a second turn scale. After decoding either `near` polarity,
8461
+ larger `z` means nearer and increases the signed depth `pivot + z - zRef`.
8462
+ Thus a back surface must declare smaller normalized depths than the face to
8463
+ sit behind it; draw order and a part's name do not calibrate its sheet.
8464
+
8465
+ A smaller declared median alone does not order every point: relief can overlap
8466
+ the sheets' depth ranges, and clipping changes the encoded range. Compare
8467
+ decoded support ranges and the emitted travel at both dial extremes. Absolute
8468
+ travel is `abs(pivot + z - zRef) * abs(sin(angle))`; beyond the pivot a further
8469
+ point moves in the opposite direction and can travel more in absolute pixels.
8470
+ Correct the consumer's existing median/relief declarations when they encode the
8471
+ wrong placement. Turn does not invent source-specific offsets, rescale relief,
8472
+ or cap a back surface's travel to the face's.
8473
+
8249
8474
  Depth-turn `"surface"` parts may use authored weighted `grid`, `contour`,
8250
8475
  `influence` or `explicit` meshes, or the turn-generated grid when attached as
8251
8476
  a region. `auto` cannot combine with `"surface"` in either `turn.roles` or
@@ -8951,15 +9176,18 @@ Internal `SeamSupport.drawings` never enters check JSON. Named requirement
8951
9176
  | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for e.slot; otherwise [] | [check.ts:3550](../src/check.ts#L3550) |
8952
9177
  | `ANIMATIONS_DO_NOT_FOLD.folding` | `ANIMATIONS_DO_NOT_FOLD.folding` | part when the supplied mapping resolves a piece; otherwise rig | finding when entry === undefined; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:3512](../src/check.ts#L3512) |
8953
9178
  | `ART_JOINT_DISTANCE.joints` | `ART_JOINT_DISTANCE.joints` | 'rig' | finding when status === 'FAIL'; otherwise evidence | [] | [artjoints.ts:86](../src/artjoints.ts#L86) |
8954
- | `BEHIND_PART_SEAMS.contributors` | `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples[].contributors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:348](../src/behindseams.ts#L348) |
8955
- | `BEHIND_PART_SEAMS.hits` | `BEHIND_PART_SEAMS.pairs[].motion_opened.frames`; `BEHIND_PART_SEAMS.pairs[].standing.frames`; `BEHIND_PART_SEAMS.pairs[].motion_opened.worst`; `BEHIND_PART_SEAMS.pairs[].standing.worst` | 'pair' | finding when r.px > allowance; otherwise evidence | parts | [behindseams.ts:408](../src/behindseams.ts#L408) |
8956
- | `BEHIND_PART_SEAMS.pairs` | `BEHIND_PART_SEAMS.pairs` | 'pair' | finding when failed; otherwise evidence | parts | [behindseams.ts:485](../src/behindseams.ts#L485) |
9179
+ | `BEHIND_PART_SEAMS.contributors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.samples[].contributors`; `BEHIND_PART_SEAMS.turn.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples[].contributors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:396](../src/behindseams.ts#L396) |
9180
+ | `BEHIND_PART_SEAMS.hits` | `BEHIND_PART_SEAMS.pairs[].motion_opened.frames`; `BEHIND_PART_SEAMS.pairs[].standing.frames`; `BEHIND_PART_SEAMS.pairs[].motion_opened.worst`; `BEHIND_PART_SEAMS.pairs[].standing.worst` | 'pair' | finding when r.px > allowance; otherwise evidence | parts | [behindseams.ts:456](../src/behindseams.ts#L456) |
9181
+ | `BEHIND_PART_SEAMS.pairs` | `BEHIND_PART_SEAMS.pairs` | 'pair' | finding when failed; otherwise evidence | parts | [behindseams.ts:533](../src/behindseams.ts#L533) |
8957
9182
  | `BEHIND_PART_SEAMS.pairs[].frames` | `BEHIND_PART_SEAMS.pairs[].frames` | | | | |
8958
9183
  | `BEHIND_PART_SEAMS.pairs[].setup` | `BEHIND_PART_SEAMS.pairs[].setup` | | | | |
8959
- | `BEHIND_PART_SEAMS.samples` | `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:347](../src/behindseams.ts#L347) |
8960
- | `BEHIND_PART_SEAMS.spans` | `BEHIND_PART_SEAMS.pairs[].motion_opened.spans`; `BEHIND_PART_SEAMS.pairs[].standing.spans` | 'pair' | evidence | parts | [behindseams.ts:416](../src/behindseams.ts#L416) |
8961
- | `BEHIND_PART_SEAMS.unmeasured` | `BEHIND_PART_SEAMS.unmeasured` | pair === null ? 'rig' : 'pair'; 'rig' | finding when required; otherwise evidence; finding | pair === null ? [] : [pair.a, pair.b]; [] | [behindseams.ts:429](../src/behindseams.ts#L429), [behindseams.ts:562](../src/behindseams.ts#L562), [behindseams.ts:590](../src/behindseams.ts#L590) |
8962
- | `BEHIND_PART_SEAMS.unread_corridors` | `BEHIND_PART_SEAMS.pairs[].setup.standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.unread_corridors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:271](../src/behindseams.ts#L271) |
9184
+ | `BEHIND_PART_SEAMS.samples` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.samples`; `BEHIND_PART_SEAMS.turn.pairs[].frames[].motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:395](../src/behindseams.ts#L395) |
9185
+ | `BEHIND_PART_SEAMS.spans` | `BEHIND_PART_SEAMS.pairs[].motion_opened.spans`; `BEHIND_PART_SEAMS.pairs[].standing.spans` | 'pair' | evidence | parts | [behindseams.ts:464](../src/behindseams.ts#L464) |
9186
+ | `BEHIND_PART_SEAMS.turn.pairs` | `BEHIND_PART_SEAMS.turn.pairs` | 'pair' | finding when required; otherwise evidence; finding when motion.status === 'FAIL' &#124;&#124; standing.status === 'FAIL' &#124;&#124; threshold !== null && read !== turn.poses.length; otherwise evidence | [pair.a, pair.b]; parts | [behindseams.ts:563](../src/behindseams.ts#L563), [behindseams.ts:605](../src/behindseams.ts#L605) |
9187
+ | `BEHIND_PART_SEAMS.turn.pairs[].frames` | `BEHIND_PART_SEAMS.turn.pairs[].frames` | | | | |
9188
+ | `BEHIND_PART_SEAMS.turn.unmeasured` | `BEHIND_PART_SEAMS.turn.unmeasured` | pair === null ? 'rig' : 'pair' | finding when mandatory; otherwise evidence | pair === null ? [] : [pair.a, pair.b] | [behindseams.ts:555](../src/behindseams.ts#L555) |
9189
+ | `BEHIND_PART_SEAMS.unmeasured` | `BEHIND_PART_SEAMS.unmeasured` | pair === null ? 'rig' : 'pair'; 'rig' | finding when required; otherwise evidence; finding | pair === null ? [] : [pair.a, pair.b]; [] | [behindseams.ts:477](../src/behindseams.ts#L477), [behindseams.ts:806](../src/behindseams.ts#L806), [behindseams.ts:838](../src/behindseams.ts#L838) |
9190
+ | `BEHIND_PART_SEAMS.unread_corridors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.unread_corridors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:319](../src/behindseams.ts#L319) |
8963
9191
  | `BOUNDARY_COLOUR_STEP.over` | `BOUNDARY_COLOUR_STEP.over` | 'pair' | finding | r.parts | [boundarycolour.ts:221](../src/boundarycolour.ts#L221) |
8964
9192
  | `BOUNDARY_COLOUR_STEP.unmeasured` | `BOUNDARY_COLOUR_STEP.unmeasured` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for r.slot; otherwise [] | [boundarycolour.ts:222](../src/boundarycolour.ts#L222) |
8965
9193
  | `CLOTH_SETTLES.rows` | `CLOTH_SETTLES.rows` | 'rig' | finding when speeds.length > 0 && s < speeds.length; otherwise evidence | [] | [check.ts:5996](../src/check.ts#L5996) |
@@ -8983,21 +9211,21 @@ Internal `SeamSupport.drawings` never enters check JSON. Named requirement
8983
9211
  | `SEAM_OVER_RANGE.joints[].poses` | `SEAM_OVER_RANGE.joints[].poses` | 'part' | finding when fail; otherwise evidence | [j.part] | [check.ts:4411](../src/check.ts#L4411) |
8984
9212
  | `SETUP_MATCHES_PAINTING.regions` | `SETUP_MATCHES_PAINTING.regions` | 'rig' | finding when status === 'FAIL'; otherwise evidence | [] | [setuppainting.ts:175](../src/setuppainting.ts#L175) |
8985
9213
  | `SETUP_MATCHES_PAINTING.regions[].slots` | `SETUP_MATCHES_PAINTING.regions[].slots` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for slot; otherwise [] | [setuppainting.ts:176](../src/setuppainting.ts#L176) |
8986
- | `STILL_REGIONS_DARK.*.crossing` | `STILL_REGIONS_DARK.*.crossing` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for sl.name; otherwise [] | [check.ts:9026](../src/check.ts#L9026) |
8987
- | `STILL_REGIONS_DARK.*.still_slots` | `STILL_REGIONS_DARK.*.still_slots` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when r.max > tolerance; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:9012](../src/check.ts#L9012), [check.ts:9017](../src/check.ts#L9017) |
9214
+ | `STILL_REGIONS_DARK.*.crossing` | `STILL_REGIONS_DARK.*.crossing` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for sl.name; otherwise [] | [check.ts:9062](../src/check.ts#L9062) |
9215
+ | `STILL_REGIONS_DARK.*.still_slots` | `STILL_REGIONS_DARK.*.still_slots` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when r.max > tolerance; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:9048](../src/check.ts#L9048), [check.ts:9053](../src/check.ts#L9053) |
8988
9216
  | `STRESS_OFF_CHAIN.not_read` | `STRESS_OFF_CHAIN.not_read` | 'part' | evidence | [r.part] | [check.ts:3971](../src/check.ts#L3971) |
8989
9217
  | `STRESS_OFF_CHAIN.per_part` | `STRESS_OFF_CHAIN.per_part` | 'part' | finding when poses.some(p => typeof p.reading === 'number' && p.reading > STRESS_RIGID); otherwise evidence | [r.part] | [check.ts:3959](../src/check.ts#L3959) |
8990
9218
  | `STRESS_OFF_CHAIN.per_part[].off_chain` | `STRESS_OFF_CHAIN.per_part[].off_chain` | 'part' | evidence | [r.part] | [check.ts:3959](../src/check.ts#L3959) |
8991
9219
  | `STRESS_OFF_CHAIN.per_part[].poses` | `STRESS_OFF_CHAIN.per_part[].poses` | 'part' | evidence; finding when shown > STRESS_RIGID; otherwise evidence | [r.part] | [check.ts:3927](../src/check.ts#L3927), [check.ts:3945](../src/check.ts#L3945) |
8992
- | `TEXTURE_STRETCH.per_mesh` | `TEXTURE_STRETCH.per_mesh` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when severity > TEXTURE_STRETCH_CEILING; otherwise evidence | resolved piece for m.slot; otherwise [] | [check.ts:9676](../src/check.ts#L9676), [check.ts:9686](../src/check.ts#L9686) |
8993
- | `TIP_OVER_ROOT.parts` | `TIP_OVER_ROOT.parts` | 'part' | evidence; finding when !ok && !(!rigid && hanging.onLink && Math.max(c.root, c.tip) < TIP_TRAVEL_FLOOR); otherwise evidence | [p.name] | [check.ts:8430](../src/check.ts#L8430), [check.ts:8435](../src/check.ts#L8435), [check.ts:8456](../src/check.ts#L8456), [check.ts:8467](../src/check.ts#L8467) |
9220
+ | `TEXTURE_STRETCH.per_mesh` | `TEXTURE_STRETCH.per_mesh` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when severity > TEXTURE_STRETCH_CEILING; otherwise evidence | resolved piece for m.slot; otherwise [] | [check.ts:9712](../src/check.ts#L9712), [check.ts:9722](../src/check.ts#L9722) |
9221
+ | `TIP_OVER_ROOT.parts` | `TIP_OVER_ROOT.parts` | 'part' | evidence; finding when !ok && !(!rigid && hanging.onLink && Math.max(c.root, c.tip) < TIP_TRAVEL_FLOOR); otherwise evidence | [p.name] | [check.ts:8466](../src/check.ts#L8466), [check.ts:8471](../src/check.ts#L8471), [check.ts:8492](../src/check.ts#L8492), [check.ts:8503](../src/check.ts#L8503) |
8994
9222
  | `WIND_BAND.pairs` | `WIND_BAND.pairs` | 'pair' | finding when !holdsAll; otherwise evidence | [p.a, p.b] | [check.ts:6500](../src/check.ts#L6500) |
8995
9223
  | `WIND_BAND.pairs[].steps` | `WIND_BAND.pairs[].steps` | 'pair' | finding when !s.holds; otherwise evidence | [p.a, p.b] | [check.ts:6511](../src/check.ts#L6511) |
8996
9224
  | `figure_openings.openings` | `figure_openings.openings` | 'pair' | finding | [ps.under, ps.above] | [check.ts:5817](../src/check.ts#L5817) |
8997
- | `loop_physics` | `loop_physics` | 'rig' | evidence | [] | [check.ts:7498](../src/check.ts#L7498) |
8998
- | `requirements.lines.* (bone)` | `requirements.lines.*` | 'rig' | finding when line.status === 'FAIL'; otherwise evidence | [] | [check.ts:7800](../src/check.ts#L7800) |
8999
- | `requirements.lines.* (seam)` | `requirements.lines.*` | 'pair' | finding when line.status === 'FAIL'; otherwise evidence | [r.part, r.neighbour] | [check.ts:7800](../src/check.ts#L7800) |
9000
- | `requirements.lines.* (stretch)` | `requirements.lines.*` | part when the supplied mapping resolves a piece; otherwise rig | finding when line.status === 'FAIL'; otherwise evidence | resolved piece for r.slot; otherwise [] | [check.ts:7800](../src/check.ts#L7800) |
9225
+ | `loop_physics` | `loop_physics` | 'rig' | evidence | [] | [check.ts:7534](../src/check.ts#L7534) |
9226
+ | `requirements.lines.* (bone)` | `requirements.lines.*` | 'rig' | finding when line.status === 'FAIL'; otherwise evidence | [] | [check.ts:7836](../src/check.ts#L7836) |
9227
+ | `requirements.lines.* (seam)` | `requirements.lines.*` | 'pair' | finding when line.status === 'FAIL'; otherwise evidence | [r.part, r.neighbour] | [check.ts:7836](../src/check.ts#L7836) |
9228
+ | `requirements.lines.* (stretch)` | `requirements.lines.*` | part when the supplied mapping resolves a piece; otherwise rig | finding when line.status === 'FAIL'; otherwise evidence | resolved piece for r.slot; otherwise [] | [check.ts:7836](../src/check.ts#L7836) |
9001
9229
  | `seam_cells.frames` | `frames` | 'pair' | evidence | [p.a, p.b] | [check.ts:4702](../src/check.ts#L4702) |
9002
9230
  | `seam_cells.frames[].cells` | `frames[].cells` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for cell.setupTop ?? ''; otherwise [] | [check.ts:4662](../src/check.ts#L4662) |
9003
9231
  | `seam_pairs` | `seam_pairs`; `seam_scope.whole_pairs`; `sets.*.seam_pairs`; `sets.*.seam_scope.whole_pairs` | subjects.length === 0 ? 'rig' : subjects.length === 1 ? 'part' : 'pair' | evidence | subjects | [check.ts:2508](../src/check.ts#L2508) |
package/docs/DEPTH.md CHANGED
@@ -46,6 +46,28 @@ use. Three things we learned the hard way are built into that path:
46
46
  `median`) and how deep its own shape is (its `relief`) are declared in rig
47
47
  pixels, and the tool never guesses them.
48
48
 
49
+ Surfaces in one turn group share one depth reference: the first surface's
50
+ opaque-art median, preferring the face in a head group. With both eye landmarks,
51
+ the head instead anchors to their mean depth on that primary surface. A surface
52
+ keeps the depth encoded from its declared `median` relative to this shared
53
+ anchor; its own median is not subtracted again. Thus two touching parts retain
54
+ their declared depth difference when they turn. Head and body groups have
55
+ separate anchors, and this applies to generated grids and authored meshes alike.
56
+
57
+ For an abutting body surface such as a sleeve, author the boundary depths in
58
+ that same group space. At yaw angle `a`, the horizontal travel is
59
+ `-(pivot + z - zRef) * sin(a)`, so the jump across a touching pair is
60
+ `abs(zA - zB) * abs(sin(a))`: the common pivot and reference cancel.
61
+ Matching medians does not match boundary depths when the relief differs.
62
+ Conversely, replacing each surface's own median with the shared anchor adds
63
+ `-(ownMedian - zRef) * sin(a)` uniformly to that surface; it can enlarge one
64
+ seam while reducing another. This is placement, not a sleeve-specific scale.
65
+ Where continuity is intended, adjust the declared `median` and `relief` so
66
+ sampled depths meet at the shared boundary, then check both seams at both turn
67
+ extremes. Choosing a different shared reference leaves the seam jump unchanged.
68
+ Neither a per-sleeve pivot nor a guessed correction is inferred. A seam reading
69
+ measures depth discontinuity, not composite visibility.
70
+
49
71
  See-through, the layer decomposition this package reads, also writes a per-layer
50
72
  depth sheet, and a config can register those directly (`config.depth`,
51
73
  [Per-layer depth sheets](AUTHORING.md#per-layer-depth-sheets-773)). In