rig-parts 1.67.0 → 1.68.0

package/README.md

@@ -407,8 +407,8 @@ These are limits of the approach, stated so nobody reads more into a green run:
 - **rig-parts generates no images.** The painting and See-through layers are made
   by models the user runs on their GPU or a web demo. No weights ship here; the
   optional `comfy` adapter drives the user's own ComfyUI host and models.
-- **One depth value per layer.** See-through gives each layer a single depth, so a
-  layer that is in front of another in one place and behind it in another is drawn
+- **Legacy turns use one ordering depth per layer.** See-through also supplies per-pixel
+  sheets, now preserved as inputs for the subsequent generator consumer (#773/#763). A layer that is in front of another in one place and behind it in another is drawn
   right in the still (the painting's own pixels are projected onto it) and wrong once
   it moves.
 - **No expression or lip-sync, and no jiggle.** The mouth is one layer; there is no
@@ -572,3 +572,22 @@ the interface it holds.
 ## Licence
 
 MIT — see [LICENSE](LICENSE). Third-party terms: [NOTICE.md](NOTICE.md).
+
+
+### 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`. Existing weighted meshes do not use them yet: production
+Core grid/contour generators and turns belong to #763. 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).

package/cli.ts

@@ -779,6 +779,7 @@ usage:
   rig-parts comfy seethrough --image <png> --out <dir> [--host <url>]
                     [--resolution 1024] [--steps 30] [--seed 42] [--offload] [--lama] [--nf4]
                     [--prefix spine_parts] [--wait 1800] [--timeout 3600] [--poll 3]
+                    [--config <config.json> --depth-run <full|head>]
       Optional. Run See-through on a ComfyUI box with the jtydhr88/ComfyUI-See-through
       wrapper installed, and write the wrapper form \`layers\` reads into <out>
       (absent or empty): layers.json, parts/<tag>.png, meta.json, previews/.
@@ -788,6 +789,9 @@ usage:
       writes <out> only after the layer reader accepts what came back.
       --lama turns the wrapper's LaMa inpainting on and --nf4 its nf4
       quantisation; both are off unless given, as --offload is.
+      Depth hints are inactive by default. --config reads its optional depth
+      block; with that block --depth-run explicitly selects full or head.
+      Active declared sheets are fetched and validated, never inferred.
 
   rig-parts comfy paint --config <config.json> --out <dir> [--host <url>]
                     [--seeds 1] [--seed0 <generation.seed>] [--wait 1800] [--timeout 3600] [--poll 3]
@@ -1055,7 +1059,7 @@ const TAKES = {
   check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment', '--wind-band'], switches: ['--seam-pairs', '--keep-stills', '--all-sets'] },
   loop: { valued: ['--frames', '--out'], switches: ['--palette'] },
   assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt', '--write-config'], switches: ['--propose-plan'] },
-  'comfy seethrough': { valued: ['--image', '--out', '--resolution', '--steps', '--seed', '--prefix', '--host', '--wait', '--timeout', '--poll'], switches: ['--offload', '--lama', '--nf4'] },
+  'comfy seethrough': { valued: ['--image', '--out', '--resolution', '--steps', '--seed', '--prefix', '--host', '--wait', '--timeout', '--poll', '--config', '--depth-run'], switches: ['--offload', '--lama', '--nf4'] },
   'comfy paint': { valued: ['--config', '--out', '--seeds', '--seed0', '--host', '--wait', '--timeout', '--poll'], switches: [] },
   inputs: { valued: ['--source', '--config', '--out'], switches: [] },
   build: { valued: ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape', '--requirements', '--idle-keys', '--lead-in', '--alt', '--set', '--environment', '--wind-band'], switches: ['--loop', '--seam-pairs', '--keep-stills', '--all-sets'] },
@@ -1761,6 +1765,10 @@ async function cmdComfy(args: string[]): Promise<number> {
     // config comfy paint cannot paint from is refused with no box named.
     const paint = sub === 'paint' ? loadPaintConfig(configPath as string) : null;
     const cfg = paint === null ? null : paint.config;
+    const depthConfig = sub === 'seethrough' && configPath !== undefined ? loadEarlyConfig(configPath, 'layers').depth : undefined;
+    const depthRun = v.get('--depth-run');
+    if (sub === 'seethrough' && depthConfig !== undefined && depthRun !== 'full' && depthRun !== 'head') return usage('active config.depth requires --depth-run <full|head>; the source run is not inferred');
+    if (sub === 'seethrough' && depthConfig === undefined && depthRun !== undefined) return usage('--depth-run requires --config with an explicit depth block');
     const host = resolveHost(v.get('--host'), process.env.COMFY_HOST);
     const client = new ComfyClient(host, { poll: poll as number, request: 30 });
     if (sub === 'seethrough') {
@@ -1784,6 +1792,7 @@ async function cmdComfy(args: string[]): Promise<number> {
         quant: on.has('--nf4') ? ('nf4' as const) : ('none' as const),
         wait: wait as number,
         timeout: timeout as number,
+        ...(depthConfig === undefined ? {} : { depth: { config: depthConfig, run: depthRun as 'full' | 'head', base: dirname(resolve(configPath as string)) } }),
       };
       console.log(`rig-parts comfy seethrough: ${image} -> ${out}`);
       console.log(`  resolution ${run.resolution}, steps ${run.steps}, seed ${run.seed}, offload ${run.offload}, lama ${run.lama}, quant ${run.quant}; wait <= ${run.wait} s, timeout ${run.timeout} s`);

package/docs/AUTHORING.md

@@ -136,7 +136,7 @@ read by no CPU stage).
 | `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 |
 | `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 |
 | `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/src/stop.ts`). `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 |
-| `turn` | rig (adds the turn control) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected: `{pivot, depths, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}}`. `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 |
+| `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?}`. When `roles` is declared (`{<part>: "surface" \| "unit" \| "rear"}`, issue #763; `CONFIG_TURN_ROLE_UNKNOWN`, `CONFIG_TURN_SURFACE_REQUIRED`), 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`), 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` under `faceshift`, and `yaw_dial` and `pitch_dial` under `root` (`CONFIG_TURN_BONE_FREE`, `RIG_TURN_NAME_FREE`), re-parents `"unit"` and `"rear"` bones and mesh weights to `faceshift` and `rear_shift`, 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 `"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 |
 | `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 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). 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 |
 | `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) |
 | `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 |
@@ -4178,6 +4178,8 @@ documents do not ship). Each is an input this package built; none is an author's
 | <a id="REDUCE_THRESHOLD_RANGE"></a>`REDUCE_THRESHOLD_RANGE` | the art threshold is not a whole number in 1..255 | an input this package built, not an author's: report it with the line |
 | <a id="COMPARE_INPUT_MISSING"></a>`COMPARE_INPUT_MISSING` | a field of the input this package handed rig-c's `compareMeshesInMotion` is missing or malformed, two builds share an id, or one attachment is listed twice | an input this package built, not an author's: report it with the line |
 | <a id="COMPARE_INPUTS_DIFFER"></a>`COMPARE_INPUTS_DIFFER` | a candidate build differs from the reference outside what the comparison may vary (the compared mesh's vertices, UVs, triangles, hull, edges and weights); the path and both values are quoted | an input this package built, not an author's: report it with the line |
+| <a id="COMPARE_PREPARED_HANDLE"></a>`COMPARE_PREPARED_HANDLE` | the comparison received a handle not made by rig-c's `prepareMotionReference` | a programmatic caller must use the genuine opaque handle returned by `prepareMotionReference`; in the rig stage this is an input this package built, so report it with the line |
+| <a id="COMPARE_PREPARED_MISMATCH"></a>`COMPARE_PREPARED_MISMATCH` | the reference, schedule, attachment art or comparison options differ from the exact input bound to the prepared handle; the changed field is named | a programmatic caller must prepare a new handle from the exact changed reference-side input before comparing; in the rig stage this is an input this package built, so report it with the line |
 | <a id="COMPARE_REFERENCE_FAILS"></a>`COMPARE_REFERENCE_FAILS` | the reference — the unreduced source — fails its own art fit at the setup pose (coverage, overshoot or undercut against `sourceBounds`); a deviation from a reference that does not carry its own art is not evidence | the source, which is the author's: `meshes.<part>.auto.sourceBounds`, or the source's `spacing` or outline (`auto.source`) |
 | <a id="COMPARE_UV_CARRIER_NOT_UNIQUE"></a>`COMPARE_UV_CARRIER_NOT_UNIQUE` | a sample lies in two UV triangles that do not meet there at a shared vertex or edge: the mesh's UVs overlap or fold, so no one triangle carries it | an input this package built, not an author's: report it with the line |
 | <a id="COMPARE_WARMUP_UNSUPPORTED"></a>`COMPARE_WARMUP_UNSUPPORTED` | a physics warm-up other than 0 was asked of the comparison; physics resets at time 0 and steps from there | an input this package built, not an author's: report it with the line |
@@ -4343,6 +4345,37 @@ and stay absent).
 | <a id="GUIDE_RULE_KNOWN"></a>`GUIDE_RULE_KNOWN` | `rig-parts guide <RULE>`: no row of this guide names the rule. The line, on stderr, lists the three nearest names the guide does hold; nothing is printed in their place | one of the names listed, spelled as the line printed it |
 | <a id="GUIDE_SECTION_KNOWN"></a>`GUIDE_SECTION_KNOWN` | `rig-parts guide §<n>`, `§<n>.<m>` or `§<n>.<m>.<k>`: there is no such section, or no such subsection under the one it names; the line, on stderr, names the deepest section that exists and lists its sections | a number the detail lists |
 
+### Depth sheet refusals (#773)
+
+| rule | means | change |
+| --- | --- | --- |
+| <a id="DEPTH_SHEET_PRESENT"></a>`DEPTH_SHEET_PRESENT` | an active source or authored part-reference file is missing | restore it; legacy hints are inactive without config.depth, but active declarations never fall back |
+| <a id="DEPTH_SHEET_DECODES"></a>`DEPTH_SHEET_DECODES` | declared bytes are not a readable PNG | supply the actual grayscale PNG |
+| <a id="DEPTH_SHEET_SIZE"></a>`DEPTH_SHEET_SIZE` | sheet dimensions differ from the declared layer/canvas | supply a sheet on that exact source grid |
+| <a id="DEPTH_SHEET_GREYSCALE"></a>`DEPTH_SHEET_GREYSCALE` | some R/G/B values differ | use scalar data, not a tinted preview; RGB-encoded gray is valid |
+| <a id="DEPTH_SHEET_OPAQUE"></a>`DEPTH_SHEET_OPAQUE` | some alpha is not255 | provide an opaque declared sheet; alpha is not an unknown-depth fallback |
+| <a id="DEPTH_SHEET_FILENAME"></a>`DEPTH_SHEET_FILENAME` | writer depth filename is not a plain file for a drawn layer | correct the manifest filename; hidden-art sheets are not drawn-layer inputs |
+| <a id="DEPTH_SHEET_UNAMBIGUOUS"></a>`DEPTH_SHEET_UNAMBIGUOUS` | duplicate locations differ, or a sheet collides with art | retain one byte-identical source and noncolliding output names |
+| <a id="DEPTH_ZSCALE_REQUIRED"></a>`DEPTH_ZSCALE_REQUIRED` | units are absent, nonfinite or not positive | author positive finite world units |
+| <a id="DEPTH_NEAR_REQUIRED"></a>`DEPTH_NEAR_REQUIRED` | user convention is absent or invalid | declare black or white; no detector chooses one |
+| <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="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` is outside `[0, 1]` | supply a non-negative rear counter-translation fraction in `[0, 1]` |
+| <a id="CONFIG_TURN_ROLE_UNKNOWN"></a>`CONFIG_TURN_ROLE_UNKNOWN` | `config.turn.roles.<part>` is not `"surface"`, `"unit"` or `"rear"` | declare `"surface"`, `"unit"` or `"rear"` |
+| <a id="CONFIG_TURN_SURFACE_REQUIRED"></a>`CONFIG_TURN_SURFACE_REQUIRED` | `config.turn.roles` declares no `"surface"` part | declare at least one part (such as `face`) as `"surface"` |
+| <a id="CONFIG_TURN_EAR_DRAW_ORDER"></a>`CONFIG_TURN_EAR_DRAW_ORDER` | an ear part in `config.turn.roles` is drawn after a `"surface"` part in `assemble.plan` | place `ear_r` and `ear_l` before `face` in `assemble.plan` so the turning cheek occludes the far ear |
+| <a id="CONFIG_TURN_HEAD_BONE"></a>`CONFIG_TURN_HEAD_BONE` | `config.turn.roles` is declared without a single bone `"head"` in `config.bones` | declare `"head"` as a single bone in `config.bones` |
+| <a id="RIG_TURN_SURFACE_DEPTH_REQUIRED"></a>`RIG_TURN_SURFACE_DEPTH_REQUIRED` | a part with role `"surface"` in `config.turn.roles` carries no depth sheet in `parts.json` | run `assemble` with `config.depth` or provide `<part>_depth.png` in `parts.json` |
+| <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` `[cols, rows]` within the per-slot and total budgets |
+| <a id="RIG_TURN_HEAD_BONE"></a>`RIG_TURN_HEAD_BONE` | `buildRig` found no `"head"` bone when emitting 2.5D turn carriers | declare `"head"` in `config.bones` |
+| <a id="RIG_TURN_SHARED_DEPTH_SCALE"></a>`RIG_TURN_SHARED_DEPTH_SCALE` | `"surface"` parts bound to one head turn declare different `near` polarities or `zScale` values | use one shared `near` and `zScale` across all `"surface"` parts in the turn |
+| <a id="RIG_TURN_UNIT_DEPTH_REQUIRED"></a>`RIG_TURN_UNIT_DEPTH_REQUIRED` | a `"unit"` bone has neither a `config.turn.unitDepths` entry nor a readable `"surface"` depth sheet | provide a `"surface"` depth sheet or an explicit `config.turn.unitDepths.<part>` value |
+| <a id="RIG_TURN_EAR_DEPTH_BEHIND_CHEEK"></a>`RIG_TURN_EAR_DEPTH_BEHIND_CHEEK` | an ear bone in `config.turn.roles` has a calibrated depth at or in front of the cheek surface depth | place the ear behind the cheek surface (for example via `config.turn.unitDepths`) |
+
 ## 7. The bars `check` enforces, and what only an eye answers today
 
 `check.json`'s `PASS` is true exactly when all of these hold (the reference
@@ -5326,3 +5359,65 @@ cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
 including unselected frames, before reading the worst pose. Identical static
 ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
 never described as no declared range.
+
+## Per-layer depth sheets (#773)
+
+`depth_filename` is a legacy source hint. Only an explicit `config.depth` block
+activates sheet binding. Without it, hints are retained internally with their
+original source directory but trigger no depth-file I/O, validation/refusal,
+fetch or output, whether files or in-memory sheets exist. Original manifests
+are not rewritten. The ordering median and art reading remain unchanged. An
+active drawn-layer sheet must match its own box, have R=G=B and alpha255 everywhere. The pinned See-through
+writer stores far as high (ComfyUI-See-through commit
+`98d754bf04f668647919ab750eccb0e0640faa81`, nodes.py261–281); its later ordering
+adjustments at875–884 do not rewrite the sheet. Accordingly `near` is explicitly
+`black`, not inferred from its median. `depth_median` still controls draw order.
+Per-layer same/opposite/indeterminate readings use a half-u8-level bound and are
+not gates or inversion certificates; constants and symmetric ramps are ambiguous.
+
+The explicit `depth` block declares `zScale` for writer sheets, positive finite
+world units, never derived from eight bits. User fallback sheets are declared
+under `depth.full` or `depth.head`, either `layers` keyed by exact source layer
+name, or `atlas` (one sheet on that run's manifest canvas). Each user sheet states
+`image`, `near` (`black`/`white`) and its positive finite `zScale`. Relative paths
+resolve beside config. A packed atlas is not a run canvas; no packed-region crop
+is inferred. Writer declarations are authoritative; overlapping user declarations
+refuse, and active missing declared files never trigger fallback. An empty
+`depth: {}` activates the hints but cannot supply their missing units. Without
+the block, existing hint-only public inputs remain art-only inputs.
+
+The reader/export APIs accept an explicit `DepthBinding` context
+`{config: config.depth, run: "full" | "head", base: configDirectory}`. With no
+context, raw export writes the legacy art-only manifest/files even if its input
+has already-bound in-memory sheets. `layers --export` retains that default.
+`comfy seethrough --config <file> --depth-run <full|head>` uses the early layers
+config loader before contacting the box. The config depth block and named run
+select binding; the run is never guessed from the uploaded image. Without the
+block no depth hints are checked or fetched, including fresh wrapper outputs.
+With it, declared downloads and the staging reader must pass before emission.
+Relative fallback paths use the actual config directory. `--depth-run` without
+a depth block is a usage error; a block without a named run is also refused.
+
+Assembly uses the actual run registration, source-copy/composite coordinates,
+merge ownership and final crop. Scalar bilinear sampling at pixel centres is
+quantized half up at each intermediate copy/composite grid, then again at
+final part registration. PAD4 repeats the resulting u8 edge values. There is no
+universal half-level total-error bound across those operators. No art-color
+premultiplication or local min/max rescaling is applied. The rig sheet receives the drawing's PAD4 with
+explicit rectangular edge clamping. Original source hashes, rectangles, medians
+and declared units accompany the optional `parts.json` part `depth` reference.
+A synthesized merge rim or replacement under-art without scalar provenance is a
+named support refusal. It is not assigned a background or host depth.
+
+`rig` writes padded sheets in `images/` and a `depth_sheets.json` companion
+(`rig-parts-depth-sheets/1`). Each companion row names the output `part`, its
+actual padded drawing `size` [width,height], and its `depth` reference. A blink
+still split has separate lower/upper scalar slices at the same row as the art;
+both keep original source provenance. Its references describe inputs for Core's
+`generator.depth = {image, near, zScale}`; sources are provenance, not Core
+fields. Existing authored weighted meshes are unchanged and do not consume the
+reference yet (#763 owns generators/turns). Measurement sheets are not packed
+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.

package/docs/STABILITY.md

@@ -53,7 +53,7 @@ defaults are the help's too, and none is guessed from the art.
 | `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols` |
 | `inputs` | `--source`, `--config`, `--out` |
 | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
-| `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll` |
+| `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll`, `--config` (optional depth block), `--depth-run` (`full` or `head`, required with the block) |
 | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`, `--write-config` (must name `--config` itself, issue #356); or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454) |
 | `propose` | `--head-box` with `--full`, `--canvas`; optional `--no-back-hair`, `--write-config` (existing config, issue #356) |
 | `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (existing config for an ordinary proposal, issue #356; a new file with `--cloth`, issue #537; not with `--from-config` — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` writes changes), `--only-missing` (only with `--parts` and `--write-config`, not with `--cloth` or `--from-config`, issue #671 — additive: without it nothing `--write-config` writes changes) |
@@ -118,7 +118,7 @@ The fields, object by object (a bold path is where the object sits; `<part>` is
 part name, `[i]` an entry of a list):
 
 <!-- stable:config -->
-- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`, `proposed_rig_scale`, `requirements` (issue #556, additive: a path beside the config that build reads in place of its requirements flag, whose behaviour is unchanged), `motion_seams`
+- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`, `proposed_rig_scale`, `requirements` (issue #556, additive: a path beside the config that build reads in place of its requirements flag, whose behaviour is unchanged), `motion_seams`, `depth`
 - **generation** — required: `checkpoint`, `loras`, `trigger`, `identity`, `sampler`, `costume`, `negative_extra`, `style`, `negative_pose`, `latent`, `seed`; optional: `pose`, `control`
 - **generation.loras[i]** — required: `name`, `strength`; optional: `strength_clip`
 - **generation.sampler** — required: `steps`, `cfg`, `sampler`, `scheduler`
@@ -176,14 +176,19 @@ part name, `[i]` an entry of a list):
 - **motion.blink** — required: `t`, `eyes`, `squash`; optional: `brows`, `brow_drop`, `still`
 - **motion.blink.still.&lt;part&gt;** — required: `row`, `bone`
 - **motion.animations_from**, the file it names — required: `spec`, `animations`
-- **turn** — required: `pivot`, `depths`; optional: `deform`, `band`, `radius`, `surface`, `head`
+- **turn** — required: `pivot`, `depths` (or `roles`, issue #763); optional: `deform`, `band`, `radius`, `surface`, `head`, `roles`, `counter`, `grid`, `unitDepths`
 - **turn.depths.&lt;part&gt;** — a See-through depth
+- **turn.roles.&lt;part&gt;** — `"surface"`, `"unit"` or `"rear"` (issue #763)
+- **turn.unitDepths.&lt;part&gt;** — a calibrated world depth in rig pixels (issue #763)
 - **turn.deform.&lt;key&gt;** — a per-degree fraction or coupling share (FACE_DEFORM_FRACTIONS, issue #436)
 - **turn.band**, when an object — optional: `yaw`, `pitch` (issue #472)
 - **turn.surface**, when an object — optional: `radius` (issue #479)
 - **turn.head**, when an object — optional: `pivot`, `radius` (issues #478, #479)
 - **scene** — no field (`{}`; a record or an annotation only)
 - **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `limbs` under `--keypoints` where an arm or a leg is drafted from its joints (issue #349), `stops` when supplied, `motion` under the rules above, `turn` with `--full`/`--head`, `proposed_rig_scale` (issue #354), and `notes`
+- **depth** — optional: `zScale`, `full`, `head` (#773)
+- **depth.full**, **depth.head** — optional: `layers`, `atlas` (one fallback route)
+- **depth.full.layers.&lt;layer&gt;**, **depth.head.layers.&lt;layer&gt;**, **depth.full.atlas**, **depth.head.atlas** — required: `image`, `near`, `zScale`
 <!-- /stable:config -->
 
 `TY14` holds the set of field names in backticks above to the set of names the
@@ -291,7 +296,7 @@ in the package.
 
 ## rig-c
 
-`dependencies` takes `rig-c` `^2.69.0`: 2.69.0 or any later 2.x. Bun 1.4 or later
+`dependencies` takes `rig-c` `^2.72.0`: 2.72.0 or any later 2.x. Bun 1.4 or later
 is the declared floor (`engines.bun` `>=1.4.0`; older 1.4 releases are not tested in
 CI, which runs `latest`, and compatibility with an older 1.4 release is handled when
 reported as an issue). What this package relies on in rig-c, every import
@@ -351,6 +356,22 @@ documents). On CI (`ubuntu-latest`), the last two green runs on `main` took 4 mi
 `22b2c5a` respectively. None of these figures is a promise: they are what the named
 runs measured.
 
+The following measurement used the unreleased [core#1595](https://github.com/rig-c/core/issues/1595)
+prepared-reference implementation, packaged locally with `rig-c` metadata version
+`2.70.0` (tarball SHA-256 `dac8c10631e9c0fbd30b9361155b26cba5526ece618c623e87e8dd20cc3dd92c`).
+Its grid-selection replays bind one exact reference and schedule, then compare each
+fresh gated candidate.
+The number of candidate probes, gated builds and packed-page checks is
+unchanged; a changed bound or reference input is refused. In one exclusive Nova
+WSL ABBA invocation, using the same rig-c tarball in both arms and two runs per
+arm, the strict switched `bottomwear` input derived from public `reference-demo` took 56.00–56.28 s
+with one-shot comparison and 50.55–51.40 s with preparation included; the similarly switched public
+`reference-sample` input took 18.96–20.41 s and 16.39–18.71 s respectively.
+The paired differences were 4.59–5.74 s and 1.70–2.57 s. These are observed
+wall times for those inputs, not an execution limit or a machine-wide idle
+measurement; load outside the Nova pool was not measured. The prior count
+bounds remain the termination guarantee.
+
 ## Determinism
 
 The same inputs, with the same version of this package and the same installed
@@ -430,3 +451,24 @@ cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
 including unselected frames, before reading the worst pose. Identical static
 ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
 never described as no declared range.
+
+
+## Optional depth sheets (#773)
+
+A wrapper `depth_filename` is a legacy hint. Without explicit `config.depth`,
+no depth file is read, validated, fetched or emitted, even when files or
+in-memory sheets exist; art/order and legacy output stay unchanged. With the
+block, a drawn layer source must be opaque grayscale on its exact grid.
+Reader/export APIs take explicit config/run/base context; raw export defaults
+to art only. Comfy CLI adds `--config` and `--depth-run full|head`; the block
+requires a named run and a named run requires the block. Active download and
+source errors remain refusals, never missing-file fallback.
+Assembly's optional part `depth` reference holds `image`, `near`, `zScale` and
+`sources` (each original `from`, `image`, `sha256`, `crop`, and `reading` with
+`orderingMedian`, `sheetMedian`, `relation`). These fields are omitted without
+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.
+The separate ordering scalar is unchanged. No-image outputs retain legacy bytes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.67.0",
+  "version": "1.68.0",
   "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": {
@@ -64,7 +64,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "rig-c": "^2.69.0"
+    "rig-c": "^2.72.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/src/assemble.ts

@@ -1,3 +1,4 @@
+import { bindDepthRun, copyDepthMaterial, registerDepthRun, transportPartDepth, type DepthConfig, type RegisteredDepth } from './depthsheets.ts';
 /**
  * The assemble stage: two See-through runs over one painting — a FULL-body run
  * and a HEAD-crop run — merged into one set of rig-space parts, each part one
@@ -101,7 +102,7 @@
  */
 import { sourceLimbTarget, nearestTargetPart } from './limbownership.ts';
 import { type ArmSplit, type BoneEntry, type CharacterConfig, type ControlSkeleton, controlSkeletonOf, type Cut, type EarlyConfig, type Extend, type Limb, type Patch, type PlanEntry, type Run, type SeeThrough } from './config.ts';
-import { type Problem, refuseIfAny } from './errors.ts';
+import { PartsError, type Problem, refuseIfAny } from './errors.ts';
 import { CORE_ALPHA, figuresPhrase, implausibleRules, type Layer, type LayerFigures, layerFigures, type LayerSet, NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE, ruleSummary } from './layers.ts';
 import { padToSquare, squarePad } from './inputs.ts';
 import type { MotionSeamDeclaration } from './motionseams.ts';
@@ -308,6 +309,9 @@ export function singleRunPadRecord(single: boolean, sourceW: number, sourceH: nu
 }
 
 export interface AssembleInput {
+  depth?: DepthConfig;
+  /** Config-relative user sheet paths; caller supplies its actual base. */
+  depthBase?: string;
   /** The painting. Its alpha is ignored, as the reference's `convert("RGB")` drops it. */
   source: Raster;
   full: LayerSet;
@@ -1360,10 +1364,11 @@ export function applyArmSplit(set: LayerSet, resolution: number, armSplit: ArmSp
     ]);
   }
   const combinedRaw = newRaster(resolution, resolution);
-  for (const l of handLayers) {
+  const scalarOwners = handLayers.some(l => l.depthSheet !== undefined) ? new Int32Array(resolution * resolution).fill(-1) : null;
+  for (const [layerIndex, l] of handLayers.entries()) {
     const { canvas } = cleanGhosts(placeLayer(l, resolution));
     for (let p = 0; p < resolution * resolution; p++) {
-      if (canvas.data[p * 4 + 3] > 0) combinedRaw.data.set(canvas.data.subarray(p * 4, p * 4 + 4), p * 4);
+      if (canvas.data[p * 4 + 3] > 0) { combinedRaw.data.set(canvas.data.subarray(p * 4, p * 4 + 4), p * 4); if (scalarOwners !== null) scalarOwners[p] = layerIndex; }
     }
   }
   const { canvas: combined } = cleanGhosts(combinedRaw);
@@ -1470,7 +1475,7 @@ export function applyArmSplit(set: LayerSet, resolution: number, armSplit: ArmSp
     }
   }
   const refLayer = handLayers.reduce((best, l) => (l.opaquePx > best.opaquePx ? l : best), handLayers[0]);
-  const makeLayer = (name: 'handwear-r' | 'handwear-l', canvas: Raster, m: ReturnType<typeof maskOf>): Layer => ({
+  const makeLayer = (name: 'handwear-r' | 'handwear-l', canvas: Raster, m: ReturnType<typeof maskOf>): Layer => copyDepthMaterial({
     name,
     tag: readLayerTag(name) as LayerTagReading,
     file: refLayer.file,
@@ -1482,7 +1487,7 @@ export function applyArmSplit(set: LayerSet, resolution: number, armSplit: ArmSp
     depth: refLayer.depth,
     drawOrder: 0,
     opaquePx: m.opaque,
-  });
+  }, handLayers, (x, y) => { const owner = scalarOwners?.[Math.floor(y) * resolution + Math.floor(x)] ?? -1; return owner < 0 ? [] : [{ layer: handLayers[owner], x, y, weight: 1 }]; });
   const byTag = {
     'handwear-r': makeLayer('handwear-r', rightCanvas, mr),
     'handwear-l': makeLayer('handwear-l', leftCanvas, ml),
@@ -1779,7 +1784,7 @@ export function splitMergedArmRunsWithNotes(
         }
       }
       if (opaque === 0 || x1 < x0) return null;
-      return {
+      return copyDepthMaterial({
         name,
         tag: readLayerTag(name) as LayerTagReading,
         file: hwLayer.file,
@@ -1791,7 +1796,7 @@ export function splitMergedArmRunsWithNotes(
         depth: hwLayer.depth,
         drawOrder: 0,
         opaquePx: opaque,
-      };
+      }, [hwLayer], (x, y) => [{ layer: hwLayer, x, y, weight: 1 }]);
     };
     const drapeLayer = buildSplitLayer(`drape-${s}`, drapeCanvas);
     const sleeveLayer = buildSplitLayer(tag, sleeveCanvas);
@@ -2085,9 +2090,14 @@ function prepareHeadFace(
         bottom: y1 + 1,
         opaquePx: compOpaquePx,
       };
+      const copiedLayer = copyDepthMaterial(replacedLayer, [headFaceLayer, fullFaceLayer], (x, y) => {
+        const ta = cleanedHead.canvas.data[(Math.floor(y) * resolution + Math.floor(x)) * 4 + 3] / 255;
+        const sx = f32(frame.fullK / frame.headK), tx = f32(-(frame.headBox[0] + frame.fullPad) / frame.headK), ty = frame.fullPadTop === 0 && frame.headBox[1] === 0 ? 0 : f32(-(frame.headBox[1] + frame.fullPadTop) / frame.headK);
+        return [{ layer: headFaceLayer, x, y, weight: ta }, { layer: fullFaceLayer, x: (x - 0.5 - tx) / sx + 0.5, y: (y - 0.5 - ty) / sx + 0.5, weight: 1 - ta }];
+      });
       activeHead = {
         ...head,
-        layers: head.layers.map((l) => (l.name === 'face' ? replacedLayer : l)),
+        layers: head.layers.map((l) => (l.name === 'face' ? copiedLayer : l)),
       };
       if (underfillPx > 0) {
         underfillNote = `face: head_face_underfill composited full:face under head:face on the head canvas, filling ${underfillPx} transparent px (${rawStats.headOv} / ${fullPx} px, ${(rawStats.cov * 100).toFixed(1)}% -> ${postStats.headOv} / ${fullPx} px, ${(postStats.cov * 100).toFixed(1)}%)`;
@@ -2559,6 +2569,7 @@ export function figureSilhouette(srcr: Raster): Mask {
 }
 
 export interface PlacedPart {
+  depthImage?: Raster;
   record: PartRecord;
   image: Raster;
 }
@@ -4313,6 +4324,7 @@ export interface AssembleResult {
   hidden: HiddenArtUse[];
   seamRule: SeamRule;
   projectRule: ProjectRule;
+  depthReadings?: Array<{ from: string; reading: import('./depthsheets.ts').DepthReading }>;
   /** Issue #492: head-canvas pixels filled by `config.assemble.head_face_underfill: true` when > 0. */
   headFaceUnderfillPx?: number;
   /** Issue #587: what each `exclude` entry took, in entry order; empty without one. */
@@ -4475,8 +4487,17 @@ export function assemble(input: AssembleInput): AssembleResult {
     { sourceW: source.width, sourceH: source.height, resolution: input.resolution, headBox: input.headBox, rigScale: input.rigScale, ...(single ? { single: true } : {}) },
     { full: input.full, head: input.head },
   );
+  if (input.depthBase === undefined && (input.depth?.full !== undefined || input.depth?.head !== undefined)) refuseIfAny([{ code: 'DEPTH_SOURCE_BASE', object: 'assemble depthBase', detail: 'user sheet paths require the actual config-directory base; no process-cwd guess is made' }]);
+  const depthInputProblems: Problem[] = [];
+  const bind = (set: LayerSet, run: 'full' | 'head'): LayerSet => {
+    try { return bindDepthRun(set, run, input.depth, input.depthBase ?? ''); }
+    catch (error) { if (error instanceof PartsError) { depthInputProblems.push(...error.problems); return set; } throw error; }
+  };
+  const depthFullInput = bind(input.full, 'full');
+  const depthHeadInput = single ? depthFullInput : bind(input.head, 'head');
+  refuseIfAny(depthInputProblems);
   // Issue #366: one run's file, padded to the resolution square; read as both runs, as before.
-  const fullPadded = single ? padSingleRun(input.full, frame, input.resolution) : input.full;
+  const fullPadded = single ? padSingleRun(depthFullInput, frame, input.resolution) : depthFullInput;
   // Issue #439: when seethrough.arm_split is declared, split the full run's overlapping handwear into handwear-r and handwear-l.
   const fullArmSplit = input.armSplit === undefined ? fullPadded : applyArmSplit(fullPadded, input.resolution, input.armSplit);
   // Issue #490: when generation.control.skeleton is present, split merged arm layers (or refuse when sleeve and drape share one colour).
@@ -4494,10 +4515,13 @@ export function assemble(input: AssembleInput): AssembleResult {
     !single &&
     (plan.some(([, r, t]) => r === 'head' && t === 'face') || (plan.some(([, r]) => r === 'full') && plan.some(([, r]) => r === 'head')));
   const headFacePrep = checkHeadFace
-    ? prepareHeadFace(full, input.head, frame, input.resolution, input.headFaceUnderfill === true)
-    : { head: single ? full : input.head, underfillPx: 0, underfillNote: null };
+    ? prepareHeadFace(full, depthHeadInput, frame, input.resolution, input.headFaceUnderfill === true)
+    : { head: single ? full : depthHeadInput, underfillPx: 0, underfillNote: null };
   const head = headFacePrep.head;
   const padRecord = singleRunPadRecord(single, source.width, source.height, input.resolution, frame);
+  const depthFull = registerDepthRun(full, 'full', input.depth, input.depthBase ?? '');
+  const depthHead = single ? new Map<string, RegisteredDepth>() : registerDepthRun(head, 'head', input.depth, input.depthBase ?? '');
+  const registeredDepth = new Map([...depthFull, ...depthHead]);
   if (single) checkSingleRun(full, plan, extend);
   checkPlanAgainstRuns(sourcePlan, extend, full, head);
   const { W, H } = frame;
@@ -5074,10 +5098,30 @@ export function assemble(input: AssembleInput): AssembleResult {
     };
     if (pushedHere.length > 0) record.fringe_pushed_back = pushedHere;
     if (limb !== undefined) record.limb = limb;
-    set({ record, image: crop(r, x0, y0, record.w, record.h) });
+    const image = crop(r, x0, y0, record.w, record.h);
+    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, {
+      map: run => runMap(frame, run), width: W, extend: extendKeys, owner: trace.from,
+      ring: trace.ring.data, region: region?.data ?? null,
+      copiedSource: (x, y) => {
+        if (capSource === null || upperIndex < 0) return null;
+        const [bx, by, bw, bh] = capSource.box;
+        if (x < bx || y < by || x >= bx + bw || y >= by + bh || capSource.codes[(y - by) * bw + x - bx] !== CAP_FROM_UPPER) return null;
+        const upper = limbPieces[upperIndex], p = y * W + x, e = upper.trace.from[p];
+        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` } : {}),
+    });
+    if (scalar !== undefined) record.depth = scalar.reference;
+    set({ record, image, ...(scalar === undefined ? {} : { depthImage: scalar.image }) });
   });
   refuseIfAny(empty);
   const placed: PlacedPart[] = order.map((d) => ('plan' in d ? planned[d.plan] : 'cut' in d ? cutPlaced[d.cut] : 'limb' in d ? limbPlaced[d.limb] : cut[d.patch]) as PlacedPart);
+  const artFiles = new Set(placed.map(p => `${p.record.name}.png`));
+  for (const p of placed) if (p.record.depth !== undefined && artFiles.has(p.record.depth.image)) refuseIfAny([{ code: 'DEPTH_SHEET_UNAMBIGUOUS', object: p.record.depth.image, detail: 'collides with a part artwork filename; choose noncolliding part names before sheet emission' }]);
+
 
   seamOverride(placed, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null, keepInOrder);
   const can = recomposite(placed, W, H);
@@ -5115,6 +5159,7 @@ export function assemble(input: AssembleInput): AssembleResult {
       ...(padRecord === null ? {} : { single_run_pad: padRecord }),
     },
     images: placed,
+    ...(registeredDepth.size === 0 ? {} : { depthReadings: ([['full', depthFullInput], ...(single ? [] : [['head', depthHeadInput]])] as Array<['full' | 'head', LayerSet]>).flatMap(([run, set]) => set.layers.flatMap(layer => layer.depthSheet === undefined ? [] : [{ from: `${run}:${layer.name}`, reading: layer.depthSheet.reading }])) }),
     recomposite: can,
     errorMap: recompositeErrorMap(can, srcr, placed, inside),
     figure: inside === null ? null : figureImage(inside, W, H),

package/src/automotion.ts

@@ -84,7 +84,7 @@
  * Pure: no clock, no randomness, nothing read or written.
  */
 import { type AcceptedOperation, MeshReductionError, type AlphaMask, type ArtFitBounds, type MeasureRow, type MeshQualityReport, type MotionAmplitude, type MotionBounds, type MotionSchedule, writeMeshQualityReport } from 'rig-c/mesh';
-import { compareMeshesInMotion, type MotionComparisonInput } from 'rig-c/meshcompare';
+import { compareMeshesInMotion, comparePreparedMotion, prepareMotionReference, type MotionComparisonInput, type MotionReferenceInput, type PreparedMotionReference } from 'rig-c/meshcompare';
 import type { AutoMotionSpec } from './config.ts';
 import type { Problem } from './errors.ts';
 import { IDLE_FPS, type MotionSpec, type MotionTrack } from './motion.ts';
@@ -334,6 +334,26 @@ export function runComparison(object: string, input: MotionComparisonInput): Mes
   }
 }
 
+/** Bind the exact reference-side input for the sequential replay candidates. */
+export function prepareComparison(object: string, input: MotionReferenceInput): PreparedMotionReference | Problem {
+  try {
+    return prepareMotionReference(input);
+  } catch (err) {
+    if (!(err instanceof MeshReductionError)) throw err;
+    return { code: 'AUTO_MESH_MOTION_INPUT', object, detail: `rig-c's compareMeshesInMotion refused the comparison's input (${err.code}): ${err.message}; nothing is built in the part's place` };
+  }
+}
+
+/** Compare a fresh gated candidate under the prepared reference and its bound schedule/art/options. */
+export function runPreparedComparison(object: string, handle: PreparedMotionReference, input: MotionComparisonInput): MeshQualityReport | Problem {
+  try {
+    return comparePreparedMotion(handle, input);
+  } catch (err) {
+    if (!(err instanceof MeshReductionError)) throw err;
+    return { code: 'AUTO_MESH_MOTION_INPUT', object, detail: `rig-c's compareMeshesInMotion refused the comparison's input (${err.code}): ${err.message}; nothing is built in the part's place` };
+  }
+}
+
 /** A gated row in one phrase: code, region, state, value against its bound, the worst frame. */
 export function motionRowText(r: MeasureRow): string {
   const region = r.object.region === null ? '' : ` [region "${r.object.region}"]`;