rig-parts 1.83.1 → 1.83.2

package/README.md

@@ -184,26 +184,7 @@ pads a non-square upload before resizing; the centre-crop reported in
 `st_input_full.png` supplies the explicit white padding that rig-parts maps back
 to the original painting. This is a source inspection, not a new demo run.
 
-**The head run is needed on every route that was read.** See-through's model
-already separates the head in a second stage of its own: it crops the head the
-first stage found, runs the face tags on that crop at the same `resolution`, and
-pastes the result back **resized to the full image's scale**. So the face comes
-back at the full run's pixel density whichever route ran it, and the separate
-head run on `st_input_head.png` is what gives the eyes more pixels
-(read on 2026-09-28 at see-through `a25a549` and wrapper 0.5.0 `98d754b`):
-
-- *Hugging Face Space* — the same two-stage code, with `resolution` capped at
-  1280 (768 by default): the head run is still needed.
-- *ModelScope demo* — its code was not read, so what the head run adds on that
-  route has not been measured.
-- *Upstream CLI* — the `.psd` frame is the `resolution`-sided square the first
-  stage ran on (1280 by default), and the head stage is pasted into it at that
-  scale: the head run is still needed.
-- *ComfyUI wrapper* — `SeeThrough_GenerateLayers` runs both stages with no input
-  to change the second, at most `resolution` 2048, which on the examples' 2432 px
-  square is 1.19 source px per layer px against 0.77 and 0.47 for their head
-  crops; at the 1024 the examples ran, the full run's right eye white is 22×13 px
-  and the head run's 60×38: the head run is still needed.
+The [head-run source reading](docs/AUTHORING.md#see-through-head-run-source-reading) explains why a separate head crop is needed.
 
 **See-through is required; ComfyUI is not.** The wrapper is one route among
 four, and `rig-parts comfy` is only a convenience for that route: every
@@ -329,86 +310,29 @@ agent skill.
 
 ## Commands
 
+Command details and config saving are in the [command reference](docs/AUTHORING.md#command-reference) and [stable interface](docs/STABILITY.md#commands-and-flags).
+
 | command | does |
 | --- | --- |
-| `inputs --source <png> --config <json> --out <dir>` | the two images See-through is fed: the painting on a white square, and the head box's crop once the config has one |
-| `comfy paint --config --out [--host]` | optional: generate the painting on a ComfyUI box from the config's `generation` block |
-| `comfy seethrough --image --out [--host]` | optional: run the ComfyUI See-through wrapper on one image and write the form `layers` reads |
-| `layers <dir \| layers.json \| file.psd>` | keep the existing columns (`opaque_px` still means alpha >8) and append source-alpha boxes `drawn(a>8)` / `opaque(a>=250)` with exclusive right/bottom; name absent boxes, report the existing body-group union height at **CORE_ALPHA (>=250)** in **input-canvas px**, and show its >8 union separately; no anatomical height, ownership/erosion or painting registration is inferred ([units and rig-scale guidance](docs/AUTHORING.md#4-the-command-order)) |
-| `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
-| `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) |
-| `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 list the uncovered holes |
-| `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 |
-| `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 |
-| `propose … --keypoints <file> [--person <id>]` | read a posed figure's joints from one explicit file (space, image size, people, each joint observed, occluded or missing, its source): a joint with a position places the neck, hip, chest or a sleeve chain as given, a note says how every joint was used or which rule stood in, and LINT reads the torso and sleeves along the joints instead of by screen y ([AUTHORING §3](docs/AUTHORING.md)) |
-| `propose … --full <run> --head <run> --write-config <config>` | [draft an independent neck](docs/AUTHORING.md#a-neck-that-moves-on-its-own) in an existing sampled body turn and reassemble its full-run source under `<out>/rig` |
-| `propose … --grid-rule figure\|part` | how each drafted lattice's spacing is chosen: `figure` (the default) one spacing for the figure, round(H / 37) rig px, a part already coarser keeping its own, with a note on its calibration and cost; `part` the reference's rule, a tenth of the part's short side (the oracle examples are proposed under it) |
-| `propose --parts --source --out --from-config <config> [--keypoints <file> [--person <id>]]` | draw and LINT the config's current bones (by the joints too, given `--keypoints`); proposes nothing, so takes only these flags (not `--full`, `--head`, `--cloth`, `--write-config`, `--wrist-snap`, `--grid-rule`, `--only-missing` or `--compare`) |
-| `compare --left <file> --right <file> [--map <bonemap.json>]` | compare two skeletons — a config, a proposal or a `rig.json` — bone by bone: origin, parent, tip, length and direction per pair, the bones neither side pairs, the required ones missing, and each side's roles read off the spec; no frame is guessed, and nothing pairs by resemblance (`propose --compare` reads origins only) |
-| `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json`, written only after rig-c's gate is green; each mesh is in the mode its config entry names — `grid` (the lattice, what `propose` writes), `contour` (the traced outline with declared interior points) or `auto` (the contour mesh at alpha 1 and above, reduced and locally refined by rig-c's `reduceMesh` under the author's declared bounds, written only when its motion against the unreduced source on the idle passes the author's `motion` bounds through rig-c's `compareMeshesInMotion`; [AUTHORING §3](docs/AUTHORING.md)); every chain link is turned along its chain and carries its `length`, so a physics constraint added later has a lever, with every offset under it in the turned frame so nothing moves; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared; the config's `constraints` go to rigc as written, and a two-bone ik over keyed links needs `--idle-keys direct` (on `rig` or `build`) |
-| `check --rig --out [--parts] [--source] [--requirements]` | build packed, gated under `rig-play`, render the idle, measure seam, loop and the six judgement lines (mesh texture stretch among them, from the idle's `render --geometry`), and report the recomposite's holes from `parts.json`; on a rig spec with no `parts.json` or no `idle` (a merged rig, issue #77) the gate still runs and every line that needs the missing input says SKIP by name; `--source <painting.png>` adds `SETUP_POSE_VS_SOURCE`, the setup pose against the painting by assemble's recomposite figures; `--requirements <scene.json>` measures what a scene declares of the motion — a contact, a follow fraction, an aim, a joint range, a mesh's stretch, the seam between two parts over the motion — each against the author's own bar, from rig-c's posed frames, one line each, PASS, FAIL or NOT MEASURABLE (AUTHORING §7, *Declared requirements*) |
-| `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
-| `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
-| `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](docs/AUTHORING.md), *Composing several characters*) |
-| `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 |
-| `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 |
-| `painting --keypoints <json> [--person <id>] <png>` | before See-through, read the painting against its declared joints and refuse named background, joint or limb-gap problems; write nothing |
-| `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 |
-| `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 |
-| `guide <RULE \| §<n> \| §<n>.<m> \| §<n>.<m>.<k>>` | print the one row of [docs/AUTHORING.md](docs/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 |
-
-`rig-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
-reason is a FAIL line), 2 a usage error or a command this version does not implement.
-Every FAIL line ends with `(see rig-parts guide <RULE>)`, the command that prints the
-guide's row for that rule, and each row is anchored on the web as
-`docs/AUTHORING.md#<RULE>`.
-
-What 1.0.0 holds stable — these commands and their flags, the config
-fields, the files a build writes and their spec ids, the environment, and what this
-package relies on in rig-c — and what is not, is [docs/STABILITY.md](docs/STABILITY.md).
-Coming from 0.16.0: [docs/MIGRATION.md](docs/MIGRATION.md).
-
-`--write-config <config.json>` saves the proposals above into an existing
-regular config file: `seethrough.head_box`, `assemble.plan` plus
-`assemble.extend_below_crop`, or the present config sections of an ordinary
-proposal. The [neck draft](docs/AUTHORING.md#a-neck-that-moves-on-its-own)
-(`propose … --full --head --write-config`) is another writer: for an existing
-`turn.body` config with one neck plan row, it selects the full-run neck, drafts a
-rigid unit and its depth, and reassembles parts under `<out>/rig`.
-For `assemble --propose-plan`, the destination must name `--config`
-itself; a different destination is a usage error. Other fields and absent optional
-sections remain; proposal notes are not copied. Changed whole values are spliced
-into the original text, preserving untouched bytes. Stage loaders validate the candidate, including `proposed_rig_scale`,
-before atomic replacement. Relative paths keep the config's directory as their
-base. Changes are listed on stderr; the head-box and plan JSON on stdout remain.
-An identical update leaves bytes and mtime untouched. Without the flag no config
-is changed. This commits the config file, not a transaction across the proposal
-artifacts.
-
-With `--cloth <config.json>`, the flag requires a **new** destination and applies
-the recipe's entry ownership: recipe-owned entries are spliced into the cloth
-config while hand entries and unrelated text survive; conflicts are refused.
-The destination must also be separate from all four artifacts under `--out`:
-`proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png`.
-Aliases, including directory symlinks and hardlinks, count as collisions too.
-Fresh output is published without overwriting a file created while the command
-runs. Its already-checked splice text may be a partial config; it is not passed
-through the full-config loader. If removing the staged temporary fails after
-publication, the error may accompany an already-published complete config.
-`--from <previous.json>` retains the previous-recipe comparison.
-With `--only-missing` (issue #671), an ordinary proposal's `--write-config` adds
-only `meshes.<part>` or `regions.<part>` for each proposed part the config
-attaches by neither, entry by entry, and, for a part the 1.37.0 arm split makes
-(`full:drape-<s>`, `full:hand-<s>`) that `assemble.plan` does not name, its plan
-row beside the arm's row; every existing row and entry and every other byte
-stays as read, and nothing else of the proposal is written. The candidate passes
-the full loader first, so an entry on a bone the config does not declare is
-refused naming the part and the bone; nothing missing leaves bytes and mtime
-untouched. It is the upgrade path for a config proposed before the 1.37.0 arm
-split ([MIGRATION](docs/MIGRATION.md#after-1370-merged-arm-layers-are-split-issue-490)),
-and a usage error with `--head-box`, `--cloth` or `--from-config`.
-`--from-config` proposes nothing and cannot be combined with `--write-config`.
-[AUTHORING §4](docs/AUTHORING.md#4-the-command-order) describes all four modes.
+| `inputs` | [Prepare the two See-through input images](docs/AUTHORING.md#command-reference) |
+| `comfy` | [Drive an optional ComfyUI painting or layer job](docs/AUTHORING.md#command-reference) |
+| `layers` | [Inspect wrapper layers or a PSD](docs/AUTHORING.md#command-reference) |
+| `sheet` | [Make a contact sheet](docs/AUTHORING.md#command-reference) |
+| `assemble` | [Merge layers into measured parts](docs/AUTHORING.md#command-reference) |
+| `propose` | [Draft or inspect a character config](docs/AUTHORING.md#command-reference) |
+| `compare` | [Compare two skeletons by name](docs/AUTHORING.md#command-reference) |
+| `rig` | [Author gated rig and motion specs](docs/AUTHORING.md#command-reference) |
+| `check` | [Build, render and measure a rig](docs/AUTHORING.md#command-reference) |
+| `loop` | [Encode rendered frames as GIF or APNG](docs/AUTHORING.md#command-reference) |
+| `build` | [Assemble, rig and check in one process](docs/AUTHORING.md#command-reference) |
+| `compose` | [Combine character builds into a scene](docs/AUTHORING.md#command-reference) |
+| `mesh-draft` | [Draft and compare contour meshes](docs/AUTHORING.md#command-reference) |
+| `mesh-stats` | [Count mesh vertices and triangles](docs/AUTHORING.md#command-reference) |
+| `painting` | [Check a painting against declared joints](docs/AUTHORING.md#command-reference) |
+| `remesh` | [Revise one mesh in a gated rig](docs/AUTHORING.md#command-reference) |
+| `retune` | [Revise constraints and idle in a gated rig](docs/AUTHORING.md#command-reference) |
+| `guide` | [Read the installed authoring reference](docs/AUTHORING.md#command-reference) |
+
 
 ## What it does not do
 
@@ -539,15 +463,7 @@ selftest and CI do; `check.json`'s `rigc_entry` records which one gated a build.
 
 ## Licence posture
 
-rig-parts is MIT. It writes rig-c's input, and rig-c writes Spine skeleton data. If a
-product integrates a Spine Runtime to play that data, the integration is under Esoteric
-Software's Spine Runtimes License: permitted under Section 2 of the Spine Editor License
-Agreement, or otherwise on the condition that each user of the product obtains their own
-Spine Editor license. What those terms turn on is the integration, as rig-c's
-[NOTICE.md](https://github.com/rig-c/core/blob/main/NOTICE.md) states it, not the data as
-a file. Neither package installs `spine-core`; this repository uses it in development,
-for the round trip in its selftest and CI. [NOTICE.md](NOTICE.md) records that chain and every other
-third-party term this package touches, See-through's included.
+MIT; see [NOTICE.md](NOTICE.md) for third-party terms and the Spine runtime licence posture.
 
 ## Development
 
@@ -579,43 +495,14 @@ records the generated default-cap case and its preservation controls.
 practice, [RELEASING.md](RELEASING.md) the cut, [docs/STABILITY.md](docs/STABILITY.md)
 the interface it holds.
 
-## Licence
-
-MIT — see [LICENSE](LICENSE). Third-party terms: [NOTICE.md](NOTICE.md).
+## Depth-driven rigging
 
+See the [depth-driven rigging reference](docs/AUTHORING.md#depth-driven-rigging) for sampled head and body turns and unit-depth precedence.
 
 ### Per-layer depth input
 
-`config.depth` explicitly enables scalar input. Without it, `depth_filename`
-is a legacy hint: no depth-file I/O, validation, fetch, reference or output is
-activated, even when files or in-memory sheets exist. Active See-through sheets
-are read as opaque grayscale source data. Declare positive finite `depth.zScale`;
-eight bits do not supply world units. See-through far-high encoding is explicitly `near: "black"`. User
-per-layer/run-canvas fallbacks declare image, near and zScale themselves; a
-missing declared file is an error, not a fallback. The ordering median remains
-separate, and its agreement reading cannot certify an image's polarity.
-
-Assembly emits registered part sheets and references; rig emits PAD4 sheets and
-`depth_sheets.json`. Since 1.68.0 (#777), [config.turn.roles](docs/AUTHORING.md#3-configjson-field-by-field)
-uses depth sheets for 2.5D head turns with grid or authored weighted surfaces and `yaw_dial`/`pitch_dial`
-controls; see [`CONFIG_TURN_ROLE_UNKNOWN`](docs/AUTHORING.md#CONFIG_TURN_ROLE_UNKNOWN)
-and [`CONFIG_TURN_SURFACE_REQUIRED`](docs/AUTHORING.md#CONFIG_TURN_SURFACE_REQUIRED).
-`turn.body.roles` adds independent body yaw. A weighted mesh declared as
-`"surface"` in either group and blending head and torso bones receives both
-fields in proportion to its skin weights. Inside the existing setup alpha
-overlap with a single-group neighbour, a blended attachment's vertex takes
-that neighbour's existing emitted triangle field at its setup position (#804), without changing skin weights,
-setup or idle. A `motion.blink.still` unit neighbour supplies both emitted
-pieces, each on its own bone and resolved depth; transparent padding does not
-let either piece lend its field to the other's art (#807). Missing emitted
-split support is refused by name. Conflicting neighbour groups are refused by name. Each sibling island takes only its
-own group; parts without a blended attachment keep their existing role behavior
-and output bytes. Unlisted meshes do not consume turn depth sheets. See the
-[blended surface contract](docs/AUTHORING.md#per-layer-depth-sheets-773).
-This copies the field at vertices; different triangle partitions can still
-differ between vertices. The [corrected #804 acceptance](https://github.com/rig-c/parts/issues/804#issuecomment-6478778123)
-checks vertex correspondence and reports those residuals per fixture; the
-contract records the measured grid residual and preserves its seam readings.
-No-image builds keep the legacy output bytes. `comfy seethrough --config <file> --depth-run <full|head>`
-uses the same opt-in; its default captures art only. Standalone authored part
-references remain active declarations. See [the input contract and refusals](docs/AUTHORING.md#per-layer-depth-sheets-773).
+See the [per-layer depth input contract](docs/AUTHORING.md#per-layer-depth-input) for opt-in sheets, calibration and their consumers.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Third-party terms: [NOTICE.md](NOTICE.md).

package/docs/AUTHORING.md

@@ -70,6 +70,29 @@ model stack. The wrapper README and the adapter graph use different node names
 and depth-model identifiers; [the adapter notes](../README.md#the-optional-comfyui-adapter)
 name the graph actually sent.
 
+### See-through head-run source reading
+
+**The head run is needed on every route that was read.** See-through's model
+already separates the head in a second stage of its own: it crops the head the
+first stage found, runs the face tags on that crop at the same `resolution`, and
+pastes the result back **resized to the full image's scale**. So the face comes
+back at the full run's pixel density whichever route ran it, and the separate
+head run on `st_input_head.png` is what gives the eyes more pixels
+(read on 2026-09-28 at see-through `a25a549` and wrapper 0.5.0 `98d754b`):
+
+- *Hugging Face Space* — the same two-stage code, with `resolution` capped at
+  1280 (768 by default): the head run is still needed.
+- *ModelScope demo* — its code was not read, so what the head run adds on that
+  route has not been measured.
+- *Upstream CLI* — the `.psd` frame is the `resolution`-sided square the first
+  stage ran on (1280 by default), and the head stage is pasted into it at that
+  scale: the head run is still needed.
+- *ComfyUI wrapper* — `SeeThrough_GenerateLayers` runs both stages with no input
+  to change the second, at most `resolution` 2048, which on the examples' 2432 px
+  square is 1.19 source px per layer px against 0.77 and 0.47 for their head
+  crops; at the 1024 the examples ran, the full run's right eye white is 22×13 px
+  and the head run's 60×38: the head run is still needed.
+
 ## 2. The folder
 
 Nothing in rig-parts requires a layout; every command takes paths. The one the
@@ -3608,6 +3631,90 @@ artifacts under `--out`: `proposal.json`, `basis.json`, `render/landmarks.png` a
 existing hardlinks are refused before artifact output; the ordinary mode names
 `CONFIG_WRITE_TARGET`, and the cloth mode `PROPOSE_WRITE_CONFIG_FRESH`.
 
+### Command reference
+
+| command | does |
+| --- | --- |
+| `inputs --source <png> --config <json> --out <dir>` | the two images See-through is fed: the painting on a white square, and the head box's crop once the config has one |
+| `comfy paint --config --out [--host]` | optional: generate the painting on a ComfyUI box from the config's `generation` block |
+| `comfy seethrough --image --out [--host]` | optional: run the ComfyUI See-through wrapper on one image and write the form `layers` reads |
+| `layers <dir \| layers.json \| file.psd>` | keep the existing columns (`opaque_px` still means alpha >8) and append source-alpha boxes `drawn(a>8)` / `opaque(a>=250)` with exclusive right/bottom; name absent boxes, report the existing body-group union height at **CORE_ALPHA (>=250)** in **input-canvas px**, and show its >8 union separately; no anatomical height, ownership/erosion or painting registration is inferred ([units and rig-scale guidance](AUTHORING.md#4-the-command-order)) |
+| `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
+| `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) |
+| `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 list the uncovered holes |
+| `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 |
+| `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 |
+| `propose … --keypoints <file> [--person <id>]` | read a posed figure's joints from one explicit file (space, image size, people, each joint observed, occluded or missing, its source): a joint with a position places the neck, hip, chest or a sleeve chain as given, a note says how every joint was used or which rule stood in, and LINT reads the torso and sleeves along the joints instead of by screen y ([AUTHORING §3](AUTHORING.md)) |
+| `propose … --full <run> --head <run> --write-config <config>` | [draft an independent neck](AUTHORING.md#a-neck-that-moves-on-its-own) in an existing sampled body turn and reassemble its full-run source under `<out>/rig` |
+| `propose … --grid-rule figure\|part` | how each drafted lattice's spacing is chosen: `figure` (the default) one spacing for the figure, round(H / 37) rig px, a part already coarser keeping its own, with a note on its calibration and cost; `part` the reference's rule, a tenth of the part's short side (the oracle examples are proposed under it) |
+| `propose --parts --source --out --from-config <config> [--keypoints <file> [--person <id>]]` | draw and LINT the config's current bones (by the joints too, given `--keypoints`); proposes nothing, so takes only these flags (not `--full`, `--head`, `--cloth`, `--write-config`, `--wrist-snap`, `--grid-rule`, `--only-missing` or `--compare`) |
+| `compare --left <file> --right <file> [--map <bonemap.json>]` | compare two skeletons — a config, a proposal or a `rig.json` — bone by bone: origin, parent, tip, length and direction per pair, the bones neither side pairs, the required ones missing, and each side's roles read off the spec; no frame is guessed, and nothing pairs by resemblance (`propose --compare` reads origins only) |
+| `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json`, written only after rig-c's gate is green; each mesh is in the mode its config entry names — `grid` (the lattice, what `propose` writes), `contour` (the traced outline with declared interior points) or `auto` (the contour mesh at alpha 1 and above, reduced and locally refined by rig-c's `reduceMesh` under the author's declared bounds, written only when its motion against the unreduced source on the idle passes the author's `motion` bounds through rig-c's `compareMeshesInMotion`; [AUTHORING §3](AUTHORING.md)); every chain link is turned along its chain and carries its `length`, so a physics constraint added later has a lever, with every offset under it in the turned frame so nothing moves; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared; the config's `constraints` go to rigc as written, and a two-bone ik over keyed links needs `--idle-keys direct` (on `rig` or `build`) |
+| `check --rig --out [--parts] [--source] [--requirements]` | build packed, gated under `rig-play`, render the idle, measure seam, loop and the six judgement lines (mesh texture stretch among them, from the idle's `render --geometry`), and report the recomposite's holes from `parts.json`; on a rig spec with no `parts.json` or no `idle` (a merged rig, issue #77) the gate still runs and every line that needs the missing input says SKIP by name; `--source <painting.png>` adds `SETUP_POSE_VS_SOURCE`, the setup pose against the painting by assemble's recomposite figures; `--requirements <scene.json>` measures what a scene declares of the motion — a contact, a follow fraction, an aim, a joint range, a mesh's stretch, the seam between two parts over the motion — each against the author's own bar, from rig-c's posed frames, one line each, PASS, FAIL or NOT MEASURABLE (AUTHORING §7, *Declared requirements*) |
+| `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
+| `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
+| `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](AUTHORING.md), *Composing several characters*) |
+| `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 |
+| `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 |
+| `painting --keypoints <json> [--person <id>] <png>` | before See-through, read the painting against its declared joints and refuse named background, joint or limb-gap problems; write nothing |
+| `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 |
+| `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 |
+| `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 |
+
+`rig-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
+reason is a FAIL line), 2 a usage error or a command this version does not implement.
+Every FAIL line ends with `(see rig-parts guide <RULE>)`, the command that prints the
+guide's row for that rule, and each row is anchored on the web as
+`docs/AUTHORING.md#<RULE>`.
+
+What 1.0.0 holds stable — these commands and their flags, the config
+fields, the files a build writes and their spec ids, the environment, and what this
+package relies on in rig-c — and what is not, is [docs/STABILITY.md](STABILITY.md).
+Coming from 0.16.0: [docs/MIGRATION.md](MIGRATION.md).
+
+### Writing proposed config fields
+
+`--write-config <config.json>` saves the proposals above into an existing
+regular config file: `seethrough.head_box`, `assemble.plan` plus
+`assemble.extend_below_crop`, or the present config sections of an ordinary
+proposal. The [neck draft](AUTHORING.md#a-neck-that-moves-on-its-own)
+(`propose … --full --head --write-config`) is another writer: for an existing
+`turn.body` config with one neck plan row, it selects the full-run neck, drafts a
+rigid unit and its depth, and reassembles parts under `<out>/rig`.
+For `assemble --propose-plan`, the destination must name `--config`
+itself; a different destination is a usage error. Other fields and absent optional
+sections remain; proposal notes are not copied. Changed whole values are spliced
+into the original text, preserving untouched bytes. Stage loaders validate the candidate, including `proposed_rig_scale`,
+before atomic replacement. Relative paths keep the config's directory as their
+base. Changes are listed on stderr; the head-box and plan JSON on stdout remain.
+An identical update leaves bytes and mtime untouched. Without the flag no config
+is changed. This commits the config file, not a transaction across the proposal
+artifacts.
+
+With `--cloth <config.json>`, the flag requires a **new** destination and applies
+the recipe's entry ownership: recipe-owned entries are spliced into the cloth
+config while hand entries and unrelated text survive; conflicts are refused.
+The destination must also be separate from all four artifacts under `--out`:
+`proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png`.
+Aliases, including directory symlinks and hardlinks, count as collisions too.
+Fresh output is published without overwriting a file created while the command
+runs. Its already-checked splice text may be a partial config; it is not passed
+through the full-config loader. If removing the staged temporary fails after
+publication, the error may accompany an already-published complete config.
+`--from <previous.json>` retains the previous-recipe comparison.
+With `--only-missing` (issue #671), an ordinary proposal's `--write-config` adds
+only `meshes.<part>` or `regions.<part>` for each proposed part the config
+attaches by neither, entry by entry, and, for a part the 1.37.0 arm split makes
+(`full:drape-<s>`, `full:hand-<s>`) that `assemble.plan` does not name, its plan
+row beside the arm's row; every existing row and entry and every other byte
+stays as read, and nothing else of the proposal is written. The candidate passes
+the full loader first, so an entry on a bone the config does not declare is
+refused naming the part and the bone; nothing missing leaves bytes and mtime
+untouched. It is the upgrade path for a config proposed before the 1.37.0 arm
+split ([MIGRATION](MIGRATION.md#after-1370-merged-arm-layers-are-split-issue-490)),
+and a usage error with `--head-box`, `--cloth` or `--from-config`.
+`--from-config` proposes nothing and cannot be combined with `--write-config`.
+[AUTHORING §4](AUTHORING.md#4-the-command-order) describes all four modes.
 ## 5. After each stage: what to read
 
 | stage | read | green looks like | a common red |
@@ -4994,7 +5101,7 @@ and stay absent).
 | <a id="DEPTH_SOURCE_AMBIGUOUS"></a>`DEPTH_SOURCE_AMBIGUOUS` | writer/user or layer/canvas declarations overlap | select one authoritative route explicitly |
 | <a id="DEPTH_SOURCE_RESOLVES"></a>`DEPTH_SOURCE_RESOLVES` | user key names no source layer | use the exact source tag in the selected run |
 | <a id="DEPTH_SOURCE_BASE"></a>`DEPTH_SOURCE_BASE` | a direct assembler caller supplied user paths without config base | pass the actual config-directory base |
-| <a id="DEPTH_PART_SUPPORT"></a>`DEPTH_PART_SUPPORT` | exact copied/generated material lacks source depth or compatible units | provide a declared scalar source/registration; do not infer or fill depth |
+| <a id="DEPTH_PART_SUPPORT"></a>`DEPTH_PART_SUPPORT` | exact copied/generated material lacks source depth or compatible units | provide a declared scalar source/registration; do not infer or fill depth; declare the part `unit` with an explicit authored `unitDepths` value when its material includes authored under-art |
 | <a id="PARTS_DEPTH_REFERENCE"></a>`PARTS_DEPTH_REFERENCE` | persisted fields/provenance violate the reference shape | restore image, near, positive zScale and exact source records |
 | <a id="DEPTH_SILHOUETTE_SIZE_MISMATCH"></a>`DEPTH_SILHOUETTE_SIZE_MISMATCH` | `extendDepthSilhouette` or `padTurnDepthSheet` received a source depth sheet and artwork raster of different dimensions | supply the part's matching unpadded depth sheet and artwork raster |
 | <a id="CONFIG_TURN_COUNTER_RANGE"></a>`CONFIG_TURN_COUNTER_RANGE` | `config.turn.counter` (or `config.turn.body.counter`) is outside `[0, 1]` | supply a non-negative rear counter-translation fraction in `[0, 1]` |
@@ -6216,6 +6323,42 @@ art. An authored `parts.json` depth reference remains an active standalone
 `rig` declaration even without config opt-in: its file/size/color/opacity
 guards still apply. With binding inactive there is no added reference, file or
 legacy-byte change. #773 adds no image generation, geometry or motion model.
+
+### Unit depth precedence
+
+For `"unit"` roles, a transported part's sheet is recorded and validated but is not
+necessarily the depth used to move its bone. `turn.unitDepths` (and the body
+map `turn.body.unitDepths`, which inherits the head map when omitted) uses
+calibrated world depths. An explicit `0` is a value, not a request to sample.
+With active depth binding, assembly skips scalar transport only when every declared turn group makes the part `unit` with explicit part or carried-bone `unitDepths` covering every still piece, records the resolved values in `provenance.depth` as `{kind: "authored-unit", values: [...]}`, and retains input-sheet validation and every implicit-unit or sampled-surface refusal.
+For each carried unit bone, the existing producer resolves depth in this order:
+
+1. `unitDepths.<part>`; when both names are present, the part entry wins.
+2. `unitDepths.<bone>`, using the carried bone's name.
+3. The primary surface's extended sheet at the unit's setup landmark. The
+   head group prefers the `face` surface, otherwise the first declared surface;
+   the body group uses its first declared surface. This depth is relative to
+   that surface's reference and the group's pivot. A unit mesh uses its child
+   landmarks, or its part centre when those landmarks are absent.
+4. Only if still unresolved, the unit's own sheet's opaque-art median. This
+   lower-level fallback is not an authoring switch: the documented config
+   reader requires a surface in each active group and supplies declared region
+   landmarks or a mesh sampling position. No documented configuration is
+   provided here to bypass primary sampling and select the own sheet instead.
+
+Outside or nonopaque primary support produces
+[`RIG_TURN_UNIT_DEPTH_SUPPORT`](#RIG_TURN_UNIT_DEPTH_SUPPORT), retains the
+extended primary sample, and does not select the own sheet. Removing all
+surfaces is refused by
+[`CONFIG_TURN_SURFACE_REQUIRED`](#CONFIG_TURN_SURFACE_REQUIRED).
+Consequently, removing `unitDepths` alone does not make an own-sheet change
+move a unit: primary-surface sampling can still mask it. In that case the own
+sheet remains in `depth_sheets.json` and its padded PNG, but is not consumed
+for that unit's turn geometry. Author an explicit calibrated `unitDepths`
+entry to control its rigid depth; change the primary surface only when that
+shared sampled field is what should change. A `"surface"` part's own sampled
+geometry is a separate consumer described above.
+
 ### Explicit source-derived waist pivot stage
 
 `withWaistPivot` is a pure, explicit candidate-stage operation over an already
@@ -6335,3 +6478,51 @@ they do not certify a new toolchain, input or packaging build. No tuning to meet
 | <a id="CONFIG_WAIST_NAME_FREE"></a>`CONFIG_WAIST_NAME_FREE` | The generated bone name already exists; declare an unused name | declare an unused name |
 | <a id="RIG_WAIST_DECLARATION"></a>`RIG_WAIST_DECLARATION` | Actual provenance, pair bindings or drawing ownership do not match the bounded declaration; supply the declared base two-bone mesh/rigid-region pair | supply the declared base pair |
 | <a id="RIG_WAIST_MOTION"></a>`RIG_WAIST_MOTION` | Imported tracks drive the generated waist frame; retain their original authored targets | retain the original authored targets |
+
+### Depth-driven rigging
+
+Registered per-part depth sheets drive sampled head yaw/pitch through
+`turn.roles` and independent body yaw through `turn.body.roles`. Region
+surfaces use depth-bearing grids; authored weighted surfaces keep their
+skinning and receive per-influence deform offsets sampled at setup positions.
+These controls are exercised on public synthetic fixtures. Unit parts use the
+[documented depth precedence](AUTHORING.md#unit-depth-precedence), so a
+recorded unit sheet does not by itself promise different turn geometry.
+See the [authoring contract](AUTHORING.md#per-layer-depth-sheets-773)
+and the [getting-started guide](https://github.com/rig-c/getting-started).
+
+### Per-layer depth input
+
+`config.depth` explicitly enables scalar input. Without it, `depth_filename`
+is a legacy hint: no depth-file I/O, validation, fetch, reference or output is
+activated, even when files or in-memory sheets exist. Active See-through sheets
+are read as opaque grayscale source data. Declare positive finite `depth.zScale`;
+eight bits do not supply world units. See-through far-high encoding is explicitly `near: "black"`. User
+per-layer/run-canvas fallbacks declare image, near and zScale themselves; a
+missing declared file is an error, not a fallback. The ordering median remains
+separate, and its agreement reading cannot certify an image's polarity.
+
+Assembly emits registered part sheets and references; rig emits PAD4 sheets and
+`depth_sheets.json`. Since 1.68.0 (#777), [config.turn.roles](AUTHORING.md#3-configjson-field-by-field)
+uses depth sheets for 2.5D head turns with grid or authored weighted surfaces and `yaw_dial`/`pitch_dial`
+controls; see [`CONFIG_TURN_ROLE_UNKNOWN`](AUTHORING.md#CONFIG_TURN_ROLE_UNKNOWN)
+and [`CONFIG_TURN_SURFACE_REQUIRED`](AUTHORING.md#CONFIG_TURN_SURFACE_REQUIRED).
+`turn.body.roles` adds independent body yaw. A weighted mesh declared as
+`"surface"` in either group and blending head and torso bones receives both
+fields in proportion to its skin weights. Inside the existing setup alpha
+overlap with a single-group neighbour, a blended attachment's vertex takes
+that neighbour's existing emitted triangle field at its setup position (#804), without changing skin weights,
+setup or idle. A `motion.blink.still` unit neighbour supplies both emitted
+pieces, each on its own bone and resolved depth; transparent padding does not
+let either piece lend its field to the other's art (#807). Missing emitted
+split support is refused by name. Conflicting neighbour groups are refused by name. Each sibling island takes only its
+own group; parts without a blended attachment keep their existing role behavior
+and output bytes. Unlisted meshes do not consume turn depth sheets. See the
+[blended surface contract](AUTHORING.md#per-layer-depth-sheets-773).
+This copies the field at vertices; different triangle partitions can still
+differ between vertices. The [corrected #804 acceptance](https://github.com/rig-c/parts/issues/804#issuecomment-6478778123)
+checks vertex correspondence and reports those residuals per fixture; the
+contract records the measured grid residual and preserves its seam readings.
+No-image builds keep the legacy output bytes. `comfy seethrough --config <file> --depth-run <full|head>`
+uses the same opt-in; its default captures art only. Standalone authored part
+references remain active declarations. See [the input contract and refusals](AUTHORING.md#per-layer-depth-sheets-773).

package/docs/STABILITY.md

@@ -80,6 +80,10 @@ command's flag union; `comfy paint` and `comfy seethrough` are checked separatel
 Required combinations within a mode remain the CLI's; the `cli` suite's controls
 read them from the help.
 
+The [command reference](AUTHORING.md#command-reference) describes each mode;
+[writing proposed config fields](AUTHORING.md#writing-proposed-config-fields)
+records the existing-file and fresh-file destinations and byte-preservation rules.
+
 ## The config contract
 
 `src/config.ts` is the schema and the loader, and
@@ -478,6 +482,15 @@ Assembly's optional part `depth` reference holds `image`, `near`, `zScale` and
 active binding. Persisted authored part references remain active for standalone
 rig reading regardless of config opt-in. `rig` adds padded measurement PNGs and the `rig-parts-depth-sheets/1`
 `depth_sheets.json` companion only with references (each output `part`, actual
-padded `size`, and `depth`; a still split names both slices). Current weighted meshes do
-not acquire a Core field or change geometry; #763 owns the generator consumer.
+padded `size`, and `depth`; a still split names both slices). Passive references
+add these companions without changing weighted geometry. Active `"surface"`
+roles in `turn.roles` and `turn.body.roles` consume registered sheets:
+region surfaces emit Core grid generators with `generator.depth`; authored
+weighted surfaces keep their topology and bindings and emit sampled per-influence
+inverse-bind deform offsets in motion, without adding a Core attachment depth
+field. Head yaw/pitch and independent body yaw use their existing turn groups.
+Blended surfaces retain the documented per-group masks and setup-overlap
+neighbour field rules in [AUTHORING](AUTHORING.md#per-layer-depth-sheets-773).
+The unit-depth precedence and its primary-surface sampling are documented in
+[AUTHORING](AUTHORING.md#unit-depth-precedence).
 The separate ordering scalar is unchanged. No-image outputs retain legacy bytes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.83.1",
+  "version": "1.83.2",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {
@@ -58,6 +58,7 @@
   "scripts": {
     "fetch-examples": "bash scripts/fetch-examples.sh",
     "selftest": "bun selftest.ts",
+    "check:readme": "bun scripts/readme_policy.ts",
     "selftest:pre": "bun selftest.ts --pre",
     "smoke": "bun scripts/install_smoke.ts",
     "typecheck": "bunx tsc --noEmit",

package/src/assemble.ts

@@ -1,4 +1,5 @@
 import { unionTakenSources } from './takesource.ts';
+import { authoredUnitDepths, type AuthoredUnitDepth } from './authoredunit.ts';
 import { paintingExtensionMasks, paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
 import { AUTOMATIC_WRITERS as AW, compactValueBaseline, pixelProvenance, rgbaEqual, type ValueBaseline } from './provenance.ts';
 import { bindDepthRun, copyDepthMaterial, registerDepthRun, transportPartDepth, type DepthConfig, type RegisteredDepth } from './depthsheets.ts';
@@ -317,6 +318,11 @@ export function singleRunPadRecord(single: boolean, sourceW: number, sourceH: nu
 }
 
 export interface AssembleInput {
+  /** Turn context for the exact part/carrier declarations, never an exemption flag. */
+  turn?: TurnSpec;
+  regions?: Record<string, RegionSpec>;
+  meshes?: Record<string, MeshSpec>;
+  motion?: CharacterConfig['motion'];
   depth?: DepthConfig;
   /** Config-relative user sheet paths; caller supplies its actual base. */
   depthBase?: string;
@@ -4638,6 +4644,7 @@ export function checkSingleRun(full: LayerSet, plan: readonly PlanEntry[] | null
  */
 export function assemble(input: AssembleInput): AssembleResult {
   const { source, extend, patches, seamRule, projectRule } = input;
+  const authoredDepths = input.depth === undefined ? new Map<string, AuthoredUnitDepth>() : authoredUnitDepths(input);
   if (input.paintingExtension !== undefined) refuseIfAny(paintingExtensionProblems(input.paintingExtension));
   const single = input.single === true;
   const frame = checkGeometry(
@@ -5541,7 +5548,8 @@ export function assemble(input: AssembleInput): AssembleResult {
     const limbIndex = limb === undefined ? -1 : lim.parts.findIndex(q => q.record.name === limb.name && q.record.segment === limb.segment);
     const upperIndex = limb === undefined ? -1 : lim.parts.findIndex(q => q.record.name === limb.name && q.record.segment === limb.segment - 1);
     const capSource = limbIndex < 0 ? null : lim.capFrom[limbIndex];
-    const scalar = transportPartDepth(record, image, registeredDepth, {
+    const authoredDepth = authoredDepths.get(name);
+    const scalar = authoredDepth === undefined ? transportPartDepth(record, image, registeredDepth, {
       map: run => runMap(frame, run), width: W, extend: extendKeys, owner: trace.from,
       ring: trace.ring.data, region: region?.data ?? null,
       copiedSource: (x, y) => {
@@ -5552,7 +5560,7 @@ export function assemble(input: AssembleInput): AssembleResult {
         return { key: e < 0 ? upper.key : upper.extendKeys[e], ring: upper.trace.ring.data[p] !== 0 };
       },
       ...((limb?.cap?.image_px ?? 0) > 0 || (limb?.cap?.lower_px ?? 0) > 0 ? { unsupported: `cap copies ${(limb?.cap?.image_px ?? 0) + (limb?.cap?.lower_px ?? 0)} pixels from a separate cap image whose scalar grid is undeclared` } : {}),
-    });
+    }) : undefined;
     if (capSource !== null && upperIndex >= 0 && capSource.codes.some(code => code === CAP_FROM_UPPER)) {
       const upper = limbPieces[upperIndex];
       const keys = [upper.key, ...upper.extendKeys.filter((_, i) => upper.trace.from.some(v => v === i))];
@@ -5573,7 +5581,11 @@ export function assemble(input: AssembleInput): AssembleResult {
 
 
   seamOverride(placed, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null, keepInOrder, input.turnMovingPair ?? null, (i, p) => { writersInOrder[i][p] = AW.seamOverride; });
-  placed.forEach((p, i) => { p.record.provenance = pixelProvenance(p.image, p.record.x, p.record.y, W, writersInOrder[i], editNames, 0, valueBaselines.get(p.record.from) ?? null); });
+  placed.forEach((p, i) => {
+    p.record.provenance = pixelProvenance(p.image, p.record.x, p.record.y, W, writersInOrder[i], editNames, 0, valueBaselines.get(p.record.from) ?? null);
+    const depth = authoredDepths.get(p.record.name);
+    if (depth !== undefined) p.record.provenance.depth = depth;
+  });
   // Provenance is now numbers/labels only. No later raster/figure operation
   // reads report buffers; release all aliases before recomposite/error work.
   valueBaselines.clear();
@@ -6487,6 +6499,7 @@ export function stageFields(
     regions?: Record<string, RegionSpec>;
     constraints?: ConfigConstraint[];
     turn?: TurnSpec;
+    motion?: CharacterConfig['motion'];
   },
   single: { w: number; h: number } | null = null,
 ): {
@@ -6512,6 +6525,10 @@ export function stageFields(
   /** Base painting only; named final parts, explicit band and path bound (#848). */
   paintingExtension?: readonly PaintingExtension[];
   turnMovingPair?: (a: string, b: string) => boolean;
+  turn?: TurnSpec;
+  regions?: Record<string, RegionSpec>;
+  meshes?: Record<string, MeshSpec>;
+  motion?: CharacterConfig['motion'];
 } {
   const problems: Problem[] = [];
   if (cfg.seethrough === undefined) {
@@ -6535,6 +6552,7 @@ export function stageFields(
     ...(cfg.assemble.keep_under_occluders === undefined ? {} : { keepUnderOccluders: cfg.assemble.keep_under_occluders }),
     ...(cfg.assemble.extend_painting === undefined ? {} : { paintingExtension: cfg.assemble.extend_painting }),
     ...(turnMovingPair === null ? {} : { turnMovingPair }),
+    ...(cfg.turn === undefined ? {} : { turn: cfg.turn, regions: cfg.regions, meshes: cfg.meshes, motion: cfg.motion }),
     rigScale: cfg.assemble.rig_scale,
     plan: cfg.assemble.plan,
     extend: cfg.assemble.extend_below_crop ?? [],

package/src/authoredunit.ts

@@ -0,0 +1,61 @@
+/** Fully explicit unit consumers may omit their unused scalar transport (#877). */
+import type { MeshSpec, Motion, RegionSpec, TurnSpec } from './config.ts';
+import { turnUnitBone } from './turn.ts';
+
+export interface AuthoredUnitDepth {
+  kind: 'authored-unit';
+  /** An absent bone means the part override, which covers every carried piece. */
+  values: Array<{ group: 'head' | 'body'; bone?: string; value: number }>;
+}
+
+export function authoredUnitDepths(cfg: {
+  turn?: TurnSpec;
+  regions?: Record<string, RegionSpec>;
+  meshes?: Record<string, MeshSpec>;
+  motion?: Pick<Motion, 'blink'>;
+}): ReadonlyMap<string, AuthoredUnitDepth> {
+  const out = new Map<string, AuthoredUnitDepth>();
+  const turn = cfg.turn;
+  if (turn === undefined || turn === null || typeof turn !== 'object' || Array.isArray(turn)) return out;
+  const groups = [
+    { group: 'head' as const, roles: turn.roles, depths: turn.unitDepths },
+    { group: 'body' as const, roles: turn.body?.roles, depths: turn.body?.unitDepths ?? turn.unitDepths },
+  ];
+  const number = (table: Record<string, number> | undefined, name: string): number | undefined => {
+    const value = table !== undefined && Object.hasOwn(table, name) ? table[name] : undefined;
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+  };
+  const parts = new Set(groups.flatMap(g => Object.keys(g.roles ?? {})));
+  for (const part of parts) {
+    const values: AuthoredUnitDepth['values'] = [];
+    let complete = true;
+    for (const g of groups) {
+      if (g.roles === undefined || !Object.hasOwn(g.roles, part)) continue;
+      if (g.roles[part] !== 'unit') { complete = false; break; }
+      const explicitPart = number(g.depths, part);
+      if (explicitPart !== undefined) { values.push({ group: g.group, value: explicitPart }); continue; }
+      const region = cfg.regions?.[part];
+      const bone = typeof region === 'string' ? region : region?.bone;
+      // Match the producer's actual unit carrier, not a mesh segment's bone.
+      const bones = cfg.meshes !== undefined && Object.hasOwn(cfg.meshes, part)
+        ? [turnUnitBone(part)]
+        : typeof bone === 'string' && bone.length > 0 ? [bone] : [];
+      if (cfg.meshes?.[part] === undefined) {
+        const still = cfg.motion?.blink?.still?.[part];
+        if (still !== undefined) {
+          if (typeof still.bone !== 'string' || still.bone.length === 0) { complete = false; break; }
+          bones.push(still.bone);
+        }
+      }
+      if (bones.length === 0) { complete = false; break; }
+      for (const name of new Set(bones)) {
+        const value = number(g.depths, name);
+        if (value === undefined) { complete = false; break; }
+        values.push({ group: g.group, bone: name, value });
+      }
+      if (!complete) break;
+    }
+    if (complete && values.length > 0) out.set(part, { kind: 'authored-unit', values });
+  }
+  return out;
+}

package/src/build.ts

@@ -665,6 +665,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
         ...(fields.headFaceUnderfill === undefined ? {} : { headFaceUnderfill: fields.headFaceUnderfill }),
         ...(fields.yieldRefused === undefined ? {} : { yieldRefused: fields.yieldRefused }),
         ...(fields.turnMovingPair === undefined ? {} : { turnMovingPair: fields.turnMovingPair }),
+        ...(fields.turn === undefined ? {} : { turn: fields.turn, regions: fields.regions, meshes: fields.meshes, motion: fields.motion }),
         seamRule: input.seam,
         projectRule: input.project,
         ...(altExclude.length === 0 ? {} : { exclude: altExclude }),

package/src/parts.ts

@@ -503,7 +503,8 @@ function checkOwnership(raw: unknown, object: string, fail: (code: string, objec
 
 function orderedProvenance(p: PixelProvenance): PixelProvenance {
   return { unchanged_layer_px: p.unchanged_layer_px, hand_px: p.hand_px, automatic_px: p.automatic_px,
-    edits: p.edits.map(e => ({ edit: e.edit, px: e.px })), automatic: p.automatic.map(e => ({ stage: e.stage, px: e.px })) };
+    edits: p.edits.map(e => ({ edit: e.edit, px: e.px })), automatic: p.automatic.map(e => ({ stage: e.stage, px: e.px })),
+    ...(p.depth === undefined ? {} : { depth: { kind: p.depth.kind, values: p.depth.values.map(v => ({ group: v.group, ...(v.bone === undefined ? {} : { bone: v.bone }), value: v.value })) } }) };
 }
 
 function serializePartList(parts: readonly PartRecord[]): Array<Record<string, unknown>> {
@@ -591,13 +592,13 @@ function show(v: unknown): string {
 }
 
 /** The same optional measurement contract for base and alternate records. */
-function checkProvenance(raw: unknown, opaque: unknown, object: string, fail: (code: string, object: string, detail: string) => void): void {
+function checkProvenance(raw: unknown, opaque: unknown, object: string, fail: (code: string, object: string, detail: string) => void, hasScalar = false): void {
   const v = raw as PixelProvenance | null;
   const count = (n: unknown): boolean => Number.isSafeInteger(n) && (n as number) >= 0;
   const edit = (name: string): boolean => /^(cuts\[\d+\]|patches\[\d+\])$/.test(name) ||
     (/^(full|head):author:/.test(name) && readFrom(name) !== null);
   const shape = v !== null && typeof v === 'object' && !Array.isArray(v) &&
-    Object.keys(v).sort().join(',') === 'automatic,automatic_px,edits,hand_px,unchanged_layer_px' &&
+    Object.keys(v).filter(k => k !== 'depth').sort().join(',') === 'automatic,automatic_px,edits,hand_px,unchanged_layer_px' &&
     [v.unchanged_layer_px, v.hand_px, v.automatic_px].every(count) && Array.isArray(v.edits) && Array.isArray(v.automatic) &&
     v.edits.every(e => e !== null && typeof e === 'object' && Object.keys(e).sort().join(',') === 'edit,px' && typeof e.edit === 'string' && edit(e.edit) && count(e.px) && e.px > 0) &&
     v.automatic.every(e => e !== null && typeof e === 'object' && Object.keys(e).sort().join(',') === 'px,stage' && typeof e.stage === 'string' && Object.hasOwn(AUTOMATIC_WRITERS, e.stage) && count(e.px) && e.px > 0) &&
@@ -612,6 +613,18 @@ function checkProvenance(raw: unknown, opaque: unknown, object: string, fail: (c
     const hand = p.edits.reduce((n, e) => n + e.px, 0), automatic = p.automatic.reduce((n, e) => n + e.px, 0);
     fail('PARTS_COUNTS_ADD_UP', object, `unchanged_layer_px ${p.unchanged_layer_px} + hand_px ${p.hand_px} + automatic_px ${p.automatic_px} = ${total}; opaque_px ${opaque} is required; edit subtotal ${hand} (hand_px ${p.hand_px} required), stage subtotal ${automatic} (automatic_px ${p.automatic_px} required)`);
   }
+  if (v !== null && typeof v === 'object' && 'depth' in v) {
+    const d = v.depth;
+    const valid = !hasScalar && d !== null && typeof d === 'object' && !Array.isArray(d) &&
+      Object.keys(d).sort().join(',') === 'kind,values' && d.kind === 'authored-unit' && Array.isArray(d.values) && d.values.length > 0 &&
+      d.values.every(q => q !== null && typeof q === 'object' && !Array.isArray(q) &&
+        Object.keys(q).sort().join(',') === (Object.hasOwn(q, 'bone') ? 'bone,group,value' : 'group,value') &&
+        (q.group === 'head' || q.group === 'body') && typeof q.value === 'number' && Number.isFinite(q.value) &&
+        (!Object.hasOwn(q, 'bone') || (typeof q.bone === 'string' && q.bone.length > 0))) &&
+      new Set(d.values.map(q => `${q.group}:${q.bone ?? ''}`)).size === d.values.length &&
+      d.values.every(q => q.bone !== undefined || d.values.filter(r => r.group === q.group).length === 1);
+    if (!valid) fail('PARTS_FIELD_TYPE', object + ' depth', 'requires authored-unit with nonempty distinct head/body finite values, optional nonempty bone names, and no transported scalar reference');
+  }
 }
 
 function checkParts(raw: unknown, path: string): PartsFile {
@@ -675,7 +688,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
         if (k in r && !(Number.isInteger(r[k]) && (r[k] as number) >= 0)) fail('PARTS_FIELD_TYPE', `${label} field "${k}"`, `is ${show(r[k])}; a non-negative integer is required`);
       }
       const count = (k: string): number | null => (Number.isInteger(r[k]) && (r[k] as number) >= 0 ? (r[k] as number) : null);
-      if ('provenance' in r) checkProvenance(r.provenance, r.opaque_px, label + ' provenance', fail);
+      if ('provenance' in r) checkProvenance(r.provenance, r.opaque_px, label + ' provenance', fail, 'depth' in r);
       checkPaintingExtensionCount(r, label, fail);
       const [op, vis, occ, vnp] = ['opaque_px', 'visible_px', 'occluded_px', 'visible_not_projected_px'].map(count);
       if (held.length === VISIBILITY_KEYS.length && op !== null && vis !== null && occ !== null && vnp !== null) {
@@ -828,7 +841,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
         if (typeof p !== 'object' || p === null || Array.isArray(p)) return;
         const r = p as Record<string, unknown>;
         const part817 = typeof r.name === 'string' ? `part "${r.name}"` : `records[${j}]`;
-        if ('provenance' in r) checkProvenance(r.provenance, r.opaque_px, `${at} ${part817} provenance`, fail);
+        if ('provenance' in r) checkProvenance(r.provenance, r.opaque_px, `${at} ${part817} provenance`, fail, 'depth' in r);
         checkPaintingExtensionCount(r, `${at} ${part817}`, fail);
         const l = r[LIMB_KEY];
         if (typeof l !== 'object' || l === null || Array.isArray(l) || !('cap' in l)) return;

package/src/provenance.ts

@@ -1,6 +1,7 @@
 /** Report-only last-writer accounting over final output pixels (#817). */
 import { OPAQUE_ALPHA_ABOVE } from './layers.ts';
 import type { PartRecord } from './parts.ts';
+import type { AuthoredUnitDepth } from './authoredunit.ts';
 import { crop, type Raster } from './raster/index.ts';
 
 /** Negative IDs distinguish automatic writes from positive, config-indexed hand edits. */
@@ -11,6 +12,8 @@ export const AUTOMATIC_WRITERS = {
 } as const;
 export type AutomaticWriter = keyof typeof AUTOMATIC_WRITERS;
 export interface PixelProvenance {
+  /** Scalar transport omitted only for fully explicit unit consumers (#877). */
+  depth?: AuthoredUnitDepth;
   unchanged_layer_px: number;
   hand_px: number;
   automatic_px: number;
@@ -83,7 +86,7 @@ export function provenanceLines(parts: readonly PartRecord[]): string[] {
     opaque += p.opaque_px; unchanged += v.unchanged_layer_px; automatic += v.automatic_px; hand += v.hand_px;
     for (const e of v.edits) edits.set(e.edit, (edits.get(e.edit) ?? 0) + e.px);
     for (const e of v.automatic) stages.set(e.stage, (stages.get(e.stage) ?? 0) + e.px);
-    lines.push(`  provenance: part "${p.name}" (${p.from}) opaque ${p.opaque_px} = unchanged layer ${v.unchanged_layer_px} + hand ${v.hand_px} + automatic ${v.automatic_px}; edits ${detail(new Map(v.edits.map(e => [e.edit, e.px])))}; stages ${detail(new Map(v.automatic.map(e => [e.stage, e.px])))}`);
+    lines.push(`  provenance: part "${p.name}" (${p.from}) opaque ${p.opaque_px} = unchanged layer ${v.unchanged_layer_px} + hand ${v.hand_px} + automatic ${v.automatic_px}; edits ${detail(new Map(v.edits.map(e => [e.edit, e.px])))}; stages ${detail(new Map(v.automatic.map(e => [e.stage, e.px])))}${v.depth === undefined ? '' : `; depth authored-unit ${v.depth.values.map(d => `${d.group}/${d.bone ?? p.name}=${d.value}`).join(', ')}`}`);
   }
   lines.push(`  provenance total: opaque ${opaque} = unchanged layer ${unchanged} + hand ${hand} + automatic ${automatic}; edits ${detail(edits)}; stages ${detail(stages)}; output pixels, including copies in separate parts; value equality first; last value-changing stage wins`);
   return lines;