@rig-c/parts 2.43.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 |
@@ -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
@@ -8285,6 +8450,26 @@ surface samples its own sheet for `z`; it does not subtract its own median or
8285
8450
  eye samples. The depth recipe's `median` is encoded upstream in that sheet,
8286
8451
  so relative placements between surfaces survive the turn. Each group keeps
8287
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.
8288
8473
 
8289
8474
  Depth-turn `"surface"` parts may use authored weighted `grid`, `contour`,
8290
8475
  `influence` or `explicit` meshes, or the turn-generated grid when attached as
package/docs/DEPTH.md CHANGED
@@ -54,6 +54,20 @@ anchor; its own median is not subtracted again. Thus two touching parts retain
54
54
  their declared depth difference when they turn. Head and body groups have
55
55
  separate anchors, and this applies to generated grids and authored meshes alike.
56
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
+
57
71
  See-through, the layer decomposition this package reads, also writes a per-layer
58
72
  depth sheet, and a config can register those directly (`config.depth`,
59
73
  [Per-layer depth sheets](AUTHORING.md#per-layer-depth-sheets-773)). In
package/docs/STABILITY.md CHANGED
@@ -294,7 +294,7 @@ and do not certify visibility. See the
294
294
  | `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--page-size`, `--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) |
295
295
  | `loop` | `--frames`, `--out`; optional `--palette` |
296
296
  | `build` | `--config`, `--source`, `--full`, `--out`; optional `--head` (as for `assemble`), `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--page-size`, `--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) |
297
- | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
297
+ | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept`, `--page-size` |
298
298
  | `mesh-draft` | `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--page-size`, `--more-triangles` |
299
299
  | `mesh-stats` | `--config`, `--parts` (issue #566, additive: prints, writes nothing) |
300
300
  | `remesh` | `--rig`, `--config`, `--parts`, `--part`, `--out`, and one of `--mesh` or `--delta` (issue #526); optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--page-size`, `--record-input-check` and `--input-check` (issue #617, additive: without them nothing `remesh` prints or writes changes) |
@@ -732,7 +732,11 @@ execution in historical evidence is inferred from a current export.
732
732
  | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `remesh.json` | `remesh` | the input revision's files, `rig.json` and `mesh_report.json` with the part's attachment and row replaced (under `--delta` the row is the input's with its counts, `bones` and influences recomputed and `mode` "delta"), every other file byte for byte; `remesh.json` is spec `rig-parts-remesh/1`: `request` (`part`, `mesh`, `mesh_sha256`, `idle_keys`, `page_edges`, `pack_shape`; under `--delta`, issue #526: `part`, `delta` — the mesh edit as read — `delta_sha256`, `ops`, `applied` — `moved`, `added`, `removed`, `constrained` — `idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `baseline` (`reproduced`, `not_compared`; under `--delta` `reproduced` holds one sentence: no config is built, the input is the baseline), `target` (`before`, `after`: `vertices`, `triangles`, `hull`), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-remesh/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `scope`) |
733
733
  | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `retune.json` | `retune` | the input revision's files, `rig.json` with `constraints` and `invariants.detached` replaced and `motion.json` with `animations.idle` replaced by the config's build, every other file byte for byte; `retune.json` is spec `rig-parts-retune/1`: `request` (`idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `held` (`compared`, `not_compared`), `changed` (`constraints` — each `name`, `type`, `fields` — `added`, `removed`, `idle`: `tracks_changed`, `duration` as before and after), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-retune/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `scope`) |
734
734
  | `input-check.json` | `remesh --record-input-check`, `retune --record-input-check` | spec `rig-parts-input-check/1` (issue #617, additive): `versions` (`parts`, `rigc` — `rigc --version`'s whole output), `options` (`page_edges`, `pack_shape`, `page_size` when `--page-size` is given, `requirements` — null, or `path` as resolved and `sha256`), `rig` and `parts` (`dir` as resolved, `files` — `path`, `bytes`, `sha256` per file: every file under `--rig`; `parts.json` and every file under `parts/`), `check` (the input's check side as `remesh.json` carries it); `--input-check` reads it back, and either command's serves the other |
735
- | the scene report | `compose` | spec `spine-parts-scene-report/1`; the plate block carries `sha256` of the plate PNG's bytes after `size` (issue #1183, additive under *What "stable" means here*: a new report key in a minor version, so the spec stays `/1`) |
735
+ | composed turn producer inputs | `compose` | issue #1344 intentionally admits previously refused yaw/pitch derive maps, turn deform offsets/transforms, depth-grid generator images, bone inherit modes and producer mesh/fold invariants; every embedded reference is resolved and prefixed except the shared default skin. Mesh-slot ceilings sum and per-mesh triangle ceilings take the maximum, using actual counts only for unbudgeted members. Weighted lengths scale; image-sized depth grids at scale other than 1 are refused by `SCENE_SCALE_EXACT`. Other nested constructs remain refused. Previously passing scene payloads are byte-identical; the existing `check/check.json` requirement is retained, so `rig` plus `rigc build` alone is not a checked character. |
736
+ | named scene plates | `compose` | issue #1345 adds optional `plates[]`: required `name`, `image`, `provenance`, `at: [x, y]`; optional `note`, `editor_receipts`, `opaque_backdrop`. `at` is two finite integers for the image top-left in canvas pixels, y down from the top-left origin; negatives/outside allowed, no scale, native image size including oversize. Each bone/slot/attachment uses its declared name, bone under root at `(0,0)`; attachment centre is `stage.x + at[0] + width/2`, `cropToSpineY(at[1] + height/2, canvas.height)`. Each layer's token is required exactly once in draw order, with duplicate/missing/unknown/collision refusals. Names cannot collide with root, legacy plate, shared idle, character ids or prefixed bones/slots/animations. Only that layer's explicit `opaque_backdrop: true` exempts it from compose alpha checks; an opaque declared backdrop must additionally meet width >= canvas.width AND height >= canvas.height (the rig stage), matching core 3.8.0 A19 size inference; otherwise SCENE_PLATE_BACKDROP_SIZE refuses before emission. Transparent layers have no size floor. rigc A19 remains enabled. Named images use `scene-plate.<index>.png` with collision checks. The additive report `plates` array records declaration, native size and PNG hash; absent declaration retains legacy output bytes and fixed first-plate behavior. |
737
+ | scene named animations | `compose` | issue #1346 adds optional `scene.animations`, a name-to-rigc-MotionAnimation map resolved against final scene bones/groups/easings. New names add clips at their own declared durations; `idle` appends timelines while retaining existing character tracks, deforms, metadata and physics. Idle duration mismatch is `SCENE_DURATION_AGREES`, without retiming; imported non-idle names cannot be replaced. Core owns missing fields, unknown bones/references, duplicate property tracks and bad times. Unknown prefixed bones also name the character ID. Generated names `<id>:yaw_dial`, `<id>:pitch_dial`, and `<id>:<turn.body.slider>` (default `<id>:body_yaw_dial`) are stable; renaming them requires a major version. A dial exists only when generated by its character. Rotation keys use that slider's declared `[from, max]` bounds; out-of-range values are `SCENE_DIAL_KEY_RANGE`, unreadable bounds `SCENE_DIAL_RANGE_DECLARED`, never guessed. Slider-input keys require explicit numeric values; derive inputs are refused as `SCENE_DIAL_KEY_DECLARED`, including derive alongside a raw value. Bounds apply to the matching scalar or paired translate/scale/shear input channel; inherited group names are refused with `CE_COMPILE_ANIMATION_GROUP_UNKNOWN`. Each declared clip's gated posed endpoints at 0 and duration must agree before emission (`SCENE_ANIMATION_LOOP_CLOSES`), with physics simulation left out only for observation. Absent declaration retains stable output bytes at the same paths. Core `check/build/run.json` records fresh `started_at` and `finished_at` clocks; comparisons report these raw differences separately and require all other receipt fields and output bytes to match. |
738
+ | `compose-run.json` | `compose` | spec `rig-compose-run/1` (issue #1348), separate from `rig-run/1`; a stable contract as of 2.44.0. Written at the `--out` root only after the gate and check are green and no accepted failing character remains, so an `--accept` preview writes none. Fixed keys in order: `spec`, `scene` (`path`, `sha256`), `characters` (each `id`, `build`, `files`, each file `path`, `sha256`), `plate` (`path`, `sha256`, or null), `plates` (each `name`, `path`, `sha256`). Scene and plate paths are the supplied and declared paths; character file paths are build-relative. Characters sort by `id`, files by `path`, named plates by `name`, in code-unit order. Each character's files are exactly `check/check.json`, `parts.json`, `rig/rig.json`, `rig/motion.json` and each distinct image the default skin names under `rig/images/`, including a generator's depth image. Every `sha256` is of the raw file bytes compose consumed before the gate. There are no clocks, directory extras, requirements or CLI-option inventory, so identical inputs at identical supplied paths give identical record bytes. Compose owns the name: a file of that name at the `--out` root is deleted at the start of every compose, before stage validation, so a refused rerun leaves none. Only this file is added; legacy outputs retain stable bytes, with the existing nested Core receipt clock comparison described above. |
739
+ | the scene report | `compose` | spec `spine-parts-scene-report/1`; the plate block carries `sha256` of the plate PNG's bytes after `size` (issue #1183, additive under *What "stable" means here*: a new report key in a minor version, so the spec stays `/1`); `pack_mode` records `page_size` only when `--page-size <px>` is given (issue #1352, additive; without `--page-size`, rigc's default 2048 px page and padding 2 on each side bound any plate or region side to at most 2044 px before `CE_ATLAS_REGION_EXCEEDS_PAGE`) |
736
740
  | `idle.png`, `idle-indexed.png`, `idle.gif` | `loop`, `build --loop` | APNG and GIF encodings of the rendered idle |
737
741
  | `run.json` | `rig`, `assemble` | spec `rig-run/1` (issue #1165, additive): `spec`, `package` (`name`, `version`), `command` (`"rig"` or `"assemble"`), `started_at` and `finished_at` (UTC ISO-8601 millisecond timestamps ending in `Z`, read in the CLI layer), `config` (`path` relative to `--out`, `sha256` of the config file on disk), `inputs` on `assemble` (issue #1316, additive: one `{role, path, sha256}` entry for each of `--source`, `--full` and `--head` that was given, in that order, with `path` relative to the run's cwd and `sha256` of the file or of the directory's `layers.json`), and `outputs` (`path` relative to `--out`, `sha256` of each written output file on disk, sorted by `path` in code-unit order and excluding `run.json` itself); written only after the command's gate is green |
738
742
  | the difference inventory (`--out`) | `diff-components` | spec `rig-parts-diff-components/1` by default (issue #1005: `stack`, `painting`, `definition`, `error_px`, `uncovered_error_px`, `components` — each `id`, `px`, `box`, `coverage`, `uncovered_px`, `borders` — and `below_floor`, byte-identical to 2.38.1), and spec `rig-parts-diff-components/2` under `--owners` (issue #1291: adds `owners` — each `{part, px}`, the topmost `parts.json` part above `COVERED_ALPHA` per covered pixel, back to front — before `borders` on every component); `--verify` verifies both `/1` and `/2` reports (with `--owners`, `/2` is required), while a `/1`-only reader (`readDiffComponents(text, input, [DIFF_COMPONENTS_SPEC])`) refuses `/2` by name |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/parts",
3
- "version": "2.43.0",
3
+ "version": "2.44.0",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/runstamp.ts CHANGED
@@ -16,6 +16,8 @@ import { SUPPORT_DOMAINS_FILE } from './supportdomains.ts';
16
16
 
17
17
  export const RUN_STAMP_SPEC = 'rig-run/1' as const;
18
18
  export const RUN_STAMP_FILE = 'run.json' as const;
19
+ export const COMPOSE_RUN_SPEC = 'rig-compose-run/1' as const;
20
+ export const COMPOSE_RUN_FILE = 'compose-run.json' as const;
19
21
  export const RUN_STAMP_INPUT_ROLES = ['source', 'full', 'head'] as const;
20
22
 
21
23
  export type RunStampCommand = 'rig' | 'assemble';
@@ -31,6 +33,15 @@ export interface RunStampFileEntry {
31
33
  sha256: string;
32
34
  }
33
35
 
36
+ /** Compose's consumed inputs, captured before its gate; no clock or output inventory. */
37
+ export interface ComposeRun {
38
+ spec: typeof COMPOSE_RUN_SPEC;
39
+ scene: RunStampFileEntry;
40
+ characters: Array<{ id: string; build: string; files: RunStampFileEntry[] }>;
41
+ plate: RunStampFileEntry | null;
42
+ plates: Array<{ name: string; path: string; sha256: string }>;
43
+ }
44
+
34
45
  export interface RunStampInputEntry {
35
46
  role: RunStampInputRole;
36
47
  path: string;
@@ -119,6 +130,11 @@ export function clearRunStamp(outDir: string): void {
119
130
  rmSync(join(outDir, RUN_STAMP_FILE), { force: true });
120
131
  }
121
132
 
133
+ /** Remove a previous compose record before CLI prevalidation or the compose stage begins. */
134
+ export function clearComposeRun(outDir: string): void {
135
+ rmSync(join(outDir, COMPOSE_RUN_FILE), { force: true });
136
+ }
137
+
122
138
  /**
123
139
  * Read package `name` and `version` from `package.json`, refusing with `RUN_STAMP_PACKAGE`
124
140
  * when the file is missing, invalid JSON, or lacks a non-empty string `name` or `version`.