@rig-c/parts 2.44.0 → 2.46.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/AUTHORING.md CHANGED
@@ -201,7 +201,7 @@ read by no CPU stage).
201
201
  | `motion.animations_from` | rig; check (named; read for folds) | optional, never proposed (issue #183): a path, relative to the config file's directory, to a file in rig-c's motion-spec shape, `{"spec": "rigc-motion/1", "animations": {"<name>": {"duration": …, "tracks": [...]}, …}}` — an expression, a gesture, anything beside the idle. On every `rig` and `build` each of its animations is written into `rig/motion.json` after `idle`, as read: nothing added, re-keyed or judged here (except `derive` keys on `turn`/`tilt`, issue #436, and `{"t": …, "set": "<name>" \| null}` keys on slot `"attachment"` tracks, issue #473, which expand to `"v": "<set>_<slot>"` or `"v": null` when the set hides the slot, or `"v": "<slot>"` for `null`, refused with `CONFIG_SET_COVERS_SLOT` when the set is undeclared or does not cover the track's slot), and each is rigc's to accept or refuse at the rig stage's gate, in rigc's words. It may name what `motion.json` already holds — the bones `bones` declares, the easings `shut` and `open`, the groups `eyes` and `brows` when the blink writes them — and nothing else from the file reaches it. The loader refuses, every problem at once: no such file or one that cannot be read (`CONFIG_FILE_PRESENT`), text that is not JSON (`CONFIG_IS_JSON`), a file that is not an object, a `spec` other than `"rigc-motion/1"`, an `animations` that is not a table of objects (`CONFIG_FIELD_TYPE`), any other key — rig-c's `easings`, `groups`, `setup`, `physics`, `mix`, `archetype` and `cut` included, which would be read and not written (`CONFIG_KEY_KNOWN`), an animation named `idle` (`CONFIG_ANIMATION_NAME_FREE`), and a key written twice in one object of the file, which JSON would fold into its last value without a word (`CONFIG_KEY_UNIQUE`). `check` names the others on one line (`beside the idle: …`) and reads each for folds, with the idle — `ANIMATIONS_DO_NOT_FOLD` (§7, issues #320, #333); every other bar reads the idle. Absent, `motion.json` holds the idle alone, byte for byte as before, and `check` reads that idle for folds |
202
202
  | `constraints` | rig (handed to rig-c as `rig.json`'s `constraints`); `compare` and the coverage lines (roles) | **authored**, optional; `propose` writes none, but with `--cloth` (issue #364), where it writes the recipe's physics and swing transforms (*Recipe: cloth and hair that answer the world*, below). A list of constraints in **rig-c's own rig-spec shape** (`RigConstraint`: `ik`, `transform`, `path`, `physics`, `slider` — rig-c's `src/rig.ts` documents every field), in the order rigc applies them. The loader checks only what this package owns: each entry is an object with a `type` rigc names (`CONFIG_CONSTRAINT_TYPE_KNOWN`) and a non-empty `name`, unique within its kind as rigc finds constraints (`CONFIG_CONSTRAINT_NAME_UNIQUE`; an ik and a transform may share one); every bone it names — `bones`, an ik's `target`, a transform's `source`, a physics or slider constraint's `bone` — is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`); the bone a constraint follows does not sit under a bone it drives (`CONFIG_CONSTRAINT_TARGET_DETACHED`). Every other field (`mix`, `softness`, `properties`, a path's `slot`, a slider's `animation`) and every value is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`) — an ik's `bones` as a shape too: from rig-c 2.15.0 rigc refuses an ik over more than two bones, or over a pair whose second bone is not the first's child (issue #103; this loader refused both itself until then). A note and an `x-` record may ride on an entry; the rig stage leaves them out of what it hands rigc. Under the default `--idle-keys ctl` a two-bone ik whose child link the idle keys is split by that link's control, and rigc refuses the pair: run `rig --idle-keys direct` or `build --idle-keys direct` (the rig stage adds that sentence, naming the flag on the command that ran, to rigc's line; `build` forwards it to its rig stage, issue #95). Each bone a constraint follows is declared to rigc as `invariants.detached` from every bone it drives, which rigc's gate rule `A25` checks |
203
203
  | `stops` | rig (handed to rig-c as `rig.json`'s `stops`, and moves slots, mesh weights and child bones on stopped links onto `<link>_d`); `propose --from-config` (`LINT stop on <chain> …`) | **authored**, optional (issues #404, #447): `[{chain, links?, against, at, inward, outward, lower?: {inward, outward}}]` — rig-c's leg stops (`RigStop`, rig-c 2.56.0, `@rig-c/core/stop`). `chain` is a chain `bones` declares (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `links`, optional, is a non-empty list of links of that chain (`CONFIG_NAME_RESOLVES`, `CONFIG_FIELD_TYPE`), or absent for every link of `chain` in chain order; `against` is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `at` is `[x, y]` in `against`'s local space, as rig-c's stop takes it (`CONFIG_FIELD_TYPE`): since each chain link (`leg_r0`, `leg_r1`) is turned to point along its segment (`+x` from origin to next link or tip, `+y` 90° counter-clockwise in Spine world), `at: [d, n]` sits `d` px from `against`'s origin toward its end and `n` px perpendicular to it; `inward`, `outward` and `lower.inward`, `lower.outward` are finite numbers (`CONFIG_FIELD_TYPE`). Every other stop rule — non-negative bounds, each stopped link written by a constraint, `against` not under the stopped chain, the aim not degenerate, `\|rest\| + outward <= 180°` (`RIG_STOP_BOUNDS`) — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). **Rising-limb / prone geometry (issue #447):** rig-c's `expandStops` aims `<chain>_rest` from `links[0]`'s setup origin at `<chain>_touch` (`at` in `against`'s local frame) and clamps `<link>_d` inside `[rest − inward, rest + outward]`; Spine wraps rotation at `±180°`, so `\|rest\| + outward <= 180°` is required (`RIG_STOP_BOUNDS`). Whenever `<chain>_touch` lies **above** `links[0]`'s root in rig pixels (`ty < y0`, i.e. higher Spine `y` — e.g. stopping a hanging cloth chain against a rising shin `leg_<s1>` in a prone or kneeling pose where the knee sits below `links[0]` and the ankle above it, so positive `at[0]` walks upward along the shin past `links[0]`'s root), `rest` lands in the upper half-plane (`\|rest\| > 90°`) and `\|rest\| + outward` exceeds `180°`. Stop against the descending thigh (`leg_<s0>`), set `links` to start at a link whose root sits above `<chain>_touch`, or omit the stop when the rising shin sits outside the hanging chain's sweep; `propose --from-config` prints `LINT stop on <chain> …` with the exact coordinates and angles when `<chain>_touch` lies above `links[0]`'s root or `\|rest\| + outward > 180°`. For every stopped link `<link>`, the rig stage moves any slot on `<link>`, any mesh weight on `<link>`, and any bone whose parent is `<link>` (a branched cloth tree's branches hanging from `<trunk_last>`, before `--idle-keys ctl` adds `<bone>_ctl` and before `turn` adds `turn_<part>_<bone>`) onto `<link>_d`, the drawn link bone rig-c's `expandStops` creates at `<link>`'s setup frame to carry the clamped rotation. Absent, `rig.json` carries no `stops` and no byte of any output moves |
204
- | `turn` | rig (adds the turn control or 2.5D head-turn producer) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected, or **authored** for 2.5D depth-sampled head turns (issue #763): `{pivot?, depths?, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}, roles?, counter?, grid?, unitDepths?, body?}`. When `roles` is declared (`{<part>: "surface" \| "unit" \| "rear"}`, issue #763; `CONFIG_TURN_ROLE_UNKNOWN`, `CONFIG_TURN_SURFACE_REQUIRED`, `RIG_TURN_SURFACE_MESH_BINDINGS`, `CONFIG_TURN_UNIT_MESH_BONES`), the rig stage runs the 2.5D depth-sampled head-turn producer: it edge-extends each turn-bound part's depth sheet across its transparent border and semi-transparent fringe from the nearest fully opaque (`alpha === 255`) texel before `PAD = 4` clamping (`padTurnDepthSheet`, `DEPTH_SILHOUETTE_SIZE_MISMATCH`), keeps authored `"surface"` meshes and their skinning (#795), sampling each vertex at its weighted setup position on its own extended sheet and emitting one inverse-setup-bone offset per influence (`D = -(pivot + z - zRef) * sin(angle)`, on x for yaw and y for pitch, with no narrowing or 2D spin); shared frames moved by another turn role are refused (`RIG_TURN_SURFACE_MESH_BINDINGS`), as are alternate drawings without their own depth sampling frame (`RIG_TURN_SURFACE_MESH_ATTACHMENT`). It promotes `"surface"` regions to `generator: {kind: "grid", cols, rows, depth}` (`grid`: `[cols, rows]` or `{<part>: [cols, rows]}`, default `[13, 16]`, bounded at `<= 2,400` triangles per slot and `<= 4,000` total, `RIG_TURN_GRID_BUDGET`, `RIG_TURN_SURFACE_DEPTH_REQUIRED`, `RIG_TURN_SHARED_DEPTH_SCALE`), emits `faceshift` and `rear_shift` under `head` (`CONFIG_TURN_HEAD_BONE`, `RIG_TURN_HEAD_BONE`), `<part>_surface` and `<part>_unit` under `faceshift`, and `yaw_dial` and `pitch_dial` under `root` (`CONFIG_TURN_BONE_FREE`, `RIG_TURN_NAME_FREE`), re-parents `"unit"` region bones and `"rear"` bones and mesh weights to `faceshift` and `rear_shift` (while `"unit"` mesh parts receive their own `<part>_unit` carrier under `faceshift`, rebind direct `"head"` weights to `<part>_unit`, reparent bound chain roots to `<part>_unit` while keeping chain skinning weights intact, and key `<part>_unit` in `turn_units`, #790), samples each `"unit"` bone's depth from the `"surface"` depth sheet at its rest position (or reads `unitDepths.<part>`, `RIG_TURN_UNIT_DEPTH_REQUIRED`), enforces ear occlusion (`ear_r`/`ear_l` drawn before the `face` surface in `assemble.plan`, `CONFIG_TURN_EAR_DRAW_ORDER`, and behind the cheek surface, `RIG_TURN_EAR_DEPTH_BEHIND_CHEEK`), and writes `turn` and `tilt` `derive` tracks (`pivot` default `55` rig px, `counter` default `0.1` in `[0, 1]`, `CONFIG_TURN_COUNTER_RANGE`). `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median, unless it rides another part's bone. With no `face` part, or more than one, the riders keep their own and a note says so. A rider by bone (issue #535) — a part every *ownable* bone of which (a chain link, or a bone no other bone hangs from; `head`, `chest` and any bone with a child are shared and never count on their own) is *hosted* by another carried part, the host of a bone being the carried part that binds it (its region's bone; a mesh's `segments`, `contour` and `auto` regions' bones) with the most `opaque_px`, the earlier in parts.json on a tie, and which hosts no bone itself — is drafted at its host's depth, 0.001 nearer when drawn after the host and 0.001 further when before, and a note names the host, the bones and its own median: a pin, clip or ornament on the back hair's links travels with the back hair, not with its own layer's depth. `propose` reads the proposal's own `bones`, `meshes` and `regions`; the face riders are read by their tag first and never by their bones. A part bound to two hosts' bones rides neither and a note says so. In the rig stage, an authored depth on a rider by bone whose fraction differs from its host's by more than 0.1 of the dial (`TURN_RIDER_APART`, a share of `pivot − nearest`) is refused (`CONFIG_TURN_RIDER_DEPTH`); the host is read off `parts.json`'s `opaque_px`, so the config loader cannot see it. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it requires `config.turn` (`CONFIG_TURN_REQUIRED`, issue #478; `propose --full`/`--head` drafts it), promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening on the trailing side, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). On yaw (`issue #479`), `evalYawFaceSurface` evaluates a **cylinder projection** (`cylinderYawDx`: `Δx(x, θ, R) = R · (sin(clamp(arcsin(clamp(x / R, −1, 1)) − θ, −π/2, π/2)) − clamp(x / R, −1, 1))`) of radius `R` (`turnSurfaceRadius`: `turn.surface.radius ?? turn.radius ?? turn.head.radius`, positive rig px checked by `CONFIG_FIELD_TYPE`, defaulting to half the face plate's opaque width `W / 2`) tapered by a cubic Hermite outline weight (`wOutline = 1` for `\|ux\| <= 0.7`, reaching `0` at `\|ux\| = 1.0`) so features slide across a fixed outline (`iris` shift within `±2%` of `cylinderYawDx`), the trailing cheek strip widens (`>= 1.54×` at `±15°`), and the leading jaw edge holds fixed (`0 px` shift) unless explicit horizontal `turn.deform` overrides (`turn_mid_x`, `turn_lead_compress_x`, `turn_trail_shift_x`) request the flat yaw table. On yaw (`issue #478`), `applyFaceSurfaceDeform` also derives a **head-only pivot** (`headTurnPivot`: `turn.head.pivot` when authored, otherwise the `opaque_px`-weighted mean of `depths[part]` across the head parts `DEFAULT_HEAD_TURN_PARTS` — `face`, `hair_front`, `hair_back`, `ear_r`, `ear_l`, `hairpin` — from `parts.json`, falling back to `turn.pivot`) so a forward torso or arm in `turn.depths` does not pull the head's rotation axis in front of `face`: `hair_back` (`depth_median > headPivot`, negative `headTurnFraction`) and `hairpin` behind `headPivot` translate opposite to the face's turn (`dx = s · turn_face_center_x · W · (headPivot − depth) / (headPivot − nearestHeadDepth)`), emerging on the trailing side to compensate for the leading-cheek foreshortening and keeping the combined head silhouette width near-constant across `±15°` without any same-sign `turn_hair_back_cheek_x` term. Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); `pivot` and `head.pivot` must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
204
+ | `turn` | assemble ([relative part motion](#keeping-assembled-parts-current)); rig (adds the turn control or 2.5D head-turn producer) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected, or **authored** for 2.5D depth-sampled head turns (issue #763): `{pivot?, depths?, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}, roles?, counter?, grid?, unitDepths?, body?}`. When `roles` is declared (`{<part>: "surface" \| "unit" \| "rear"}`, issue #763; `CONFIG_TURN_ROLE_UNKNOWN`, `CONFIG_TURN_SURFACE_REQUIRED`, `RIG_TURN_SURFACE_MESH_BINDINGS`, `CONFIG_TURN_UNIT_MESH_BONES`), the rig stage runs the 2.5D depth-sampled head-turn producer: it edge-extends each turn-bound part's depth sheet across its transparent border and semi-transparent fringe from the nearest fully opaque (`alpha === 255`) texel before `PAD = 4` clamping (`padTurnDepthSheet`, `DEPTH_SILHOUETTE_SIZE_MISMATCH`), keeps authored `"surface"` meshes and their skinning (#795), sampling each vertex at its weighted setup position on its own extended sheet and emitting one inverse-setup-bone offset per influence (`D = -(pivot + z - zRef) * sin(angle)`, on x for yaw and y for pitch, with no narrowing or 2D spin); shared frames moved by another turn role are refused (`RIG_TURN_SURFACE_MESH_BINDINGS`), as are alternate drawings without their own depth sampling frame (`RIG_TURN_SURFACE_MESH_ATTACHMENT`). It promotes `"surface"` regions to `generator: {kind: "grid", cols, rows, depth}` (`grid`: `[cols, rows]` or `{<part>: [cols, rows]}`, default `[13, 16]`, bounded at `<= 2,400` triangles per slot and `<= 4,000` total, `RIG_TURN_GRID_BUDGET`, `RIG_TURN_SURFACE_DEPTH_REQUIRED`, `RIG_TURN_SHARED_DEPTH_SCALE`), emits `faceshift` and `rear_shift` under `head` (`CONFIG_TURN_HEAD_BONE`, `RIG_TURN_HEAD_BONE`), `<part>_surface` and `<part>_unit` under `faceshift`, and `yaw_dial` and `pitch_dial` under `root` (`CONFIG_TURN_BONE_FREE`, `RIG_TURN_NAME_FREE`), re-parents `"unit"` region bones and `"rear"` bones and mesh weights to `faceshift` and `rear_shift` (while `"unit"` mesh parts receive their own `<part>_unit` carrier under `faceshift`, rebind direct `"head"` weights to `<part>_unit`, reparent bound chain roots to `<part>_unit` while keeping chain skinning weights intact, and key `<part>_unit` in `turn_units`, #790), samples each `"unit"` bone's depth from the `"surface"` depth sheet at its rest position (or reads `unitDepths.<part>`, `RIG_TURN_UNIT_DEPTH_REQUIRED`), enforces ear occlusion (`ear_r`/`ear_l` drawn before the `face` surface in `assemble.plan`, `CONFIG_TURN_EAR_DRAW_ORDER`, and behind the cheek surface, `RIG_TURN_EAR_DEPTH_BEHIND_CHEEK`), and writes `turn` and `tilt` `derive` tracks (`pivot` default `55` rig px, `counter` default `0.1` in `[0, 1]`, `CONFIG_TURN_COUNTER_RANGE`). `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median, unless it rides another part's bone. With no `face` part, or more than one, the riders keep their own and a note says so. A rider by bone (issue #535) — a part every *ownable* bone of which (a chain link, or a bone no other bone hangs from; `head`, `chest` and any bone with a child are shared and never count on their own) is *hosted* by another carried part, the host of a bone being the carried part that binds it (its region's bone; a mesh's `segments`, `contour` and `auto` regions' bones) with the most `opaque_px`, the earlier in parts.json on a tie, and which hosts no bone itself — is drafted at its host's depth, 0.001 nearer when drawn after the host and 0.001 further when before, and a note names the host, the bones and its own median: a pin, clip or ornament on the back hair's links travels with the back hair, not with its own layer's depth. `propose` reads the proposal's own `bones`, `meshes` and `regions`; the face riders are read by their tag first and never by their bones. A part bound to two hosts' bones rides neither and a note says so. In the rig stage, an authored depth on a rider by bone whose fraction differs from its host's by more than 0.1 of the dial (`TURN_RIDER_APART`, a share of `pivot − nearest`) is refused (`CONFIG_TURN_RIDER_DEPTH`); the host is read off `parts.json`'s `opaque_px`, so the config loader cannot see it. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it requires `config.turn` (`CONFIG_TURN_REQUIRED`, issue #478; `propose --full`/`--head` drafts it), promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening on the trailing side, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). On yaw (`issue #479`), `evalYawFaceSurface` evaluates a **cylinder projection** (`cylinderYawDx`: `Δx(x, θ, R) = R · (sin(clamp(arcsin(clamp(x / R, −1, 1)) − θ, −π/2, π/2)) − clamp(x / R, −1, 1))`) of radius `R` (`turnSurfaceRadius`: `turn.surface.radius ?? turn.radius ?? turn.head.radius`, positive rig px checked by `CONFIG_FIELD_TYPE`, defaulting to half the face plate's opaque width `W / 2`) tapered by a cubic Hermite outline weight (`wOutline = 1` for `\|ux\| <= 0.7`, reaching `0` at `\|ux\| = 1.0`) so features slide across a fixed outline (`iris` shift within `±2%` of `cylinderYawDx`), the trailing cheek strip widens (`>= 1.54×` at `±15°`), and the leading jaw edge holds fixed (`0 px` shift) unless explicit horizontal `turn.deform` overrides (`turn_mid_x`, `turn_lead_compress_x`, `turn_trail_shift_x`) request the flat yaw table. On yaw (`issue #478`), `applyFaceSurfaceDeform` also derives a **head-only pivot** (`headTurnPivot`: `turn.head.pivot` when authored, otherwise the `opaque_px`-weighted mean of `depths[part]` across the head parts `DEFAULT_HEAD_TURN_PARTS` — `face`, `hair_front`, `hair_back`, `ear_r`, `ear_l`, `hairpin` — from `parts.json`, falling back to `turn.pivot`) so a forward torso or arm in `turn.depths` does not pull the head's rotation axis in front of `face`: `hair_back` (`depth_median > headPivot`, negative `headTurnFraction`) and `hairpin` behind `headPivot` translate opposite to the face's turn (`dx = s · turn_face_center_x · W · (headPivot − depth) / (headPivot − nearestHeadDepth)`), emerging on the trailing side to compensate for the leading-cheek foreshortening and keeping the combined head silhouette width near-constant across `±15°` without any same-sign `turn_hair_back_cheek_x` term. Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); `pivot` and `head.pivot` must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
205
205
  | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite (and the same bytes beside `parts.json` when standalone `assemble` writes it to another directory, issue #1177), and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). When `assemble` writes `figure_rig.png`, it also prints `figure mask (figure_rig.png):` and one `figure rim full:<tag>` row per full-run layer with a nonzero count, naming the union `alpha >= 250` core, the outer `alpha 9..127` soft rim in the 4-connected exterior of that core and its pixels more than 40 (`ERROR_LIMIT`) off the painting in the rig, and the mask pixels outside every emitted part at `alpha > 8`: when a soft rim over a contrasting ground or an outside-all-parts island is present, declare `setup_painting.figure_mask` for an independent figure domain, or retouch against the painting only inside the `alpha >= 250` core (issue #1297). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
206
206
  | `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `meshes.<part>` and `regions.<part>`, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — and every other byte as read; `--from <previous config>` (issue #571) takes an entry equal to the previous recipe's draft as the recipe's (*The config written*, under the recipe below) |
207
207
  | `proposed_rig_scale` | assemble, rig, build, `propose --from-config`/`--compare` | **proposed** by `propose` (issue #354): `parts.json`'s `scale_rig_per_source`, the `assemble.rig_scale` the rig sections (`bones`, `meshes`, `limbs`, `motion`) were drafted at. Held equal to `assemble.rig_scale` when present (`CONFIG_PROPOSED_RIG_SCALE`; 0, negative or not a number: `CONFIG_FIELD_TYPE`). Absent on a hand-authored config, where no byte of any output moves |
@@ -1115,6 +1115,41 @@ receipt is demanded, and a run with no author-made or hidden-art layer, no
1115
1115
  `under` and no `cap` demands none either. Absent the block, no file is read and
1116
1116
  every output is byte-identical to a build without it.
1117
1117
 
1118
+ ### External mask receipt
1119
+
1120
+ Record an externally produced mask with
1121
+ `rig-parts external-receipt --kind mask --file <mask.png> --painting <painting.png> --producer <json> --out <receipt.json>`.
1122
+ Both inputs must decode as PNG and their measured widths and heights must
1123
+ match. Pixel coordinates start at the upper left and no resampling is applied.
1124
+ Each mask pixel must be opaque black (outside) or opaque white (inside), using
1125
+ the same pixel check as `comfy plate`. These checks measure pixel dimensions
1126
+ and values. Content alignment is the producer's responsibility.
1127
+
1128
+ Command paths resolve from the working directory. Use an unused output path
1129
+ in an existing writable directory. The command publishes the receipt only
1130
+ after validation. It reads the image files without altering them. The receipt
1131
+ is UTF-8 JSON with two-space indentation and a trailing newline.
1132
+
1133
+ | Key in write order | Type and source |
1134
+ | --- | --- |
1135
+ | `spec` | Literal string `rig-parts-external-receipt/1`. |
1136
+ | `kind` | Literal string `mask`. |
1137
+ | `file` | Object with `path` then `sha256`. The path is relative to the receipt directory, uses forward slashes and may include `../`. The lowercase 64-hex SHA-256 is measured from the mask PNG bytes. |
1138
+ | `painting` | Object with the same ordered keys and types as `file`, measured from the painting path and PNG bytes. |
1139
+ | `grid` | Object with `width` then `height`, positive integers measured by decoding the painting PNG. |
1140
+ | `producer` | Object with required nonblank string `tool`, optional nonblank string `model`, then exactly one lowercase 64-hex SHA-256 string in `checkpoint_sha256`, `graph_sha256` or `script_sha256`. These values come from the caller's JSON argument. |
1141
+
1142
+ The producer declaration does not prove which tool generated the mask or
1143
+ verify the digest of the declared producer artifact. No polygon, coordinates
1144
+ or typed geometry are inputs.
1145
+
1146
+ Run `rig-parts external-receipt --verify <receipt.json>` by itself to validate
1147
+ the receipt version and shape, resolve its paths relative to its directory,
1148
+ recompute both hashes, and recheck the pixel dimensions and mask values.
1149
+ Verify writes nothing. `setup_painting.figure_mask` continues to take the
1150
+ mask's own path and hash. See the [refusal ledger](#EXTERNAL_RECEIPT_ARGUMENT).
1151
+
1152
+
1118
1153
  ### Edited rig-space parts (`assemble.edited_parts`, issue #1278)
1119
1154
 
1120
1155
  Use this block for a PNG edited at the exact crop and scale written by
@@ -1136,24 +1171,25 @@ alone does not apply a replacement.
1136
1171
  ```
1137
1172
 
1138
1173
  The block belongs in `assemble`. Both fields are required; `receipts` may be
1139
- empty. Every receipt takes all five fields. `part` must name an existing part
1174
+ empty. Each receipt requires the four common fields and one author field. `part` must name an existing part
1140
1175
  in the base plan, once only. `dir` resolves relative to the config's directory;
1141
1176
  `file` resolves relative to that directory and must be a relative path.
1142
1177
  Hashes are lowercase SHA-256 of encoded file bytes, including PNG metadata;
1143
1178
  `from_sha256` is checked against the PNG the normal assemble would write for
1144
- this config, rather than merely accepted as a declaration. `editor` remains
1145
- the author's non-empty declaration; the tool cannot verify which editor was
1146
- used. The decoded width and height must equal the assembled part's box.
1179
+ this config. Supply either the structured `producer` described under
1180
+ [External mask receipt](#external-mask-receipt) or a legacy nonblank `editor`
1181
+ string. Both forms are caller declarations. The decoded width and height must equal the assembled part's box.
1147
1182
  A changed crop, scale, name or order needs a plan or cut change instead.
1148
1183
 
1149
- Record a receipt with the shipped writer (issue #1328), after declaring
1184
+ Record a receipt with the shipped writer (issue #1328) after declaring
1150
1185
  `assemble.edited_parts` with its directory and an empty `receipts` array in
1151
- each full character config:
1186
+ each named config. `--config` accepts the assembly config, including the full
1187
+ config after `propose --write-config`. Use the [parts assembled from that config](#keeping-assembled-parts-current).
1152
1188
 
1153
1189
  ```sh
1154
- rig-parts edited-part --config draft/config.json --part sleeve_r --file retouched/sleeve_r.png --from assembled/parts/sleeve_r.png --editor "image editor"
1190
+ rig-parts edited-part --config draft/config.json --parts assembled/parts.json --part sleeve_r --file retouched/sleeve_r.png --from assembled/parts/sleeve_r.png --producer '{"tool":"image-editor","script_sha256":"<lowercase 64-hex digest>"}'
1155
1191
  # Update a second full config only when explicitly named:
1156
- rig-parts edited-part --config draft/config.json --part sleeve_r --file retouched/sleeve_r.png --from assembled/parts/sleeve_r.png --editor "image editor" --rig-config rig/config.json
1192
+ rig-parts edited-part --config draft/config.json --part sleeve_r --file retouched/sleeve_r.png --from assembled/parts/sleeve_r.png --producer '{"tool":"image-editor","script_sha256":"<lowercase 64-hex digest>"}' --rig-config rig/config.json
1157
1193
  ```
1158
1194
 
1159
1195
  CLI paths resolve from the working directory; the stored `file` resolves from
@@ -1161,21 +1197,32 @@ each config's own `edited_parts.dir`. The writer hashes the encoded PNG bytes,
1161
1197
  checks that both files decode and have equal dimensions, and validates every
1162
1198
  candidate config before writing either destination. It replaces the existing row for that
1163
1199
  part or appends at the array's length. New rows use key order `part`, `file`,
1164
- `sha256`, `from_sha256`, `editor`; other rows and unrelated config bytes retain
1200
+ `sha256`, `from_sha256`, then `producer` or `editor`. Supply exactly one of
1201
+ `--producer <json>` and `--editor <text>`. Omitting both is a usage error
1202
+ (exit 2). Other rows and unrelated config bytes retain
1165
1203
  their original spelling and whitespace. No matching config is discovered.
1166
1204
 
1167
- The writer never reassembles or certifies the baseline. A wrong same-size
1168
- `--from` is recorded; the next build refuses `ASSEMBLE_EDITED_PART_BASELINE`,
1169
- naming the current assembled hash and the recorded hash. Supply the exact PNG
1170
- from a normal build of this config. A successful writer prints one stdout line
1171
- with the part, both hashes and the declared editor; it does not prove which
1172
- editor was used. The shared writer prints `config <path>: added/replaced
1205
+ With `--parts <parts.json>`, the writer compares the recorded assembly config
1206
+ digest with `--config` before writing. A mismatch is `ASSEMBLY_CONFIG_STALE`.
1207
+ Re-run assemble from the current config and use its manifest and baseline PNG.
1208
+ Legacy manifests without a digest are accepted. For standalone PNGs, omit
1209
+ `--parts`. The command then prints that no assembly config check ran.
1210
+
1211
+ Supply the exact `--from` PNG from a normal assemble of this config. The
1212
+ writer can record a wrong same-size baseline. The next assemble or build
1213
+ refuses it with `ASSEMBLE_EDITED_PART_BASELINE`, naming the current assembled
1214
+ hash and the recorded hash. The writer prints a receipt line on stdout with
1215
+ the part, both hashes and the producer or editor declaration. In
1216
+ `parts.json`, `provenance.edited_part.receipt` carries the same five ordered
1217
+ fields. For a legacy row the last field remains `editor` and both the
1218
+ `parts.json` and edited PNG bytes are unchanged for the same inputs. The shared writer prints `config <path>: added/replaced
1173
1219
  assemble.edited_parts.receipts[index]` or `config <path>: unchanged` on stderr.
1174
1220
  Validation refusals leave all named configs byte-identical.
1175
1221
 
1176
1222
  Receipt updates use the same staged config writer as other config commands.
1177
- The full loader validates each same-directory staged file, including relative
1178
- motion sidecars. All configs stage before any commits. The shared batch helper
1223
+ The assemble loader validates the staged `--config`. The full loader validates
1224
+ the staged `--rig-config`, when supplied, including its relative motion sidecars.
1225
+ All configs stage before any commits. The shared batch helper
1179
1226
  restores earlier original configs if a later commit fails; a restoration
1180
1227
  failure names the retained original backup. A backup-cleanup failure can be
1181
1228
  reported after both complete configs are published; inspect its named path.
@@ -1704,13 +1751,13 @@ for the generated band. Its `part` must be unique among all produced names.
1704
1751
 
1705
1752
  The full axial width is twice `halfWidthAbout(limbRun(...))`: the source's
1706
1753
  alpha-above-8 run across the joint line, measured from the joint to the nearer
1707
- run edge on each side. This chooses a scale from the pixels, not a material
1708
- property. `"hybrid": {"part": "joint_band", "width": 12}` explicitly overrides
1709
- it with a finite positive full width in rig pixels. No art crossing, a
1710
- nonpositive derived width, a band reaching either bone span's end, or bands
1711
- overlapping on source art are named refusals (`ASSEMBLE_LIMB_JOINT_ON_ART`,
1712
- `ASSEMBLE_HYBRID_WIDTH`, `ASSEMBLE_HYBRID_OVERLAP`). Move the joint onto the
1713
- art or supply a width that fits; the tool does not clamp it.
1754
+ run edge on each side. `"hybrid": {"part": "joint_band", "width": 12}`
1755
+ explicitly selects a finite positive full width in rig pixels. Assembly
1756
+ refuses a missing art crossing, a nonpositive effective width, a band
1757
+ reaching either bone span's end, or bands overlapping on source art
1758
+ (`ASSEMBLE_LIMB_JOINT_ON_ART`, `ASSEMBLE_HYBRID_WIDTH`,
1759
+ `ASSEMBLE_HYBRID_OVERLAP`). Move the joint onto the art or supply a width that
1760
+ fits the bone spans.
1714
1761
 
1715
1762
  The band copies the source pixels within half that width on either side of
1716
1763
  the joint line. A one-pixel sampling overlap at each boundary remains bound
@@ -1719,11 +1766,18 @@ upper and lower bones, linearly along the axis, clamped at the band boundaries.
1719
1766
  No hidden-art cap or generated colour fills the band. `parts.json` records
1720
1767
  `limb.hybrid` on the lower rigid piece, including the generated part name, and
1721
1768
  `limb.band` on the mesh. Both carry the source-measured joint centre, unit axis,
1722
- full width, existing range-disc radius and upper carrier. The band repeats the
1723
- lower carrier through `limb.bone`; only the rigid lower piece carries `range`.
1724
- The strict reader requires the pair to agree. Re-run assemble after changing
1725
- the declaration (`RIG_HYBRID_SOURCE`); non-region neighbours are
1726
- `RIG_HYBRID_RIGID`.
1769
+ effective full `width`, existing range-disc radius and upper carrier. An optional
1770
+ `measured_width` records the finite full width measured across the joint from
1771
+ the source art. A valid explicit `width` can produce a band even when the
1772
+ measured width is zero or negative. Both records retain that measurement.
1773
+ The band repeats the lower carrier through `limb.bone`. The rigid lower piece
1774
+ alone carries `range`. The strict reader requires the pair to agree. With
1775
+ `measured_width` recorded, adding or removing an explicit width preserves the
1776
+ assembly reading when the effective width stays the same in the base and
1777
+ every alternate that carries the band. Re-run assemble after changing the band
1778
+ name or effective width.
1779
+ Rig reports `RIG_HYBRID_SOURCE` for a mismatch with the assembled joint and
1780
+ `RIG_HYBRID_RIGID` for neighbours that are not regions.
1727
1781
 
1728
1782
  A subset alternate covering the limb automatically covers its generated bands
1729
1783
  as well. A band may also be listed explicitly in `parts`; it cannot be hidden
@@ -3128,7 +3182,9 @@ What each rule drafts (`src/cloth.ts` holds them):
3128
3182
  | rule | drafts | from |
3129
3183
  | --- | --- | --- |
3130
3184
  | where | `bottomwear`: from `hip`, the root row 20 px below hip's y (the keyed chains' row), the tip row 4 px above the cloth's own bottom under each column (4 px above the part box's bottom when every column reaches the bottom band, or 4 px above where the cloth's alpha ends under that column on a floor-spread skirt whose middle hem ends above bare thighs; a column with no cloth below the root row gets no tree drafted there and emits a note saying so, issue #438). `back hair` that reaches below the shoulders: from `head`, per side of the eye axis (twin tails are a side each), the eye line to 4 px above its bottom. `front hair`: each qualifying strand that hangs below the chin (the lock rule's: each connected component below `chin + 4` of height at least `0.3` face heights, `src/propose.ts`), from `head`, 0.22 face heights above the eye line to 5 px below the strand — the recipe's `chains`, `links` and `split` are applied separately to each qualifying hanging strand and do not replace the fringe's fixed three two-link columns (`bang_r`, `bang_c`, `bang_l` keep their two links and their places and take physics on both links) | the keyed chains' own rows, which these replace |
3185
+ | sleeve carrier | `handwear-r` and `handwear-l` each take one named uncut part with the matching source tag. Give the side's elbow in `--keypoints`. The elbow row begins the span and the last opaque row in each column ends it. The named Form 1 sleeve hangs from `chest` with physics on its trees and the upper carrier fixed to `chest`. The recipe refuses a shared or joint-cut carrier. | `part`, the elbow, and the part's opaque art |
3131
3186
  | trees | tree k of `chains` (`N`) owns the cell k/N .. (k+1)/N of the art's width in every row, and its links sit at the cell's centre in the 24-row band there, so a piece that widens fans its trees. **Count unit of `chains`:** on `back hair`, an explicit `chains: N` is passed to **each emitted side of the eye axis** (`N` trees on `r` and `N` on `l` when both sides emit, not a combined total across both sides; `src/cloth.ts`, `src/propose.ts`); on `front hair`, `chains: N` is applied **separately to each qualifying hanging strand** and does not replace the fringe's fixed two-link columns (`src/propose.ts`). On `back hair`, `chains` is optional (issues #390, #445, #461): when omitted, `propose --cloth` derives the tree count on each side from the side's **visible hair masses** and root-row reach — it is **not** a universal default of 1 or 2 trees for every painting (`RECIPE_BACK_HAIR_CHAINS = 2` in `src/cloth.ts` is only the fallback when `draftTrees` is called with neither `masses` nor `chains`) — connected components of the `back hair` part's alpha below the eye-line root row (after skipping any undivided crown rows that bridge continuously across the eye axis), merged when they touch within one mesh grid cell — placing `max(1, floor(w / (4 * grid)) + 1)` trees inside each mass across its root-row opaque width `w` (one tree per `4 * grid` of horizontal reach, where a tree's segment weight `1 / (d + r)^2` with `r ≈ 0.42 * grid` drops to `MIN_WEIGHT = 0.03` at `2 * grid` on each side of the trunk), rooted at that mass's own top row and with every link inside that mass's column range; `propose`'s `LINT` names the masses it found and their columns when a side's tree count or link leaves them. An explicit `chains` that exceeds what the narrower side's opaque width at the eye-line root row holds (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`) or places a root off the 15 px dilated art is refused (`PROPOSE_CLOTH_BACK_HAIR_CHAINS`). With `split`, the trunk's tip is the fork, and branch b of `into` follows the centre of its share of the cell. Chains are named `<prefix><k>_` (trunk) and `<prefix><k><a, b, …>_` (branches): `skirt`, `hairback_r`/`hairback_l`, `lockt`. With `split.hold_tip: true` (issues #403, #392), sibling branches keep `strength.branch` across the fork, the mesh's `r` is raised to `grid`, and the rig stage blends each fork's sibling branch weight shares across four passes of 1-ring mesh-edge averaging (self weight 0.5, floor 0.005, cap 8 influences) — every share alike, trunk, branch and fixed bones, none held in place — holding the triangles where two branches' cells meet; when the recipe also declares `influence`, the drafted influence mesh carries `hold_tip: true` and `max` at least 8, and the rig stage smooths it by the same passes capped at that `max` (issue #615, the `meshes.<part>.influence` row) | `chains`, `links`, `split` |
3187
+ | extent | on one bottomwear or sleeve carrier, a fraction above 0 and at most 1 measured from each tree's free end over its existing root-to-tip row span. The shortest resolved path sets the common fork root. Longer branches keep their tips and the proposal prints each realized fraction. The swing keeps its original anchor. The generated mesh field `fixed_above` holds art above the earliest tree root on the fixed frame (hip on a skirt, chest and hip on a dress). The first mesh cell crossing that row also stays fixed, so the transition lies below the root. The draft reports the held strip and first-link length for each tree and refuses a strip that reaches the end of that link. | `extent` |
3132
3188
  | lengths | link j's length is the first's times q^j, q = `length_ratio`^(1/(links − 1)), the whole spanning root row to tip row: the links shorten toward the tip | `length_ratio` (default 0.5, below) |
3133
3189
  | stiffness | a trunk link takes `strength.trunk`, a branch link `strength.branch`, and the edge — the outermost branch on each outer side of the piece (both sides of a skirt or a strand; the outer side of each back-hair side; or, under `split.hold_tip: true` with `strength` left out, kept at `strength.branch` so a fork's sibling branches do not pull apart at the default 2:1 stiffness), or without `split` the outermost tree — `strength.edge`; a fringe column is a trunk, its outer two the edge. **Strength does not fall along a chain**: a tip reads soft because each link turns on top of every link above it, so the motion accumulates down the chain at one strength. Only the edge is declared softer | `strength` (default trunk 100, branch 100, edge 50, below) |
3134
3190
  | response | link j of an n-link path takes `wind` and `gravity` at j/(n − 1) of the way from the root value to the tip value; a single-link path takes the tip value. Each is a scalar **multiplier** of the environment the consumer sets (spine-core's skeleton `windX, windY`, `gravityX, gravityY`; rig-c 2.52.0's live track `setEnvironment`, rig-play 1.10.0's `environment()`): no direction is drafted | `wind`, `gravity` |
@@ -3704,8 +3760,8 @@ drives **the body with keyframes** and **every cloth and hair chain with `physic
3704
3760
  constraints**. Plain `propose` (without `--cloth`) drafts keyframed harmonic `chain`
3705
3761
  tracks on every hair, fringe, sleeve, skirt and strap chain and writes no
3706
3762
  `constraints`, while `propose --cloth` replaces only the `cloth`-declared tags
3707
- (`bottomwear`, `back hair`, `front hair`) and leaves `handwear` sleeves and
3708
- `topwear` straps on keyframed chains. To author a Form 1 idle where cloth and hair
3763
+ (`bottomwear`, `back hair`, `front hair`, and explicitly named `handwear-r` or
3764
+ `handwear-l` carriers). Other sleeves and `topwear` straps keep their keyframed chains. To author a Form 1 idle where cloth and hair
3709
3765
  all move by physics instead of keyframed sine chains:
3710
3766
 
3711
3767
  1. **Key only the body carrier in `motion.tracks`.** Keep the torso breath on `chest`
@@ -3795,7 +3851,7 @@ step-up method below.
3795
3851
  | `motion.duration` and `track.period` | `check`'s 12 fps grid (`1/12` s per frame) | Choose `N` frames (e.g. `N = 40`, `duration = 40 / 12 = 3.3333333333333335` s, or `N = 48`, `duration = 4.0` s) and set every body track's `period = duration`. `CHECK_LOOP_LAST_FRAME_AT_DURATION` requires `duration` to land on a `1/12` s tick, and `CONFIG_PERIOD_DIVIDES_DURATION` requires `duration / period` to be an integer. |
3796
3852
  | Torso breath (`chest` `translatey`, `scalex`) | Figure height `H` (`parts.json` union height, kept near `1,100..1,200` rig px via `assemble.rig_scale`), torso span `L_torso = hypot(hip.x - neck.x, hip.y - neck.y)` from `bones`, and `BREATH_VISIBLE`'s `torso_heat_mean` vs `torso_floor` (pictured in `motion_heat.png`) | Floor: peak-to-peak vertical travel at `1.25 %` of `L_torso` (`amp = round2(0.00625 * L_torso)`, `base = amp`, `phase = 0.0`, i.e. `amp = 1.2` rig px on `demo`), paired with `chest` `scalex` `amp = 0.008`, `base = 1.008`, `phase = 0.0`. `check` scales the reference floor (`2.13` at `render_scale = 0.4211`) by `render_scale / 0.4211` and isolates the breath by posing only `chest`/`hip` `translate` and `scale` tracks. |
3797
3853
  | Upper-body sway (`chest` → `neck` → `head` `rotate`) | Shoulder lever arm `R_shoulder = \|sleeve_s0.x - chest.x\|` in `bones`, and `CHAIN_LAG` / `TIP_OVER_ROOT` on `handwear` | Floor: `amp(chest) = 0.7°`, `amp(neck) = 0.85°`, `amp(head) = 1.0°` with lag `0.05` (`phase: 0.25, 0.30, 0.35`). **Set `chest` `rotate` `phase` to `0.25` (quadrature, 90° from `chest` `translatey`'s `phase: 0.0`), never near `0.0`:** at `phase ≈ 0`, vertical breath `y(t)` and shoulder lift `Δx · θ(t)` reinforce on one shoulder and cancel on the other, inflating `root_rig_px` on the reinforced sleeve and dropping `tip_rig_px / root_rig_px` below `1.4725`. At `phase = 0.25`, vertical breath and rotational sway are orthogonal on both shoulders alike. |
3798
- | Sleeve motion (`sleeve_<s>0..2` under `chest`) | `CHECK_TIP_OVER_ROOT` certifies that the lower band of each `handwear` part's box travels more than the upper band (`ratio >= 1.4725`), in the frame of the bone it hangs from; it does not prove physics. Also measure `CHECK_ANIMATIONS_DO_NOT_FOLD`. | Set `"rotate": 1, "mix": 1, "inertia": 1.0, "damping": 0.75, "mass": 1` and taper `strength` down the chain: `[45, 30, 20]` for a 3-link sleeve (`1 : 0.67 : 0.44`). Stiff follow-through springs (`strength: 200`, `inertia: 0.2`) barely bend under a `3.333` s idle and move the sleeve as a rigid unit (`ratio ≈ 1.19..1.22`, failing `TIP_OVER_ROOT`); tapering `45 → 30 → 20` lets cumulative link rotation amplify cuff travel past `2.0x` the shoulder travel while keeping `0` folded triangles in `wave` and `hop`. Those ratios are the world reading `TIP_OVER_ROOT` took until issue #987; it now reads the halves against `chest`, the bone the sleeves hang from, and this recipe on `demo` (the working build reproduced below) reads `9.383` and `9.952` there (`handwear_l`, `handwear_r`; `3.626` and `2.905` in the world, which the row keeps as `world_ratio`) — it passes the reading the line holds (rig-parts at `c17292c` with #987's change, rigc 3.2.1). |
3854
+ | Sleeve motion (`sleeve_<s>0..2` under `chest`) | `CHECK_TIP_OVER_ROOT` certifies that the lower band of each `handwear` part's box travels more than the upper band (`ratio >= 1.4725`), in the frame of the bone it hangs from; it does not prove physics. Also measure `CHECK_ANIMATIONS_DO_NOT_FOLD`. | To draft a named sleeve end through the tool, use the sleeve carrier recipe above and declare its response. For a hand-authored sleeve on the existing keyed-chain geometry, set `"rotate": 1, "mix": 1, "inertia": 1.0, "damping": 0.75, "mass": 1` and taper `strength` down the chain: `[45, 30, 20]` for a 3-link sleeve (`1 : 0.67 : 0.44`). Stiff follow-through springs (`strength: 200`, `inertia: 0.2`) barely bend under a `3.333` s idle and move the sleeve as a rigid unit (`ratio ≈ 1.19..1.22`, failing `TIP_OVER_ROOT`); tapering `45 → 30 → 20` lets cumulative link rotation amplify cuff travel past `2.0x` the shoulder travel while keeping `0` folded triangles in `wave` and `hop`. Those ratios are the world reading `TIP_OVER_ROOT` took until issue #987; it now reads the halves against `chest`, the bone the sleeves hang from, and this recipe on `demo` (the working build reproduced below) reads `9.383` and `9.952` there (`handwear_l`, `handwear_r`; `3.626` and `2.905` in the world, which the row keeps as `world_ratio`) — it passes the reading the line holds (rig-parts at `c17292c` with #987's change, rigc 3.2.1). |
3799
3855
  | Hair physics (`hairback_*`, `bang_*` under `head`) | `CLOTH_SETTLES` (`>= 0.01694` rig px/s to the last frame), `CHECK_TEXTURE_STRETCH` (`<= 1.926544`), and `CHECK_ANIMATIONS_DO_NOT_FOLD` | Taper `strength` down each `n`-link chain by `strength_0 * (1 - 0.35 * i / (n - 1))`: on long back-hair chains, `strength_0 = 90` (`[90, 74.25, 58.5]` for 3 links), `inertia = 0.8`, `damping = 0.85`; on shorter fringe chains (`bang_*`), `strength = [130, 105]`, `inertia = 0.2`, `damping = 0.9`. |
3800
3856
  | Skirt / `bottomwear` physics (`skirt_*` under `hip`) | `CHECK_TIP_OVER_ROOT` on `bottomwear` (`ratio >= 1.4725`), `CHECK_ANIMATIONS_DO_NOT_FOLD` on `hop`, and `CLOTH_SETTLES` | Keep high restoration `strength` (`[200, 165, 130]` for 3 links, `inertia = 0.5`, `damping = 0.82`) so `bottomwear` does not fold during `hop`. With `hip` unkeyed, floor `"wind": [0.4, 0.6, 0.8]` passes `TIP_OVER_ROOT` (`ratio 1.83`); with `hip` keyed in `rotate` (`amp <= 0.4°`, `phase: 0.20`), set `"wind": 0` on the upper-half link `skirt_*0` and put `"wind"` on the lower links (`[0, 15, 40]`) so `tip / root` stays above `1.4725` and `CLOTH_SETTLES` clears on the default world. |
3801
3857
 
@@ -4117,7 +4173,7 @@ full loader before its assemble stage writes anything.
4117
4173
  rig px, so every origin reads 0, each chain link's tip, length and direction its
4118
4174
  config's, and every `<bone>_ctl` the rig stage inserted is the bone between a
4119
4175
  keyed mesh bone and its parent (§5).
4120
- **Before a person looks**, open every `out/check/extremes/<anim>/extremes.png`
4176
+ **Before a person looks**, open every `out/check/extremes/<segment>/extremes.png`
4121
4177
  after `check` (or the check inside `build`). Read setup, the geometry pair's
4122
4178
  min/max, and `|max - min|` at native scale. Crop every changed part boundary
4123
4179
  at native size and 4x nearest-neighbour; label it **tear** (background or
@@ -4431,6 +4487,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
4431
4487
  | `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
4432
4488
  | `assemble --propose-plan … [--write-config <config>]` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule, naming in a note any full-run body no planned part covers, and naming every layer no row takes with why (empty, taken from the other run only, a plausibility rule; `nose`, never planned, with the row that lets `propose` read the head's pitch). Front/back hair reaching more than 8 rig pixels beyond a side or top edge receives explicit `edges`; each explicit edge has the same strict reach bar. The legacy bottom entry is retained unchanged; qualifying side/top edges receive a separate entry without bottom. With no qualifying side/top edge, the proposal remains unchanged. |
4433
4489
  | `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json`, the recomposite and its error map, and `run.json` (`spec` `rig-run/1`), and list the uncovered holes |
4490
+ | `diff-drafts --left <dir> --right <dir> --out <json>` | compare two assemble or build outputs (`rig/parts.json` + `rig/parts/` + `render/recomposite_rig.png`, or `parts.json` + `parts/` + `recomposite_rig.png`) and write `rig-parts-draft-diff/1` JSON: per-part status (`same`, `changed`, `added`, `removed`), file `sha256`, rig-pixel `box` and draw-order `index` per present side, `pixels_equal` and rig-space `pixels` (`changed_px`, `colour_px`, `alpha_px`, `bounds`) on changed parts, and `composite` ([Draft-to-draft assemble comparison](#draft-to-draft-assemble-comparison-issue-1369)) |
4434
4491
  | `head-crop-preflight --full <run> --canvas WxH --head-box '[left,top,right,bottom]'` | before the head run: JSON on stdout, one advice line per hit tag on stderr, exit 0 even when clipped. Counts original alpha > 8 full-run samples after centre registration through the square pad into painting coordinates: centres below left/top or at/above right/bottom are outside. Fractional boxes are accepted; corner samples count on both edges. No ghost cleanup, resampling, head run or assemble is needed. These counts cannot be compared with `ASSEMBLE_CROP_CLIPPED`, which counts rig pixels at alpha >= 128 after `cleanGhosts`. Preflight reads original samples before the head run exists, so soft fringes and ghost specks can be hits only here. Bottom is distinct because `extend_below_crop` handles it. Zero-hit tags remain in JSON. Existing pipeline outputs stay unchanged; help adds this command and guide reflects these documentation edits. |
4435
4492
  | `propose --head-box --full <run> --canvas WxH [--no-back-hair] [--write-config <config>]` | propose `seethrough.head_box` from the full run, held inside the painting; `--no-back-hair` leaves the back-hair layer out of that proposal |
4436
4493
  | `propose --parts --source --out [--compare <config>] [--write-config <config> [--only-missing]]` | propose bones, meshes, regions and an idle; draw the overlay; print, per bone, which check read it or that none did and why (its role, its kind of segment), and write `basis.json` beside the proposal — what each bone rests on (a joint, a part's mask, a ratio, other bones) and, with `--compare`, whether the config's bone differs |
@@ -4447,7 +4504,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
4447
4504
  | `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
4505
  | `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
4506
  | `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 |
4450
- | `remesh --rig <dir> --config <json> --parts <dir> --part <name> --out <dir>` | with exactly one of `--mesh <entry.json>` or `--delta <mesh-edit.json>`, re-fit one part of a gated rig into a fresh revision, preserving the input |
4507
+ | `remesh --rig <dir> --config <json> --parts <dir> --part <name> --out <dir>` | with exactly one of `--mesh <entry.json>` or the legacy `--delta <mesh-edit.json>`, re-fit one part of a gated rig into a fresh revision, preserving the input |
4451
4508
  | `retune --rig <dir> --config <json> --parts <dir> --out <dir>` | splice the config's constraints and idle onto a gated rig in a fresh revision, carrying its attachments over as bytes |
4452
4509
  | `guide <RULE \| §<n> \| §<n>.<m> \| §<n>.<m>.<k>>` | print the one row of [docs/AUTHORING.md](AUTHORING.md) that names a rule (a refusal and the bar it enforces, `CHECK_<LINE>` and `<LINE>`, print together), or one section, `###` subsection or `####` under it, read from the installed file when it runs |
4453
4510
 
@@ -4505,6 +4562,45 @@ split ([MIGRATION](MIGRATION.md#after-1370-merged-arm-layers-are-split-issue-490
4505
4562
  and a usage error with `--head-box`, `--cloth` or `--from-config`.
4506
4563
  `--from-config` proposes nothing and cannot be combined with `--write-config`.
4507
4564
  [AUTHORING §4](AUTHORING.md#4-the-command-order) describes all four modes.
4565
+
4566
+ ### Keeping assembled parts current
4567
+
4568
+ Use one config through `assemble` → `propose --write-config` → `assemble` →
4569
+ `edited-part`. The first assemble supplies the parts for drafting `turn`.
4570
+ An already authored turn can be present for the first assemble. Use the second
4571
+ assemble's `parts.json` and PNGs to prepare and record an edit. Declare
4572
+ `assemble.edited_parts` with its directory and empty receipts before that
4573
+ assemble, then assemble again to apply the recorded edit.
4574
+
4575
+ `assemble` reads `turn` to identify parts that move relative to each other.
4576
+ That classification controls fringe pushback, source projection and seam
4577
+ override so those passes preserve separately moving art. With depth binding,
4578
+ assemble also resolves explicit unit depths using the mesh or region carrier
4579
+ and, when needed, `motion.blink.still`. `motion_seams` supplies the seam
4580
+ declarations carried in `parts.json` for check.
4581
+
4582
+ `parts.json` records the effective assembly digest and per-field hashes in
4583
+ `assembly_config`. Both `assemble` and `build` choose `--seam` and `--project`
4584
+ over `assemble.seam` and `assemble.project` in the config. The corresponding
4585
+ hashes reflect the values used, including the defaults when neither the flag
4586
+ nor the config supplies a value.
4587
+
4588
+ `build` uses those effective values for its own rig and check stages in the
4589
+ same invocation. When a standalone command validates the manifest, it reads
4590
+ the caller's config. To reuse parts made with a different `--seam` or `--project`
4591
+ than the config specifies, put the values used for assembly in `assemble.seam`
4592
+ and `assemble.project` in the config you pass to the standalone command.
4593
+ To use other values, re-run assemble with the config you intend to keep.
4594
+
4595
+ Ordinary keyed-animation edits through `motion.animations_from` leave
4596
+ the assembly digest intact. Cloth changes can require reassembly when physics
4597
+ bone bindings change which part pairs move relative to each other under turn.
4598
+ When `propose --write-config` changes the recorded reading, it saves the
4599
+ config, names the changed assembly fields and asks you to re-run assemble.
4600
+ Reassembling into the same output also reports the changed fields. Consumers
4601
+ that check the manifest against a config refuse a stale digest as
4602
+ [`ASSEMBLY_CONFIG_STALE`](#ASSEMBLY_CONFIG_STALE).
4603
+
4508
4604
  ## 5. After each stage: what to read
4509
4605
 
4510
4606
  | stage | read | green looks like | a common red |
@@ -4517,7 +4613,7 @@ and a usage error with `--head-box`, `--cloth` or `--from-config`.
4517
4613
  | `compare` | one line per pair (origin, parent, tip, length, direction — or SKIP and why), then the per-row summary, the unmapped bones of each side, `required:`, each side's roles and the `controls:` line | proposal against the config you corrected: the rows you changed and no others. Config against the `rig.json` `build` writes for it: measured on both examples, every origin within 6.19e-7 px (the rig's offsets are written to 6 places) and every chain link's tip and length within 4.99e-4 px (`length` is written to 3), printed to three places as `0.000` (a signed figure as `+0.000` or `-0.000`); `parent … is the right's ancestor at depth 2, <bone>_ctl between` for every keyed mesh bone, no `DIFFERENT` and no `NOT MAPPED` | `parent DIFFERENT: left a, right b` — a bone hangs from another parent than the other side's; `frames not related` — a rig with no stage (`skeleton.width`/`height`), two configs at different `rig_scale`: the distance rows SKIP, so declare the frame in a `--map` file if the author knows it; `FAIL STRUCTURE_REQUIRED_PRESENT` — a bone the map requires is missing through its pairs |
4518
4614
  | `rig` (inside `build`) | one line per mesh: vertices, triangles, bones, influences, `cover`; the `bones` line; the `idle keys` line; then rigc's gate lines (with A15's declared SKIP under `--idle-keys direct`); in `rig.json`, each chain link's (or its `_ctl`'s) `length` and `rotation` | `cover 1.00000` on every mesh, both gate summaries `0 failed` (the compile and the packed pages); every link's `length` the distance to the next link and `rotation` its direction (Spine degrees, counter-clockwise, y up, local to the parent), every offset under it — a child bone's `x, y`, a weight's bind `x, y`, a region's `x, y` — in that turned frame, and a region on a link carrying `rotation` that turns it back upright. Nothing moved: `flattenRig` (`src/rig.ts`) turns every offset back and gives the unturned numbers | `RIG_LATTICE_ONE_LOOP`: change that mesh's `grid` |
4519
4615
  | `check` (inside `build`) | the gate lines verbatim, the pack line, `loop:` (and `loop physics:` when the rig declares a physics constraint, §7), `seam:`, the six judgement lines, then — when `motion.json` holds an animation, the idle included — `ANIMATIONS_DO_NOT_FOLD` and one `folds` line per folding mesh, rigc's own (issues #320, #333), then — where a `footwear` part rides a bone that hangs from another — `FEET_STAY_LEVEL` and one `foot` line per such part (issue #348), then — when `parts.json` names a `handwear` part and there is an idle — `STRESS_OFF_CHAIN` (issue #347), then — where `parts.json` holds a limb segment's part — `LIMB_ONE_BONE` and one `limb` line per such part (issue #349), then — where a limb record carries a `range` — `SEAM_OVER_RANGE` and one `joint` line per joint and angle (issue #360), then `SEAM_OVER_MOTION` — a SKIP naming why on a rig that declares no neighbour pair, else the pairs read in every animation; existing internal-joint and explicit-seam pairs retain their `WARN seam` policy (issue #493), while proven body-root tears print `FAIL seam` and fail a counted bar (issue #686), then `CLOTH_SETTLES` — a SKIP naming why on a rig with no physics constraint, else the chains read and one `WARN chain` line per chain whose tip comes to rest before the idle's loop length (issue #501, a warning and never a bar), then `figure_openings:` — `CLEAR` or `WARN` with the undeclared setup-overlapping pairs, animations and cell size read and one `WARN opening` line per pair and animation whose transparent interior opening exceeds the one-cell floor, or a named `SKIP` when there is no `parts.json`, no animation or no undeclared setup-overlapping pair (issue #933, a warning and never a bar), `RECOMPOSITE_HOLES` and, under `--source`, `SETUP_POSE_VS_SOURCE` (§7), `check.json`; the last line says how many of the bars measured — nine, ten with the fold bar, one more each with the feet-level bar, the stress bar, the limb bar, the range bar and, where proven body-root pairs exist, the body-root seam bar — and names the ones that said SKIP, then — where `SEAM_OVER_MOTION` read a pair — how many warnings it printed, `; N warning(s) (SEAM_OVER_MOTION, not a bar)` — with `CLOTH_SETTLES` named beside it, and N their sum, where the rig declares a physics constraint — which no bar counts | `check: PASS; 11 of 11 bar(s) measured, 0 skipped` on `demo` and `scarf`, whose sleeves each ride one chain; `check: PASS; 10 of 11 bar(s) measured, 1 skipped (STRESS_OFF_CHAIN)` on `reference-demo` and `reference-sample`, whose one `sleeves` mesh rides both sleeve chains (issue #347) — no example writes `FEET_STAY_LEVEL`, every shoe riding `root`; a judgement line SKIP only where the character lacks what it reads; on a rig spec with no `parts.json` or no `idle` (a merged rig, §7 *Measuring a rig rig-parts did not assemble*), PASS with the skipped bars named | `CHECK_SEAM_WITHIN_BAR` or `CHECK_LOOP_CLOSES` (§6); `CHECK_ANIMATIONS_DO_NOT_FOLD` — a clip turns a mesh over (§6); `CHECK_STRESS_OFF_CHAIN` — a sleeve weighted off its chain (§6); `CHECK_LIMB_ONE_BONE` — a limb part on a second bone (§6); `CHECK_SEAM_OVER_RANGE` — a joint that opens when bent (§6); `CHECK_SEAM_OVER_MOTION` — a proven body-root seam opens over the existing floor (§6) |
4520
- | `check` / `build`: extremes observations | `extremes/<anim>/extremes.png` and `extremes.json` beside the other check outputs, generated by core `render --extremes-only` at 12 fps on its fitted world box at scale 1; one `EXTREMES` geometry-pair frame/distance summary per animation | open the native setup/min/max/diffs and label every changed boundary tear, ghost or clean before human review (step 9) | core's named static/observation SKIPs retain JSON without a PNG; diagnostic failure is `CHECK_EXTREMES_RENDER_FAILED` SKIP and leaves the measured verdict unchanged; `--no-extremes` runs no extra render and removes stale `extremes/` |
4616
+ | `check` / `build`: extremes observations | `extremes/<segment>/extremes.png` and `extremes.json` beside the other check outputs; `<segment>` follows [Diagnostic path segments](STABILITY.md#diagnostic-path-segments), while JSON retains the original animation; generated by core `render --extremes-only` at 12 fps on its fitted world box at scale 1; one `EXTREMES` geometry-pair frame/distance summary per animation | open the native setup/min/max/diffs and label every changed boundary tear, ghost or clean before human review (step 9) | core's named static/observation SKIPs retain JSON without a PNG; diagnostic failure is `CHECK_EXTREMES_RENDER_FAILED` SKIP and leaves the measured verdict unchanged; `--no-extremes` runs no extra render and removes stale `extremes/` |
4521
4617
  | `check --requirements` (and `build --requirements`) | after the lines above, one line per declared requirement, `NAME: PASS`, `FAIL` or `NOT MEASURABLE — …` with its figures, the bar as declared and the worst frame; then `requirements: N declared — M measured (P PASS, F FAIL), K NOT MEASURABLE; not declared: <kinds>`; `check.json`'s `requirements` block, first its `file` record (issue #556); the renders under `requirements/` (§7, *Declared requirements*) — `build` reads `config.requirements` in place of the flag when it is not given | every line PASS and `0 NOT MEASURABLE`; a follow's `released_copy` says whether rigc's consumer-driven door was taken on the throwaway copy; a `stretch` line's `held_by` (issue #321), right after `worst`, names the bones the worst edge's two vertices hang on and their idle chains, in `CHECK_TEXTURE_STRETCH`'s words (§6) and by the same function, on a PASS as on a FAIL | `CHECK_REQUIREMENT_MET` (a figure past its bar; the line names the frame) or `CHECK_REQUIREMENT_MEASURABLE` (the quantity is undefined in the frames: a tip or an axis on a bone of length 0, an aim with no line, a follow no frame of which reaches its least drive); the last line then reads `check: FAIL — B bar(s) not met, R declared requirement(s) not PASS` |
4522
4618
  | `compose` | the `[compose]` lines: one per character (its offset, its scale, its placed bounds, the shift and how many first-level bones, regions on `root` and weights bound to `root` it moved, its bone, slot, track and constraint counts, its `rig_scale` and idle), the declared order and the slot count it expands to, rigc's gate lines; then the `[check]` lines as for `check`, and `scene.json` | both gate summaries `0 failed`, `check: PASS` with the bars that measured and the ones that said SKIP named — on a composed rig `4 of 9`: the gate, the loop, `CHAIN_LAG` and `TEXTURE_STRETCH` (there is no `parts.json`; each character's own `build` measured all nine). `scene.json`'s `order.slots` is the order the compiled skeleton draws | a `SCENE_*` refusal (§6, *compose*) — the scene file, a build, or the order; `COMPOSE_RIGC_GREEN` — rigc's own line, quoted |
4523
4619
  | `loop` (inside `build --loop`, or `loop --frames … --out …`) | the dropped-duplicate line, or, when the end frame is not frame 0, the jump line: its max \|d\| and px over 40, then why — under `build`, `the rig holds N physics constraint(s), and rigc's render starts every one at rest at frame 0` with the remedy `build --loop --lead-in <n>`, or `the rig holds no physics constraint, so the idle itself does not close` (`CHECK_LOOP_CLOSES`); under `loop --frames`, which reads frames alone, both causes (issue #325); under `build --lead-in`, the lead-in line in its place (the frames kept and the jump at the wrap); each file's line, then `loop: idle.png N B (lossless); idle-indexed.png N B (max …, mean …); idle.gif N B (max …, mean …)` | `f0048.png equals f0000.png byte for byte, so it is dropped` | `LOOP_ENCODE` (§6) |
@@ -5466,6 +5562,7 @@ See-through with another seed.
5466
5562
  | <a id="CONFIG_SET_LAYERS"></a>`CONFIG_SET_LAYERS` | `assemble.alternates[i].layers` names an unknown, uncovered or hidden part, or a painting patch with no run-layer source | name a covered layer-backed output part (a limb segment name, not its consumed source); use `author:<label>` for author art |
5467
5563
  | <a id="CONFIG_MOTION_SEAM"></a>`CONFIG_MOTION_SEAM` | motion_seams has a malformed entry, an unknown output part, a self-pair, duplicate/reversed pair or unknown entry field | declare each unordered pair once with two resolved output part names |
5468
5564
  | <a id="PARTS_MOTION_SEAM"></a>`PARTS_MOTION_SEAM` | parts.json motion_seams violates the same declaration shape/name/uniqueness contract | reassemble with the declared output part names |
5565
+ | <a id="ASSEMBLY_CONFIG_STALE"></a>`ASSEMBLY_CONFIG_STALE` | the effective assembly inputs in the supplied config differ from the digest recorded in parts.json; the refusal names the fields with changed presence or hash | re-run assemble from the current config, then use its manifest and part PNGs |
5469
5566
  | <a id="CHECK_MOTION_SEAM_DECLARATION"></a>`CHECK_MOTION_SEAM_DECLARATION` | a directly supplied parts record has an invalid explicit motion seam declaration | supply a valid parts.json declaration; check never infers a replacement |
5470
5567
  | <a id="CONFIG_NAME_RESOLVES"></a>`CONFIG_NAME_RESOLVES` | a parent, segment, region, track, blink member, blink still part or bone, extend part, patch or cut `draw.before`, or cut `from` names nothing declared above it (a cut's `from` must be a plan part); or a constraint's `bones`, `target`, `source` or `bone` names a bone `bones` does not declare (the detail names the constraint and lists the bones that exist); in `meshes.<part>.auto`, a bone or region name nothing declares; or `bones[i].link_inherit` names a link outside its own chain (the detail lists that chain's expanded links) | the named reference, or the declaration it needs |
5471
5568
  | <a id="CONFIG_BONE_UNIQUE"></a>`CONFIG_BONE_UNIQUE` | a bone or chain declared twice, or `root` declared | `bones` |
@@ -5493,8 +5590,10 @@ See-through with another seed.
5493
5590
  | <a id="CONFIG_CLOTH_SPLIT_BEFORE_TIP"></a>`CONFIG_CLOTH_SPLIT_BEFORE_TIP` | a `cloth` recipe's `split.at` is at or past its `links`: the trunk would leave no link for the branches (issue #364) | `split.at` below `links`, or leave `split` out |
5494
5591
  | <a id="CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP"></a>`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP` | a `cloth` recipe's `wind` or `gravity` is `[root, tip]` with tip below root: the response grows from the root to the tip, where the motion accumulates down the chain | that pair |
5495
5592
  | <a id="CONFIG_CLOTH_ALTERNATE_DIFFERS"></a>`CONFIG_CLOTH_ALTERNATE_DIFFERS` | a `cloth` recipe's `alternate_damping` without `damping`, or equal to it: neighbouring trees are declared out of phase, and an alternate that alternates nothing declares nothing | `damping` beside it, a different value, or leave `alternate_damping` out |
5593
+ | <a id="CONFIG_CLOTH_SLEEVE_PART"></a>`CONFIG_CLOTH_SLEEVE_PART` | a sleeve recipe lacks a singular `part` declaration or carries `parts` | declare one matching carrier by name in `part` |
5594
+ | <a id="CONFIG_CLOTH_EXTENT"></a>`CONFIG_CLOTH_EXTENT` | the declared extent is outside (0, 1], or belongs to a hair or multi-part recipe | declare a finite fraction for a single bottomwear or sleeve carrier |
5496
5595
  | <a id="CONFIG_CLOTH_SWING_SCALE_PER_TREE"></a>`CONFIG_CLOTH_SWING_SCALE_PER_TREE` | `swing` on a tag other than `bottomwear`, or `swing.scales` not one scale per tree (`chains`) | one scale per tree, in tree order across the skirt |
5497
- | <a id="CONFIG_CLOTH_PART_ON_BOTTOMWEAR"></a>`CONFIG_CLOTH_PART_ON_BOTTOMWEAR` | `part` as a string on a `cloth` recipe for a tag other than `bottomwear` (issue #402; a list of parts in `parts` or `part` is accepted on any tag, issue #437) | leave it out there, or pass a list of parts in root-to-tip order (`parts: [...]`); a single string `part` hands the skirt's recipe to a `topwear` part that holds a skirt (a dress) |
5596
+ | <a id="CONFIG_CLOTH_PART_ON_BOTTOMWEAR"></a>`CONFIG_CLOTH_PART_ON_BOTTOMWEAR` | `part` as a string on a `cloth` recipe for a hair target (issue #402; hair may use a list in `parts` or `part`, issue #437) | leave it out there, or pass a list of parts in root-to-tip order (`parts: [...]`); a single string `part` hands the skirt's recipe to a `topwear` part that holds a skirt (a dress) |
5498
5597
  | <a id="CONFIG_CLOTH_PARTS_UNIQUE"></a>`CONFIG_CLOTH_PARTS_UNIQUE` | a `cloth` recipe sets both `part` and `parts`, or its part list names the same part more than once (issue #437) | set at most one of `part` or `parts`, and list each part once in root-to-tip order |
5499
5598
  | <a id="CONFIG_CLOTH_SPRING_STABLE"></a>`CONFIG_CLOTH_SPRING_STABLE` | a `cloth` recipe's strength — declared, or the default 100 / 100 / 50 — whose spring is unstable at a damping the recipe runs at (`damping`, `alternate_damping`, or rig-c's 0.85 when `damping` is left out): k = strength·massInverse·step² at or past 2(1 + damping^(60·step)), step 1/60 and mass 1 (rig-c's defaults; the recipe sets neither). The detail gives k and the bound | a lower strength, or a higher damping |
5500
5599
  | <a id="CONFIG_TURN_BONE_FREE"></a>`CONFIG_TURN_BONE_FREE` | the config has `turn` and `bones` declares a bone named `turn`, the control the rig stage adds | rename that bone |
@@ -5798,7 +5897,17 @@ recorded transform. The record fields and sampling formula are specified in
5798
5897
  | <a id="ASSEMBLE_TAKE_UNIQUE"></a>`ASSEMBLE_TAKE_UNIQUE` | repeated donor for one target tag at runtime | declare each target run/tag once |
5799
5898
  | <a id="CONFIG_TAKE_UNIQUE"></a>`CONFIG_TAKE_UNIQUE` | config selects the same target run/tag more than once | retain one donor per target tag |
5800
5899
  | <a id="ASSEMBLE_PART_SOURCE"></a>`ASSEMBLE_PART_SOURCE` | `assemble.editor_receipts.trace_parts` is `true` and a part's pixels are decided by a shape drawn in the config — an `assemble.cuts` (or an alternate set's `cuts`) `polygon`, `seethrough.arm_split`, a limb's `split.line`, an `assemble.patches` `box`, an `assemble.extend_painting` `band`; the object names the part and where the shape is declared, the detail the shape found (issue #947) | `config.json`: remove that entry and paint the piece as an author layer (`author:<label>`) in an image editor with its receipt in `assemble.editor_receipts.receipts`, or take the part whole from a layer of the split (a limb split may use `"edge": "painting"`) |
5801
- | <a id="EDITED_PART_ARGUMENT"></a>`EDITED_PART_ARGUMENT` | A writer argument is missing or blank. | Supply a non-empty config, part, file, from and editor; omit rig-config or name a non-empty path. |
5900
+ | <a id="EDITED_PART_ARGUMENT"></a>`EDITED_PART_ARGUMENT` | A writer argument is missing or blank, or both author flags are present. | Supply config, part, file and from, plus exactly one of producer or editor. Omit rig-config or name a non-empty path. |
5901
+ | <a id="EXTERNAL_RECEIPT_ARGUMENT"></a>`EXTERNAL_RECEIPT_ARGUMENT` | Write or verify arguments are absent, malformed or incompatible, or kind is outside the accepted set. | Give one complete write or verify invocation. The accepted kind is mask. |
5902
+ | <a id="EXTERNAL_RECEIPT_SCHEMA"></a>`EXTERNAL_RECEIPT_SCHEMA` | The receipt is unreadable or has invalid JSON, version, keys or field values. | Supply a rig-parts-external-receipt/1 receipt. |
5903
+ | <a id="RECEIPT_PRODUCER"></a>`RECEIPT_PRODUCER` | Producer JSON or its fields are invalid. | Give a nonblank tool, optional nonblank model and exactly one declared lowercase SHA-256 digest. |
5904
+ | <a id="EXTERNAL_RECEIPT_INPUT"></a>`EXTERNAL_RECEIPT_INPUT` | The painting or mask cannot be read. | Supply the named readable PNG. |
5905
+ | <a id="EXTERNAL_RECEIPT_FILE_HASH"></a>`EXTERNAL_RECEIPT_FILE_HASH` | The mask bytes differ from the recorded SHA-256. | Restore the recorded mask bytes. |
5906
+ | <a id="EXTERNAL_RECEIPT_PAINTING_HASH"></a>`EXTERNAL_RECEIPT_PAINTING_HASH` | The painting bytes differ from the recorded SHA-256. | Restore the recorded painting bytes. |
5907
+ | <a id="EXTERNAL_RECEIPT_PNG"></a>`EXTERNAL_RECEIPT_PNG` | An input does not decode as PNG. | Supply a decodable PNG. |
5908
+ | <a id="EXTERNAL_RECEIPT_GRID"></a>`EXTERNAL_RECEIPT_GRID` | The mask or recorded grid differs from the painting dimensions. | Supply the mask on the painting grid and record the measured dimensions. |
5909
+ | <a id="EXTERNAL_RECEIPT_MASK_VALUES"></a>`EXTERNAL_RECEIPT_MASK_VALUES` | The mask contains a pixel outside opaque black and opaque white. | Supply a binary mask with opaque pixels. |
5910
+ | <a id="EXTERNAL_RECEIPT_OUTPUT"></a>`EXTERNAL_RECEIPT_OUTPUT` | The receipt destination cannot be published. | Use an unused path in a writable directory. |
5802
5911
  | <a id="EDITED_PART_BLOCK"></a>`EDITED_PART_BLOCK` | A named config has no assemble.edited_parts. | Declare its directory and receipts array before recording. |
5803
5912
  | <a id="EDITED_PART_FILE"></a>`EDITED_PART_FILE` | The file or from path is unreadable. | Supply readable PNG files at both explicit paths. |
5804
5913
  | <a id="EDITED_PART_PNG"></a>`EDITED_PART_PNG` | The file or from bytes are not a decodable PNG. | Supply PNGs supported by the existing codec. |
@@ -5852,6 +5961,9 @@ recorded transform. The record fields and sampling formula are specified in
5852
5961
  | <a id="DIFF_COMPONENTS_INPUT"></a>`DIFF_COMPONENTS_INPUT` | `diff-components` needs readable PNG stack/painting/part images, a writable `--out` target when writing, explicit parts, positive integer floor, a finite threshold in [0,255], matching native dimensions and valid coverage/domain inputs; flags must be unique and known, with nonempty values | Supply the named missing or invalid input; no resampling or inferred figure is performed |
5853
5962
  | <a id="DIFF_COMPONENTS_BINDING"></a>`DIFF_COMPONENTS_BINDING` | The shipped report reader found a stack or painting SHA-256 different from the supplied bytes; found and required digests are printed | Regenerate against the bytes being reviewed |
5854
5963
  | <a id="DIFF_COMPONENTS_REPORT"></a>`DIFF_COMPONENTS_REPORT` | Invalid report JSON/spec (`rig-parts-diff-components/1` or `rig-parts-diff-components/2` is required, or the spec requested by a narrow reader), or its exhaustive inventory, definition, paths, domain, coverage or topmost `owners` (on `/2`) differs from remeasurement; capped inventories are refused | Regenerate the complete versioned report against the same input paths, bytes, parts and figure domain |
5964
+ | <a id="DIFF_DRAFTS_INPUT"></a>`DIFF_DRAFTS_INPUT` | `diff-drafts` requires unique `--left`, `--right` and `--out` flags with non-empty paths; each input directory must hold either the standalone `assemble` layout (`rig/parts.json`, `rig/parts/<name>.png`, `render/recomposite_rig.png`) or the `build` layout (`parts.json`, `parts/<name>.png`, `recomposite_rig.png`), with readable PNG bytes whose dimensions match `parts.json` | Supply two readable assemble or build output directories |
5965
+ | <a id="DIFF_DRAFTS_CANVAS"></a>`DIFF_DRAFTS_CANVAS` | `--left` and `--right` declare different `rig_size` canvas dimensions in `parts.json`, so the two outputs are not drafts of one rig | Compare two drafts assembled at the same `rig_size` canvas |
5966
+ | <a id="DIFF_DRAFTS_OUT"></a>`DIFF_DRAFTS_OUT` | `--out` already exists, lies inside `--left` or `--right`, or cannot be written | Name a fresh writable output file path outside both input directories |
5855
5967
  | <a id="ASSEMBLE_PINHOLES"></a>`ASSEMBLE_PINHOLES` | the requirements file declares `pinholes.required: true` and the flat parts stack holds a pinhole: an 8-connected opening (alpha 0 on every part, enclosed by the parts' alpha above 0) whose every pixel the painting shows as figure. One refusal per pinhole, largest first, naming its box, its px and the parts bordering it; nothing is written (issue #944, [Pinholes at rest](#pinholes-at-rest-issue-944)) | `assemble.plan` / `assemble.take` / the head pass: take the pinhole's pixels from a layer that holds them ([Source before scissors](#source-before-scissors)); where no layer holds them, the defect is the input's. Without the declaration the bar reports SKIP |
5856
5968
  | <a id="ASSEMBLE_PATCH_BOX_INSIDE"></a>`ASSEMBLE_PATCH_BOX_INSIDE` | a patch's box reaches past the rig (the painting times `rig_scale`; the detail gives the size) | that patch's `box` — it is in rig pixels, not painting pixels |
5857
5969
  | <a id="ASSEMBLE_PATCH_OPAQUE"></a>`ASSEMBLE_PATCH_OPAQUE` | a patch takes no pixel: a `"silhouette"` patch whose box holds none of the figure | move the box onto the figure, or `"alpha": "box"` |
@@ -5893,6 +6005,7 @@ recorded transform. The record fields and sampling formula are specified in
5893
6005
  | <a id="PROPOSE_CUT_FROM_RECORDED"></a>`PROPOSE_CUT_FROM_RECORDED` | two parts share one layer and none of them records `cut_from`: a `parts.json` an `assemble` before 1.6.0 wrote with `assemble.cuts`. The records are in draw order, so which is the plan part and which the piece cannot be read off the file; the message names the parts and the layer. Every other reader still takes the file | `--parts`: re-run assemble (1.6.0+) to record `cut_from` |
5894
6006
  | <a id="PROPOSE_LIMB_PARTS"></a>`PROPOSE_LIMB_PARTS` | `parts.json` holds a standalone or incomplete limb part `config.limbs` cut at its joints (issues #349, #440) that cannot be reassembled into the source part `of` (a missing segment or `cap` record, or `of` still present beside the limb parts); a complete `assemble` output with `config.limbs` reconstructs its pre-limb parts in the same run | `--parts` a complete `assemble` output (every segment of each limb, with its `cap` record) or a build assembled with `config.limbs` left out; `propose --from-config` reads the config's bones on either build |
5895
6007
  | <a id="PROPOSE_FIGURE_LAYER"></a>`PROPOSE_FIGURE_LAYER` | with `--keypoints` (issue #577): a limb is drafted from the figure layer (no handwear or legwear part over 500 px for it), and two or more `topwear` parts each hold every joint and the trunk bones' origins within 15 px with the same opaque px in the 31x31 squares about them, so nothing says which is the figure; or the only `topwear` parts that hold them are named by a cloth recipe (`config.cloth.<tag>.part` or `.parts`, issue #631), whose mesh a limb would take (§3, *A figure of one material*) | leave the others out of `assemble.plan`, or give the arms and legs their own handwear and legwear layers; for a recipe's part, take it out of the recipe |
6008
+ | <a id="PROPOSE_CLOTH_EXTENT"></a>`PROPOSE_CLOTH_EXTENT` | the carrier has no resolved span, a shortened link has no downward span after whole-pixel row rounding, or the fixed mesh transition reaches the end of a tree's first link | choose a carrier with art below its root, increase the extent, declare fewer links for a collapsed span, or use a smaller mesh cell for the transition |
5896
6009
  | <a id="PROPOSE_CLOTH_DRAFTED"></a>`PROPOSE_CLOTH_DRAFTED` | with `--cloth` (issue #364): the config's `cloth` block holds a recipe for a tag the proposer drafts no chain on — no part has that tag, or every `back hair` part ends above the shoulders (a bun bone, no chain). A `bottomwear` recipe with no `bottomwear` part names every `topwear` part shaped like a skirt (issue #402) | leave that recipe out, or assemble the layer it is for, or declare the named part in `cloth.bottomwear.part` |
5897
6010
  | <a id="PROPOSE_CLOTH_PART"></a>`PROPOSE_CLOTH_PART` | with `--cloth` (issues #402, #437): `cloth.bottomwear.part` (a string) names no part, a part or cut piece whose source is not `topwear` (a `bottomwear` part takes the recipe by its tag already), or a target whose box ends above the hip + 0.25 face heights, the topwear rule's waist line; or `cloth.<tag>.parts` (or `part` as a list, issue #437) names a part not in `parts.json`, a part no link of the drafted tree crosses (`spanCrosses == 0`), or parts out of root-to-tip depth order along the chain | name the `topwear` part or its cut skirt piece that holds the skirt (or leave `part` out), or list only parts in `parts.json` that the drafted tree links cross in root-to-tip order |
5898
6011
  | <a id="PROPOSE_WRITE_CONFIG_FRESH"></a>`PROPOSE_WRITE_CONFIG_FRESH` | with `--cloth … --write-config` (issues #537, #356): the out path exists or collides with one of the four artifacts under `--out` — `proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png` — including directory-symlink and hardlink aliases; the config is written to a new file, never over the `--cloth` config or an earlier one (unlike `assemble --propose-plan` and `propose` without `--cloth`, which update an existing `--config` in place; §4, *Saving proposed config fields*) | name a file that does not exist yet, beside the `--cloth` config and separate from all four artifact paths and their aliases |
@@ -5907,7 +6020,7 @@ recorded transform. The record fields and sampling formula are specified in
5907
6020
  | <a id="KEYPOINTS_JOINT_KNOWN"></a><a id="KEYPOINTS_JOINT_STATE"></a><a id="KEYPOINTS_POSITION_STATED"></a><a id="KEYPOINTS_POSITION_INSIDE"></a>`KEYPOINTS_JOINT_KNOWN`, `KEYPOINTS_JOINT_STATE`, `KEYPOINTS_POSITION_STATED`, `KEYPOINTS_POSITION_INSIDE` | a joint name outside body-18, a state outside observed / occluded / missing, an observed joint with no `at` or a missing one with one, or a position outside the `width`x`height` image | that joint |
5908
6021
  | <a id="KEYPOINTS_PERSON_UNIQUE"></a><a id="KEYPOINTS_PERSON_CHOSEN"></a>`KEYPOINTS_PERSON_UNIQUE`, `KEYPOINTS_PERSON_CHOSEN` | two people share an id; or the file holds more than one person and no `--person` names one, or `--person` names none of them (the message lists the ids) | `--person <id>` |
5909
6022
  | <a id="KEYPOINTS_IMAGE_SIZE"></a>`KEYPOINTS_IMAGE_SIZE` | the file's `width`x`height` is not the `--source` painting's | a file measured on this painting |
5910
- | <a id="PARTS_PAINTING_PRESENT"></a>`PARTS_PAINTING_PRESENT` | The declared rig-resolution painting cannot be read. | Re-run assemble; restore the declared file and manifest together. |
6023
+ | <a id="PARTS_PAINTING_PRESENT"></a>`PARTS_PAINTING_PRESENT` | The declared rig-resolution painting (`painting_in_rig.png`, beside `parts.json`) cannot be read. `check --parts <build>` reads the complete assemble output folder beside `parts.json`, not `parts.json` copied alone. | Re-run assemble, or copy/keep the complete assemble folder (`parts.json`, `parts/*.png`, `painting_in_rig.png`, and any sidecars assemble wrote) together in `<build>`. |
5911
6024
  | <a id="PARTS_PAINTING_SHA256"></a>`PARTS_PAINTING_SHA256` | The declared rig-resolution painting does not match its SHA-256. | Re-run assemble; restore the declared file and manifest together. |
5912
6025
  | <a id="PARTS_PAINTING_PNG"></a>`PARTS_PAINTING_PNG` | The declared rig-resolution painting is not a decodable PNG. | Re-run assemble; restore the declared file and manifest together. |
5913
6026
  | <a id="PARTS_PAINTING_SIZE"></a>`PARTS_PAINTING_SIZE` | The declared rig-resolution painting dimensions differ from rig_size. | Re-run assemble; restore the declared file and manifest together. |
@@ -6024,6 +6137,9 @@ exits 0, and `mesh_draft.json` and the console name the reading and the amount.
6024
6137
  | <a id="REMESH_DELTA_JSON"></a>`REMESH_DELTA_JSON` | `--delta` is missing, does not parse, is not one object, its `schema` is not `rig-review-mesh-edit/1`, or `slot`, `skin`, `attachment` or `source` is not of its shape | export the mesh edit from rig-c/review as it writes it |
6025
6138
  | <a id="REMESH_DELTA_BASIS"></a>`REMESH_DELTA_BASIS` | the mesh edit's `basis` is not `"setup"`: it was drawn over a pose, and the producer binds setup positions, so it is refused rather than posed back (the basis found is quoted) | edit the mesh in setup space (rig-c/review #100) and export again |
6026
6139
  | <a id="REMESH_DELTA_OPS"></a>`REMESH_DELTA_OPS` | `ops` is not an array, or holds more than 300 ops — review's own cap per attachment | split the edit: apply the first part, then edit the revision |
6140
+ | <a id="REMESH_DELTA_ACT"></a>`REMESH_DELTA_ACT` | the act identity is malformed, a known key has a conflicting source hash or payload digest, its recorded edit is invalid, or its record fails to bind the current rig files | use the finalized act's identity and original binding together with the rig revision its record binds |
6141
+ | <a id="REMESH_DELTA_ACT_SUPERSEDED"></a>`REMESH_DELTA_ACT_SUPERSEDED` | the same act and edit were applied on an earlier, hash-bound revision. The refusal's object is the path to the record that binds the current revision | keep the current revision |
6142
+ | <a id="REMESH_DELTA_DIGEST"></a>`REMESH_DELTA_DIGEST` | the API refused the mesh edit's `payloadSha256` | pass the digest paired with the unchanged `edit` in the finalized act |
6027
6143
  | <a id="REMESH_DELTA_SOURCE"></a>`REMESH_DELTA_SOURCE` | the mesh edit was not drawn over this part's mesh: its `slot` or `attachment` is not `--part`, its skin is not `default`, a `source` count (`vertexCount`, `triangleCount`, `hullLength`) or `source.hash` is not the input's (both figures quoted; the hash is SHA-256 of the part's entry in rigc's `skeleton.model.json` over the input); or the input's bindings are not where its uvs and `parts.json` place the image, so no position can be bound | export the edit from the revision you pass as `--rig` |
6028
6144
  | <a id="REMESH_DELTA_OP"></a>`REMESH_DELTA_OP` | one op, named `ops[i]` and quoted, does not apply at its place in the replay: an unknown kind, a non-finite number, an id out of range or already removed, a `from` that is not the live position within 0.001 px, a position outside the part's image, a split of an edge the producer's triangulation does not hold or outside its triangles, a free `add` outside every triangle, a move that folds its ring, a removal that leaves fewer than 3 vertices, ends a constraint or leaves a ring no ear clips, an `edge` that duplicates a constraint, is a hull edge, runs through a vertex or crosses the hull or a constraint, or an `unedge` of any edge this edit did not constrain | read the op the line names; an edge the producer flipped is not one review can unedge — redraw it with `edge`, or move the vertices |
6029
6145
  | <a id="REMESH_DELTA_TOPOLOGY"></a>`REMESH_DELTA_TOPOLOGY` | the replayed mesh breaks an outline rule (`contourTopologyProblems`' code quoted: one loop, the hull first, every triangle wound one way, no self-intersection, no coincident vertices), or holds more interior edges that are not locally Delaunay than the input did; or the input's own triangles are not wound one way | read the quoted code; the ops that made it are the edit's last ones |
@@ -6082,7 +6198,43 @@ check measured from other bytes. The revision is always measured. `retune` reads
6082
6198
  record, so either command's serves the other over the same input. Without either flag
6083
6199
  nothing printed or written changes.
6084
6200
 
6085
- **`--delta <mesh-edit.json>`** (in place of `--mesh`, exactly one of the two; issue
6201
+ #### Apply a mesh edit act in Bun
6202
+
6203
+ Pass one edit from a finalized `rig-review/act@8` Request changes act to the typed,
6204
+ in-process API (issue #1159). Use the same rig, config and parts paths as for the
6205
+ CLI and choose a fresh revision directory for `out`.
6206
+
6207
+ ```ts
6208
+ import { applyMeshEditAct } from '@rig-c/parts/src/remesh-api.ts';
6209
+
6210
+ const revision = applyMeshEditAct({
6211
+ rig, config, parts, part, out,
6212
+ edit: entry.edit,
6213
+ actId: act.actId,
6214
+ actSourceHash: act.source.sourceHash,
6215
+ payloadSha256: entry.sha256,
6216
+ });
6217
+ ```
6218
+
6219
+ Here `entry` is the selected item in `act.value.meshEdits`. The caller supplies
6220
+ these values in memory. Before applying any op, Parts recomputes the canonical
6221
+ payload SHA-256 using recursively sorted object keys and checks `source.hash`
6222
+ against the target attachment in its gated model. It checks `source.frame` against
6223
+ the rig size and compares every recorded `source.positions` vertex, in attachment
6224
+ order, with its own position in setup crop pixels. A frame mismatch or a position
6225
+ more than 0.001 px away refuses the edit, including edits with only `add` or
6226
+ `edge` ops. See the [signed mesh-edit contract](https://github.com/rig-c/review/issues/952#issuecomment-7001413869).
6227
+
6228
+ New revisions record the act identity and payload digest in `remesh.json`.
6229
+ Passing the same edit again with the current revision as `rig` returns that
6230
+ revision without writing another when that revision's record binds the rig
6231
+ files and matches the act source hash and payload digest. If the rig has moved
6232
+ past the matching edit, `REMESH_DELTA_ACT_SUPERSEDED` names the record that
6233
+ binds the current revision. A conflicting binding, including one on an earlier
6234
+ revision, or an unbound record still refuses `REMESH_DELTA_ACT`. A new edit
6235
+ bound to a stale source is refused before any output write.
6236
+
6237
+ **Legacy `--delta <mesh-edit.json>`** (in place of `--mesh`, exactly one of the two; issue
6086
6238
  #526) reads rig-c/review's mesh edit, `rig-review-mesh-edit/1`: `slot`, `skin`,
6087
6239
  `attachment`, `source` (`vertexCount`, `triangleCount`, `hullLength`, `hash`), `units`,
6088
6240
  `basis` and up to 300 `ops`, each one of `move {v, from, to}`, `add {at, onEdge?}`,
@@ -6223,7 +6375,7 @@ outside the consumed inputs pending [#1177](https://github.com/rig-c/parts/issue
6223
6375
 
6224
6376
  | rule | means | change |
6225
6377
  | --- | --- | --- |
6226
- | <a id="CHECK_RIGC_PRESENT"></a>`CHECK_RIGC_PRESENT` | no `rigc` binary found (every place looked is listed) | `bun install` |
6378
+ | <a id="CHECK_RIGC_PRESENT"></a>`CHECK_RIGC_PRESENT` | no `rigc` binary found in ancestor `node_modules/.bin` directories or on `PATH`. This also applies when the in-process remesh API needs to build a new revision | `bun install` |
6227
6379
  | <a id="CHECK_RIGC_PACKAGE"></a>`CHECK_RIGC_PACKAGE` | `node_modules/.bin/rigc` is missing under the package root named: this lookup (the selftest's, issue #337) takes this package's own rigc and no other — no directory above, no `PATH` | `bun install` in that root |
6228
6380
  | <a id="CHECK_INPUT_PRESENT"></a><a id="CHECK_INPUT_IS_JSON"></a><a id="CHECK_PART_PNG_PRESENT"></a><a id="CHECK_PART_PNG_MATCHES_BOX"></a><a id="CHECK_PART_SLOT_PRESENT"></a><a id="CHECK_RIG_STAGE_PRESENT"></a><a id="CHECK_RIG_STAGE_IS_THE_CANVAS"></a><a id="CHECK_RIG_ROOT_BONE"></a><a id="CHECK_IDLE_PRESENT"></a>`CHECK_INPUT_PRESENT`, `CHECK_INPUT_IS_JSON`, `CHECK_PART_PNG_PRESENT`, `CHECK_PART_PNG_MATCHES_BOX`, `CHECK_PART_SLOT_PRESENT`, `CHECK_RIG_STAGE_PRESENT`, `CHECK_RIG_STAGE_IS_THE_CANVAS`, `CHECK_RIG_ROOT_BONE`, `CHECK_IDLE_PRESENT` | the rig directory is incomplete or disagrees with `parts.json` (`CHECK_PART_SLOT_PRESENT`: a part with no slot of its own name, which the judgement lines render it by; `CHECK_INPUT_PRESENT` on `--set` / `--all-sets`: no `parts.json`, no `alternates`, or the named set is not in `alternates`). `motion.json` is required even with no animation in it, because `rigc build` takes `--motion` (a spec with `"animations": {}` builds green); `CHECK_IDLE_PRESENT` is an `idle` that is there with no positive `duration` — an absent `idle` is measured around (§7). `CHECK_INPUT_PRESENT` on `…/parts.json`: `--parts` named a directory without `parts.json` — most often `parts/` itself — or, without `--parts`, the rig directory has none while the directory above it does (build's layout, `<out>/rig` under `<out>/parts.json`). The detail says it: "--parts names the directory holding parts.json and parts/, not parts/ itself (after build, that is build's --out, whose rig is <out>/rig); without --parts it is --rig", and names the parent when the parent holds `parts.json`. With neither (no `--parts`, and no `parts.json` beside `rig.json` or above it), the rig is measured without parts and nothing is refused (§7) | re-run rig (`build` does both); for `…/parts.json`, `--parts` — the directory above `parts/` |
6229
6381
  | <a id="CHECK_SOURCE_SIZE"></a>`CHECK_SOURCE_SIZE` | the painting `--source` names is not this rig's: no single `rig_scale` takes its width and height to the stage's (assemble makes the canvas `trunc(w × rig_scale)` x `trunc(h × rig_scale)`), or, with `parts.json` read, its `scale_rig_per_source` does not; or the stage is not whole pixels. Refused before anything is built | the painting the rig was made from — the stage's own size, or the painting `assemble` was given |
@@ -6265,6 +6417,7 @@ outside the consumed inputs pending [#1177](https://github.com/rig-c/parts/issue
6265
6417
  | <a id="CLOTH_SETTLES"></a>`CLOTH_SETTLES` | **a warning, never a refusal** (issue #501; the owner's ruling: cloth at rest while the character stands may be intended). Every physics chain, read by its tip on the idle `check` renders — `rigc render --animation idle --fps 12 --geometry`, physics on, rigc's default environment. A chain is a **physics leaf** — a bone a physics constraint names (`rig.json`'s `constraints` or `motion.json`'s `physics`) with no such bone under it — and the run of physics bones above it; its tip is the leaf's end (origin plus `length` along its world x axis), or its origin when the leaf has no length; its speed between frames is the tip's distance over their time, from the idle's `geometry.json`. A chain **settles** at the first frame from which every speed to the idle's last frame is under the floor, and each one that does — before the loop's length is out — prints `WARN chain "<root>" .. "<tip>" (N physics link(s)) settles at <t> s of the <d> s idle — its tip's end under 0.01694 rig px/s from there to the last frame (fastest on the idle <v> rig px/s)`. **The floor**, 0.01694 rig px/s, is derived, not chosen: half the slowest tip an idle key drives on the public examples (the repository's floor rule, half the weaker figure) — measured with this port's build of each (rig-c 2.60.0), over the 31 chains a keyed bone at or above the leaf drives (`demo` 12, `reference-sample` 1, `scarf` 11, `wind` 7) the slowest frame-to-frame tip speed is `scarf`'s `skirt_l2`, 0.03388 rig px/s; the ten no key drives — `wind`'s skirt, eight trees and the swing, hung from a `hip` its idle never keys, and `reference-sample`'s `hip_jiggle` — fall under it from 1.5 to 2.75 s on a 3.333 s idle (`hip_jiggle` at 0 s: it never moves) and end at 0.0025 rig px/s or less. `check.json`'s `CLOTH_SETTLES` holds `status` (`WARN`, `CLEAR`), `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings` and one row per chain (`tip`, `root`, `links`, `point` — `end` or `origin` — `settles_at`, null when it does not, `max_rig_px_per_s`, `min_rig_px_per_s`); it moves no exit status, no `check: PASS` and no bar count — the summary's warning clause names it, `; N warning(s) (CLOTH_SETTLES, not a bar)` (with `SEAM_OVER_MOTION` before it, and N their sum, where that read a pair). It reads the idle alone, one loop from rigc's physics reset at frame 0: a chain that settles later than the idle is long is not seen. **SKIP**, named: no physics constraint (then `check.json` has no key), or no idle — nothing measured, never a pass | if the chain should move while the character stands, one of the consumer's two levers: an environment at render (`rigc render --environment`, wind and gravity in time — rig-c's AUTHORING §8.4), or a consumer's animation that moves the bone the chain hangs from. The drafted idle keys no hip, by measurement: a hip turn at the idle's period fails a bar on all five public examples (issue #502, §3 *What moves them*). A `cloth` recipe's skirt hangs from `hip`, which the drafted idle never keys (§3, *Recipe: cloth and hair that answer the world*, *What moves them*, which has a worked schedule for `wind`). If it is intended, nothing |
6266
6418
  | <a id="figure_openings"></a>`figure_openings` | **a warning, never a refusal** (issue #933; see [Openings inside the figure on undeclared layer pairs](#openings-inside-the-figure-on-undeclared-layer-pairs-issue-933)). Reads transparent openings inside the pair's own posed hole-filled union (`alpha == 0` inside `fillHoles(a ∪ b)`, excluding cells already transparent at setup) across every undeclared setup-overlapping (`alpha >= 128`) layer pair in `rig.json` draw order in every animation `motion.json` holds at 12 fps (`scale = 1 / cell`). Prints `figure_openings: CLEAR — N undeclared setup-overlapping pair(s) in M animation(s) (<names>) at 12 fps (cell <cell> world units): 0 warning(s), never a bar` when clean, `figure_openings: WARN — …` followed by one `WARN opening "<a>\|<b>" above "<above>" (under "<under>") on K frame(s) [<frames>], worst frame <f> (t = <t>s) in "<animation>": found <found_cells> cell(s), <= <allowed_cells> cell(s) allowed in <w>x<h> world units at <cell> world units/cell — transparent opening inside the figure over motion on an undeclared layer pair (not a bar)` line per opening above the one-cell floor (`found_cells > allowed_cells`), or `figure_openings: SKIP — <reason>` when there is no `parts.json`, no animation, or no undeclared setup-overlapping pair. `check.json`'s `figure_openings` is written whenever the reader ran (`status` `"CLEAR"` or `"WARN"`), holding `status`, `fps`, `cell`, `pairs`, `animations`, `warnings` and `openings` (`pair`, `under`, `above`, `animation`, `frame`, `time`, `opens`, `cell`, `found_cells`, `allowed_cells`, `box`); it moves no exit status, no `check: PASS` and no bar count | if the opening is an unintended tear where a lower layer lacks opaque art under an opaque upper layer, use `assemble.extend_painting` (not `assemble.keep_under_occluders`, which only preserves existing `alpha >= 250` lower pixels under a translucent cover), or adjust mesh weights / motion keys; if it is a deliberate silhouette loop shifting in world space, nothing |
6267
6419
  | <a id="CHECK_FOLDS_READ"></a>`CHECK_FOLDS_READ` | the fold render's `frames.json` names no set for an animation, a `folds.json` is missing, not `rigc-folds/1`, another animation's or another rate's, or a folding mesh has no line rigc printed for it | a rigc problem; report it, with `rigc --version` |
6420
+ | <a id="DIAGNOSTIC_PATH_SEGMENT"></a>`DIAGNOSTIC_PATH_SEGMENT` | an original diagnostic name is empty, its [mapped segment](STABILITY.md#diagnostic-path-segments) including the fixed filename/rate suffix exceeds 255 characters, or sibling mapped folders alias under ASCII case folding; collision preflight names both originals, both folders and the shared case-folded folder before any scope writes | supply nonempty names whose encoded segments fit and whose sibling folders remain distinct under ASCII case folding; uppercase ASCII stays literal, and public names are never silently changed |
6268
6421
  | <a id="CHECK_SEAM_FRAME_SIZE"></a><a id="FRAMES_SIDECAR"></a><a id="CHECK_GEOMETRY_FILE"></a>`CHECK_SEAM_FRAME_SIZE`, `FRAMES_SIDECAR`, `CHECK_GEOMETRY_FILE` | rigc's render is not what its `frames.json` says, or its `geometry.json` is not a whole `rigc-geometry/1` export of the frames beside it (a frame count, a mesh whose vertex count differs from its rest entry; for the face half, another viewport than `frames.json`'s, other frame indices, the head bone or a feature's bone missing from a frame, a non-finite transform or time) | a rigc problem; report it |
6269
6422
  | <a id="CHECK_SEAM_DOMAIN"></a>`CHECK_SEAM_DOMAIN` | the source-relative common union U cannot prove finite, bounded, exactly representable scale1 coverage of every actual drawn setup state, or official pinned.outside is not empty; U is the enlarged render and A remains the fixed authored denominator | retain the named evidence and report the unavailable or outside-art boundary; do not shrink art, pad the measured domain or infer transparency from geometry alone |
6270
6423
  | <a id="CHECK_SEAM_SUPPORT"></a>`CHECK_SEAM_SUPPORT` | the affected-set effect mask does not match the fixed source grid, or the declared source cells leave no mean denominator | report the named support mismatch; no alternate denominator or successful zero is substituted |
@@ -6421,8 +6574,8 @@ and stay absent).
6421
6574
  | <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
6575
  | <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
6576
  | <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 |
6577
+ | <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 plate whose name is refused here does not also draw a cascaded `SCENE_ORDER_COMPLETE`) | a distinct name and its exact once-only order token |
6578
+ | <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. `opaque_backdrop` is checked for image size only, not for whether `at: [x, y]` covers the stage | use alpha or a backdrop meeting both canvas dimensions, which equal the stage; positioning the backdrop to cover the stage is the scene author's job |
6426
6579
  | <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 |
6427
6580
  | <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*) |
6428
6581
  | <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 |
@@ -6495,6 +6648,7 @@ and stay absent).
6495
6648
  | <a id="RIG_TURN_SURFACE_DEPTH_REQUIRED"></a>`RIG_TURN_SURFACE_DEPTH_REQUIRED` | a part with role `"surface"` in `config.turn.roles` or `config.turn.body.roles` carries no depth sheet in `parts.json` | run `assemble` with `config.depth` or provide `<part>_depth.png` in `parts.json` |
6496
6649
  | <a id="RIG_TURN_GRID_BUDGET"></a>`RIG_TURN_GRID_BUDGET` | a `"surface"` grid exceeds 2,400 triangles on one slot or 4,000 triangles across all `"surface"` slots | lower `config.turn.grid` / `config.turn.body.grid` `[cols, rows]` within the per-slot and total budgets |
6497
6650
  | <a id="RIG_TURN_HEAD_BONE"></a>`RIG_TURN_HEAD_BONE` | `buildRig` found no `"head"` (or body turn root) bone when emitting 2.5D turn carriers | declare `"head"` (or the body turn root bone) in `config.bones` |
6651
+ | <a id="RIG_TURN_BOUNDARY_DEPTH"></a>`RIG_TURN_BOUNDARY_DEPTH` | boundary names or sheets do not resolve; surfaces are not different, abutting without overlap in one group with common units; band is empty/outside/not boundary-reaching; declarations cycle; or grid support is missing | use exact existing parts, different abutting surfaces in one group with common near/zScale, a contained nonempty band reaching their boundary, acyclic declarations and the generated grid support |
6498
6652
  | <a id="RIG_TURN_SHARED_DEPTH_SCALE"></a>`RIG_TURN_SHARED_DEPTH_SCALE` | `"surface"` parts bound to one head or body turn declare different `near` polarities or `zScale` values | use one shared `near` and `zScale` across all `"surface"` parts in the turn group |
6499
6653
  | <a id="RIG_TURN_UNIT_DEPTH_REQUIRED"></a>`RIG_TURN_UNIT_DEPTH_REQUIRED` | a `"unit"` bone has neither a `unitDepths` entry nor a readable `"surface"` depth sheet | provide a `"surface"` depth sheet or an explicit `unitDepths.<part>` value |
6500
6654
  | <a id="RIG_TURN_UNIT_DEPTH_SUPPORT"></a>`RIG_TURN_UNIT_DEPTH_SUPPORT` | WARN only: an implicit unit depth sample is outside the source surface pixel-index bounds or its sampled art alpha is below 255 | author an explicit calibrated `unitDepths.<part>` value when this cross-part extrapolation is unintended; existing scalar sampling and refusal behavior are retained |
@@ -7200,12 +7354,12 @@ single-character path (§4, steps 0–9) on its own, already isolated input to a
7200
7354
  | `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 |
7201
7355
  | `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 |
7202
7356
  | `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 |
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 |
7357
+ | `characters[].build` | a character build directory (relative to the scene file) holding `<build>/parts.json`, `<build>/rig/` and a green `<build>/check/check.json`. When built with standalone `assemble` and `rig` instead of `build`, place the complete assemble folder at `<build>/` beside `<build>/rig/` and run the canonical pre-compose check `rig-parts check --rig <build>/rig --parts <build> --source <painting.png> --requirements <requirements.json> --out <build>/check` (see *Input layout and the pre-compose check* below) |
7204
7358
  | `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` |
7359
+ | `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. **Size is the only check on `opaque_backdrop`:** whether `at: [x, y]` positions the backdrop to cover the stage is the scene author's job (a canvas-sized backdrop at `[400, 0]` passes size while leaving part of the stage uncovered). rigc's A19 remains enabled |
7360
+ | `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`; a name refused by either does not also draw a cascaded `SCENE_ORDER_COMPLETE`). Emitted image files and packed atlas regions are named by 0-based declaration index (`scene-plate.<index>.png`, atlas region `scene-plate.<index>`, Spine attachment `path: "scene-plate.<index>"`), separately from character images (`SCENE_IMAGE_NAME_FREE` on any collision) — so **reordering `plates[]` renames the `scene-plate.<index>` atlas regions** even when `plates[].name` and `order` are unchanged |
7207
7361
  | `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 |
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 |
7362
+ | `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`. When `check/check.json` declares `spec: "rig-parts-check/1"`, `compose` reads its `bar_outcomes` for the bars whose outcome status is `FAIL` in the report's order (issue #1373); without that spec it keeps the legacy `barsNotMet` reading. 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
7363
  | `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) |
7210
7364
  | `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` |
7211
7365
 
@@ -7253,6 +7407,32 @@ or the second `shear` channel. Only the channel that drives that slider is
7253
7407
  compared to its bounds. Group names must be own declared keys; inherited object
7254
7408
  properties are refused with `CE_COMPILE_ANIMATION_GROUP_UNKNOWN`.
7255
7409
 
7410
+ **Turn-dial sign convention (issue #1358).** On an upright, unmirrored 2.5D
7411
+ turn rig, positive `rotate` keys on `<id>:yaw_dial` turn toward **screen left**
7412
+ (the viewer's left, decreasing world x); negative keys turn toward screen right.
7413
+ The body dial `<id>:<turn.body.slider>` (default `<id>:body_yaw_dial`) has the
7414
+ same sign. To turn toward leftward travel, key a positive yaw/body angle within
7415
+ that dial's declared range. These dials turn the depth layers about their pivot;
7416
+ they do not translate the character's scene root, and counter-moving parts can
7417
+ move in the opposite direction. Positive `<id>:pitch_dial` turns downward
7418
+ (decreasing world y, because rig coordinates are y up).
7419
+
7420
+ Measured example: the synthetic `writeTurnSceneBuild` fixture from
7421
+ `fixtures/scene.ts`, composed as character `a` on a 64×64 canvas at offset
7422
+ `[0, 0]`, was gated through Core 3.8.0 with the `rig-play` profile. Separate clips
7423
+ keyed each dial from `0°` at t=0 to `+4°` at t=1 and back to `0°` at t=2.
7424
+ Posing the packed model gave these carrier world-x readings (rig pixels,
7425
+ rounded to six decimals); the face and torso mesh vertices also moved left:
7426
+
7427
+ | keyed dial | observed carrier | world x at 0° | world x at +4° | displacement |
7428
+ | --- | --- | ---: | ---: | ---: |
7429
+ | `a:yaw_dial` | `a:faceshift` | −0.000001 | −1.392281 | −1.392279 |
7430
+ | `a:body_yaw_dial` | `a:bodyshift` | −0.000001 | −1.392280 | −1.392279 |
7431
+
7432
+ Each carrier returned to its exact starting coordinates at t=2, and the other
7433
+ dial's carrier stayed fixed. In the pitch clip, `a:faceshift` world y moved from
7434
+ 28.000000 to 26.606287 at `+4°`, establishing the downward sign independently.
7435
+
7256
7436
  For example, this declaration adds a plate take independently of character idle:
7257
7437
 
7258
7438
  ```json
@@ -7357,25 +7537,60 @@ What is composed:
7357
7537
  declared per-mesh ceilings and actual maxima of members with none. These
7358
7538
  counts come from emitted weighted triangles or declared grid dimensions;
7359
7539
  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.
7369
- - **Gated as `rig` gates its own:** `rigc build --profile rig-play --pack`, the
7540
+ - **Input layout and the pre-compose `check` (issue #1350).** `compose` expects each
7541
+ character's `build` directory to hold `<build>/parts.json` (with the complete
7542
+ assemble folder beside it), `<build>/rig/` (`rig.json`, `motion.json`, `images/`),
7543
+ and `<build>/check/check.json` in one folder. `rig-parts build --out <build>` writes
7544
+ that layout directly. When a consumer ran `assemble` and `rig` into separate folders
7545
+ (for example `assemble --out work`, which writes `work/rig/parts.json`,
7546
+ `work/rig/parts/*.png` and `work/rig/painting_in_rig.png`, and `rig --out <build>/rig`),
7547
+ `rig-parts rig --out <build>/rig` followed by `rigc build` does not create
7548
+ `<build>/check/check.json` and remains `SCENE_BUILD_PRESENT`, even if the rigc gate
7549
+ is green. Put the **complete assemble folder** at `<build>/` beside `<build>/rig/`
7550
+ — `parts.json`, `parts/<name>.png` (and any alternate/depth PNGs),
7551
+ `painting_in_rig.png`, and any sidecars assemble wrote (`figure_rig.png`,
7552
+ `cut_material_sources.json`, `part_support_domains.json`); copying `parts.json`
7553
+ alone fails `PARTS_PAINTING_PRESENT` on `painting_in_rig.png` and `PARTS_FILE_PRESENT`
7554
+ on `parts/*.png` — then run the one canonical pre-compose check command:
7555
+ `rig-parts check --rig <build>/rig --parts <build> --source <painting.png> --requirements <requirements.json> --out <build>/check`
7556
+ before composing. Standalone `check` does not read `config.requirements`;
7557
+ `--requirements <requirements.json>` and `--source <painting.png>` are its only
7558
+ doors. **Why `SKIP` is not "checked":** `check.json` sets `PASS: true` when every
7559
+ bar that actually measured passed, so a bar or requirement that printed `SKIP` was
7560
+ not measured, not passed. Without `--requirements`, `check.json` writes no
7561
+ `requirements` block at all — every declared requirement (`contact`, `follow`, `aim`,
7562
+ `range`, `stretch`, `seam`) and requirements-driven bar (`setup_painting`,
7563
+ `boundary_colour`, `behind_seams`, `seam_over_motion.required`, `cut_material`,
7564
+ `fixed_skeleton`, `may_fold`, `motion_seams`, `not_planted`, `not_swinging`,
7565
+ `rises`, `rests`) goes unmeasured, `BOUNDARY_COLOUR_STEP` prints
7566
+ `SKIP — not measured, not a pass: no requirements file declares boundary_colour; declare {"boundary_colour": {"max_step_excess": <0-255>}} in the --requirements file (config.requirements under build) to hold every part boundary of the setup and every idle frame to the rig's own pieces`,
7567
+ `BEHIND_PART_SEAMS` prints
7568
+ `SKIP — HOLE: no requirements.behind_seams declares an authored threshold T; not measured, never a pass`,
7569
+ `SEAM_OVER_MOTION` prints
7570
+ `SKIP — no neighbour pair is declared: parts.json holds no limb segment below a joint (config.limbs) and no --requirements seam names two parts`
7571
+ when `parts.json` has no limb segments, and with `--source` alone
7572
+ `SETUP_MATCHES_PAINTING` prints
7573
+ `SKIP — setup_painting is undeclared; setup-to-painting was not measured. To measure it, give --requirements <file> declaring setup_painting.rgb_tolerance and setup_painting.regions with name, box and authored max_pixels limits`.
7574
+ Without `--source`, `SETUP_POSE_VS_SOURCE` is omitted (and a requirements file
7575
+ declaring `setup_painting` is refused as `CHECK_SETUP_PAINTING_SOURCE`). Only a
7576
+ standalone rig with no manifest in its own or parent directory may omit `--parts`;
7577
+ its parts-dependent lines retain named SKIPs. The check must report both
7578
+ `PASS: true` and `gate_spine_html_green: true`; named accepted failing bars keep
7579
+ the existing preview-only semantics. No alternate gated-only admission is implied
7580
+ by the turn contract.
7581
+ - **Gated as `rig` gates its own, and where outputs are written:** `rigc build --profile rig-play --pack`, the
7370
7582
  compile and the packed pages on disk, in a scratch directory; `--out` receives
7371
- `rig/` (`rig.json`, `motion.json`, `images/`) and `scene.json` only when it is
7583
+ `rig/` (`rig.json`, `motion.json`, `images/` — the composed rig spec, not the
7584
+ compiled Spine skeleton) and `scene.json` only when it is
7372
7585
  green. `--page-size <px>` (a positive integer, refused as `PACK_PAGE_SIZE`
7373
7586
  otherwise; issue #1352) is forwarded to both packed builds and recorded as
7374
7587
  `pack_mode.page_size` in `scene.json` and `check/check.json` only when given;
7375
7588
  without it, rigc's default 2048 px page and padding 2 on each side bound any
7376
7589
  plate or region side to at most 2044 px before `CE_ATLAS_REGION_EXCEEDS_PAGE`
7377
7590
  (`COMPOSE_RIGC_GREEN`). Then `check` runs over `rig/` into `check/`, as on any rig it did not
7378
- build: without a `parts.json` the seam, `BREATH_VISIBLE`, `BLINK_NO_HOLE`,
7591
+ build: **the compiled Spine model and packed atlas (`skeleton.json`,
7592
+ `skeleton.model.json`, `skeleton.atlas`, `skeleton.png`) are written only under
7593
+ `<out>/check/build/`** (there is no `<out>/build/` at the root). Without a `parts.json` the seam, `BREATH_VISIBLE`, `BLINK_NO_HOLE`,
7379
7594
  `TIP_OVER_ROOT`, `STILL_REGIONS_DARK` and `RECOMPOSITE_HOLES` say SKIP and why,
7380
7595
  and the gate, the loop, `CHAIN_LAG` and `TEXTURE_STRETCH` measure.
7381
7596
  `--requirements` is forwarded, and its names are `<id>:<name>`. Every bar and
@@ -7384,10 +7599,13 @@ What is composed:
7384
7599
  (`CHAIN_LAG`, a `range` in degrees) does not move with it, while a requirement's
7385
7600
  px figures and its px bar are canvas px — a character composed at 0.5 shows half
7386
7601
  the px its own `build` measured.
7387
- - **`scene.json`** (`spine-parts-scene-report/1`): the scene file's path as given,
7602
+ - **`scene.json`** (`spine-parts-scene-report/1`, written at `<out>/scene.json` —
7603
+ **the same filename as a typical input `--scene scene.json` file**, so write `--out`
7604
+ to a separate output directory rather than the directory holding the input scene
7605
+ file): the scene file's path as given,
7388
7606
  the canvas, the rig's name (the ids joined by `+`), the pack flags, the plate (its
7389
7607
  image, provenance, note, bone, slot, size, `sha256` of the PNG's bytes as compose read them — issue #1183, additive —
7390
- and `judged_by: "nothing"`), per character
7608
+ and `judged_by: "nothing"`), `plates` when `scene.plates` is declared (each named plate's declaration, bone, slot, size, `sha256` and `judged_by: "nothing"`; the `[compose]` header line also names them in declaration order as `<N> named plate(s): <name>, ...`, and prints `no plate` only when neither `plate` nor `plates[]` is present), per character
7391
7609
  its build, offset, `scale` (only when it is not 1), `rig_size`, `rig_scale`, placed bounds (the union of its part
7392
7610
  boxes, canvas px), shift and what it moved (`shifted`: the first-level bones, the
7393
7611
  regions on `root`, the count of weights bound to `root`), its counts and `accepted`
@@ -8363,6 +8581,71 @@ including unselected frames, before reading the worst pose. Identical static
8363
8581
  ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
8364
8582
  never described as no declared range.
8365
8583
 
8584
+ ## Declared boundary depths (#1342)
8585
+
8586
+ Optional `turn.boundaryDepths` and `turn.body.boundaryDepths` are maps keyed by
8587
+ an exact target part name. Every entry requires `neighbour` and `band`, both
8588
+ exact existing names in `parts.json`. Target and neighbour must be different
8589
+ `surface` parts in that same turn group, with common `near` and `zScale`.
8590
+ The band can be the target itself or another part whose nonzero alpha support
8591
+ is contained in the target and reaches its shared boundary with the neighbour.
8592
+ Missing fields use `CONFIG_FIELD_PRESENT`; malformed fields use
8593
+ `CONFIG_FIELD_TYPE`; unresolved config names use `CONFIG_NAME_RESOLVES`.
8594
+ Rig-time support failures and reciprocal or longer cycles use
8595
+ [`RIG_TURN_BOUNDARY_DEPTH`](#RIG_TURN_BOUNDARY_DEPTH).
8596
+
8597
+ A contained rectangular band already has a producer: `assemble.patches`.
8598
+ For example, on a target occupying `[18,20,34,44]` and a neighbour ending at
8599
+ `y=20`, add this patch and its ordinary region binding to the existing config:
8600
+
8601
+ ```json
8602
+ {
8603
+ "assemble": {
8604
+ "patches": [{"name":"band_mask","box":[18,20,26,28],"alpha":"box","draw":"back"}]
8605
+ },
8606
+ "regions": {"band_mask":"chest"},
8607
+ "turn": {
8608
+ "body": {
8609
+ "boundaryDepths": {"garment":{"neighbour":"upper","band":"band_mask"}}
8610
+ }
8611
+ }
8612
+ }
8613
+ ```
8614
+
8615
+ Merge these fields into a complete config with the existing plan, regions or
8616
+ meshes, body roles and pivot. The patch reads the painting in rig pixels and
8617
+ makes a separate opaque part without subtracting any target pixels. Verify
8618
+ its support lies inside the actual target alpha, not merely its bounding box.
8619
+ It is an ordinary drawn region: use a back drawing order that the target
8620
+ covers. `trace_parts: true` rejects painting patches; this route does not
8621
+ claim traced source-part provenance. A separately authored layer added to
8622
+ `assemble.plan` can also supply an existing named support part. No band
8623
+ producer, inferred width or hidden drawing is introduced by this feature.
8624
+
8625
+ Support is the union of closed native pixel cells with alpha greater than
8626
+ zero. Target and neighbour must share cell edges and have no overlapping
8627
+ support; corner-only contact is not an abutting edge. Inside the band each
8628
+ sample projects onto the nearest shared edge and bilinearly samples the
8629
+ **original**, silhouette-extended neighbour sheet there. Distinct equidistant
8630
+ projection points contribute their arithmetic mean, once per point. The
8631
+ result stays floating point until the existing motion encoding; no corrected
8632
+ sheet is written. Outside the band the original target sample is used exactly:
8633
+ a hard switch with no blend. Transparent silhouette and image-padding samples
8634
+ inherit their nearest opaque target cell, as with the existing scalar extension.
8635
+ Sample locations are the existing generated grid
8636
+ or authored mesh vertices; mesh interpolation between them still applies.
8637
+ A partial boundary band only constrains the boundary it reaches.
8638
+
8639
+ The original group anchor stays unchanged. A neighbour that has its own
8640
+ boundary declaration still lends its original sheet, so declaration order
8641
+ cannot feed corrections back into another target. Head yaw/pitch and body yaw
8642
+ use the same scalar rule. Without declarations, existing rig, motion, art,
8643
+ sheet and compiled output bytes remain unchanged. This opt-in changes motion,
8644
+ not prepared maps, bindings, calibration or setup geometry. Inspect both turn
8645
+ extremes and the inner band edge: the hard switch can stretch or fold cells.
8646
+ Existing fold, stretch and seam checks keep their existing bars and scope;
8647
+ a depth-continuity reading alone does not establish composite visibility.
8648
+
8366
8649
  ## Per-layer depth sheets (#773)
8367
8650
 
8368
8651
  `depth_filename` is a legacy source hint. Only an explicit `config.depth` block
@@ -9099,6 +9382,64 @@ compare those to their own policy. The report does not choose which components
9099
9382
  a consumer accepts. The named refusals are `DIFF_COMPONENTS_INPUT`,
9100
9383
  `DIFF_COMPONENTS_BINDING` and `DIFF_COMPONENTS_REPORT` in the rule table.
9101
9384
 
9385
+ ### Draft-to-draft assemble comparison (issue #1369)
9386
+
9387
+ `rig-parts diff-drafts --left <dir> --right <dir> --out <json>` reads two
9388
+ assemble outputs and writes one JSON report, spec `rig-parts-draft-diff/1`, with
9389
+ fixed key order, no clock and no file paths. Each input directory may use either
9390
+ the standalone `assemble --out <dir>` layout (`<dir>/rig/parts.json`,
9391
+ `<dir>/rig/parts/<name>.png`, `<dir>/render/recomposite_rig.png`) or the
9392
+ `build --out <dir>` layout (`<dir>/parts.json`, `<dir>/parts/<name>.png`,
9393
+ `<dir>/recomposite_rig.png`); a directory holding neither layout (or both) is
9394
+ refused by name (`DIFF_DRAFTS_INPUT`). `--out` must not already exist and must
9395
+ not lie inside `--left` or `--right` (`DIFF_DRAFTS_OUT`). Different `rig_size`
9396
+ canvas dimensions between `--left` and `--right` are refused by name
9397
+ (`DIFF_DRAFTS_CANVAS`). The command records no threshold and makes no verdict;
9398
+ it exits 0 whenever the report is written.
9399
+
9400
+ The top-level fields of `rig-parts-draft-diff/1`, in key order:
9401
+
9402
+ | Field | Shape | Meaning |
9403
+ | --- | --- | --- |
9404
+ | `spec` | `"rig-parts-draft-diff/1"` | Schema identifier. |
9405
+ | `left` | `{ parts_sha256: string, part_count: number, composite_sha256: string }` | Lowercase 64-hex SHA-256 of the raw left `parts.json` bytes, `parts.length`, and lowercase 64-hex SHA-256 of the left `recomposite_rig.png` bytes. The command only records these hashes; a consumer that holds the two pictures can detect a report that does not belong to them by comparing hashes. |
9406
+ | `right` | `{ parts_sha256: string, part_count: number, composite_sha256: string }` | Lowercase 64-hex SHA-256 of the raw right `parts.json` bytes, `parts.length`, and lowercase 64-hex SHA-256 of the right `recomposite_rig.png` bytes. |
9407
+ | `canvas` | `{ width: number, height: number }` | Shared `rig_size` dimensions `[width, height]` in rig pixels. |
9408
+ | `order` | `"same" \| "changed"` | `"same"` when the part names in `parts.json` draw order are equal as lists; `"changed"` otherwise. |
9409
+ | `parts` | `DiffDraftPart[]` | One entry per part name in the union of left and right, sorted by `name` in UTF-16 code-unit order. |
9410
+ | `composite` | `{ changed_px: number, colour_px: number, alpha_px: number, bounds: { x: number, y: number, w: number, h: number } \| null }` | Pixel comparison in rig-pixel space between the two `recomposite_rig.png` rasters. The recomposite is drawn on opaque white, so an alpha change there shows as a colour change; alpha is read from the per-part rows. |
9411
+ | `summary` | `{ same: number, changed: number, added: number, removed: number }` | Counts of `parts` entries by `status`. |
9412
+
9413
+ Each `parts[i]` entry carries, in key order:
9414
+
9415
+ - `name`: the part name.
9416
+ - `status`: `"same"` when the part is present on both sides with equal PNG file
9417
+ `sha256` and equal `box`; `"added"` when only `right` has it; `"removed"` when
9418
+ only `left` has it; otherwise `"changed"`.
9419
+ - `left` (present on `"same"`, `"changed"` and `"removed"`):
9420
+ `{ sha256: string, box: { x: number, y: number, w: number, h: number }, index: number }`,
9421
+ where `sha256` is the lowercase 64-hex SHA-256 of the part PNG file bytes,
9422
+ `box` is the part's rig-pixel crop box from `parts.json`, and `index` is its
9423
+ 0-based draw-order index in `parts.json`.
9424
+ - `right` (present on `"same"`, `"changed"` and `"added"`):
9425
+ `{ sha256: string, box: { x: number, y: number, w: number, h: number }, index: number }`.
9426
+ - `pixels_equal` (present on `"changed"` only): `true` or `false`. `true`
9427
+ exactly when the two decoded part images have the same width and height and
9428
+ are equal in every RGBA channel at every position of the part's own crop,
9429
+ whatever their boxes. A re-encoded PNG with identical decoded RGBA pixels has
9430
+ `status: "changed"`, `pixels_equal: true` and `pixels.changed_px: 0`; a part
9431
+ that moved (`left.box` != `right.box`) with the same art has
9432
+ `status: "changed"`, `pixels_equal: true` and non-zero rig-space `pixels`
9433
+ counts; a repaint has `status: "changed"` and `pixels_equal: false`.
9434
+ - `pixels` (present on `"changed"` only):
9435
+ `{ changed_px: number, colour_px: number, alpha_px: number, bounds: { x: number, y: number, w: number, h: number } \| null }`,
9436
+ compared in rig-pixel space over the union of `left.box` and `right.box`, with
9437
+ any position outside a side's box counting as RGBA `0, 0, 0, 0`. `changed_px`
9438
+ counts rig pixels where any of R, G, B or A differs; `colour_px` where any of
9439
+ R, G or B differs; `alpha_px` where A differs; `bounds` is the bounding box
9440
+ `{ x, y, w, h }` of the changed rig positions, or `null` when
9441
+ `changed_px` is `0`.
9442
+
9102
9443
 
9103
9444
  ### Consumer check rows (issue #1089)
9104
9445
 
@@ -9173,8 +9514,8 @@ Internal `SeamSupport.drawings` never enters check JSON. Named requirement
9173
9514
  <!-- check-row-table:begin -->
9174
9515
  | Row family | Registered JSON paths | row_scope | row_kind | row_subjects (producer expression) | Producer |
9175
9516
  | --- | --- | --- | --- | --- | --- |
9176
- | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for e.slot; otherwise [] | [check.ts:3550](../src/check.ts#L3550) |
9177
- | `ANIMATIONS_DO_NOT_FOLD.folding` | `ANIMATIONS_DO_NOT_FOLD.folding` | part when the supplied mapping resolves a piece; otherwise rig | finding when entry === undefined; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:3512](../src/check.ts#L3512) |
9517
+ | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | `ANIMATIONS_DO_NOT_FOLD.declared_not_folding` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for e.slot; otherwise [] | [check.ts:3697](../src/check.ts#L3697) |
9518
+ | `ANIMATIONS_DO_NOT_FOLD.folding` | `ANIMATIONS_DO_NOT_FOLD.folding` | part when the supplied mapping resolves a piece; otherwise rig | finding when entry === undefined; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:3659](../src/check.ts#L3659) |
9178
9519
  | `ART_JOINT_DISTANCE.joints` | `ART_JOINT_DISTANCE.joints` | 'rig' | finding when status === 'FAIL'; otherwise evidence | [] | [artjoints.ts:86](../src/artjoints.ts#L86) |
9179
9520
  | `BEHIND_PART_SEAMS.contributors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.samples[].contributors`; `BEHIND_PART_SEAMS.turn.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].motion_opened.samples[].contributors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.samples[].contributors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:396](../src/behindseams.ts#L396) |
9180
9521
  | `BEHIND_PART_SEAMS.hits` | `BEHIND_PART_SEAMS.pairs[].motion_opened.frames`; `BEHIND_PART_SEAMS.pairs[].standing.frames`; `BEHIND_PART_SEAMS.pairs[].motion_opened.worst`; `BEHIND_PART_SEAMS.pairs[].standing.worst` | 'pair' | finding when r.px > allowance; otherwise evidence | parts | [behindseams.ts:456](../src/behindseams.ts#L456) |
@@ -9190,50 +9531,50 @@ Internal `SeamSupport.drawings` never enters check JSON. Named requirement
9190
9531
  | `BEHIND_PART_SEAMS.unread_corridors` | `BEHIND_PART_SEAMS.turn.pairs[].frames[].standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].setup.standing.unread_corridors`; `BEHIND_PART_SEAMS.pairs[].frames[].standing.unread_corridors` | 'pair' | evidence | [pair.a, pair.b] | [behindseams.ts:319](../src/behindseams.ts#L319) |
9191
9532
  | `BOUNDARY_COLOUR_STEP.over` | `BOUNDARY_COLOUR_STEP.over` | 'pair' | finding | r.parts | [boundarycolour.ts:221](../src/boundarycolour.ts#L221) |
9192
9533
  | `BOUNDARY_COLOUR_STEP.unmeasured` | `BOUNDARY_COLOUR_STEP.unmeasured` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for r.slot; otherwise [] | [boundarycolour.ts:222](../src/boundarycolour.ts#L222) |
9193
- | `CLOTH_SETTLES.rows` | `CLOTH_SETTLES.rows` | 'rig' | finding when speeds.length > 0 && s < speeds.length; otherwise evidence | [] | [check.ts:5996](../src/check.ts#L5996) |
9534
+ | `CLOTH_SETTLES.rows` | `CLOTH_SETTLES.rows` | 'rig' | finding when speeds.length > 0 && s < speeds.length; otherwise evidence | [] | [check.ts:6144](../src/check.ts#L6144) |
9194
9535
  | `CUT_JOINT_MATERIAL.rows` | `CUT_JOINT_MATERIAL.rows` | 'part' | finding when r.status === 'FAIL'; otherwise evidence | [r.part] | [cutmaterial.ts:280](../src/cutmaterial.ts#L280) |
9195
- | `FEET_STAY_LEVEL.feet` | `FEET_STAY_LEVEL.feet` | 'part' | finding when row.status === 'FAIL'; otherwise evidence | [row.part] | [check.ts:3751](../src/check.ts#L3751) |
9196
- | `FEET_STAY_LEVEL.feet[].worst.through` | `FEET_STAY_LEVEL.feet[].worst.through` | 'rig' | evidence | [] | [check.ts:3726](../src/check.ts#L3726) |
9197
- | `LIMB_ONE_BONE.parts` | `LIMB_ONE_BONE.parts` | 'part' | finding when fail; otherwise evidence | [p.name] | [check.ts:4043](../src/check.ts#L4043) |
9536
+ | `FEET_STAY_LEVEL.feet` | `FEET_STAY_LEVEL.feet` | 'part' | finding when row.status === 'FAIL'; otherwise evidence | [row.part] | [check.ts:3898](../src/check.ts#L3898) |
9537
+ | `FEET_STAY_LEVEL.feet[].worst.through` | `FEET_STAY_LEVEL.feet[].worst.through` | 'rig' | evidence | [] | [check.ts:3873](../src/check.ts#L3873) |
9538
+ | `LIMB_ONE_BONE.parts` | `LIMB_ONE_BONE.parts` | 'part' | finding when fail; otherwise evidence | [p.name] | [check.ts:4190](../src/check.ts#L4190) |
9198
9539
  | `PART_SUPPORT_REPORT.pairs` | `PART_SUPPORT_REPORT.pairs` | 'pair' | evidence; finding when length > 0; otherwise evidence | [F.name, B.name] | [coincide.ts:114](../src/coincide.ts#L114), [coincide.ts:130](../src/coincide.ts#L130) |
9199
9540
  | `PART_SUPPORT_REPORT.raw_pairs` | `PART_SUPPORT_REPORT.raw_pairs` | 'pair' | evidence | [F.name, B.name] | [coincide.ts:110](../src/coincide.ts#L110) |
9200
9541
  | `PART_SUPPORT_REPORT.unowned.regions` | `PART_SUPPORT_REPORT.unowned.regions` | 'rig' | finding | [] | [coincide.ts:145](../src/coincide.ts#L145) |
9201
- | `SEAM_OVER_MOTION.pairs` | `SEAM_OVER_MOTION.pairs` | 'pair' | evidence | [p.a, p.b] | [check.ts:5393](../src/check.ts#L5393) |
9202
- | `SEAM_OVER_MOTION.required.pairs` | `SEAM_OVER_MOTION.required.pairs` | 'pair' | finding when open > 0; otherwise evidence | [p.a, p.b] | [check.ts:4713](../src/check.ts#L4713) |
9203
- | `SEAM_OVER_MOTION.required.pairs[].open_frames` | `SEAM_OVER_MOTION.required.pairs[].open_frames` | 'pair' | evidence | [p.a, p.b] | [check.ts:4705](../src/check.ts#L4705) |
9204
- | `SEAM_OVER_MOTION.roots.unmeasured` | `SEAM_OVER_MOTION.roots.unmeasured` | 'part' | evidence | [root.part] | [check.ts:5370](../src/check.ts#L5370) |
9205
- | `SEAM_OVER_MOTION.rows` | `SEAM_OVER_MOTION.rows` | 'pair'; unique ? 'pair' : 'rig' | finding when motionSeamFinding(want.root !== undefined, p.status, p.banded, opens.length); otherwise evidence; finding when motionSeamFinding(rootNames.has(r.pair), r.status, r.banded, r.opens.length); otherwise evidence | [want.a, want.b]; unique ? [pair.a, pair.b] : [] | [check.ts:5327](../src/check.ts#L5327), [check.ts:5399](../src/check.ts#L5399) |
9206
- | `SEAM_OVER_MOTION.rows[].cells` | `SEAM_OVER_MOTION.rows[].cells` | 'pair' | evidence | [want.a, want.b] | [check.ts:5340](../src/check.ts#L5340) |
9207
- | `SEAM_OVER_MOTION.rows[].joint_contact.reasons` | `SEAM_OVER_MOTION.rows[].joint_contact.reasons` | 'pair' | evidence | [want.a, want.b] | [check.ts:5330](../src/check.ts#L5330) |
9542
+ | `SEAM_OVER_MOTION.pairs` | `SEAM_OVER_MOTION.pairs` | 'pair' | evidence | [p.a, p.b] | [check.ts:5541](../src/check.ts#L5541) |
9543
+ | `SEAM_OVER_MOTION.required.pairs` | `SEAM_OVER_MOTION.required.pairs` | 'pair' | finding when open > 0; otherwise evidence | [p.a, p.b] | [check.ts:4860](../src/check.ts#L4860) |
9544
+ | `SEAM_OVER_MOTION.required.pairs[].open_frames` | `SEAM_OVER_MOTION.required.pairs[].open_frames` | 'pair' | evidence | [p.a, p.b] | [check.ts:4852](../src/check.ts#L4852) |
9545
+ | `SEAM_OVER_MOTION.roots.unmeasured` | `SEAM_OVER_MOTION.roots.unmeasured` | 'part' | evidence | [root.part] | [check.ts:5518](../src/check.ts#L5518) |
9546
+ | `SEAM_OVER_MOTION.rows` | `SEAM_OVER_MOTION.rows` | 'pair'; unique ? 'pair' : 'rig' | finding when motionSeamFinding(want.root !== undefined, p.status, p.banded, opens.length); otherwise evidence; finding when motionSeamFinding(rootNames.has(r.pair), r.status, r.banded, r.opens.length); otherwise evidence | [want.a, want.b]; unique ? [pair.a, pair.b] : [] | [check.ts:5475](../src/check.ts#L5475), [check.ts:5547](../src/check.ts#L5547) |
9547
+ | `SEAM_OVER_MOTION.rows[].cells` | `SEAM_OVER_MOTION.rows[].cells` | 'pair' | evidence | [want.a, want.b] | [check.ts:5488](../src/check.ts#L5488) |
9548
+ | `SEAM_OVER_MOTION.rows[].joint_contact.reasons` | `SEAM_OVER_MOTION.rows[].joint_contact.reasons` | 'pair' | evidence | [want.a, want.b] | [check.ts:5478](../src/check.ts#L5478) |
9208
9549
  | `SEAM_OVER_MOTION.rows[].pose_at_worst.joints` | `SEAM_OVER_MOTION.rows[].pose_at_worst.joints` | 'rig' | evidence | [] | [motionseampose.ts:53](../src/motionseampose.ts#L53) |
9209
- | `SEAM_OVER_MOTION.worlds.*.rows` | `SEAM_OVER_MOTION.worlds.*.rows` | 'pair' | evidence | [want.a, want.b] | [check.ts:5324](../src/check.ts#L5324) |
9210
- | `SEAM_OVER_RANGE.joints` | `SEAM_OVER_RANGE.joints` | 'part' | evidence; finding when poses.some(p => p.status === 'FAIL'); otherwise evidence | [j.part] | [check.ts:4367](../src/check.ts#L4367), [check.ts:4413](../src/check.ts#L4413) |
9211
- | `SEAM_OVER_RANGE.joints[].poses` | `SEAM_OVER_RANGE.joints[].poses` | 'part' | finding when fail; otherwise evidence | [j.part] | [check.ts:4411](../src/check.ts#L4411) |
9550
+ | `SEAM_OVER_MOTION.worlds.*.rows` | `SEAM_OVER_MOTION.worlds.*.rows` | 'pair' | evidence | [want.a, want.b] | [check.ts:5472](../src/check.ts#L5472) |
9551
+ | `SEAM_OVER_RANGE.joints` | `SEAM_OVER_RANGE.joints` | 'part' | evidence; finding when poses.some(p => p.status === 'FAIL'); otherwise evidence | [j.part] | [check.ts:4514](../src/check.ts#L4514), [check.ts:4560](../src/check.ts#L4560) |
9552
+ | `SEAM_OVER_RANGE.joints[].poses` | `SEAM_OVER_RANGE.joints[].poses` | 'part' | finding when fail; otherwise evidence | [j.part] | [check.ts:4558](../src/check.ts#L4558) |
9212
9553
  | `SETUP_MATCHES_PAINTING.regions` | `SETUP_MATCHES_PAINTING.regions` | 'rig' | finding when status === 'FAIL'; otherwise evidence | [] | [setuppainting.ts:175](../src/setuppainting.ts#L175) |
9213
9554
  | `SETUP_MATCHES_PAINTING.regions[].slots` | `SETUP_MATCHES_PAINTING.regions[].slots` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for slot; otherwise [] | [setuppainting.ts:176](../src/setuppainting.ts#L176) |
9214
- | `STILL_REGIONS_DARK.*.crossing` | `STILL_REGIONS_DARK.*.crossing` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for sl.name; otherwise [] | [check.ts:9062](../src/check.ts#L9062) |
9215
- | `STILL_REGIONS_DARK.*.still_slots` | `STILL_REGIONS_DARK.*.still_slots` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when r.max > tolerance; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:9048](../src/check.ts#L9048), [check.ts:9053](../src/check.ts#L9053) |
9216
- | `STRESS_OFF_CHAIN.not_read` | `STRESS_OFF_CHAIN.not_read` | 'part' | evidence | [r.part] | [check.ts:3971](../src/check.ts#L3971) |
9217
- | `STRESS_OFF_CHAIN.per_part` | `STRESS_OFF_CHAIN.per_part` | 'part' | finding when poses.some(p => typeof p.reading === 'number' && p.reading > STRESS_RIGID); otherwise evidence | [r.part] | [check.ts:3959](../src/check.ts#L3959) |
9218
- | `STRESS_OFF_CHAIN.per_part[].off_chain` | `STRESS_OFF_CHAIN.per_part[].off_chain` | 'part' | evidence | [r.part] | [check.ts:3959](../src/check.ts#L3959) |
9219
- | `STRESS_OFF_CHAIN.per_part[].poses` | `STRESS_OFF_CHAIN.per_part[].poses` | 'part' | evidence; finding when shown > STRESS_RIGID; otherwise evidence | [r.part] | [check.ts:3927](../src/check.ts#L3927), [check.ts:3945](../src/check.ts#L3945) |
9220
- | `TEXTURE_STRETCH.per_mesh` | `TEXTURE_STRETCH.per_mesh` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when severity > TEXTURE_STRETCH_CEILING; otherwise evidence | resolved piece for m.slot; otherwise [] | [check.ts:9712](../src/check.ts#L9712), [check.ts:9722](../src/check.ts#L9722) |
9221
- | `TIP_OVER_ROOT.parts` | `TIP_OVER_ROOT.parts` | 'part' | evidence; finding when !ok && !(!rigid && hanging.onLink && Math.max(c.root, c.tip) < TIP_TRAVEL_FLOOR); otherwise evidence | [p.name] | [check.ts:8466](../src/check.ts#L8466), [check.ts:8471](../src/check.ts#L8471), [check.ts:8492](../src/check.ts#L8492), [check.ts:8503](../src/check.ts#L8503) |
9222
- | `WIND_BAND.pairs` | `WIND_BAND.pairs` | 'pair' | finding when !holdsAll; otherwise evidence | [p.a, p.b] | [check.ts:6500](../src/check.ts#L6500) |
9223
- | `WIND_BAND.pairs[].steps` | `WIND_BAND.pairs[].steps` | 'pair' | finding when !s.holds; otherwise evidence | [p.a, p.b] | [check.ts:6511](../src/check.ts#L6511) |
9224
- | `figure_openings.openings` | `figure_openings.openings` | 'pair' | finding | [ps.under, ps.above] | [check.ts:5817](../src/check.ts#L5817) |
9225
- | `loop_physics` | `loop_physics` | 'rig' | evidence | [] | [check.ts:7534](../src/check.ts#L7534) |
9226
- | `requirements.lines.* (bone)` | `requirements.lines.*` | 'rig' | finding when line.status === 'FAIL'; otherwise evidence | [] | [check.ts:7836](../src/check.ts#L7836) |
9227
- | `requirements.lines.* (seam)` | `requirements.lines.*` | 'pair' | finding when line.status === 'FAIL'; otherwise evidence | [r.part, r.neighbour] | [check.ts:7836](../src/check.ts#L7836) |
9228
- | `requirements.lines.* (stretch)` | `requirements.lines.*` | part when the supplied mapping resolves a piece; otherwise rig | finding when line.status === 'FAIL'; otherwise evidence | resolved piece for r.slot; otherwise [] | [check.ts:7836](../src/check.ts#L7836) |
9229
- | `seam_cells.frames` | `frames` | 'pair' | evidence | [p.a, p.b] | [check.ts:4702](../src/check.ts#L4702) |
9230
- | `seam_cells.frames[].cells` | `frames[].cells` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for cell.setupTop ?? ''; otherwise [] | [check.ts:4662](../src/check.ts#L4662) |
9231
- | `seam_pairs` | `seam_pairs`; `seam_scope.whole_pairs`; `sets.*.seam_pairs`; `sets.*.seam_scope.whole_pairs` | subjects.length === 0 ? 'rig' : subjects.length === 1 ? 'part' : 'pair' | evidence | subjects | [check.ts:2508](../src/check.ts#L2508) |
9232
- | `seam_scope.changes` | `seam_scope.changes`; `sets.*.seam_scope.changes` | 'rig' | evidence | [] | [check.ts:1986](../src/check.ts#L1986) |
9233
- | `seam_scope.domain.states` | `seam_scope.domain.states`; `sets.*.seam_scope.domain.states` | 'rig' | evidence | [] | [check.ts:2071](../src/check.ts#L2071) |
9234
- | `seam_scope.pairs` | `seam_scope.pairs`; `sets.*.seam_scope.pairs` | subjects.length === 0 ? 'rig' : subjects.length === 1 ? 'part' : 'pair' | evidence | subjects | [check.ts:7397](../src/check.ts#L7397) |
9235
- | `seam_scope.population.pairs` | `seam_scope.population.pairs`; `sets.*.seam_scope.population.pairs` | 'pair' | evidence | row.parts | [check.ts:2442](../src/check.ts#L2442) |
9236
- | `seam_scope.population.single_art` | `seam_scope.population.single_art`; `sets.*.seam_scope.population.single_art` | 'part' | evidence | [row.part] | [check.ts:2443](../src/check.ts#L2443) |
9555
+ | `STILL_REGIONS_DARK.*.crossing` | `STILL_REGIONS_DARK.*.crossing` | part when the supplied mapping resolves a piece; otherwise rig | finding | resolved piece for sl.name; otherwise [] | [check.ts:9286](../src/check.ts#L9286) |
9556
+ | `STILL_REGIONS_DARK.*.still_slots` | `STILL_REGIONS_DARK.*.still_slots` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when r.max > tolerance; otherwise evidence | resolved piece for slot; otherwise [] | [check.ts:9272](../src/check.ts#L9272), [check.ts:9277](../src/check.ts#L9277) |
9557
+ | `STRESS_OFF_CHAIN.not_read` | `STRESS_OFF_CHAIN.not_read` | 'part' | evidence | [r.part] | [check.ts:4118](../src/check.ts#L4118) |
9558
+ | `STRESS_OFF_CHAIN.per_part` | `STRESS_OFF_CHAIN.per_part` | 'part' | finding when poses.some(p => typeof p.reading === 'number' && p.reading > STRESS_RIGID); otherwise evidence | [r.part] | [check.ts:4106](../src/check.ts#L4106) |
9559
+ | `STRESS_OFF_CHAIN.per_part[].off_chain` | `STRESS_OFF_CHAIN.per_part[].off_chain` | 'part' | evidence | [r.part] | [check.ts:4106](../src/check.ts#L4106) |
9560
+ | `STRESS_OFF_CHAIN.per_part[].poses` | `STRESS_OFF_CHAIN.per_part[].poses` | 'part' | evidence; finding when shown > STRESS_RIGID; otherwise evidence | [r.part] | [check.ts:4074](../src/check.ts#L4074), [check.ts:4092](../src/check.ts#L4092) |
9561
+ | `TEXTURE_STRETCH.per_mesh` | `TEXTURE_STRETCH.per_mesh` | part when the supplied mapping resolves a piece; otherwise rig | evidence; finding when severity > TEXTURE_STRETCH_CEILING; otherwise evidence | resolved piece for m.slot; otherwise [] | [check.ts:9936](../src/check.ts#L9936), [check.ts:9946](../src/check.ts#L9946) |
9562
+ | `TIP_OVER_ROOT.parts` | `TIP_OVER_ROOT.parts` | 'part' | evidence; finding when !ok && !(!rigid && hanging.onLink && Math.max(c.root, c.tip) < TIP_TRAVEL_FLOOR); otherwise evidence | [p.name] | [check.ts:8661](../src/check.ts#L8661), [check.ts:8666](../src/check.ts#L8666), [check.ts:8687](../src/check.ts#L8687), [check.ts:8698](../src/check.ts#L8698) |
9563
+ | `WIND_BAND.pairs` | `WIND_BAND.pairs` | 'pair' | finding when !holdsAll; otherwise evidence | [p.a, p.b] | [check.ts:6648](../src/check.ts#L6648) |
9564
+ | `WIND_BAND.pairs[].steps` | `WIND_BAND.pairs[].steps` | 'pair' | finding when !s.holds; otherwise evidence | [p.a, p.b] | [check.ts:6659](../src/check.ts#L6659) |
9565
+ | `figure_openings.openings` | `figure_openings.openings` | 'pair' | finding | [ps.under, ps.above] | [check.ts:5965](../src/check.ts#L5965) |
9566
+ | `loop_physics` | `loop_physics` | 'rig' | evidence | [] | [check.ts:7702](../src/check.ts#L7702) |
9567
+ | `requirements.lines.* (bone)` | `requirements.lines.*` | 'rig' | finding when line.status === 'FAIL'; otherwise evidence | [] | [check.ts:8029](../src/check.ts#L8029) |
9568
+ | `requirements.lines.* (seam)` | `requirements.lines.*` | 'pair' | finding when line.status === 'FAIL'; otherwise evidence | [r.part, r.neighbour] | [check.ts:8029](../src/check.ts#L8029) |
9569
+ | `requirements.lines.* (stretch)` | `requirements.lines.*` | part when the supplied mapping resolves a piece; otherwise rig | finding when line.status === 'FAIL'; otherwise evidence | resolved piece for r.slot; otherwise [] | [check.ts:8029](../src/check.ts#L8029) |
9570
+ | `seam_cells.frames` | `frames` | 'pair' | evidence | [p.a, p.b] | [check.ts:4849](../src/check.ts#L4849) |
9571
+ | `seam_cells.frames[].cells` | `frames[].cells` | part when the supplied mapping resolves a piece; otherwise rig | evidence | resolved piece for cell.setupTop ?? ''; otherwise [] | [check.ts:4809](../src/check.ts#L4809) |
9572
+ | `seam_pairs` | `seam_pairs`; `seam_scope.whole_pairs`; `sets.*.seam_pairs`; `sets.*.seam_scope.whole_pairs` | subjects.length === 0 ? 'rig' : subjects.length === 1 ? 'part' : 'pair' | evidence | subjects | [check.ts:2548](../src/check.ts#L2548) |
9573
+ | `seam_scope.changes` | `seam_scope.changes`; `sets.*.seam_scope.changes` | 'rig' | evidence | [] | [check.ts:2026](../src/check.ts#L2026) |
9574
+ | `seam_scope.domain.states` | `seam_scope.domain.states`; `sets.*.seam_scope.domain.states` | 'rig' | evidence | [] | [check.ts:2111](../src/check.ts#L2111) |
9575
+ | `seam_scope.pairs` | `seam_scope.pairs`; `sets.*.seam_scope.pairs` | subjects.length === 0 ? 'rig' : subjects.length === 1 ? 'part' : 'pair' | evidence | subjects | [check.ts:7563](../src/check.ts#L7563) |
9576
+ | `seam_scope.population.pairs` | `seam_scope.population.pairs`; `sets.*.seam_scope.population.pairs` | 'pair' | evidence | row.parts | [check.ts:2482](../src/check.ts#L2482) |
9577
+ | `seam_scope.population.single_art` | `seam_scope.population.single_art`; `sets.*.seam_scope.population.single_art` | 'part' | evidence | [row.part] | [check.ts:2483](../src/check.ts#L2483) |
9237
9578
 
9238
9579
  | Open serialized type path | Reason for schema exclusion |
9239
9580
  | --- | --- |