@rig-c/parts 2.46.0 → 2.47.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/cli.ts CHANGED
@@ -608,7 +608,9 @@ usage:
608
608
  ${PARTS_HOME_SENTENCE}; ${NO_PARTS_SENTENCE}.
609
609
  Both are only read. Into --out:
610
610
  build/ (rigc build --profile rig-play --pack --page-edges <value>
611
- --pack-shape <value>: the packed atlas is the artifact), gate_spine-html.txt (the gate lines
611
+ --pack-shape <value>: the packed atlas is the artifact), build-report.json
612
+ (rigc's own build-report/1 for that compile, written verbatim beside
613
+ build/ on a failing compile as on a green one), gate_spine-html.txt (the gate lines
612
614
  verbatim), idle_frames/ (rigc render --animation idle --fps 12 --max 640
613
615
  --geometry: the frames and geometry.json, the skinned vertices and
614
616
  every bone's world transform per frame),
package/docs/AUTHORING.md CHANGED
@@ -178,7 +178,7 @@ read by no CPU stage).
178
178
  | `assemble.cuts` | assemble; `meshes`/`regions` keys may name the new parts too, and must (each is a part like any other) | **authored**, optional (issue #170): `[{from, into, polygon, draw, overlap, under, under_fill}]`, `under` and `under_fill` optional — a structural separation under [Source before scissors](#source-before-scissors), cut from a plan part's layer by the author's polygon: the pixels of plan part `from` whose **centre** lies inside `polygon` (even-odd; a centre exactly on an edge is outside) leave `from` and make the new part `into`, colour and alpha, so every pixel of the layer ends in exactly one of the two. `polygon` is `[[x, y], …]`, at least three points, non-negative integer **rig** pixels — the space of `parts.json` and of the patches' boxes. The file that shows the layer in those coordinates is `assemble`'s own `rig/parts/<from>.png`, placed at its `parts.json` `x`, `y` (the PNG's pixel `(i, j)` is rig pixel `(x + i, y + j)`), or `render/recomposite_rig.png`, the whole rig 1:1; the contact sheets (`sheet`) are scaled and carry no coordinates. `draw` is `"back"`, `"front"` or `{"before": "<plan part>"}`, as for a patch (to keep the setup pose, draw the piece immediately in front of `from` — `{"before": "<the plan part after from>"}`, or `"front"` when `from` is the last plan part; `{"before": "<from>"}` draws it behind `from`, which `under` refuses as `ASSEMBLE_UNDER_DRAW` because the fill would hide it). `from` must be a plan part (`CONFIG_NAME_RESOLVES`; a patch or another cut's piece is refused; a part a limb takes may be cut where no segment of the limb holds it, issue #564, §5 *Limbs*), `into` a new name (`CONFIG_PART_UNIQUE`), the polygon three or more integer points (`CONFIG_FIELD_TYPE`). The piece's `parts.json` record carries `from`'s `<run>:<tag>` and its own counts, each split from the layer's by where the pixel lies; it is a mesh or a region under its own name, and the coverage rule holds it like a plan part. What the config cannot know the stage refuses: a polygon point past the rig (`ASSEMBLE_CUT_INSIDE`), two cuts of one part sharing a pixel (`ASSEMBLE_CUT_OVERLAP`), a cut that takes none of the layer's opaque pixels or leaves `from` none (`ASSEMBLE_CUT_PIXELS`), a cut of a part a limb takes that takes a pixel a segment of the limb holds (`ASSEMBLE_CUT_CROSSES_LIMB`). `overlap` is required, a non-negative integer of rig pixels with no default (`CONFIG_FIELD_TYPE`): the **band** — the polygon's pixels within `overlap` px of its edge by Chebyshev distance (the polygon's mask less its erosion by a `2 * overlap + 1` square) — stays in `from` as well as going to the piece, so the piece's resampled edge has art under it; the counts stay a strict partition and the band is the base's extra copy, printed on the `cut:` line. At `0` the two abut and `check`'s seam bar judges the edge between them (`CHECK_SEAM_WITHIN_BAR`, §5). A band only covers the edge at rest: a piece that swings well clear of where it was painted shows the hole it leaves, and a thin piece's band shows a ghost of the piece. `under` (issues #193, #1230), optional, is the author's image of what lies under the piece: either a PNG path relative to the config's directory (`CONFIG_FIELD_TYPE` unless a non-empty string or `{"plate": "<dir>"}`), in rig pixels over the polygon's **bounding box** — the least and greatest polygon x and y, so the image is `max x − min x` by `max y − min y` and its pixel `(i, j)` is rig pixel `(min x + i, min y + j)` — or `{"plate": "<dir>"}` (`CONFIG_FIELD_PRESENT`, `CONFIG_KEY_KNOWN`, `CONFIG_FIELD_TYPE`), a receipted `comfy plate --mode occluder` directory relative to the config's directory whose `<dir>/receipt.json` (`CONFIG_FILE_PRESENT`, `PLATE_RECEIPT_*`) has `mode: "occluder"` (`PLATE_RECEIPT_KEYS`), `painting.sha256` equal to `--source` (`ASSEMBLE_UNDER_PLATE_PAINTING`), and `occluder.sha256` equal to the PNG bytes that `assemble --emit-fill-masks <dir>` writes for this cut (`ASSEMBLE_UNDER_PLATE_MASK`), resampled to rig pixels (`sourceInRig`) and cropped to the polygon's bounding box (`boxOf`) before feeding the same `fillUnder` path and recording `cut_ownership[i].under_plate` in `parts.json` (exempt from `editor_receipts.required` and `trace_parts`). Where the cut removed pixels from `from` — the piece's pixels (alpha above 0) less the band — `from` takes the image's pixel, colour and alpha wherever the image's alpha is at least the alpha the cut removed there (**filled**); elsewhere `from` stays empty there (**left empty**): a transparent pixel is the author's statement that nothing lies under it (the background, or a part drawn behind), and a less opaque one is not half-filled. The image is read nowhere else, so its pixels over the band, over the box outside the polygon or where the layer had no art never change `from`. The `cut:` line then ends `; under <n> px filled, <m> px left empty` (`n + m` is every removed pixel), so an unintended hole is a number in the log, not a guess; the filled pixels count in `from`'s `opaque_px` and `occluded_px` (the piece is drawn over them), never as visible or projected. The stage refuses: a file that is not there (`ASSEMBLE_UNDER_PRESENT`) or not a PNG (`ASSEMBLE_UNDER_DECODES`), an image not exactly the box's size (`ASSEMBLE_UNDER_SIZE`, both sizes given), an image that fills none of the removed pixels — all transparent there, or another file (`ASSEMBLE_UNDER_EMPTY`; to leave the whole hole, drop `under`), and a piece drawn behind `from` (`ASSEMBLE_UNDER_DRAW`: the fill would hide it; draw it `"front"` or `{"before": "<the plan part after from>"}`). Producing the image is the author's, by whatever means; absent, `from` keeps only its band. `under_fill` (issue #360), optional, is the one value `"colour"` (`CONFIG_FIELD_TYPE` on any other): the same pixels are filled and left empty, and a filled pixel takes the image's **colour** at the alpha the cut removed there instead of the image's alpha, so `from`'s alpha is the uncut layer's wherever the image fills and its silhouette does not grow — an opaque image over a soft edge leaves the edge soft. It applies to the part's hidden-art layer as well as to a file; a cut with neither is refused (`ASSEMBLE_UNDER_FILL_SOURCE`). The `cut:` line's filled count then says how many took the colour only: `; under 190 px filled (190 colour only, at the alpha the cut removed), 0 px left empty`. Absent, a filled pixel takes the image's colour and alpha, as above |
179
179
  | `assemble.alternates` | assemble, rig, check (`--set`, `--all-sets`) | **authored**, optional (issues #454, #465, #472, #473, #476): `[{name, source?, full?, head?, head_box?, parts?, hides?, cuts?, skeleton?, anchor?, base_anchor?, drawn?, tips?, front?}]` — alternate painting sets assembled into `<out>/rig/parts/<set>_<part>.png` (`parts.json` `alternates`), attached on each covered slot in `rig.json` as `<set>_<part>` beside the base attachment, and indexed in `<out>/rig/sets.json` (`rig-parts-sets/1`: `sets.<set>.slots`, `.hides`, `.drawn` when present, and `.threshold: {yaw: 15, pitch: 12}` when the set replaces `face` on a rig with `turn` or `turn`/`tilt` slider animations). `source`, `full` and `head` may instead be given on the CLI with `--alt <name>=<source>:<full>[:<head>]`. Windows absolute drive paths such as `C:\paint\painting.png` are accepted as written; each segment's leading drive colon belongs to that path, while other colons still separate `source`, `full` and `head`. `parts` lists the subset of parts the set replaces (default: every part not in `hides`); a **subset set** (issue #473, e.g. mouth visemes `a`, `i`, `u` with `"parts": ["mouth"]`) cuts only its covered parts from the alternate runs (refusing with `ASSEMBLE_ALT_INPUT_PRESENT` if a covered part's layer is missing or empty), writes only `{slot: "<set>_<slot>"}` in `sets.json` so `@rig-c/play`'s `setSet(name)` switches those slots while leaving every other slot on its base attachment (and `setSet(null)` restores the base pose), may be keyed on a slot attachment track in `motion.animations_from` as `{"t": …, "set": "<name>" \| null}` (`CONFIG_SET_COVERS_SLOT` if `"set"` is undeclared or does not cover the track's slot), and under `check --set <name>` counts `ANIMATIONS_DO_NOT_FOLD` only on its own covered slots; `hides` lists slots the set hides (`null` in `sets.json`). A **gesture subset set** (issue #476) covers a limb chain declared in `config.limbs.<limb>` (all of its segment `part`s; with `drawn` alone, cut at the base's joints posed to the set's own `drawn` angles by `poseBoneEntriesForDrawn`, each segment keeping the base's length; with `skeleton` (issue #539), cut at the skeleton's own joint positions by `placeBoneEntriesForSkeleton` — each covered bone the body-18 table names (`sleeve_*`, `arm_*0`/`arm_*1`, `leg_*0`/`leg_*1`) at its skeleton origin with the skeleton segment's own length and direction (`drawn` overriding the direction of a bone it names), and a covered bone the table does not name (a hand link `arm_r2`, a single `foot_r`) placed from its parent's new place — its base offset from the parent, stretched along the parent by the parent's length change and turned by its turn, so a link or a foot at the parent's end lands on the skeleton's end — with its base length and the drawn or base direction, so a foreshortened shin or forearm is cut where it is painted; naming the unsplit `from` layer, covering only some segments of the limb, or declaring polygon `cuts` on a limb set is refused with `CONFIG_LIMB_SET_JOINTS`) and carries `drawn` (or `skeleton`) for the covered bones only (giving `drawn` for an uncovered bone is refused with `CONFIG_SET_COVERS_BONE` / `RIG_SET_COVERS_BONE`; uncovered bones keep the base's `drawn`). A subset set's limb part takes no pixel that a base part drawn after it, which the set neither covers nor hides, covers at setup (issue #587): the set's attachment is drawn in the base slot's place, so that base part is drawn over it and what the set's painting shows there is that base part (shorts over a leg set's thigh top, which See-through synthesised in the set's leg layer); `assemble` clears those pixels — the base part's PNG at alpha above 8, at its `parts.json` x, y, on the shared canvas — from the set's part once its limbs are cut, before any count — its `merged_px` and its cap's record too (issue #603): a cap pixel it clears leaves the count it was in (`layer_px`, `image_px`, `upper_px`, `lower_px`, `lower_kept_px`) for the cap's `excluded_px`, written only when above 0, so every count is the written PNG's — and prints `LINT set "<set>" <part>: <n> px under <base part> excluded` per part and base part that took a pixel (n counts alpha above 8); a set that carries that base part itself (`"parts": ["thigh_l", "shin_l", "bottomwear"]`) excludes nothing and writes what it wrote before. A subset set that names one limb side of a layer more limbs take (issue #588: `"parts": ["thigh_r", "shin_r"]` where `leg_r` and `leg_l` both take the one `legs` layer) would put every pixel of that layer on its one limb, so each of its parts would hold a piece of both legs; when the set's layer holds more than one island (8-connected pixels with alpha above 8) of at least 1 % of its largest (issue #608: the ghost clean-up's own share; a smaller island is a speck, which goes with the island nearest it — the one holding the pixel centre nearest one of the speck's, none when two are equally near — and is never an island of its own), each segment part keeps the island its joints fall on — its bone's origin and the next segment's bone's origin, at the set's own bones, a joint on the island of a pixel whose square holds the point, and a joint on no island on the one island whose nearest pixel centre lies within the radius of the cap cut at that joint (`cap.radius`: an ankle just past the legwear's edge, on the shoe) — and drops the rest, once its limbs are cut and before the exclusion above, and `assemble` prints `LINT set "<set>" <part>: <layer part> holds <n> islands (8-connected, alpha above 8)[, and <s> speck(s) under 1 % of the largest (<f> px), each with the island nearest it], kept the one under <bone> [x, y] and <bone> [x, y][ (<e> px off it, within its cap's radius <r>)] (<k> px), dropped <m> (<d> px)` per part (k and d count the part's pixels above alpha 8, m the islands it lost one from, and `dropped none` when it lost none); a joint on no island with none or two within that radius, or with no cap cut at it (a limb's first joint), and a segment whose joints fall on two, are refused with `ASSEMBLE_ALT_LIMB_ISLAND` rather than guessed. A layer of one island — specks aside — may hold both legs over each other (a folded shin across the standing leg; issue #609): each of the set's segment parts then keeps the pixels nearer its own limb's segment line — the polyline of only its segments taking that source, their bone origins and the last segment's supplied tip or following segment's joint (issue #638) — than the other limb's, both in the set's pose, and gives the rest away, once its limbs are cut and before the exclusion above; a pixel whose two distances differ by 0.5 px or less (the overlap band: half a pixel, the reach by which a pixel centre is read as on a line) goes to the limb whose part there is drawn later in the base's draw order, and the `LINT set` line above counts what each part kept, gave and held in the band. The other limb stands where the set's `skeleton` places it — its keypoints place every limb bone of the body-18 table, the other leg's as well as the set's own (its `drawn` and `drawnLength` stay the covered bones') — and never at the base's place: a set that does not place it (a `drawn` set, which may not name a bone it does not cover, or a set with neither) is refused with `ASSEMBLE_ALT_LIMB_POSE` when its layer has art where the base draws that limb, and when it has none nothing says the layer holds it and the layer is cut as before; two limbs whose segment lines run closer than the limb's half-width over most of where their art can meet are refused with `ASSEMBLE_ALT_LIMB_OVERLAP`. A set that carries every limb of the layer is cut as before. For a subset set, where a limb's own source layer holds art (`alpha > 8`) under another layer of that run drawn in front (`alpha > 8`, by the projection's plan/depth order), the limb keeps its own layer pixels through projection, limb cutting, island/nearest-line assignment, base-footprint exclusion, fringe clearing and seam correction (issue #637). Those pixels are occluded, never counted as painting projection; no base footprint or painting colour replaces them. After source-art island/nearest-line assignment, a source-transparent cap pixel is assigned before protection, in both doors: its centre is compared against only the segments taking the recipient's source, at the set's supplied bones (ankle-to-toe for a separate foot source), with the existing 0.5 px overlap band and base draw order. A missing last endpoint is refused with `ASSEMBLE_ALT_LIMB_POSE`; an actual following joint may supply that endpoint, never a guessed point. An unposed other limb with base art beneath these cap pixels is likewise refused; without such overlap the existing compatible path retains the cap without inventing the other limb's pose. A pixel cleared by this assignment is never restored. `CAP_FROM_UPPER` records a copy made before assignment and alone proves no ownership: only a retained copy is protected beneath the upper segment, which is drawn over it. The source-art island selection itself is unchanged. Other retained cap pixels (from the layer or a supplied cap image) are protected under an actual front layer even where the lower source is transparent. Protection follows each assigned piece through exclusion, fringe clearing and seam correction; it never restores a pixel ownership removed. Cap pixels removed during ownership leave their original counts for `excluded_px`, just as excluded pixels do, so the cap ledger describes the written PNG. Target assignment reconciles this ledger even when there are no source-transparent cap candidates and when a direct caller does not request cover protection. Unprotected source pixels still obey the base-footprint exclusion. Missing limb/cap art is never extended or guessed. Base builds and uncovered, unexcluded sets keep their existing bytes. `skeleton` (a pose file path relative to the config's directory, `{"width": W, "height": H, "points": {…}}` with all 18 body-18 keypoints on the canvas, validated by the same rules as `generation.control.skeleton`: `CONFIG_FILE_PRESENT`, `CONFIG_IS_JSON`, `CONFIG_FIELD_TYPE`, `CONFIG_KEY_KNOWN`, `CONFIG_KEY_UNIQUE`, `CONFIG_POSE_CANVAS`, `CONFIG_POSE_KEYPOINTS`, `CONFIG_POSE_IN_CANVAS`) or `drawn` (`{<bone>: <worldDegrees>}`, each bone resolved against `bones`, `CONFIG_NAME_RESOLVES`) declares the posed angles the alternate was painted at (issue #465); when `skeleton` is given, `assemble` derives `drawn` from its 18 keypoints (filtered to covered bones on a subset set, with `drawn` overriding any bone named in both), records both `skeleton` (scaled by `assemble.rig_scale` to rig px) and `drawn` in `parts.json` `alternates` — and, when the skeleton placed the set's limb bones (issue #539), `drawnLength` (`{<bone>: <ratio>}`, each covered table bone's skeleton segment length over its base length, 6 places) and `registration` (`{offset: [dx, dy], scale}`: the similarity without rotation, about the canvas origin, that maps the skeleton's torso — the mean of its shoulders `r_shoulder`/`l_shoulder` to the mean of its hips `r_hip`/`l_hip`, read where the base declares the bone rooted there, `sleeve_*0`/`arm_*0` and `leg_*0` — onto those base bones' origins, 6 places), both also written to `sets.json`; the set's painting must be registered, its torso within 1 rig px and 1 % in scale of the base's, or the set is refused by name before any joint is cut (`ASSEMBLE_ALT_SKELETON_REGISTERED`, with the offset and scale the painting would need) — and the `rig` stage writes `<set>_*` region and mesh attachments in the bone-local frame of `poseRigBonesForDrawn(bones, drawn)` (weighting limb segments directly from `skeleton`'s joint endpoints when `skeleton` is present) and emits `drawn` in `sets.json` so `rig-pose` and `check --set <name>` / `--all-sets` pose the bones at `drawn` without rotating the already-posed art a second time. `front` (issue #664) lists covered limb segment parts the set draws on their **front slot** instead of the base slot: each must be in the set's `parts` and not its `hides`, and listed in some `config.limbs.<limb>.front.parts` (`CONFIG_SET_FRONT`); the set then maps `<part>_front` (never `<part>`) to `<set>_<part>` in `parts.json` and `sets.json` and hides `<part>` (and `<part>_still`), its #587 exclusion counts only base parts drawn after the front slot's target, and keying that part's set on a slot track is refused (`CONFIG_SET_FRONT_KEYED`) — *Front slots (issue #664)* below `layers` optionally maps covered, nonhidden output part names to layer names in their existing source run (issue #666); for example `"layers": {"upperarm_r": "author:raised", "forearm_r": "author:raised"}`. Limb cuts, caps, islands and base exclusions read the selected layer; the base plan stays unchanged. |
180
180
  | `assemble.head_face_underfill` | assemble, `assemble --propose-plan` | **authored**, optional (issue #492): `boolean` (`CONFIG_FIELD_TYPE` on any other). During head-face preparation, when both runs exist and `full:face` has at least `150` opaque run px (`PROPOSE_MIN_PX`), the stage maps `full:face` into the head canvas via `fullLayerToHead` and measures how much of its hole-filled silhouette (`alpha > 8`) is covered by `head:face` (`alpha > 8`). An explicit plan selecting `head:face` is refused when that layer covers less than `75 %` (`HEAD_FACE_COVERAGE_FLOOR`, measured `0.0 %..48.6 %` on hollow/omitted head runs vs `84.8 %..99.6 %` on clean head runs across the 4 public examples and 9-standee corpus), with `SEETHROUGH_HEAD_RUN_HOLLOW`, unless `head_face_underfill: true` is declared. When `head_face_underfill: true` is declared and `head:face` exists (`opaqueRunPx >= 150`), `fullLayerToHead(full:face)` is composited under `head:face` on the head canvas (`alpha = max(headAlpha, fullAlpha)`, RGB blended by `headAlpha / 255`) before `head:face` is placed in rig space (`underfill=<N>px(full:face)` on the `face` part log line and a `face: head_face_underfill composited …` note in `assemble --propose-plan`). The fill restores transparent pixels only and leaves the cut's own edge where it is — a hollow whose edge is not under hair stays visible; follow [Source before scissors](#source-before-scissors) for its source remedy. When `head:face` has fewer than `150` opaque pixels, `SEETHROUGH_HEAD_RUN_HOLLOW` still fires even under `head_face_underfill: true` because the head run omitted the face layer and cannot supply a jawline. The proposer instead selects `full:face` after this refusal when that full-run candidate passes the pixel floor and plausibility guards (issue #863); if it does not, the refusal remains. An assemble plan selecting `full:face` without `head:face` does not prepare the unused head face |
181
- | `assemble.yield_refused` | assemble | **authored**, optional boolean, default `false` (issue #819; other types: `CONFIG_FIELD_TYPE`). With `true`, an original front projection-core pixel refused at max-channel drift > `DRIFT_LIMIT` (90) can yield when its original source pixel is still opaque. Non-core rim pixels (0 < alpha < `CORE_ALPHA`, 250) on the same 8-connected part body can then yield too (issue #832). Connectivity reads the part support before clearing: the opaque border outside the eroded projection core connects the body to its rim but is not itself newly cleared. A separate rim island without a yielded core seed is unchanged. At every cleared pixel, the actual top-most opaque holder below it (alpha >= 250), after earlier yields, must have colour within 90 of the painting. A deeper matching part cannot bypass an intervening opaque mismatch. This setting also applies to alternate sets. A yielded pixel's alpha becomes 0 and its RGB is not repainted. Accepted own-core pixels in the same connected support within the original yielded core's Gaussian footprint (radius 4 rig pixels), with a matching opaque behind holder, finish to painting RGB while retaining alpha and ownership (issue #841); original refusals, protected samples and replacements are excluded. Away from that footprint projection is unchanged. Merge/ring replacements, samples explicitly kept by `keep_under_occluders`, and pixels outside a derived piece cannot connect a rim or be newly yielded. Front is relative to the matching part behind, so original refusals in another run are eligible even when a different part is the global top holder. The reading proceeds back to front against the current behind pixels; alpha changes do not repaint or create a new matching colour. `yieldReadings` optionally records `finishedProjection` (accepted samples whose RGB changed), and records `yieldedRim` as the rim subset of total `yielded`, skipped core merge/ring/nonopaque/no-match counts and original/final global holders; a yielded pixel also taken by projection closing is omitted from the written `source_px_taken` count. Existing cuts/patches and thresholds are unchanged. The `drift:` line reports `yielded N px` per affected part, even below the drift-body size bar; with the setting off it names `assemble.yield_refused: true` as the conditional remedy. Rebuild and inspect the newly exposed layer in motion before considering any cut; a mismatching or absent behind holder cannot be repaired by this setting. |
181
+ | `assemble.yield_refused` | assemble | **authored**, optional boolean or nonempty list of final yielding part names, default `false` (issues #819 and #1384). With `true` every eligible part can yield. With a list, only listed parts can clear refused pixels. The behind-holder lookup reads unlisted parts with all their pixels still in place. A listed part whose matching holder would only appear after an unlisted part yields sees that unlisted part unchanged. A listed part’s behind-holder is recoloured where the yield exposes it, by the same seam pass as `true`. Use final output names, including the names of pieces made by cuts or limb splits. Source tags and aliases fail `CONFIG_NAME_RESOLVES` when they do not name a final output. Repeats fail `CONFIG_PART_UNIQUE`. An empty list fails `CONFIG_FIELD_TYPE`; use `false` or omit the key. An original front projection-core pixel refused at max-channel drift > `DRIFT_LIMIT` (90) can yield when its original source pixel is still opaque. Non-core rim pixels (0 < alpha < `CORE_ALPHA`, 250) on the same 8-connected part body can then yield too (issue #832). Connectivity reads the part support before clearing: the opaque border outside the eroded projection core connects the body to its rim but is not itself newly cleared. A separate rim island without a yielded core seed is unchanged. At every cleared pixel, the actual top-most opaque holder below it (alpha >= 250), after earlier yields, must have colour within 90 of the painting. A deeper matching part cannot bypass an intervening opaque mismatch. This setting also applies to alternate sets. Assembly reports `ASSEMBLE_YIELD_NOTHING` by name when a listed part yields no eligible projection refusal in the base or any alternate, a fact measured after projection. A changed list makes an existing assembly reading stale (`ASSEMBLY_CONFIG_STALE`). A yielded pixel's alpha becomes 0 and its RGB is not repainted. Accepted own-core pixels in the same connected support within the original yielded core's Gaussian footprint (radius 4 rig pixels), with a matching opaque behind holder, finish to painting RGB while retaining alpha and ownership (issue #841); original refusals, protected samples and replacements are excluded. Away from that footprint projection is unchanged. Merge/ring replacements, samples explicitly kept by `keep_under_occluders`, and pixels outside a derived piece cannot connect a rim or be newly yielded. Front is relative to the matching part behind, so original refusals in another run are eligible even when a different part is the global top holder. The reading proceeds back to front against the current behind pixels; alpha changes do not repaint or create a new matching colour. `yieldReadings` optionally records `finishedProjection` (accepted samples whose RGB changed), and records `yieldedRim` as the rim subset of total `yielded`, skipped core merge/ring/nonopaque/no-match counts and original/final global holders; a yielded pixel also taken by projection closing is omitted from the written `source_px_taken` count. Existing cuts/patches and thresholds are unchanged. The `drift:` line reports `yielded N px` per affected part, even below the drift-body size bar; with the setting off it names `assemble.yield_refused: true` as the conditional remedy. Rebuild and inspect the newly exposed layer in motion before considering any cut; a mismatching or absent behind holder cannot be repaired by this setting. |
182
182
  | `assemble.keep_under_occluders` | assemble | **authored**, optional array of unique source part names from `assemble.plan`, default `[]` (issue #825). For each named part, keep its own See-through RGBA where the front-most covering part in the final draw stack has alpha greater than 0 and below `CORE_ALPHA` (250), including a cover in the other run. Covers at raw alpha <= 8 are ghosts and are not kept under; a ghost-cleaned sample with final alpha 0 is absent cover and does not trigger restoration. Only original opaque own-layer samples are restored after source projection/closing and protected from later seam re-take; merged/rim, cap, under-fill and authored replacement pixels are excluded. This keeps their existing provenance and makes no holes; fully opaque cover and absent cover keep the old path. Cuts and limb pieces inherit the source part's protection. Unknown names: `CONFIG_NAME_RESOLVES`; duplicates: `CONFIG_PART_UNIQUE`; invalid shape: `CONFIG_FIELD_TYPE`. Inspect the part's own amodal layer first: this handle preserves its existing content and cannot complete a missing pixel — in particular, it does not close a motion opening inside the figure (`figure_openings` / [Openings inside the figure on undeclared layer pairs](#openings-inside-the-figure-on-undeclared-layer-pairs-issue-933)) where the lower layer has no opaque core under an opaque upper layer (measured with every `assemble.plan` part named in `keep_under_occluders`: `0` of `1` pair-animation warnings across `demo`'s eight animations closed, with `hair_back\|handwear_r` on `hop` frame `5` staying at `40` cells over `28` allowed in `38x70` world units at `2.517` world units/cell, while `scarf` reads `CLEAR` (`0` warnings) both with and without `keep_under_occluders`; use `assemble.extend_painting` when the lower part lacks opaque source material under an opaque upper cover). Example: `"keep_under_occluders": ["shin_r"]`. |
183
183
  | `assemble.require_hidden_extent` | assemble, build | **authored**, optional array of unique `{part, occluder}` source-name pairs from `assemble.plan` (issue #1047). The distinct occluder must draw after the part. Before cleanup, projection, underfill, cuts or limb splitting, the original selected source is normalized to the rig grid. Own support is alpha >8. Its enclosed holes are `fillHoles(support) \ support`, using four-connected exterior background. Any hole cell under the resolved front-most named occluder (alpha >8) refuses `ASSEMBLE_HIDDEN_EXTENT_ABSENT`. Zero holes with measurable filled-support overlap passes. No overlap or unavailable original ancestry refuses `ASSEMBLE_HIDDEN_EXTENT_UNMEASURED`. A region take's output (`assemble.take`) counts as the selected source. Cover resolves over `assemble.plan` source families only; cut slots are not resolved as cover, which is a stated limit. Omitted or `[]` adds no reading or output. This is a source-support bar reached by build at assemble. See [Original hidden extent required](#original-hidden-extent-required). |
184
184
  | `assemble.occluders` | assemble, build | **authored**, optional (issues #1230, #1237, #1241, #1246, #1251, #1259): `[{image, sha256, under, over?, plate?, part?, grow?, guard?, rgb_within}]` — an RGBA PNG of what stands in front of the character on the painting's grid (`image`, relative to the config's directory; another size refuses `ASSEMBLE_OCCLUDER_GRID`), its bytes' sha256 (`CONFIG_OCCLUDER_SHA256`), the plan parts it stands over (`under`, `CONFIG_NAME_RESOLVES`), optional distinct plan parts that draw this occluder (`over`, `CONFIG_NAME_RESOLVES`, `CONFIG_PART_UNIQUE`), optional receipted plate directory (`plate`, `ASSEMBLE_OCCLUDER_PLATE_*`), optional part name (`part`, `CONFIG_FIELD_TYPE`, `CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE`, `CONFIG_PART_ATTACHED`), optional non-negative integer rig-px dilation radius (`grow`, `CONFIG_FIELD_TYPE`; absent means `0`), optional non-negative integer rig-px under-keep dilation radius (`guard`, `CONFIG_FIELD_TYPE`; absent means `0`), and an integer 0–255 (`rgb_within`). After any take and before projection, a pixel of an `under` part's selected layer at alpha above 128, where the occluder's alpha is above 0, within `rgb_within` (max channel) of the painting there, is the occluder's colour copied into the layer: `assemble` prints `WARN ASSEMBLE_OCCLUDER_COLOUR_COPIED` with the part, the rig px count and the first pixel. On the rig grid, occluder membership is the boolean core where the occluder image's alpha is strictly above `128` (`COPIED_ALPHA_ABOVE`), dilated by `growMask`'s `(2 * grow + 1)^2` square when `grow > 0` (`parts.json` records top-level `occluder_grow` with `{occluder, image, grow, covered_px_before, covered_px_after}` for each entry with `grow > 0`; the occluder-split take and `occluders[i].plate` do not read `grow`); holding is a front part's alpha at or above `250` (`CORE_ALPHA`). Under `--project visible`, an `under` part's pixels (and every cut piece or limb segment derived from it) inside the under-keep mask — the `alpha > 128` core dilated by `max(grow, guard)` via `growMask`'s `(2 * r + 1)^2` square (`parts.json` records top-level `occluder_guard` with `{occluder, image, guard, guarded_px_before, guarded_px_after}` for each entry with `guard > 0`; `guard` paints nothing, changes neither `occluders[i].part` nor `ASSEMBLE_OCCLUDER_UNHELD`, has no effect when `guard <= grow` though the record is still written, and is not read by the occluder-split take or `occluders[i].plate`) — keep the base run's surface rather than projecting `--source`. When `over` is declared, each `(over, under)` pair in an entry draws `over` in front of `under` regardless of mixed-run depth or two-run role band (`ASSEMBLE_OCCLUDER_DRAW_ORDER` if `assemble.plan` draws `over` behind `under`, `ASSEMBLE_OCCLUDER_DRAW_CYCLE` on contradictory `over`/`under` cycles, `ASSEMBLE_OCCLUDER_OVER_TAKEN` if an `over` part's layer is not taken by `assemble.take`). When `part` is declared, `assemble` emits a `painting:<part>` part (`parts/<part>.png`, placed immediately before the first slot of any `over` part of that entry across `full` and `head`, counting pieces cut from an `over` part — "before the first `over` part" wins when a piece derived from `under` sits after `over`, and when `over` is omitted the part is placed after the last slot derived from `under`) holding `--source` at alpha `255` over the occluder membership (`alpha > 128`, after `grow`) minus the pixels held at `alpha >= 250` (`CORE_ALPHA`) by every part drawn in front of it (`ASSEMBLE_OCCLUDER_EMPTY` if `0` rig px remain); when `part` is omitted and any occluder pixel (`alpha > 128`, after `grow`) is not held at `alpha >= 250` (`CORE_ALPHA`) by a part drawn in front of it, `assemble` prints `WARN ASSEMBLE_OCCLUDER_UNHELD` with the count and first pixel. |
@@ -1184,7 +1184,12 @@ A changed crop, scale, name or order needs a plan or cut change instead.
1184
1184
  Record a receipt with the shipped writer (issue #1328) after declaring
1185
1185
  `assemble.edited_parts` with its directory and an empty `receipts` array in
1186
1186
  each named config. `--config` accepts the assembly config, including the full
1187
- config after `propose --write-config`. Use the [parts assembled from that config](#keeping-assembled-parts-current).
1187
+ config after `propose --write-config`. Finalize the effective assembly inputs,
1188
+ including `turn` and `constraints.physics`, then assemble again. Start the edit
1189
+ from the PNG written by that assembly and use that same PNG as `--from`.
1190
+ Pass its manifest with `edited-part --parts` so `ASSEMBLY_CONFIG_STALE` can
1191
+ name any assembly fields that changed since it was written. See
1192
+ [Keeping assembled parts current](#keeping-assembled-parts-current).
1188
1193
 
1189
1194
  ```sh
1190
1195
  rig-parts edited-part --config draft/config.json --parts assembled/parts.json --part sleeve_r --file retouched/sleeve_r.png --from assembled/parts/sleeve_r.png --producer '{"tool":"image-editor","script_sha256":"<lowercase 64-hex digest>"}'
@@ -4567,8 +4572,11 @@ and a usage error with `--head-box`, `--cloth` or `--from-config`.
4567
4572
 
4568
4573
  Use one config through `assemble` → `propose --write-config` → `assemble` →
4569
4574
  `edited-part`. The first assemble supplies the parts for drafting `turn`.
4570
- An already authored turn can be present for the first assemble. Use the second
4571
- assemble's `parts.json` and PNGs to prepare and record an edit. Declare
4575
+ An already authored turn can be present for the first assemble. Finalize all
4576
+ effective assembly inputs, including `turn` and `constraints.physics`, before
4577
+ assembling again. Use that assembly's PNGs as the edit baselines and pass its
4578
+ manifest to `edited-part --parts`. If effective inputs changed after assembly,
4579
+ `ASSEMBLY_CONFIG_STALE` names the changed fields. Declare
4572
4580
  `assemble.edited_parts` with its directory and empty receipts before that
4573
4581
  assemble, then assemble again to apply the recorded edit.
4574
4582
 
@@ -5915,7 +5923,7 @@ recorded transform. The record fields and sampling formula are specified in
5915
5923
  | <a id="ASSEMBLE_EDITED_PART_UNKNOWN"></a>`ASSEMBLE_EDITED_PART_UNKNOWN` | A receipt names a part outside the base plan. | Use the existing base-plan part name; a new name needs a plan change. |
5916
5924
  | <a id="ASSEMBLE_EDITED_PART_FILE"></a>`ASSEMBLE_EDITED_PART_FILE` | The receipt file does not exist at dir/file. | Correct the config-relative dir or the directory-relative file, or supply that file. |
5917
5925
  | <a id="ASSEMBLE_EDITED_PART_SHA256"></a>`ASSEMBLE_EDITED_PART_SHA256` | The edited file bytes do not match sha256. | Use the intended edited file and record its exact file hash. |
5918
- | <a id="ASSEMBLE_EDITED_PART_BASELINE"></a>`ASSEMBLE_EDITED_PART_BASELINE` | The current normal assembled part PNG does not match from_sha256. | Rebase the edit on this config's current assembled part and record that original file hash. |
5926
+ | <a id="ASSEMBLE_EDITED_PART_BASELINE"></a>`ASSEMBLE_EDITED_PART_BASELINE` | The current normal assembled part PNG does not match from_sha256. | Finalize the effective assembly inputs, including `turn` and `constraints.physics`, and assemble again. Rebase and record the edit using the new baseline. Run `edited-part --parts` with the prior manifest and current config to identify stale fields via `ASSEMBLY_CONFIG_STALE`. |
5919
5927
  | <a id="ASSEMBLE_EDITED_PART_SIZE"></a>`ASSEMBLE_EDITED_PART_SIZE` | The edited PNG width or height differs from the assembled box. | Edit at the original crop and rig-pixel size; use a plan change for a new box. |
5920
5928
  | <a id="ASSEMBLE_EDITED_PART_DUPLICATE"></a>`ASSEMBLE_EDITED_PART_DUPLICATE` | More than one receipt names the same part. | Keep exactly one receipt for that part. |
5921
5929
  | <a id="ASSEMBLE_EDITED_PART_DECODES"></a>`ASSEMBLE_EDITED_PART_DECODES` | The verified file cannot be decoded as a PNG. | Supply a valid PNG and update its receipt hash. |
@@ -5943,6 +5951,7 @@ recorded transform. The record fields and sampling formula are specified in
5943
5951
  | <a id="ASSEMBLE_PAINTING_CANVAS"></a>`ASSEMBLE_PAINTING_CANVAS` | a callable extension stage receives a part outside the rig canvas | pass the final in-canvas assembled stack with its crop offsets |
5944
5952
  | <a id="ASSEMBLE_PART_OPAQUE"></a>`ASSEMBLE_PART_OPAQUE` | a part ended with no opaque pixel | drop the entry, or take the tag from the other run |
5945
5953
  | <a id="ASSEMBLE_HIDDEN_EXTENT_ABSENT"></a>`ASSEMBLE_HIDDEN_EXTENT_ABSENT` | a declared `assemble.require_hidden_extent` pair has an enclosed own-source hole beneath its resolved front-most occluder, before cleanup or any writer. The refusal names both source parts, original run:tag, absent/overlap rig-cell counts, soft/opaque cover counts and the first cell | supply a source that already carries the extent, such as a second decomposition run. That source-production route is separate from this change. [Original hidden extent required](#original-hidden-extent-required) states the domain and open-cuff boundary |
5954
+ | <a id="ASSEMBLE_YIELD_NOTHING"></a>`ASSEMBLE_YIELD_NOTHING` | a part named in `assemble.yield_refused` yielded zero pixels across the base and alternate sets | inspect that part’s projection drift and the actual opaque holder behind it; this is an assembly observation |
5946
5955
  | <a id="ASSEMBLE_HIDDEN_EXTENT_UNMEASURED"></a>`ASSEMBLE_HIDDEN_EXTENT_UNMEASURED` | a declared pair has no filled own-support overlap under the resolved occluder, empty own support, unavailable original selected-layer ancestry or a partial alternate replacing only one declared source family | resolve the original sources and their declared overlap. An empty hole set with measurable overlap is a valid zero reading. See [Original hidden extent required](#original-hidden-extent-required) |
5947
5956
  | <a id="ASSEMBLE_OCCLUDER_COLOUR_COPIED"></a>`ASSEMBLE_OCCLUDER_COLOUR_COPIED` (WARN) | a selected layer of an `assemble.occluders` `under` part holds pixels (alpha above 128) under the occluder (alpha above 0) within `rgb_within` of the painting: the decomposition painted the thing in front into the surface behind it | take the part from a See-through run on the painting with the occluder removed (`comfy plate --mode occluder`), as `--full`, with the occluder's own layers taken from the painting's run through `assemble.take` |
5948
5957
  | <a id="CONFIG_OCCLUDER_SHA256"></a><a id="ASSEMBLE_OCCLUDER_GRID"></a>`CONFIG_OCCLUDER_SHA256`, `ASSEMBLE_OCCLUDER_GRID` | an `assemble.occluders` image whose bytes do not hash to its declared `sha256`; an occluder image whose size is not the painting's | declare the bytes the image holds; export the occluder on the painting's grid |
@@ -6663,7 +6672,14 @@ assemble*, at the end of this section):
6663
6672
 
6664
6673
  - `gate_spine-html.txt`: every summary line `(N passed, 0 failed)` — the packed build
6665
6674
  under the `rig-play` profile, gated once over the compile and once over the packed
6666
- pages on disk. There is no `spine` gate of its own: `rig-play` holds every rule
6675
+ pages on disk. Beside `build/`, `build-report.json` (`<out>/check/build-report.json`
6676
+ under `build` and `compose`; `<out>/build-report.json` under standalone `check`) holds
6677
+ rigc's own `build-report/1` (`--report`) for that primary packed compile, written
6678
+ verbatim by `rigc` (and listed in `build/run.json`'s `outputs[]` as
6679
+ `../build-report.json`) on a failing compile as on a green one (issue #1394); `rig`
6680
+ keeps no compile report because its compiles (the gate scratch and the `--lead-in`
6681
+ scratch) are throwaway runs whose outputs are deleted. There is no `spine` gate of
6682
+ its own: `rig-play` holds every rule
6667
6683
  `spine` measures (on reference-demo, rigc 1.5.1 and 2.0.3: `validate --profile spine`'s 14
6668
6684
  measured rules are all among the build's 23, the 15 others not in `spine`; rigc
6669
6685
  2.1.3 and 2.10.1: the same 14 among the build's 24, which adds
@@ -8968,6 +8984,12 @@ rig-parts depth-apply --parts assembled --manifest inference/manifest.json --con
8968
8984
  rig-parts rig --parts mapped --config mapped/config.json --out compiled
8969
8985
  ```
8970
8986
 
8987
+ When parts.json carries an assembly config digest, use a rig config with the
8988
+ same assembly inputs. `depth-apply` checks both the supplied config and the
8989
+ config it would emit with the recipe applied. If either changes the assembly
8990
+ reading, it reports [`ASSEMBLY_CONFIG_STALE`](#ASSEMBLY_CONFIG_STALE) before
8991
+ writing the mapped output. A successful handoff carries the original digest.
8992
+
8971
8993
  The separate recipe is not a new field on character config:
8972
8994
 
8973
8995
  ```json
package/docs/STABILITY.md CHANGED
@@ -344,7 +344,16 @@ New assemble and build manifests carry an optional top-level `assembly_config`
344
344
  object shaped as `{ sha256, fields: [{ name, sha256 }] }`. Its lowercase
345
345
  SHA-256 digests describe the effective assembly config inputs, in deterministic
346
346
  field-name order. Entries name the individual inputs, such as
347
- `assemble.rig_scale`. The aggregate binds the ordered field names and digests.
347
+ `assemble.rig_scale`. Field names use dot-separated lowercase keys. From this
348
+ version the manifest reader also accepts one indexed form,
349
+ `assemble.take[i].meta` (split donor metadata, `i` zero-based), and refuses
350
+ every other indexed name. A later version may accept more indexed names. A
351
+ reader refuses a name it does not accept with `PARTS_FIELD_TYPE`, so a
352
+ consumer upgrades Parts before it reads manifests written by a newer one.
353
+ Earlier readers refuse `assemble.take[i].meta`, so release Parts first, then
354
+ upgrade and release Review, then update both pins in Create before those
355
+ consumers read split-take manifests written by this release.
356
+ The aggregate binds the ordered field names and digests.
348
357
  Declared assembly files are resolved relative to their declaring config or
349
358
  requirements file and hashed by content. Equivalent path spellings give the
350
359
  same reading. A built-in control skeleton is identified by its name and latent
@@ -360,6 +369,12 @@ checks a recorded digest against a config refuses a mismatch as
360
369
  `ASSEMBLY_CONFIG_STALE`, names the changed fields and directs the author to
361
370
  re-run assemble.
362
371
 
372
+ An occluder-split take binds the donor's `meta.json` bytes at
373
+ `assemble.take[i].meta`, where `i` is the zero-based take index. When only
374
+ these new fields are missing from an older stamp, the stale refusal says
375
+ that the stamp predates the binding and asks for one re-assemble with the
376
+ same config.
377
+
363
378
  The stable named subpath `@rig-c/parts/assembly-reading` exports
364
379
  `assemblyConfigReading(configPath: string, parts: PartsFile): AssemblyConfigRecord`
365
380
  and `assemblyConfigChanges(configPath: string, parts: PartsFile): string[]`.
@@ -571,7 +586,7 @@ part name, `[i]` an entry of a list):
571
586
  - **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
572
587
  - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`, `arm_split`
573
588
  - **seethrough.arm_split** — required: `order`, and one of `x` or `line` (issue #439)
574
- - **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `project`, `ground`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `stage_map`, `keep_under_occluders`, `require_hidden_extent`, `extend_painting`, `edge_splits`, `take`, `editor_receipts`, `edited_parts`, `occluders`
589
+ - **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `project`, `ground`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `stage_map`, `keep_under_occluders`, `require_hidden_extent`, `extend_painting`, `edge_splits`, `take`, `editor_receipts`, `edited_parts`, `occluders`. The yield setting accepts a boolean or a nonempty list of final yielding output part names. The list is bound to the assembly config reading.
575
590
  - **assemble.edge_splits[i]** — required: `over`, `under`, `band`
576
591
  - **assemble.require_hidden_extent[i]** — required: `part`, `occluder`
577
592
  - **assemble.occluders[i]** — required: `image`, `sha256`, `under`, `rgb_within`; optional: `over`, `plate`, `part`, `grow`, `guard` (issues #1230, #1237, #1241, #1246, #1251, #1259)
@@ -988,7 +1003,7 @@ execution in historical evidence is inferred from a current export.
988
1003
  | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), `excluded_px` after them only on a subset set's limb part whose cap the set exclusion took a pixel of (issue #603, additive: each pixel taken out of the count it was in, so the cap's counts are the written PNG's), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px` — on a subset set's limb part counted after the set exclusion, issue #603 — `seam_override_px`, and `fringe_pushed_back` when not empty); per-part `taken_layers` (with optional `transport`, issue #973, and optional `split` — `occluder`, `image`, `sha256`, `covered_px`, `visible_px` — on a split take, additive, issue #1242) and `provenance` (`unchanged_layer_px`, `hand_px`, `automatic_px`, `edits`, `automatic`, additive, issue #823); optional top-level [`assembly_config`](#assembly-config-reading), `motion_seams`, `occluder_plates` (one record per `assemble.occluders` entry declaring `plate` — `receipt`, `receipt_sha256`, `occluder_sha256`, `painting_sha256`, `output_sha256`, `mask_sha256`, additive, issue #1237), `occluder_grow` (one record per `assemble.occluders` entry with `grow > 0` — `occluder`, `image`, `grow`, `covered_px_before`, `covered_px_after`, additive, issue #1251), `occluder_guard` (one record per `assemble.occluders` entry with `guard > 0` — `occluder`, `image`, `guard`, `guarded_px_before`, `guarded_px_after`, additive, issue #1259), `alternates` and `cut_ownership` (one row per cut, independent of RGBA equality, issue #823, with optional `under_plate` — `receipt`, `receipt_sha256`, `occluder_sha256`, `painting_sha256`, `output_sha256`, `mask_sha256` — on a `{plate}` under, additive, issue #1230); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242), and the same bytes beside `parts.json` when the two directories differ (issue #1177); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
989
1004
  | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
990
1005
  | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones` (the sorted names the attachment's weights bind in the written `rig.json`, in every mode — since 1.49.1 (issue #536) a rig with `turn` or `stops` names the twins and `<link>_d` bones there, where the row named the segment bones they replace: a fix of a wrong name, not a format change; a rig with neither writes the bytes it wrote), `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); or `mode` "explicit" with `image_sha256` and `region_sha256` (the verified guards; counts and coverage are measured from the supplied mesh, no legacy generator report is adopted); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
991
- | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | [Check verdict spec](#check-report-rig-parts-check1) followed by the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode` (with `page_size` under `--page-size` only, issue #1273, additive), `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #941 adds optional `required` only under the requirements file's `seam_over_motion.required: true` — `status` (`PASS` or `FAIL`), `mode` `gap-open`, `bar_px` 0, `pairs` (each `pair`, `class` — `body-root`, `internal-joint` or `explicit` — `frames`, `background_frames`, `max_px`) and `failed` — and with it the key is written even when no pair is declared; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes. Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
1006
+ | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | [Check verdict spec](#check-report-rig-parts-check1) followed by the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode` (with `page_size` under `--page-size` only, issue #1273, additive), `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #941 adds optional `required` only under the requirements file's `seam_over_motion.required: true` — `status` (`PASS` or `FAIL`), `mode` `gap-open`, `bar_px` 0, `pairs` (each `pair`, `class` — `body-root`, `internal-joint` or `explicit` — `frames`, `background_frames`, `max_px`) and `failed` — and with it the key is written even when no pair is declared; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes, and `check/build-report.json` (`<out>/build-report.json` under standalone `check`) is rig-c's own `build-report/1` (`--report`) for that primary packed compile, written verbatim by `rigc` beside `check/build/` (and listed in `check/build/run.json`'s `outputs[]` as `../build-report.json`) on a failing compile as on a green one (issue #1394; `rig` keeps no compile report because its gate and `--lead-in` compiles are throwaway scratch runs whose outputs are deleted). Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
992
1007
  | `part_support_domains.json` | `assemble`, `build` | optional `rig-parts-support-domains/1` independent cut masks and unavailable reasons, with per-domain config-entry provenance and parts/PNG/payload digests; additive beside parts.json, whose bytes and PNGs are unchanged. Legacy output may omit it. `PART_SUPPORT_REPORT` reads pairs in the assembly placement frame and Unowned in actual setup, never as an acceptance gate. |
993
1008
  | `layers.json`, `<index>_<name>.png` | `layers --export` | the wrapper form `layers` reads (issue #359): `width`, `height`, then `layers` — each `name`, `filename`, `left`, `top`, `right`, `bottom`, `depth_median` (the input's own; `null` for a PSD, the manifest's order then being the draw order) — drawn layers in draw order, then the hidden-art layers; a PNG's name is its index and its layer's name, and the manifest, not the file name, says which layer it is |
994
1009
  | the template `.psd` | `layers --template` | one empty layer per name `templateLayerNames` (`src/layers.ts`) holds, bottom first; the same canvas writes the same bytes |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/parts",
3
- "version": "2.46.0",
3
+ "version": "2.47.0",
4
4
  "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
5
5
  "type": "module",
6
6
  "exports": {
@@ -1,5 +1,6 @@
1
1
  /** Per-covered-part alternate sources; all coordinates and pixels stay in their original run. */
2
2
  import type { Cut, Limb, PlanEntry } from './config.ts';
3
+ import type { AssemblyLimb } from './assembly-reading.ts';
3
4
  import type { OtherLimbs } from './assemble.ts';
4
5
  import { refuseIfAny, type Problem } from './errors.ts';
5
6
  import { readLayerTag } from './tags.ts';
@@ -16,7 +17,7 @@ export interface AlternateLayerSources {
16
17
 
17
18
  /** Resolve output names before the stage checks required layers. Never mutate the base plan or limb declarations. */
18
19
  export function alternateLayerSources(
19
- plan: PlanEntry[], cuts: Cut[], limbs: Record<string, Limb>, covered: ReadonlySet<string>, layers?: Readonly<Record<string, string>>,
20
+ plan: PlanEntry[], cuts: Cut[], limbs: Record<string, AssemblyLimb>, covered: ReadonlySet<string>, layers?: Readonly<Record<string, string>>,
20
21
  ): AlternateLayerSources {
21
22
  if (layers === undefined || Object.keys(layers).length === 0) return { plan, cuts, limbs, cutLayers: new Map(), groups: new Map() };
22
23
  const problems: Problem[] = [];
package/src/assemble.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { projectAssemblyConfig, type AssemblyLimb, type AssemblySource, type AssemblyView } from './assembly-reading.ts';
1
2
  import { sourceCoverRun, type SourceCoverReading } from './sourcecover.ts';
2
3
  import { replaceEditedParts, type EditedPartContext, type EditedPartFrontColourReading, type VerifiedEditedPart } from './editedparts.ts';
3
4
  import { paintingReceivers, rawPaintingOwner, type PaintingOwner } from './paintingowner.ts';
@@ -119,7 +120,7 @@ import { COPIED_ALPHA_ABOVE, OCCLUDER_EMPTY, occluderDrawCycleProblems, type Occ
119
120
  * Pure: no clock, no randomness, no file access. The CLI reads and writes.
120
121
  */
121
122
  import { sourceLimbTarget, nearestTargetPart } from './limbownership.ts';
122
- import { type ArmSplit, type BoneEntry, type CharacterConfig, type ConfigConstraint, type ControlSkeleton, controlSkeletonOf, type CropEdge, type Cut, type EarlyConfig, type Extend, type Limb, type MeshSpec, type Patch, type PlanEntry, type RegionSpec, type Run, type SeeThrough, turnMovingPartPair, type TurnSpec } from './config.ts';
123
+ import { type ArmSplit, type BoneEntry, type ControlSkeleton, controlSkeletonOf, type CropEdge, type Cut, type EarlyConfig, type Extend, type MeshSpec, type Patch, type PlanEntry, type RegionSpec, type Run, type SeeThrough, turnMovingPartPair, type TurnSpec } from './config.ts';
123
124
  import { foldName, PartsError, type Problem, refuseIfAny } from './errors.ts';
124
125
  import { CORE_ALPHA, figuresPhrase, implausibleRules, type Layer, type LayerFigures, layerFigures, type LayerSet, NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE, ruleSummary } from './layers.ts';
125
126
  import { padToSquare, squarePad } from './inputs.ts';
@@ -237,7 +238,7 @@ export interface Geometry {
237
238
  /** `assemble.head_face_underfill` (issue #492): composite `full:face` under `head:face` on the head canvas to fill transparent bare-skin holes. */
238
239
  headFaceUnderfill?: boolean;
239
240
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
240
- yieldRefused?: boolean;
241
+ yieldRefused?: boolean | readonly string[];
241
242
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
242
243
  keepUnderOccluders?: readonly string[];
243
244
  /** `assemble.occluders` as declared (issue #1247; `AssembleInput.occluders` carries the decoded images): declared occluder entries whose `over` parts sit after their `under` parts in a proposed plan. */
@@ -335,7 +336,7 @@ export interface AssembleInput {
335
336
  turn?: TurnSpec;
336
337
  regions?: Record<string, RegionSpec>;
337
338
  meshes?: Record<string, MeshSpec>;
338
- motion?: CharacterConfig['motion'];
339
+ motion?: AssemblyView['motion'];
339
340
  depth?: DepthConfig;
340
341
  /** Config-relative user sheet paths; caller supplies its actual base. */
341
342
  depthBase?: string;
@@ -371,7 +372,7 @@ export interface AssembleInput {
371
372
  /** `config.scene` (issue #242): the painting is a scene, so the recomposite is read inside the figure ({@link sceneFigure}). Absent or false: nothing changes. */
372
373
  scene?: boolean;
373
374
  /** `config.limbs` (issue #349): the parts cut at their joints ({@link LimbCount}). Absent or empty: nothing changes. */
374
- limbs?: Record<string, Limb>;
375
+ limbs?: Record<string, AssemblyLimb>;
375
376
  /** Alternate sources with different layers retain the original joint cut bounds. */
376
377
  limbSourceGroups?: ReadonlyMap<string, string>;
377
378
  /** `config.bones`, read for the limbs' joints; required with `limbs`. */
@@ -389,7 +390,7 @@ export interface AssembleInput {
389
390
  /** `assemble.head_face_underfill` (issue #492): composite `full:face` under `head:face` on the head canvas to fill transparent bare-skin holes. */
390
391
  headFaceUnderfill?: boolean;
391
392
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
392
- yieldRefused?: boolean;
393
+ yieldRefused?: boolean | readonly string[];
393
394
  /** Report-only last-writer sidecar, default off. */
394
395
  stageMap?: boolean;
395
396
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
@@ -455,7 +456,7 @@ export interface OtherLimbs {
455
456
  /** Issue #638's test-only pre-fix mutant; absent uses only segments taking the source. No CLI/config field. */
456
457
  line?: 'whole-limb';
457
458
  /** The config's limbs, by name, that the set does not carry and that take one of `limbIslands`. */
458
- limbs: Readonly<Record<string, Limb>>;
459
+ limbs: Readonly<Record<string, AssemblyLimb>>;
459
460
  /**
460
461
  * Per limb, its segment bones the set does not place: neither its skeleton names it (`SKELETON_LIMB_BONES`) nor
461
462
  * its `drawn`, nor an ancestor of it. Empty: the limb stands where the set's own bones (`bones`) put it.
@@ -553,8 +554,8 @@ export interface IslandCount {
553
554
  * limb that takes a part shares its pixels by the nearest polyline, so each limb gets its own side; a set that carries
554
555
  * fewer of them puts every pixel of the part on the limbs it carries, both legs of a two-leg layer on one leg.
555
556
  */
556
- export function setIslandSources(limbs: Readonly<Record<string, Limb>>, setLimbs: Readonly<Record<string, Limb>>): string[] {
557
- const takes = (all: Readonly<Record<string, Limb>>, src: string): number => Object.values(all).filter((l) => l.segments.some((sg) => sg.from === src)).length;
557
+ export function setIslandSources(limbs: Readonly<Record<string, AssemblyLimb>>, setLimbs: Readonly<Record<string, AssemblyLimb>>): string[] {
558
+ const takes = (all: Readonly<Record<string, AssemblyLimb>>, src: string): number => Object.values(all).filter((l) => l.segments.some((sg) => sg.from === src)).length;
558
559
  const froms = [...new Set(Object.values(setLimbs).flatMap((l) => l.segments.map((sg) => sg.from)))];
559
560
  return froms.filter((src) => takes(limbs, src) > takes(setLimbs, src));
560
561
  }
@@ -679,7 +680,7 @@ function squaredDistanceTo(cc: Components, W: number, label: number, at: readonl
679
680
  * transparent (a `cap_shape: "ball"` lower half from the cap image) is on no island and kept.
680
681
  */
681
682
  /** Layer variants share the original source's segment line for ownership, without changing its pixel source. */
682
- function logicalSourceLimb(limb: Limb, source: string, groups: ReadonlyMap<string, string>): Limb {
683
+ function logicalSourceLimb(limb: AssemblyLimb, source: string, groups: ReadonlyMap<string, string>): AssemblyLimb {
683
684
  if (!groups.has(source)) return limb;
684
685
  const original = groups.get(source);
685
686
  return { ...limb, segments: limb.segments.map(s => (groups.get(s.from) ?? s.from) === original ? { ...s, from: source } : s) };
@@ -687,7 +688,7 @@ function logicalSourceLimb(limb: Limb, source: string, groups: ReadonlyMap<strin
687
688
 
688
689
  function keepJointIslands(
689
690
  sources: readonly string[],
690
- limbs: Readonly<Record<string, Limb>>,
691
+ limbs: Readonly<Record<string, AssemblyLimb>>,
691
692
  bones: readonly BoneEntry[],
692
693
  parts: readonly LimbPart[],
693
694
  pieces: readonly Built[],
@@ -918,7 +919,7 @@ function skeletonsTooClose(own: readonly LinePt[], other: readonly LinePt[], hal
918
919
  function splitOneIsland(
919
920
  src: string,
920
921
  source: Built,
921
- limbs: Readonly<Record<string, Limb>>,
922
+ limbs: Readonly<Record<string, AssemblyLimb>>,
922
923
  places: ReadonlyMap<string, BonePlace>,
923
924
  parts: readonly LimbPart[],
924
925
  pieces: readonly Built[],
@@ -965,10 +966,10 @@ function splitOneIsland(
965
966
  if (refused || posed.length === 0) return;
966
967
  // Issue #638: a separate footwear layer belongs to the ankle-to-toe segments, not to a nearby thigh or shin.
967
968
  // The same source selection applies to every segment, without reading a part name or a layer tag.
968
- const taking = (l: string, all: Readonly<Record<string, Limb>>): Limb => others.line === 'whole-limb'
969
+ const taking = (l: string, all: Readonly<Record<string, AssemblyLimb>>): AssemblyLimb => others.line === 'whole-limb'
969
970
  ? all[l]
970
971
  : { ...all[l], segments: logicalSourceLimb(all[l], src, sourceGroups).segments.filter((sg) => sg.from === src) };
971
- const polyOf = (l: string, all: Readonly<Record<string, Limb>>): Array<[number, number]> =>
972
+ const polyOf = (l: string, all: Readonly<Record<string, AssemblyLimb>>): Array<[number, number]> =>
972
973
  others.line === 'whole-limb' ? limbPolyline(all[l], places) : sourceLimbTarget(logicalSourceLimb(all[l], src, sourceGroups), src, places).line;
973
974
  for (const [l, all] of [...ownNames.map((l) => [l, limbs] as const), ...posed.map((l) => [l, others.limbs] as const)]) {
974
975
  const selected = taking(l, all);
@@ -1072,7 +1073,7 @@ function splitOneIsland(
1072
1073
  * a source verdict. Cap origin is provenance, never proof of ownership.
1073
1074
  */
1074
1075
  function assignCapOwnership(
1075
- sources: readonly string[], limbs: Readonly<Record<string, Limb>>, bones: readonly BoneEntry[],
1076
+ sources: readonly string[], limbs: Readonly<Record<string, AssemblyLimb>>, bones: readonly BoneEntry[],
1076
1077
  parts: readonly LimbPart[], pieces: readonly Built[], sourceOf: (name: string) => Built | null,
1077
1078
  capFrom: ReadonlyArray<CapFrom | null>, W: number, H: number, others?: OtherLimbs, tips?: Record<string, [number, number]>,
1078
1079
  sourceGroups: ReadonlyMap<string, string> = new Map(),
@@ -4346,7 +4347,7 @@ function shiftedAt(line: JointLine, offset: number): [number, number] {
4346
4347
  function limbBands(
4347
4348
  cuts: readonly Cut[],
4348
4349
  pieces: ReadonlyArray<Built | null>,
4349
- limbs: Readonly<Record<string, Limb>>,
4350
+ limbs: Readonly<Record<string, AssemblyLimb>>,
4350
4351
  bones: readonly BoneEntry[],
4351
4352
  W: number,
4352
4353
  H: number,
@@ -4441,7 +4442,7 @@ function limbBands(
4441
4442
  * box's size, or transparent over every cap pixel).
4442
4443
  */
4443
4444
  function cutLimbs(
4444
- limbs: Readonly<Record<string, Limb>>,
4445
+ limbs: Readonly<Record<string, AssemblyLimb>>,
4445
4446
  bones: readonly BoneEntry[],
4446
4447
  caps: ReadonlyMap<string, Raster>,
4447
4448
  W: number,
@@ -4533,7 +4534,7 @@ function cutLimbs(
4533
4534
  const underNames = on.filter((l) => l !== coverLimb);
4534
4535
  const underIndices = underNames.map((l) => names.indexOf(l));
4535
4536
  const underPolys = underNames.map((l) => polylines.get(l) as Array<[number, number]>);
4536
- assignCrossedLimbs(coverIdx, polylines.get(coverLimb) as Array<[number, number]>, limbs[coverLimb].split as NonNullable<Limb['split']>, underIndices, underPolys, b.r, OPAQUE_ALPHA_ABOVE, own);
4537
+ assignCrossedLimbs(coverIdx, polylines.get(coverLimb) as Array<[number, number]>, limbs[coverLimb].split as NonNullable<AssemblyLimb['split']>, underIndices, underPolys, b.r, OPAQUE_ALPHA_ABOVE, own);
4537
4538
  }
4538
4539
  owners.set(src, own);
4539
4540
  jobs.push({ src, b, on, own, before });
@@ -5230,7 +5231,7 @@ export function checkSingleRun(full: LayerSet, plan: readonly PlanEntry[] | null
5230
5231
 
5231
5232
  /** All output pieces that consume a taken source, including cut-to-limb paths.
5232
5233
  * Painting patches have no source-part edge in the supported Patch schema. */
5233
- export function regionTakeTargets(names: readonly string[], cuts: readonly Cut[], limbs: Readonly<Record<string, Limb>> = {}): ReadonlySet<string> {
5234
+ export function regionTakeTargets(names: readonly string[], cuts: readonly Cut[], limbs: Readonly<Record<string, AssemblyLimb>> = {}): ReadonlySet<string> {
5234
5235
  const targets = new Set(names);
5235
5236
  const edges = cuts.map(c => ({ from: c.from, into: c.into }));
5236
5237
  for (const limb of Object.values(limbs)) for (const [index, segment] of limb.segments.entries()) {
@@ -6163,9 +6164,11 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6163
6164
  const stackNames = stack.map((q) => q.record.name);
6164
6165
  const drift: DriftBodies[] = [];
6165
6166
  const yields = new Map<string, { mask: Mask; reading: DriftYieldReading }>();
6167
+ const yieldSelection = typeof input.yieldRefused === 'object' ? new Set(input.yieldRefused) : null;
6166
6168
  order.forEach((d, orderIdx) => {
6167
6169
  if ('patch' in d) return;
6168
6170
  const { name, b } = pieceAt(d);
6171
+ const yieldPart = input.yieldRefused === true || yieldSelection?.has(name) === true;
6169
6172
  if (b.st.refusedMask === null) return;
6170
6173
  const refused = newMask(W, H);
6171
6174
  for (let p = 0; p < W * H; p++) if (b.st.refusedMask.data[p] === 1 && (b.region === null || b.region.data[p] === 1)) refused.data[p] = 1;
@@ -6176,7 +6179,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6176
6179
  if (under[p * 4 + 3] < CORE_ALPHA) continue;
6177
6180
  // The opt-in resolves the actual exposed opaque holder before comparing its colour.
6178
6181
  // Keep the legacy matching-holder diagnostic unchanged when the setting is off.
6179
- if (input.yieldRefused === true) { behindAt[p] = j; continue; }
6182
+ if (yieldPart) { behindAt[p] = j; continue; }
6180
6183
  const dMax = Math.max(
6181
6184
  Math.abs(under[p * 4] - srcr.data[p * 4]),
6182
6185
  Math.abs(under[p * 4 + 1] - srcr.data[p * 4 + 1]),
@@ -6185,7 +6188,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6185
6188
  if (dMax <= DRIFT_LIMIT) behindAt[p] = j;
6186
6189
  }
6187
6190
  }
6188
- if (input.yieldRefused === true) {
6191
+ if (yieldPart) {
6189
6192
  for (let p = 0; p < W * H; p++) {
6190
6193
  if (behindAt[p] < 0) continue;
6191
6194
  const under = stack[behindAt[p]].image.data;
@@ -6200,7 +6203,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6200
6203
  // The refusal belongs to b.key. A copied/ring replacement cannot inherit that source's refusal.
6201
6204
  // "Front" is relative to behindAt, not the fixed global top holder: another run may cover this source.
6202
6205
  let yielded = 0;
6203
- if (input.yieldRefused === true) {
6206
+ if (yieldPart) {
6204
6207
  const mask = newMask(W, H);
6205
6208
  const reading: DriftYieldReading = { part: name, from: b.key, refusedCandidates: 0, yielded: 0, yieldedRim: 0, yieldedTaken: 0, skipped: { merge: 0, ring: 0, notOpaque: 0, noMatchingBehind: 0 }, originalGlobalHolderWouldSkip: 0, originalHolders: [], finalHolders: [] };
6206
6209
  const holders = new Map<string | null, number>();
@@ -6263,10 +6266,10 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6263
6266
  reading.originalHolders = [...holders].map(([part, px]) => ({ part, px }));
6264
6267
  yields.set(name, { mask, reading });
6265
6268
  }
6266
- const found = driftBodies(name, b.key, refused, bodyMinPx(frame), holderAt, stackNames, behindAt, input.yieldRefused === true ? yielded : undefined);
6267
- if (found !== null) drift.push(found);
6269
+ const found = driftBodies(name, b.key, refused, bodyMinPx(frame), holderAt, stackNames, behindAt, yieldPart ? yielded : undefined);
6270
+ if (found !== null) drift.push(yieldPart && yieldSelection !== null ? { ...found, scopedYield: true } : found);
6268
6271
  });
6269
- if (input.yieldRefused === true) {
6272
+ if (input.yieldRefused === true || yields.size > 0) {
6270
6273
  const finalAt = new Int32Array(W * H).fill(-1);
6271
6274
  stack.forEach(({ image }, i) => { for (let p = 0; p < W * H; p++) if (image.data[p * 4 + 3] >= CORE_ALPHA) finalAt[p] = i; });
6272
6275
  for (const { mask, reading } of yields.values()) {
@@ -6804,7 +6807,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6804
6807
  uncovered,
6805
6808
  holeKinds: kinds,
6806
6809
  drift,
6807
- ...(input.yieldRefused === true ? { yieldReadings: [...yields.values()].map(q => q.reading) } : {}),
6810
+ ...(input.yieldRefused === true || yieldSelection !== null ? { yieldReadings: [...yields.values()].map(q => q.reading) } : {}),
6808
6811
  ...(occluderUnheldWarnings.length === 0 ? {} : { occluderUnheldWarnings }),
6809
6812
  hidden: [...hiddenUses].map(([layer, readBy]) => ({ layer, readBy })),
6810
6813
  seamRule,
@@ -6829,6 +6832,8 @@ export { edgeSplitLines };
6829
6832
 
6830
6833
  /** A part whose `DRIFT_LIMIT` refusals hold a body, and which parts the draw order puts there. */
6831
6834
  export interface DriftBodies {
6835
+ /** An explicit part list enabled the yield reading for this part. */
6836
+ scopedYield?: true;
6832
6837
  /** The part, and its `<run>:<tag>`. */
6833
6838
  part: string;
6834
6839
  from: string;
@@ -6931,7 +6936,7 @@ export function driftLine(d: DriftBodies): string {
6931
6936
  "informational: no gate reads this. Swapping the plan order of the parts named here can clear it (when only the front one differs from the painting) or move it to the other part (when both do): swap, rebuild and read this line again; if it moves, removing it needs different input layers. At rest, the seam pass repaints the holder's pixels that pass its rule from the painting" +
6932
6937
  (d.yieldedPx === undefined
6933
6938
  ? '; set assemble.yield_refused: true to yield original refused front pixels and their connected non-core rims only where the top-most opaque behind holder matches the painting, before considering a cut'
6934
- : `; yielded ${d.yieldedPx} px to top-most opaque behind holders matching the painting (assemble.yield_refused: true; alpha only)`)
6939
+ : `; yielded ${d.yieldedPx} px to top-most opaque behind holders matching the painting (${d.scopedYield ? 'listed in assemble.yield_refused' : 'assemble.yield_refused: true'}; alpha only)`)
6935
6940
  );
6936
6941
  }
6937
6942
 
@@ -7701,24 +7706,19 @@ function unplannedNotes(
7701
7706
  // ---------------------------------------------------------------------------
7702
7707
 
7703
7708
  /**
7704
- * The config fields the stage reads: `seethrough.resolution` and `.head_box`,
7705
- * `assemble.rig_scale`, `.plan`, `.extend_below_crop`, `.patches` and `.cuts` — and
7706
- * nothing of the rig. The CLI hands it a config from
7707
- * `parseEarlyConfig(raw, 'assemble')`; a config the full loader accepted is
7708
- * the same shape with more in it. The head box is refused here rather than by
7709
- * the loader, because `inputs` runs before it exists; `seethrough` too, for a
7710
- * full-loader config, where it is optional.
7709
+ * Select the assembly view before deriving geometry. A full-loader config may
7710
+ * omit seethrough, and an early config can precede the head-box declaration.
7711
+ * Keep those refusals here, where the run shape is known.
7711
7712
  */
7712
7713
  export function stageFields(
7713
- cfg: Pick<CharacterConfig, 'seethrough' | 'assemble' | 'scene' | 'motion_seams'> & {
7714
- limbs?: Record<string, Limb>;
7715
- bones?: BoneEntry[];
7716
- meshes?: Record<string, MeshSpec>;
7717
- regions?: Record<string, RegionSpec>;
7718
- constraints?: ConfigConstraint[];
7719
- turn?: TurnSpec;
7720
- motion?: CharacterConfig['motion'];
7721
- },
7714
+ cfg: Omit<AssemblySource, 'key' | 'proposed_rig_scale'>,
7715
+ single: { w: number; h: number } | null = null,
7716
+ ): ReturnType<typeof projectedStageFields> {
7717
+ return projectedStageFields(projectAssemblyConfig(cfg).config, single);
7718
+ }
7719
+
7720
+ export function projectedStageFields(
7721
+ cfg: AssemblyView,
7722
7722
  single: { w: number; h: number } | null = null,
7723
7723
  ): {
7724
7724
  resolution: number;
@@ -7730,14 +7730,14 @@ export function stageFields(
7730
7730
  cuts: Cut[];
7731
7731
  motion_seams?: MotionSeamDeclaration[];
7732
7732
  scene?: boolean;
7733
- limbs?: Record<string, Limb>;
7733
+ limbs?: Record<string, AssemblyLimb>;
7734
7734
  bones?: BoneEntry[];
7735
7735
  single?: boolean;
7736
7736
  armSplit?: ArmSplit;
7737
7737
  keySkeleton?: ControlSkeleton;
7738
7738
  headFaceUnderfill?: boolean;
7739
7739
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
7740
- yieldRefused?: boolean;
7740
+ yieldRefused?: boolean | readonly string[];
7741
7741
  /** Report-only last-writer sidecar, default off. */
7742
7742
  stageMap?: boolean;
7743
7743
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
@@ -7752,7 +7752,7 @@ export function stageFields(
7752
7752
  turn?: TurnSpec;
7753
7753
  regions?: Record<string, RegionSpec>;
7754
7754
  meshes?: Record<string, MeshSpec>;
7755
- motion?: CharacterConfig['motion'];
7755
+ motion?: AssemblyView['motion'];
7756
7756
  /** `assemble.ground` (issue #996); absent, `plain`. */
7757
7757
  ground?: Ground;
7758
7758
  } {
@@ -7764,8 +7764,8 @@ export function stageFields(
7764
7764
  problems.push({ code: 'ASSEMBLE_FIELD_PRESENT', object: 'config.seethrough.head_box', detail: 'is absent; the head run cannot be placed on the painting without the box it was cropped from' });
7765
7765
  }
7766
7766
  refuseIfAny(problems);
7767
- const st = cfg.seethrough as SeeThrough;
7768
- const keySkeleton = controlSkeletonOf(cfg);
7767
+ const st = cfg.seethrough!;
7768
+ const keySkeleton = cfg.keySkeleton;
7769
7769
  const turnMovingPair = turnMovingPartPair(cfg);
7770
7770
  return {
7771
7771
  resolution: st.resolution,
@@ -7789,7 +7789,7 @@ export function stageFields(
7789
7789
  patches: cfg.assemble.patches ?? [],
7790
7790
  cuts: cfg.assemble.cuts ?? [],
7791
7791
  ...(cfg.motion_seams === undefined ? {} : { motion_seams: cfg.motion_seams }),
7792
- ...(cfg.scene === undefined ? {} : { scene: true }),
7792
+ ...(cfg.scene === undefined ? {} : { scene: cfg.scene }),
7793
7793
  ...(cfg.limbs === undefined ? {} : { limbs: cfg.limbs, bones: cfg.bones ?? [] }),
7794
7794
  };
7795
7795
  }