@rig-c/parts 2.43.0 → 2.45.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/docs/STABILITY.md CHANGED
@@ -150,6 +150,150 @@ compare this list with the command's allowlist, and plant an undeclared code.
150
150
  - `USAGE`
151
151
  <!-- /parts-check:codes -->
152
152
 
153
+ ## Programmatic mesh edit acts
154
+
155
+ `@rig-c/parts/src/remesh-api.ts` is a public Bun/TypeScript import path for
156
+ `applyMeshEditAct(input: ApplyMeshEditActInput): RemeshResult` (issue #1159).
157
+ `applyMeshEditAct` is the sole runtime export from this entry. The two
158
+ type-only exports are `ApplyMeshEditActInput` and `RemeshResult`. Other
159
+ `src/` paths and names outside the interfaces documented on this page are
160
+ unpromised.
161
+
162
+ ### ApplyMeshEditActInput
163
+
164
+ | Field | Type | Meaning |
165
+ | --- | --- | --- |
166
+ | `rig` | `string` | Path to the current rig revision directory, with `rig.json`, `motion.json`, `mesh_report.json` and `images/`. |
167
+ | `config` | `string` | Path to the config used to build the input rig. |
168
+ | `parts` | `string` | Path to the assembled directory containing `parts.json` and `parts/` used for the input rig. |
169
+ | `part` | `string` | Target part name. The slot and attachment both use this name in the default skin. |
170
+ | `out` | `string` | Destination for a new revision. When applying a new edit, the directory must not exist and must be outside `rig`. |
171
+ | `edit` | Object with the fields below | One in-memory value from the finalized act's `value.meshEdits[].edit`. |
172
+ | `actId` | `string` | Finalized act's identity. It must contain a non-whitespace character. |
173
+ | `actSourceHash` | `string` | Finalized act's `source.sourceHash`, as 64 lowercase hex digits. |
174
+ | `payloadSha256` | `string` | The selected mesh edit's `sha256`, as 64 lowercase hex digits. It must match the digest of the canonical `edit` payload. |
175
+
176
+ Use `ApplyMeshEditActInput['edit']` to annotate an edit value.
177
+
178
+ | Edit field | Type | Meaning |
179
+ | --- | --- | --- |
180
+ | `slot`, `skin`, `attachment` | `string` each | Non-empty names identifying the edited attachment in the model. |
181
+ | `basis` | `"setup"` | The undeformed setup pose. |
182
+ | `source.vertexCount`, `source.triangleCount`, `source.hullLength` | `number` each | Non-negative safe-integer counts from the source attachment. |
183
+ | `source.hash` | `string` | Lowercase SHA-256 of the UTF-8 `JSON.stringify` of the parsed attachment entry in the input's gated `skeleton.model.json`, with stored key order. |
184
+ | `source.frame` | `{ width: number; height: number }` | Positive finite dimensions of the rig canvas in crop pixels. |
185
+ | `source.positions` | `[number, number][]` | Dense array of unrounded setup positions in vertex order, one per source vertex, in crop pixels (x right, y down). |
186
+ | `ops` | `MeshEditOp[]` | Ordered list of 1 to 300 operations. |
187
+
188
+ Each operation is one of the following shapes. Vertex indices are non-negative
189
+ safe integers and coordinate pairs are finite. `from` is unrounded, while
190
+ `to` and `at` are recorded to 0.01 px.
191
+
192
+ ```ts
193
+ type MeshEditOp =
194
+ | { op: 'move'; v: number; from: [number, number]; to: [number, number] }
195
+ | { op: 'add'; at: [number, number]; onEdge?: [number, number] }
196
+ | { op: 'remove'; v: number }
197
+ | { op: 'edge'; a: number; b: number }
198
+ | { op: 'unedge'; a: number; b: number };
199
+ ```
200
+
201
+ The payload digest is SHA-256 over the UTF-8 bytes of compact JSON. Sort
202
+ object keys at every level by UTF-16 code units and preserve array order.
203
+ Serialize strings with JSON escaping and numbers with ECMAScript number
204
+ formatting. The signed edit domain excludes integer-like keys, negative zero
205
+ and non-finite numbers. [Signed mesh-edit contract](https://github.com/rig-c/review/issues/952#issuecomment-7001413869)
206
+
207
+ ### RemeshResult
208
+
209
+ | Field | Type | Meaning |
210
+ | --- | --- | --- |
211
+ | `provenance` | `RemeshProvenance` | The `rig-parts-remesh/1` record of the revision, as stored in `remesh.json`. |
212
+ | `written` | `string[]` | Paths written by the call, relative to the new revision directory, including `remesh.json`. An exact replay returns `[]`. |
213
+
214
+ The API uses the [remesh revision record](#files-this-package-writes)
215
+ with the following `request` variant.
216
+
217
+ | Request field | Type | Meaning |
218
+ | --- | --- | --- |
219
+ | `part` | `string` | Target part. |
220
+ | `edit` | `ApplyMeshEditActInput['edit']` | Mesh edit value supplied by the caller. |
221
+ | `act_id`, `act_source_hash`, `payload_sha256` | `string` each | Act identity, act source hash and canonical payload digest. |
222
+ | `ops` | `number` | Number of operations replayed. |
223
+ | `applied` | `{ moved: number; added: number; removed: number; constrained: number }` | Counts of moves, additions, removals and edit constraints still present after replay. |
224
+ | `idle_keys` | `"ctl" \| "direct"` | Idle key routing used for the build. |
225
+ | `page_edges` | `"pot" \| "free"` | Page edge mode used by the gate. |
226
+ | `pack_shape` | `"rect" \| "polygon"` | Packing shape used by the gate. |
227
+
228
+ ### Refusals
229
+
230
+ Named refusals throw a `PartsError`. Its read-only `problems` array contains
231
+ `{ code: string; object: string; detail: string }` entries. The entries name
232
+ the rule, affected object and details of the refusal. The error message joins
233
+ the rendered entries with newlines. Each entry renders as
234
+ `<code>: <object> — <detail>`. Consumers branch on `code` and `object` and
235
+ display `detail`, which carries the found and required values.
236
+
237
+ The remesh stage's existing refusal catalog covers
238
+ [`REMESH_OUT_FRESH`](AUTHORING.md#REMESH_OUT_FRESH),
239
+ [`REMESH_INPUT_PRESENT`](AUTHORING.md#REMESH_INPUT_PRESENT),
240
+ [`REMESH_INPUT_WRITTEN`](AUTHORING.md#REMESH_INPUT_WRITTEN),
241
+ [`REMESH_TARGET_MESH`](AUTHORING.md#REMESH_TARGET_MESH),
242
+ [`REMESH_TARGET_CLOSED`](AUTHORING.md#REMESH_TARGET_CLOSED),
243
+ [`REMESH_RIGC_GREEN`](AUTHORING.md#REMESH_RIGC_GREEN),
244
+ [`REMESH_PRESERVED`](AUTHORING.md#REMESH_PRESERVED) and
245
+ [`REMESH_CHECK_HELD`](AUTHORING.md#REMESH_CHECK_HELD).
246
+ Setup frame evaluation uses [`REMESH_BONE_ORDER`](AUTHORING.md#REMESH_BONE_ORDER)
247
+ and [`REMESH_BONES_POSED`](AUTHORING.md#REMESH_BONES_POSED).
248
+
249
+ | Code | Object | Found and required values |
250
+ | --- | --- | --- |
251
+ | [`REMESH_DELTA_ACT`](AUTHORING.md#REMESH_DELTA_ACT) | `actId` or `actSourceHash` | The requirement is a non-empty finalized act ID or a finalized act source hash of 64 lowercase hex digits, respectively. |
252
+ | [`REMESH_DELTA_ACT`](AUTHORING.md#REMESH_DELTA_ACT) | Path to the matching provenance record | A binding conflict reports the recorded and received act source hashes and payload digests. A recorded edit that fails validation or hashes differently names the act, part and required digest. |
253
+ | [`REMESH_DELTA_ACT`](AUTHORING.md#REMESH_DELTA_ACT) | Path to the unbound provenance record | Identifies the recorded act and part and reports that its revision hashes do not bind the current rig files. |
254
+ | [`REMESH_DELTA_ACT_SUPERSEDED`](AUTHORING.md#REMESH_DELTA_ACT_SUPERSEDED) | Path to the provenance record that binds the current revision | Names the act, part and earlier provenance path. Replaying that edit requires the earlier revision as input. |
255
+ | [`REMESH_DELTA_DIGEST`](AUTHORING.md#REMESH_DELTA_DIGEST) | `payloadSha256` | The required format is 64 lowercase hex digits. A digest mismatch reports the supplied and recomputed digests. |
256
+ | [`REMESH_DELTA_JSON`](AUTHORING.md#REMESH_DELTA_JSON) | Edit, attachment identity, `source`, `source.frame`, or `source.positions` and its first malformed position | The edit must have the declared object and field shapes. Field mismatches identify the offending keys or values and the required shape. An invalid edit container or position array reports the required container. |
257
+ | [`REMESH_DELTA_BASIS`](AUTHORING.md#REMESH_DELTA_BASIS) | `edit basis` | The supplied basis and required `"setup"`. |
258
+ | [`REMESH_DELTA_OPS`](AUTHORING.md#REMESH_DELTA_OPS) | `edit ops` | The supplied value or length and the required dense array of 1 to 300 operations. A sparse array reports the density requirement. |
259
+ | [`REMESH_DELTA_OP`](AUTHORING.md#REMESH_DELTA_OP) | `edit ops[i]` | The offending operation and the required shape or replay condition. Replay stops at the first operation that cannot apply. A move names its recorded `from` and live position when the two differ by more than the 0.001 px tolerance. |
260
+ | [`REMESH_DELTA_SOURCE`](AUTHORING.md#REMESH_DELTA_SOURCE) | `edit slot`, `edit attachment`, `edit skin` or one of the `edit source` count fields | The recorded identity or count and the required part, default skin or input attachment count. |
261
+ | [`REMESH_DELTA_SOURCE`](AUTHORING.md#REMESH_DELTA_SOURCE) | `edit source.hash` or `edit source.frame` | For a hash mismatch, the recorded and input model attachment hash prefixes, or a notice that the attachment entry is absent. For a frame mismatch, the recorded dimensions and both required frames from the rig and the parts manifest. |
262
+ | [`REMESH_DELTA_SOURCE`](AUTHORING.md#REMESH_DELTA_SOURCE) | `edit source.positions` or `edit source.positions[i]` | The recorded position count and declared vertex count, or the first mismatching vertex with its recorded and required coordinates. The tolerance is 0.001 px on each coordinate. |
263
+ | [`REMESH_DELTA_TOPOLOGY`](AUTHORING.md#REMESH_DELTA_TOPOLOGY) | Input triangle or replayed attachment | The observed topology and the required winding, outline or Delaunay condition. |
264
+ | [`CHECK_RIGC_PRESENT`](AUTHORING.md#CHECK_RIGC_PRESENT) | `` the rig-c CLI `rigc` `` | No `rigc` was found in the ancestor `node_modules/.bin` directories or on `PATH`. Applying a new edit requires the rig-c CLI. |
265
+
266
+ ### Replay
267
+
268
+ Parts identifies an edit by `(actId, part)`. The default skin and the part's
269
+ slot and attachment names fix the target identity. The act source hash and
270
+ payload digest bind that key.
271
+
272
+ - **Exact replay.** When the current provenance matches the key, binds the
273
+ current rig files by hash, and holds the same source hash and payload digest,
274
+ the API returns its stored provenance and `written: []`. The recorded and
275
+ submitted edits must validate and hash to that digest. The call leaves the
276
+ current revision byte for byte as it was and creates no output directory.
277
+ - **Binding conflict.** A known key with a changed `actSourceHash` or
278
+ `payloadSha256` refuses `REMESH_DELTA_ACT` even if the key was recorded on
279
+ an earlier revision. A record whose stored edit is invalid or fails its
280
+ digest also refuses `REMESH_DELTA_ACT`. If the supplied digest agrees with
281
+ the record but the submitted edit hashes differently, the refusal is
282
+ `REMESH_DELTA_DIGEST`.
283
+ - **Superseded revision.** The same key, act source hash and validated edit
284
+ digest in a hash-bound ancestor refuse `REMESH_DELTA_ACT_SUPERSEDED`. The
285
+ refusal's `object` is the path to the record that binds the current revision.
286
+ - **Unbound record.** A matching root record whose hashes fail to bind the
287
+ current tree refuses `REMESH_DELTA_ACT` when no root record binds it.
288
+ - **New key.** The API validates the canonical payload digest and the source
289
+ attachment, counts, frame and positions against the input. It refuses stale
290
+ source evidence before any edit operation or output write. After a valid
291
+ edit passes the remesh gate, it writes a fresh revision with the act binding
292
+ in `remesh.json`.
293
+
294
+ The CLI's `--delta` flag remains supported as the legacy file-based path.
295
+ [Apply a mesh edit act in Bun](AUTHORING.md#apply-a-mesh-edit-act-in-bun)
296
+
153
297
  ## Programmatic config file references
154
298
 
155
299
  `@rig-c/parts/src/config.ts` exports `configFileReferences(raw: unknown):
@@ -239,9 +383,21 @@ core compile-error line receives `(see rigc guide §5.1)` inside the enclosing
239
383
  rig-parts refusal; no core error code is invented. A command
240
384
  also answers to the alias `spine-parts` as long as the install keeps it
241
385
  ([MIGRATION.md](MIGRATION.md)). `-h`, `help` and `-v` are the short forms of
242
- `--help` and `--version`. The flags' meanings are `rig-parts --help`'s; their
386
+ `--help` and `--version`. Every command (and `comfy` with each of its
387
+ subcommands) also answers `--help` and `-h` by printing its own usage section
388
+ and exiting 0 (issue #1360); on `layers` and `painting`, a file literally named
389
+ `-h` is reached as `./-h`. The flags' meanings are `rig-parts --help`'s; their
243
390
  defaults are the help's too, and none is guessed from the art.
244
391
 
392
+ Issue #1358 extends `CHECK_TIP_OVER_ROOT` remedy prose without changing its
393
+ rule code, thresholds, measurements or verdicts. Existing remedy branches remain.
394
+ For a breathing carrier inside one keyed chain, it warns that rebinding to the
395
+ hang bone can pass TIP while failing `STRESS_OFF_CHAIN`. It may name an already
396
+ bound carrier under the immediate next keyed link, or suggest moving the keyed
397
+ translate to the hang bone or an ancestor. These are options to measure on the
398
+ authored rig, not guaranteed fixes. Every TIP remedy calls for re-checking
399
+ `STRESS_OFF_CHAIN`; no new report fields or built rig bytes are introduced.
400
+
245
401
  The check diagnostic vocabulary adds the following refusal (issue #1308):
246
402
 
247
403
  - `CHECK_CARRIER_NOT_EXCITED` — the measured root-to-carrier chain, including
@@ -271,36 +427,38 @@ and do not certify visibility. See the
271
427
  <!-- stable:commands -->
272
428
  | command | flags |
273
429
  | --- | --- |
274
- | `edited-part` | `--config`, `--part`, `--file`, `--from`, `--editor`; optional `--rig-config` (issue #1328; splice a receipt into explicit full configs, without reassembly) |
275
- | `diff-components` | `--stack`, `--painting`, `--parts`, `--floor`; optional `--threshold`, `--figure`, `--owners`; exactly one of `--out`, `--verify` (issues #1005, #1291; exhaustive native error inventory, `rig-parts-diff-components/1` by default and `rig-parts-diff-components/2` with `--owners`, and byte-bound reader for both) |
276
- | `depth-prepare` | `--parts`, `--config`, `--out` (issue #897; separate numeric-depth recipe) |
277
- | `depth-bind` | `--map`, `--input`, `--part` (issue #1284; exclusive receipt creation from current file bytes) |
278
- | `depth-apply` | `--parts`, `--manifest`, `--config`, `--rig-config`, `--out` (issue #897; original character config is read-only) |
279
- | `layers` | one positional path: a wrapper directory, a `layers.json` or a `.psd`; with it, optional `--export` (a directory to write the wrapper form into, issue #359); or `--template` with `--canvas` and no path; or a positional head run with `--full`, `--source`, `--config` together for `PLAN_HEAD_GARMENT_OVERLAP` (issue #826) |
280
- | `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols` |
281
- | `inputs` | `--source`, `--config`, `--out` |
282
- | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
283
- | `comfy` | `matte`: `--painting`, `--out`, `--node` (`BiRefNetRMBG`), `--model` (`BiRefNet-HR-matting`), `--checkpoint-sha256` (declared, required); optional `--resolution`, `--threshold`, `--host`, `--wait`, `--timeout`, `--poll` (issue #1204) |
284
- | `comfy` | `plate`: `--mode` (`background`, `foreground` or `occluder`), `--painting`, `--mask-from` (`seethrough:<dir>`, `figure-mask:<dir>` or `matte:<dir>`; not with `occluder`), `--out`; with `--mode occluder`, `--occluder` (an RGBA PNG on the painting's grid, required) and optional `--holes` (issue #1230), and the background flags below; with `--mode background` also `--checkpoint-sha256` (required) and optional `--graph` (`lama` or `core`), `--model` (required with `core`), `--seed`, `--grow`, `--steps`, `--cfg`, `--prompt`, `--negative` (the last four with `core` only), `--host`, `--wait`, `--timeout`, `--poll` (issue #1183, additive) |
285
- | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--no-offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll`, `--config` (See-through settings and optional depth block), `--depth-run` (`full` or `head`, required with the block) |
286
- | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`, `--write-config` (must name `--config` itself, issue #356); or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454), `--requirements` (source-bound cut-material evidence only when the file declares `cut_material`, issue #888); or `--emit-fill-masks` (a directory) with `--source`, `--full`, `--config`, optional `--head` (each cut's hidden-band mask on the painting grid, issue #1230) |
287
- | `head-crop-preflight` | `--full`, `--canvas`, `--head-box` (JSON coordinate array); read-only advice before the head run, original alpha > 8 samples (issue #1082) |
288
- | `propose` | `--head-box` with `--full`, `--canvas`; optional `--no-back-hair`, `--write-config` (existing config, issue #356) |
289
- | `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (existing config for an ordinary proposal, issue #356; a new file with `--cloth`, issue #537; not with `--from-config` — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` writes changes), `--only-missing` (only with `--parts` and `--write-config`, not with `--cloth` or `--from-config`, issue #671 — additive: without it nothing `--write-config` writes changes) `--bust-landmarks` (rig-pixel apex_r/apex_l and optional cleavage), or `--no-bust` (non-blank omission reason), one required when drafting a chest-holding torso, both incompatible with `--from-config` |
430
+ | `edited-part` | `--config`, `--part`, `--file`, `--from`, exactly one of `--editor` or `--producer`; optional `--rig-config`, `--help` (`-h`) (issue #1328; splice a receipt into explicit full configs, without reassembly) |
431
+ | `external-receipt` | `--kind` (mask), `--file`, `--painting`, `--producer`, `--out`; or `--verify`; or `--help` (`-h`) |
432
+ | `diff-components` | `--stack`, `--painting`, `--parts`, `--floor`; optional `--threshold`, `--figure`, `--owners`, `--help` (`-h`); exactly one of `--out`, `--verify` (issues #1005, #1291; exhaustive native error inventory, `rig-parts-diff-components/1` by default and `rig-parts-diff-components/2` with `--owners`, and byte-bound reader for both) |
433
+ | `diff-drafts` | `--left`, `--right`, `--out`; optional `--help` (`-h`) (issue #1369; draft-to-draft assemble comparison, `rig-parts-draft-diff/1`) |
434
+ | `depth-prepare` | `--parts`, `--config`, `--out`; optional `--help` (`-h`) (issue #897; separate numeric-depth recipe) |
435
+ | `depth-bind` | `--map`, `--input`, `--part`; optional `--help` (`-h`) (issue #1284; exclusive receipt creation from current file bytes) |
436
+ | `depth-apply` | `--parts`, `--manifest`, `--config`, `--rig-config`, `--out`; optional `--help` (`-h`) (issue #897; original character config is read-only) |
437
+ | `layers` | one positional path: a wrapper directory, a `layers.json` or a `.psd` (a file literally named `-h` is reached as `./-h`); with it, optional `--export` (a directory to write the wrapper form into, issue #359); or `--template` with `--canvas` and no path; or a positional head run with `--full`, `--source`, `--config` together for `PLAN_HEAD_GARMENT_OVERLAP` (issue #826); or `--help` (`-h`) |
438
+ | `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols`, `--help` (`-h`) |
439
+ | `inputs` | `--source`, `--config`, `--out`; optional `--help` (`-h`) |
440
+ | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll`, `--help` (`-h`) |
441
+ | `comfy` | `matte`: `--painting`, `--out`, `--node` (`BiRefNetRMBG`), `--model` (`BiRefNet-HR-matting`), `--checkpoint-sha256` (declared, required); optional `--resolution`, `--threshold`, `--host`, `--wait`, `--timeout`, `--poll`, `--help` (`-h`) (issue #1204) |
442
+ | `comfy` | `plate`: `--mode` (`background`, `foreground` or `occluder`), `--painting`, `--mask-from` (`seethrough:<dir>`, `figure-mask:<dir>` or `matte:<dir>`; not with `occluder`), `--out`; with `--mode occluder`, `--occluder` (an RGBA PNG on the painting's grid, required) and optional `--holes` (issue #1230), and the background flags below; with `--mode background` also `--checkpoint-sha256` (required) and optional `--graph` (`lama` or `core`), `--model` (required with `core`), `--seed`, `--grow`, `--steps`, `--cfg`, `--prompt`, `--negative` (the last four with `core` only), `--host`, `--wait`, `--timeout`, `--poll`, `--help` (`-h`) (issue #1183, additive) |
443
+ | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--no-offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll`, `--config` (See-through settings and optional depth block), `--depth-run` (`full` or `head`, required with the block), `--help` (`-h`) |
444
+ | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`, `--write-config` (must name `--config` itself, issue #356); or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454), `--requirements` (source-bound cut-material evidence only when the file declares `cut_material`, issue #888); or `--emit-fill-masks` (a directory) with `--source`, `--full`, `--config`, optional `--head` (each cut's hidden-band mask on the painting grid, issue #1230); or `--help` (`-h`) |
445
+ | `head-crop-preflight` | `--full`, `--canvas`, `--head-box` (JSON coordinate array); optional `--help` (`-h`); read-only advice before the head run, original alpha > 8 samples (issue #1082) |
446
+ | `propose` | `--head-box` with `--full`, `--canvas`; optional `--no-back-hair`, `--write-config` (existing config, issue #356), `--help` (`-h`) |
447
+ | `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (existing config for an ordinary proposal, issue #356; a new file with `--cloth`, issue #537; not with `--from-config` — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` writes changes), `--only-missing` (only with `--parts` and `--write-config`, not with `--cloth` or `--from-config`, issue #671 — additive: without it nothing `--write-config` writes changes) `--bust-landmarks` (rig-pixel apex_r/apex_l and optional cleavage), or `--no-bust` (non-blank omission reason), one required when drafting a chest-holding torso, both incompatible with `--from-config`, `--help` (`-h`) |
290
448
  | `propose` | `--parts`, `--source`, `--out`, `--full`, `--head`, `--write-config` together: the [neck draft](AUTHORING.md#a-neck-that-moves-on-its-own) for an existing config with `turn.body` and one neck plan row; reassembles under `<out>/rig`, preserves the sampled turn and drafts a rigid neck unit (issue #826) |
291
- | `compare` | `--left`, `--right`; optional `--map` |
292
- | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--page-size` |
293
- | `check-parts` | `--parts`, `--out`; optional `--json` |
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
- | `loop` | `--frames`, `--out`; optional `--palette` |
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` |
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
- | `mesh-stats` | `--config`, `--parts` (issue #566, additive: prints, writes nothing) |
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) |
301
- | `retune` | `--rig`, `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--page-size`, `--record-input-check` and `--input-check` (as for `remesh`, issue #617, additive) |
302
- | `painting` | one positional path, the painting; `--keypoints`; optional `--person`, `--form` (`standee` or `illustration`, issue #931) |
303
- | `guide` | one positional argument: a rule name, `§<n>`, `§<n>.<m>` or `§<n>.<m>.<k>` |
449
+ | `compare` | `--left`, `--right`; optional `--map`, `--help` (`-h`) |
450
+ | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--page-size`, `--help` (`-h`) |
451
+ | `check-parts` | `--parts`, `--out`; optional `--json`, `--help` (`-h`) |
452
+ | `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), `--help` (`-h`) |
453
+ | `loop` | `--frames`, `--out`; optional `--palette`, `--help` (`-h`) |
454
+ | `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), `--help` (`-h`) |
455
+ | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept`, `--page-size`, `--help` (`-h`) |
456
+ | `mesh-draft` | `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--page-size`, `--more-triangles`, `--help` (`-h`) |
457
+ | `mesh-stats` | `--config`, `--parts`; optional `--help` (`-h`) (issue #566, additive: prints, writes nothing) |
458
+ | `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), `--help` (`-h`) |
459
+ | `retune` | `--rig`, `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--page-size`, `--record-input-check` and `--input-check` (as for `remesh`, issue #617, additive), `--help` (`-h`) |
460
+ | `painting` | one positional path, the painting (a file literally named `-h` is reached as `./-h`); `--keypoints`; optional `--person`, `--form` (`standee` or `illustration`, issue #931), `--help` (`-h`) |
461
+ | `guide` | one positional argument: a rule name, `§<n>`, `§<n>.<m>` or `§<n>.<m>.<k>`; or `--help` (`-h`) |
304
462
  | (none) | `--version`, `--help` |
305
463
  <!-- /stable:commands -->
306
464
 
@@ -394,7 +552,7 @@ part name, `[i]` an entry of a list):
394
552
  - **assemble.editor_receipts** — required: `receipts`; optional: `required` (issue #946, additive), `trace_parts` (issue #947, additive)
395
553
  - **assemble.editor_receipts.receipts[i]** — required: `file`, `sha256`, `from_sha256`, `editor` (issue #946)
396
554
  - **assemble.edited_parts** — required: `dir`, `receipts` (issue #1278; directory relative to the config)
397
- - **assemble.edited_parts.receipts[i]** — required: `part`, `file`, `sha256`, `from_sha256`, `editor` (issue #1278; file relative to the edited-parts directory)
555
+ - **assemble.edited_parts.receipts[i]** — required: `part`, `file`, `sha256`, `from_sha256`; exactly one of `editor` or `producer` (issue #1278; file relative to the edited-parts directory)
398
556
  - **assemble.patches[i]** — required: `name`, `box`, `alpha`, `draw`
399
557
  - **assemble.patches[i].draw**, when an object — required: `before`
400
558
  - **assemble.cuts[i]** — required: `from`, `into`, `polygon`, `draw`, `overlap`; optional: `under`, `under_fill` (issue #1230: `under` is a path string or an object)
@@ -410,7 +568,7 @@ part name, `[i]` an entry of a list):
410
568
  - **bones[i]**, a chain — required: `chain`, `parent`, `points`, `tip`; optional: `link_inherit`
411
569
  - **stops[i]** — required: `chain`, `against`, `at`, `inward`, `outward`; optional: `links`, `lower` (issue #404)
412
570
  - **stops[i].lower** — required: `inward`, `outward`
413
- - **meshes.&lt;part&gt;** — exactly one of `grid`, `contour`, `auto`, `influence`, `explicit`; required in every mode: `segments`, and `r` in generated modes other than `influence`; `explicit` refuses generation fields and uses direct bone names in `segments`, the first the slot bone; optional in every mode: `exponent`, `rule`, `gather` (issue #680, false only: preserve an exclusive non-segment rider's authored draw position without changing its binding; absent, output bytes unchanged); optional with `contour` or `auto`: `ribs`; optional with `grid` or `contour`: `influences` (issue #284; beside `auto` it is refused, CONFIG_INFLUENCES_MODE); optional with `grid`: `stray` (issue #303; beside `contour` or `auto` it is refused, CONFIG_STRAY_MODE)
571
+ - **meshes.&lt;part&gt;** — exactly one of `grid`, `contour`, `auto`, `influence`, `explicit`; required in every mode: `segments`, and `r` in generated modes other than `influence`; `explicit` refuses generation fields and uses direct bone names in `segments`, the first the slot bone; optional in every mode: `exponent`, `rule`, `gather` (issue #680, false only: preserve an exclusive non-segment rider's authored draw position without changing its binding; absent, output bytes unchanged); optional with `contour` or `auto`: `ribs`; optional with `grid` or `contour`: `influences` (issue #284; beside `auto` it is refused, CONFIG_INFLUENCES_MODE); optional with a distance lattice, distance contour or influence mesh: `fixed_above`; optional with `grid`: `stray` (issue #303; beside `contour` or `auto` it is refused, CONFIG_STRAY_MODE)
414
572
  - **meshes.&lt;part&gt;.explicit** — required: `image_sha256`, `region_sha256`, and either `uvs`, `triangles`, `hull`, `weights` (single-slot, issue #658) or `islands` (at least two island entries, issue #734); direct payload numbers are transferred without normalization; weights require `bone`, `x`, `y`, `weight`. Image SHA-256 is over decoded unpadded RGBA bytes; region SHA-256 is over JSON.stringify([rig width, rig height, part x, part y, part w, part h]). Both must match before output, and when `islands` is declared its entry count must match the part's non-dust 4-connected art island count. All weighted and island slot bones must occur in segments; declared stopped links may use their emitted `<link>_d` names. Other unknown names remain refused. Alternate artwork for this part is refused; use a generated mesh for it.
415
573
  - **meshes.&lt;part&gt;.explicit.islands[i]** — required: `slot` (`<part>` at index 0, `<part>__island<i+1>` at index i >= 1), `uvs`, `triangles`, `hull`, `weights`; optional: `bone` (defaults to `segments[0]`), `before` (index i >= 1 only: the base part slot in `rig.json` to splice `<part>__island<i+1>` immediately before; absent, immediately after the part's previous island slot)
416
574
  - **meshes.&lt;part&gt;.influence** — required: `cell`, `radius`, `across`, `max`, `shape` (issue #378); optional: `hold_tip` (issue #615, the value true only); beside it `r`, `exponent`, `rule`, `influences`, `stray` and `ribs` are refused by name
@@ -422,6 +580,7 @@ part name, `[i]` an entry of a list):
422
580
  - **meshes.&lt;part&gt;.auto** — required: `source`, `sourceBounds`, `targets`, `influences`, `budget`, `minArtSamples`, `motion`; optional: `protect`, `regions`, the three Stage B opt-ins `boundaryRuns`, `retriangulate`, `removalOrder`, and `stimulus`
423
581
  - **meshes.&lt;part&gt;.auto.source** — required: `tolerance`, `margin`, `spacing`; optional: `stray`
424
582
  - **meshes.&lt;part&gt;.auto.sourceBounds** and **meshes.&lt;part&gt;.auto.targets.artFit** — required: `minCoverage`, `maxOvershoot`, `maxUndercut` (each of the last two a number or null, the bound declared absent)
583
+ - **meshes.&lt;part&gt;.fixed_above** — optional on a distance lattice, distance contour or influence mesh; required when present: `row`, `bones` (non-empty list of fixed segment bone names)
425
584
  - **meshes.&lt;part&gt;.auto.targets** — required: `artFit`, `maxBoundaryDeviation`; optional: `minAngle`
426
585
  - **meshes.&lt;part&gt;.auto.influences** — required: `maxInfluences`, `minWeight`
427
586
  - **meshes.&lt;part&gt;.auto.budget** — required: `maxCandidates`
@@ -432,7 +591,7 @@ part name, `[i]` an entry of a list):
432
591
  - **meshes.&lt;part&gt;.auto.regions[i]** — required: `name`, `shape`, `maxEdgeLength`, `transition`, `grade`, `minArtSamples`, and `cx`, `cy`, `r` for a circle or `points` for a polygon; optional: `bone`, `band` (both or neither; with neither the region is density only)
433
592
  - **meshes.&lt;part&gt;.auto.boundaryRuns** — required: `maxVertices`
434
593
  - **meshes.&lt;part&gt;.auto.stimulus**, or each entry of it when a list — required: `chain`, `degrees`
435
- - **cloth.&lt;tag&gt;**, the tag bottomwear, back hair or front hair (issue #364; read by propose --cloth only) — required: `chains` (optional on `back hair`, issue #390), `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only), `part` (a string on bottomwear, or a list of parts in root-to-tip order on any tag, issue #437), `parts` (a list of parts in root-to-tip order on any tag, issue #437)
594
+ - **cloth.&lt;tag&gt;**, the tag bottomwear, back hair, front hair, handwear-r or handwear-l (issue #364; read by propose --cloth only) — required: `chains` (optional on `back hair`, issue #390), `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `extent` (one bottomwear or sleeve carrier), `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only), `part` (a string on bottomwear, required as one name on handwear-r and handwear-l, or a list in root-to-tip order on bottomwear and hair recipes), `parts` (a list in root-to-tip order on bottomwear and hair recipes)
436
595
  - **cloth.&lt;tag&gt;.split** — required: `at`, `into`; optional: `hold_tip`
437
596
  - **cloth.&lt;tag&gt;.strength** — required: `trunk`, `branch`, `edge`
438
597
  - **cloth.&lt;tag&gt;.swing** — required: `scales`
@@ -443,11 +602,13 @@ part name, `[i]` an entry of a list):
443
602
  - **motion.blink** — required: `t`, `eyes`, `squash`; optional: `brows`, `brow_drop`, `still`, `more`
444
603
  - **motion.blink.still.&lt;part&gt;** — required: `row`, `bone`
445
604
  - **motion.animations_from**, the file it names — required: `spec`, `animations`
446
- - **turn** — required: `pivot`, `depths` (or `roles` / `body`, issues #763, #787); optional: `deform`, `band`, `radius`, `surface`, `head`, `roles`, `counter`, `grid`, `unitDepths`, `body`
605
+ - **turn** — required: `pivot`, `depths` (or `roles` / `body`, issues #763, #787); optional: `deform`, `band`, `radius`, `surface`, `head`, `roles`, `counter`, `grid`, `unitDepths`, `boundaryDepths`, `body`
606
+ - **turn.boundaryDepths.&lt;part&gt;**, when an object — required: `neighbour`, `band` (issue #1342)
607
+ - **turn.body.boundaryDepths.&lt;part&gt;**, when an object — required: `neighbour`, `band` (issue #1342)
447
608
  - **turn.depths.&lt;part&gt;** — a See-through depth
448
609
  - **turn.roles.&lt;part&gt;** — `"surface"`, `"unit"` or `"rear"` (issue #763)
449
610
  - **turn.unitDepths.&lt;part&gt;** — a calibrated world depth in rig pixels (issue #763)
450
- - **turn.body**, when an object — required: `roles`, `pivot` (when `turn.pivot` is absent); optional: `bone`, `slider`, `counter`, `grid`, `unitDepths` (issue #787)
611
+ - **turn.body**, when an object — required: `roles`, `pivot` (when `turn.pivot` is absent); optional: `bone`, `slider`, `counter`, `grid`, `unitDepths`, `boundaryDepths` (issue #787)
451
612
  - **turn.body.roles.&lt;part&gt;** — `"surface"`, `"unit"` or `"rear"` (issue #787)
452
613
  - **turn.body.unitDepths.&lt;part&gt;** — a calibrated world depth in rig pixels (issue #787)
453
614
  - **turn.deform.&lt;key&gt;** — a per-degree fraction or coupling share (FACE_DEFORM_FRACTIONS, issue #436)
@@ -497,8 +658,83 @@ The values a field takes (`retriangulate` is "delaunay", `removalOrder`
497
658
  "deformation-load", `selection.policy` "multi-interval"; the units and ranges of
498
659
  every number) are AUTHORING §3's tables, and the loader refuses any other by name.
499
660
 
661
+ Optional turn boundary-depth declarations (issue #1342) resolve existing part
662
+ names and project band samples onto the original neighbour sheet. Bands may be
663
+ the target itself or contained boundary-reaching parts, including existing
664
+ painting patches. Shared anchors, calibration, prepared maps and setup geometry
665
+ are unchanged; omission preserves existing output bytes. Projection ties use
666
+ the arithmetic mean and the inner band edge is a hard switch, without blending.
667
+ See [boundary authoring](AUTHORING.md#declared-boundary-depths-1342).
668
+
500
669
  ## Files this package writes
501
670
 
671
+ ### Diagnostic path segments
672
+
673
+ Issue #1362 changes name-derived diagnostic paths written by `check`, including
674
+ the check inside `build` and `compose`. The one mapping is
675
+ `diagnosticSegment` in `src/outputpaths.ts`: read original UTF-16 code units
676
+ left to right. An ASCII unit in `[A-Za-z0-9_@+.-]` stays literal; every
677
+ other unit becomes `~` followed by exactly four lowercase hexadecimal digits.
678
+ Unicode units (including each surrogate), punctuation outside that alphabet
679
+ and `~` itself are escaped. Uppercase ASCII letters stay literal. No normalization or case conversion
680
+ is applied. A left-to-right decoder copies each literal and consumes exactly
681
+ four hex digits after each `~`, recovering the original code units; escape-like
682
+ input names therefore cannot collide with an escaped name.
683
+
684
+ Two positional/whole-name hazards override literal units. Escape the final dot
685
+ if present, which also covers `.` and `..`. After that unit encoding, if the
686
+ emitted basename before its first dot matches `con`, `prn`, `aux`, `nul`,
687
+ `com1` through `com9`, or `lpt1` through `lpt9` without regard to ASCII case,
688
+ escape its first unit. Thus `idle`
689
+ stays `idle`, `a:turn` becomes `a~003aturn`, `..` becomes `.~002e`, `tail.`
690
+ becomes `tail~002e`, `con.txt` becomes `~0063on.txt`, and `con.` needs only
691
+ `con~002e`. Trailing spaces are already escaped as unsafe units. Distinct
692
+ names have distinct case-sensitive mapped segments; all emitted units are ASCII,
693
+ so Unicode normalization does not change them. Windows punctuation, C0 controls,
694
+ device basenames and trailing dots/spaces cannot occur in the mapped segment.
695
+
696
+ ASCII-case aliases are refused rather than renamed: `Idle` and `idle` each map
697
+ literally, but cannot be siblings. `diagnosticSiblings` checks the entire sibling
698
+ scope before its writes, using the mapped folders' ASCII lowercase spellings.
699
+ A collision raises `DIAGNOSTIC_PATH_SEGMENT` naming both original inputs,
700
+ both folder spellings and their shared case-folded folder. Scopes are extremes
701
+ animations, retained render sets, selected alternate-set folders, and each of
702
+ `requirements/as-declared`, `requirements/released` and `requirements/full`.
703
+ Check preflights all known scopes before creating or clearing its output;
704
+ requirement measurement also preflights before cleanup, and retained copies
705
+ validate every set before creating a destination. The retained reference-world
706
+ publisher validates all worlds before staging them. Safe uppercase names such as
707
+ `VANE_HALF` and `RIDER_HALF` keep their existing paths.
708
+
709
+ An empty original name, or a resulting segment longer than 255 ASCII characters
710
+ including a fixed filename/rate suffix, is refused as `DIAGNOSTIC_PATH_SEGMENT`,
711
+ naming the original input and the required bound. No truncation or hashing is
712
+ applied. The suffix is appended after unit mapping and included in that length
713
+ check; it does not change the name's encoding.
714
+
715
+ `extremes/<segment>/` uses the original animation name. Retained render sets
716
+ use its mapped animation name plus `@<fps>fps` only outside the protocol
717
+ 12 fps, with `frames.json`'s `sets[].dir` updated to the actual directory.
718
+ A setup-only set maps its renderer directory instead. The original animation
719
+ fields, including `extremes.json`, and the public `<id>:<name>` animation
720
+ names stay unchanged. Readers follow `sets[].dir` rather than reconstructing
721
+ a folder from `animation`. Safe unchanged indexes retain their original bytes.
722
+ Fixed root sidecar names and bytes are copied verbatim; only the frame index
723
+ may change its set directory references.
724
+
725
+ The same mapping applies to alternate-set folders in `setup_still/`,
726
+ `setup_still_auto/` and `seam/`, the complete ranked seam-picture filename stem,
727
+ and animation/requirement folders in `requirements/{as-declared,released,full}`.
728
+ The retained seam reference worlds under `seam_motion/{default,still}` use
729
+ the mapped render indexes. Loop output filenames are fixed; fold, loop,
730
+ stress, sweep and wind-band render scratch is removed rather than published.
731
+ Source part/image references retain their separate asset contracts.
732
+
733
+ The mapping lives in this package's retention step. Core's `frameSetDir`
734
+ still writes original names in staging before that step; this layout fix
735
+ does not certify native Windows rendering or repair staging collisions on a
736
+ filesystem that already aliases two original names.
737
+
502
738
  `depth-bind` writes `<map>.binding.json` beside the numeric map, spec
503
739
  `rig-parts-depth-map-binding/1`, with `spec`, `part`, `mapSha256`, `inputSha256`
504
740
  in that order. Hashes are computed from current map and input PNG bytes.
@@ -720,7 +956,7 @@ execution in historical evidence is inferred from a current export.
720
956
  | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), `excluded_px` after them only on a subset set's limb part whose cap the set exclusion took a pixel of (issue #603, additive: each pixel taken out of the count it was in, so the cap's counts are the written PNG's), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px` — on a subset set's limb part counted after the set exclusion, issue #603 — `seam_override_px`, and `fringe_pushed_back` when not empty); per-part `taken_layers` (with optional `transport`, issue #973, and optional `split` — `occluder`, `image`, `sha256`, `covered_px`, `visible_px` — on a split take, additive, issue #1242) and `provenance` (`unchanged_layer_px`, `hand_px`, `automatic_px`, `edits`, `automatic`, additive, issue #823); optional top-level `motion_seams`, `occluder_plates` (one record per `assemble.occluders` entry declaring `plate` — `receipt`, `receipt_sha256`, `occluder_sha256`, `painting_sha256`, `output_sha256`, `mask_sha256`, additive, issue #1237), `occluder_grow` (one record per `assemble.occluders` entry with `grow > 0` — `occluder`, `image`, `grow`, `covered_px_before`, `covered_px_after`, additive, issue #1251), `occluder_guard` (one record per `assemble.occluders` entry with `guard > 0` — `occluder`, `image`, `guard`, `guarded_px_before`, `guarded_px_after`, additive, issue #1259), `alternates` and `cut_ownership` (one row per cut, independent of RGBA equality, issue #823, with optional `under_plate` — `receipt`, `receipt_sha256`, `occluder_sha256`, `painting_sha256`, `output_sha256`, `mask_sha256` — on a `{plate}` under, additive, issue #1230); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242), and the same bytes beside `parts.json` when the two directories differ (issue #1177); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
721
957
  | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
722
958
  | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones` (the sorted names the attachment's weights bind in the written `rig.json`, in every mode — since 1.49.1 (issue #536) a rig with `turn` or `stops` names the twins and `<link>_d` bones there, where the row named the segment bones they replace: a fix of a wrong name, not a format change; a rig with neither writes the bytes it wrote), `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); or `mode` "explicit" with `image_sha256` and `region_sha256` (the verified guards; counts and coverage are measured from the supplied mesh, no legacy generator report is adopted); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
723
- | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode` (with `page_size` under `--page-size` only, issue #1273, additive), `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #941 adds optional `required` only under the requirements file's `seam_over_motion.required: true` — `status` (`PASS` or `FAIL`), `mode` `gap-open`, `bar_px` 0, `pairs` (each `pair`, `class` — `body-root`, `internal-joint` or `explicit` — `frames`, `background_frames`, `max_px`) and `failed` — and with it the key is written even when no pair is declared; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes. Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
959
+ | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | [Check verdict spec](#check-report-rig-parts-check1) followed by the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode` (with `page_size` under `--page-size` only, issue #1273, additive), `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #941 adds optional `required` only under the requirements file's `seam_over_motion.required: true` — `status` (`PASS` or `FAIL`), `mode` `gap-open`, `bar_px` 0, `pairs` (each `pair`, `class` — `body-root`, `internal-joint` or `explicit` — `frames`, `background_frames`, `max_px`) and `failed` — and with it the key is written even when no pair is declared; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes. Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
724
960
  | `part_support_domains.json` | `assemble`, `build` | optional `rig-parts-support-domains/1` independent cut masks and unavailable reasons, with per-domain config-entry provenance and parts/PNG/payload digests; additive beside parts.json, whose bytes and PNGs are unchanged. Legacy output may omit it. `PART_SUPPORT_REPORT` reads pairs in the assembly placement frame and Unowned in actual setup, never as an acceptance gate. |
725
961
  | `layers.json`, `<index>_<name>.png` | `layers --export` | the wrapper form `layers` reads (issue #359): `width`, `height`, then `layers` — each `name`, `filename`, `left`, `top`, `right`, `bottom`, `depth_median` (the input's own; `null` for a PSD, the manifest's order then being the draw order) — drawn layers in draw order, then the hidden-art layers; a PNG's name is its index and its layer's name, and the manifest, not the file name, says which layer it is |
726
962
  | the template `.psd` | `layers --template` | one empty layer per name `templateLayerNames` (`src/layers.ts`) holds, bottom first; the same canvas writes the same bytes |
@@ -732,10 +968,17 @@ execution in historical evidence is inferred from a current export.
732
968
  | `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
969
  | `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
970
  | `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`) |
971
+ | 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. |
972
+ | 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; a plate name already refused by `SCENE_PLATE_NAME_FREE` or `SCENE_PLATE_NAME_UNIQUE` does not also draw a cascaded `SCENE_ORDER_COMPLETE` (issue #1350). 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 (placement coverage of the stage is the scene author's, not checked by the tool). Transparent layers have no size floor. rigc A19 remains enabled. Named images use `scene-plate.<index>.png` (atlas region `scene-plate.<index>`, by declaration index) with collision checks. The `[compose]` header line names composed `plates[]` in declaration order (`<N> named plate(s): <name>, ...`) when `plates[]` is non-empty and prints `no plate` only when neither `plate` nor `plates[]` is present (issue #1350). The additive report `plates` array records declaration, native size and PNG hash; absent declaration retains legacy output bytes and fixed first-plate behavior. |
973
+ | 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. |
974
+ | scene loop refusal detail | `compose` | Issue #1358 enriches `SCENE_ANIMATION_LOOP_CLOSES` with the first differing bone or slot, channel, start/end values and numeric tolerance 0 (exact equality). The existing exact JSON endpoint comparison is unchanged: bones, slots, draw order, drawn geometry, clipping polygons and clipped geometry remain covered. Selection follows that family order, then producer row and field order; geometry-only differences name the slot and geometry channel. Physics is still excluded only from observation. The refusal code, acceptance, emitted rig/motion and built scene bytes are unchanged. |
975
+ | `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. |
976
+ | 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
977
  | `idle.png`, `idle-indexed.png`, `idle.gif` | `loop`, `build --loop` | APNG and GIF encodings of the rendered idle |
737
978
  | `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
979
  | 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 |
980
+ | the draft comparison (`--out`) | `diff-drafts` | spec `rig-parts-draft-diff/1` (issue #1369), a stable contract as of 2.45.0: fixed keys in order `spec`, `left` and `right` (each `parts_sha256`, `part_count`, `composite_sha256`), `canvas` (`width`, `height`), `order` (`"same"` or `"changed"`), `parts` (one entry per part name in the union of both sides, sorted by `name` in code-unit order: `name`, `status`, then `left` and `right` on the sides that hold the part, each `sha256`, `box`, `index`, then `pixels_equal` and `pixels` on `changed` only), `composite` and `summary`; no clock and no file paths. The command records no threshold and judges nothing; it exits 0 whenever the report is written. [Draft-to-draft assemble comparison](AUTHORING.md#draft-to-draft-assemble-comparison-issue-1369) defines each field. |
981
+ | the external mask receipt (`--out`) | `external-receipt` | spec `rig-parts-external-receipt/1` (issue #1368), a stable contract as of 2.45.0: keys in write order `spec`, `kind` (`"mask"`), `file` and `painting` (each `path` relative to the receipt directory, then `sha256` of the file bytes), `grid` (`width`, `height` of the decoded painting) and `producer` (`tool`, optional `model`, then exactly one of `checkpoint_sha256`, `graph_sha256`, `script_sha256`); UTF-8 JSON, two-space indentation, trailing newline. `--verify` reads it back and writes nothing. The producer is the caller's declaration, not a proof of which tool made the mask. [External mask receipt](AUTHORING.md#external-mask-receipt) defines each field. |
739
982
 
740
983
  Issue #705 pins setup-seam acceptance to one source-relative scale1 union U of the authored stage and all actual drawn base/checked-set still vertices. U is snapped relative to the source origin, including odd-width half phase.
741
984
  The existing seam fields and pair pictures use that grid; source/blink and
@@ -834,6 +1077,76 @@ Files authors write for this package, each with a spec id the reader holds:
834
1077
  name on purpose: they name a file format, not the tool, and a file written before
835
1078
  the rename still reads. They do not change at 1.0.
836
1079
 
1080
+ ### Check report (`rig-parts-check/1`)
1081
+
1082
+ Spec `rig-parts-check/1` (issues #1372, #1378) is a stable contract as of
1083
+ 2.45.0, the first version that writes it.
1084
+
1085
+ A completed report starts with `spec: "rig-parts-check/1"`, `bar_outcomes`,
1086
+ and `build: { "model_sha256": "<64 lowercase hex>" }` — the SHA-256 of the
1087
+ exact bytes of the primary `check/build/skeleton.model.json` the check read
1088
+ (auxiliary `_loop`, `_still` and `_behind_seams_turn` builds are not hashed).
1089
+ The model file carries paths relative to the rig's images, so the same rig
1090
+ checked into another folder records another hash; the key identifies a build
1091
+ output, not rig content. The check only records; a consumer holding the report
1092
+ and the build can detect a report that does not belong to it by hashing the
1093
+ model file. Existing keys retain their relative order after `build`, with
1094
+ `PASS` last.
1095
+ `check --json` emits the same report as the file. The bar map has every id
1096
+ in the order below. Its values are `{"status":"PASS"}`, `{"status":"FAIL"}`,
1097
+ or `{"status":"SKIP","reason":"<stable reason>"}`. The `reason` field appears
1098
+ only on SKIP. Read the existing blocks for detailed measurements and diagnostics.
1099
+
1100
+ The existing boolean `PASS` is the overall outcome. For a completed
1101
+ `rig-parts check`, true corresponds to exit 0 and false to exit 1. It is
1102
+ false exactly when a bar is FAIL or a declared requirement is FAIL or
1103
+ NOT MEASURABLE. Each entry in `requirements.lines` identifies the requirement
1104
+ by its object key, the unique authored requirement name, and carries its
1105
+ verdict in the entry's `status` field. Input, execution and publication
1106
+ refusals can exit without a completed report.
1107
+
1108
+ Reports keep their existing statuses and have no bar-map entries. A WARN
1109
+ is never a bar outcome, so a consumer that refuses on FAIL does not
1110
+ refuse on a WARN, matching the exit code. The outer `SEAM_OVER_MOTION.status`
1111
+ remains a diagnostic and the bar uses the precedence below.
1112
+
1113
+ | Bar id | Measurement | SKIP reasons in precedence order |
1114
+ | --- | --- | --- |
1115
+ | `gate` | Packed rig-play gate | Never |
1116
+ | `loop` | First vs final idle-frame pixel difference under the existing physics policy | `no-idle` |
1117
+ | `seam` | Setup against the composited parts on the canonical grid. Counts the base alone by default, the base and the named alternate with `--set`, or the base and every declared alternate with `--all-sets`. Fails if the base or any counted alternate fails its existing seam rule. | `no-parts` |
1118
+ | `BREATH_VISIBLE` | Idle breath signal on eligible torso or planted-foot regions | `no-idle`, `no-parts`, `no-eligible-region`, `no-reading` (eligible region outside frame) |
1119
+ | `BLINK_NO_HOLE` | Closed-eye coverage vs open eye and idle | `no-idle`, `no-parts`, `no-eye-parts`, `no-blink-track`, `no-reading` (incompatible grids or eye outside frame) |
1120
+ | `CHAIN_LAG` | Phase lag for comparable idle parent and child rotation tracks | `no-idle`, `no-comparable-tracks` |
1121
+ | `TIP_OVER_ROOT` | Hem or sleeve tip excursion relative to root | `no-idle`, `no-parts`, `no-swing-parts`, `no-reading` (all eligible parts unread) |
1122
+ | `STILL_REGIONS_DARK` | Face and planted foot movement in idle | `no-idle`, `no-parts`, `no-eligible-region`, `no-reading` (missing geometry or neither region readable) |
1123
+ | `TEXTURE_STRETCH` | Idle change to skinned triangle edges, including rejected zero-length rest edges even when no stretch ratio is available | `no-idle`, `no-reading` (missing geometry), `no-meshes`, `no-visible-meshes` |
1124
+ | `ANIMATIONS_DO_NOT_FOLD` | Undeclared folds across authored animations and unmatched fold exceptions | `no-animation` |
1125
+ | `FEET_STAY_LEVEL` | Relative rotation of hanging footwear while drawn | `no-animation`, `no-parts`, `no-hanging-footwear`, `no-posed-footwear` |
1126
+ | `STRESS_OFF_CHAIN` | Skinned handwear stress in authored chain test poses | `no-idle`, `no-parts`, `no-handwear`, `no-readable-binding` |
1127
+ | `LIMB_ONE_BONE` | Each declared limb piece's slot and weights resolve to its single segment bone | `no-parts`, `no-limb-segments` |
1128
+ | `SEAM_OVER_RANGE` | Joint seams at poses across the declared range | `no-parts`, `no-joint-range` |
1129
+ | `ART_JOINT_DISTANCE` | Setup joint distance from fixed art-derived declarations | `undeclared`, `no-limit` |
1130
+ | `CUT_JOINT_MATERIAL` | Declared joint cut-material support and crossing evidence | `undeclared` |
1131
+ | `SETUP_MATCHES_PAINTING` | Native-grid source vs rendered setup under authored regional mismatch limits | `undeclared`, `no-limit` (at least one region lacks a limit and none fail) |
1132
+ | `BOUNDARY_COLOUR_STEP` | Authored allowance for excess colour step between parts in idle | `undeclared` |
1133
+ | `BEHIND_PART_SEAMS` | Authored thresholds for standing and motion-opened rear seam cells, including requested turn poses | `undeclared`, `no-complete-threshold-reading` (including no eligible pairs or an incomplete non-failing reading) |
1134
+ | `SEAM_OVER_MOTION` | Body-root gap plus under-owned ghost floor and required zero-background seam readings | `no-root-gate`, `no-animation`, `no-complete-root-reading` (root evidence unmeasured) |
1135
+
1136
+ | SEAM_OVER_MOTION precedence | Declared outcome |
1137
+ | --- | --- |
1138
+ | Root FAIL or required FAIL | FAIL |
1139
+ | Otherwise required PASS | PASS |
1140
+ | No required block, root PASS | PASS |
1141
+ | No required block, root SKIP | SKIP with `no-animation` or `no-complete-root-reading` |
1142
+ | Neither root nor required gate present | SKIP with `no-root-gate` |
1143
+
1144
+ Version-aware consumers read the declared outcomes on the known spec.
1145
+ Compose reads `bar_outcomes` on a report that declares this spec (issue
1146
+ #1373); on a report without it, and in the remesh/retune input-check
1147
+ readers, the historical interpretation is kept, including for reports
1148
+ written before this version.
1149
+
837
1150
  ### Run stamp (`run.json`, spec `rig-run/1`)
838
1151
 
839
1152
  The CLI commands `rig` and `assemble` (when writing `--out`) write `<out>/run.json`
@@ -1332,8 +1645,13 @@ moves.
1332
1645
 
1333
1646
  ### Edited rig-space parts
1334
1647
 
1648
+ The [external mask receipt](AUTHORING.md#external-mask-receipt) is
1649
+ `rig-parts-external-receipt/1`. Its producer declaration is also accepted
1650
+ by `edited-part --producer`. Edited-part receipts with an `editor` string
1651
+ remain readable and keep their output bytes for identical inputs.
1652
+
1335
1653
  `edited-part` (issue #1328) records `sha256` and `from_sha256` from the
1336
- supplied PNG bytes and the non-empty `editor` declaration. It replaces the
1654
+ supplied PNG bytes, plus the supplied `producer` or nonblank `editor`. It replaces the
1337
1655
  named part's receipt in place or appends one, preserving every other row and
1338
1656
  unrelated config byte. Both explicit full configs are validated before either
1339
1657
  destination changes; each must already declare `assemble.edited_parts`. Paths are recorded
@@ -1344,7 +1662,7 @@ Writer validation refusals leave both configs unchanged. The shared staged
1344
1662
  writer validates full configs and their relative sidecars; all configs stage
1345
1663
  before the shared batch commits, restoring earlier originals on a later commit
1346
1664
  failure. The command prints shared config-change lines on stderr and one
1347
- stdout line naming the part, both hashes and the declared editor. Repeated
1665
+ stdout line naming the part, both hashes and the author declaration. Repeated
1348
1666
  identical receipts preserve bytes and report `unchanged`.
1349
1667
 
1350
1668
  The optional `assemble.edited_parts` block (issue #1278, additive) replaces