@rig-c/parts 2.45.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/docs/STABILITY.md CHANGED
@@ -338,6 +338,53 @@ files nor changes its inputs. Inputs that resolve from the rig or parts director
338
338
  (seam and `cut_material` part images, `cut_material_sources.json`) are not listed,
339
339
  because the caller already carries that directory with the check.
340
340
 
341
+ ## Assembly config reading
342
+
343
+ New assemble and build manifests carry an optional top-level `assembly_config`
344
+ object shaped as `{ sha256, fields: [{ name, sha256 }] }`. Its lowercase
345
+ SHA-256 digests describe the effective assembly config inputs, in deterministic
346
+ field-name order. Entries name the individual inputs, such as
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.
357
+ Declared assembly files are resolved relative to their declaring config or
358
+ requirements file and hashed by content. Equivalent path spellings give the
359
+ same reading. A built-in control skeleton is identified by its name and latent
360
+ size. A missing declared input produces a named refusal.
361
+ The `assemble.seam` and `assemble.project` entries hash the effective rules,
362
+ resolved in order from the CLI override, the config value and the default.
363
+ `build` carries its effective rules to the in-process rig and check stages.
364
+ Standalone validation derives its reading from the caller's config. That
365
+ config must resolve to the rules used at assembly time, including any values
366
+ originally selected by `--seam` or `--project`.
367
+ Legacy manifests without `assembly_config` remain accepted. A consumer that
368
+ checks a recorded digest against a config refuses a mismatch as
369
+ `ASSEMBLY_CONFIG_STALE`, names the changed fields and directs the author to
370
+ re-run assemble.
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
+
378
+ The stable named subpath `@rig-c/parts/assembly-reading` exports
379
+ `assemblyConfigReading(configPath: string, parts: PartsFile): AssemblyConfigRecord`
380
+ and `assemblyConfigChanges(configPath: string, parts: PartsFile): string[]`.
381
+ Use a manifest read with `readParts` from `@rig-c/parts/src/parts.ts` as
382
+ `parts`. The first function computes the current reading using the assemble
383
+ config loader. The second compares it with `parts.assembly_config` and returns
384
+ the sorted field names whose presence or digest changed. It returns an empty
385
+ array for matching or legacy manifests. See the workflow in
386
+ [Keeping assembled parts current](AUTHORING.md#keeping-assembled-parts-current).
387
+
341
388
  ## Programmatic parts file references
342
389
 
343
390
  `@rig-c/parts/src/parts.ts` exports `partsFileReferences(dir: string):
@@ -427,7 +474,7 @@ and do not certify visibility. See the
427
474
  <!-- stable:commands -->
428
475
  | command | flags |
429
476
  | --- | --- |
430
- | `edited-part` | `--config`, `--part`, `--file`, `--from`, exactly one of `--editor` or `--producer`; optional `--rig-config`, `--help` (`-h`) (issue #1328; splice a receipt into explicit full configs, without reassembly) |
477
+ | `edited-part` | `--config`, `--part`, `--file`, `--from`, exactly one of `--editor` or `--producer`; optional `--parts` (`parts.json`), `--rig-config`, `--help` (`-h`) |
431
478
  | `external-receipt` | `--kind` (mask), `--file`, `--painting`, `--producer`, `--out`; or `--verify`; or `--help` (`-h`) |
432
479
  | `diff-components` | `--stack`, `--painting`, `--parts`, `--floor`; optional `--threshold`, `--figure`, `--owners`, `--help` (`-h`); exactly one of `--out`, `--verify` (issues #1005, #1291; exhaustive native error inventory, `rig-parts-diff-components/1` by default and `rig-parts-diff-components/2` with `--owners`, and byte-bound reader for both) |
433
480
  | `diff-drafts` | `--left`, `--right`, `--out`; optional `--help` (`-h`) (issue #1369; draft-to-draft assemble comparison, `rig-parts-draft-diff/1`) |
@@ -539,7 +586,7 @@ part name, `[i]` an entry of a list):
539
586
  - **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
540
587
  - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`, `arm_split`
541
588
  - **seethrough.arm_split** — required: `order`, and one of `x` or `line` (issue #439)
542
- - **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.
543
590
  - **assemble.edge_splits[i]** — required: `over`, `under`, `band`
544
591
  - **assemble.require_hidden_extent[i]** — required: `part`, `occluder`
545
592
  - **assemble.occluders[i]** — required: `image`, `sha256`, `under`, `rgb_within`; optional: `over`, `plate`, `part`, `grow`, `guard` (issues #1230, #1237, #1241, #1246, #1251, #1259)
@@ -953,10 +1000,10 @@ execution in historical evidence is inferred from a current export.
953
1000
  | file | written by | what is stable |
954
1001
  | --- | --- | --- |
955
1002
  | `stage-map.json` | `assemble`, `build`, under `assemble.stage_map: true` | `rig-parts-stage-map/1`, cropped last-writer and pre-seam RLE maps with writer dictionaries and excluded counts. See [Per-pixel stage map](AUTHORING.md#per-pixel-stage-map). |
956
- | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), `excluded_px` after them only on a subset set's limb part whose cap the set exclusion took a pixel of (issue #603, additive: each pixel taken out of the count it was in, so the cap's counts are the written PNG's), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px` — on a subset set's limb part counted after the set exclusion, issue #603 — `seam_override_px`, and `fringe_pushed_back` when not empty); per-part `taken_layers` (with optional `transport`, issue #973, and optional `split` — `occluder`, `image`, `sha256`, `covered_px`, `visible_px` — on a split take, additive, issue #1242) and `provenance` (`unchanged_layer_px`, `hand_px`, `automatic_px`, `edits`, `automatic`, additive, issue #823); optional top-level `motion_seams`, `occluder_plates` (one record per `assemble.occluders` entry declaring `plate` — `receipt`, `receipt_sha256`, `occluder_sha256`, `painting_sha256`, `output_sha256`, `mask_sha256`, additive, issue #1237), `occluder_grow` (one record per `assemble.occluders` entry with `grow > 0` — `occluder`, `image`, `grow`, `covered_px_before`, `covered_px_after`, additive, issue #1251), `occluder_guard` (one record per `assemble.occluders` entry with `guard > 0` — `occluder`, `image`, `guard`, `guarded_px_before`, `guarded_px_after`, additive, issue #1259), `alternates` and `cut_ownership` (one row per cut, independent of RGBA equality, issue #823, with optional `under_plate` — `receipt`, `receipt_sha256`, `occluder_sha256`, `painting_sha256`, `output_sha256`, `mask_sha256` — on a `{plate}` under, additive, issue #1230); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242), and the same bytes beside `parts.json` when the two directories differ (issue #1177); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
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) |
957
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) |
958
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) |
959
- | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | [Check verdict spec](#check-report-rig-parts-check1) followed by the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode` (with `page_size` under `--page-size` only, issue #1273, additive), `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #941 adds optional `required` only under the requirements file's `seam_over_motion.required: true` — `status` (`PASS` or `FAIL`), `mode` `gap-open`, `bar_px` 0, `pairs` (each `pair`, `class` — `body-root`, `internal-joint` or `explicit` — `frames`, `background_frames`, `max_px`) and `failed` — and with it the key is written even when no pair is declared; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes. Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
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. |
960
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. |
961
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 |
962
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 |
@@ -1328,12 +1375,18 @@ field by field, with the tolerances `CH07` plants against.
1328
1375
 
1329
1376
  A lower rigid limb piece may carry `limb.hybrid` instead of `limb.cap`:
1330
1377
  `{part, upper, width, radius, at, axis}`. Its generated mesh carries
1331
- `limb.band`: `{upper, width, radius, at, axis}`. Their source, joint, lower
1332
- carrier and measured geometry must agree; the lower rigid piece alone carries
1333
- `range`. The default limb records and byte contracts are unchanged. The
1334
- existing `LIMB_ONE_BONE` line checks ordinary segments as before; the band
1335
- requires exactly its two adjacent carriers. `SEAM_OVER_RANGE` uses the stored
1336
- radius and existing rest-art comparison, without changing its bar.
1378
+ `limb.band`: `{upper, width, radius, at, axis}`. `width` is the finite positive
1379
+ effective full band width in rig pixels. Both records carry the finite
1380
+ source-derived `measured_width` in rig pixels, including zero or negative
1381
+ measurements when an explicit width lets assembly succeed. Readers accept
1382
+ pairs without this optional field and require both records to agree on it
1383
+ when present. For the base and each alternate carrying the band, the assembly
1384
+ reading uses the config's explicit width when supplied and the recorded
1385
+ `measured_width` otherwise. The pair also
1386
+ agrees on source, joint, lower carrier and geometry. The lower rigid piece
1387
+ alone carries `range`. The existing `LIMB_ONE_BONE` line checks ordinary
1388
+ segments as before. The band requires exactly its two adjacent carriers.
1389
+ `SEAM_OVER_RANGE` uses the stored radius and existing rest-art comparison.
1337
1390
 
1338
1391
  ## Explicit motion seam observations (issue #750)
1339
1392
 
@@ -1653,16 +1706,18 @@ remain readable and keep their output bytes for identical inputs.
1653
1706
  `edited-part` (issue #1328) records `sha256` and `from_sha256` from the
1654
1707
  supplied PNG bytes, plus the supplied `producer` or nonblank `editor`. It replaces the
1655
1708
  named part's receipt in place or appends one, preserving every other row and
1656
- unrelated config byte. Both explicit full configs are validated before either
1657
- destination changes; each must already declare `assemble.edited_parts`. Paths are recorded
1709
+ unrelated config byte. It validates `--config` through the assemble loader
1710
+ and optional `--rig-config` through the full loader. Each must already declare
1711
+ `assemble.edited_parts`. With `--parts`, the manifest's assembly config digest
1712
+ is checked against `--config` before writing. Without it, the command prints
1713
+ that no assembly config check ran. Paths are recorded
1658
1714
  relative to each config's edited-parts directory. There is no config discovery
1659
1715
  or reassembly: a wrong same-size `--from` is recorded successfully, then the
1660
1716
  existing build baseline verifier refuses it with `ASSEMBLE_EDITED_PART_BASELINE`.
1661
- Writer validation refusals leave both configs unchanged. The shared staged
1662
- writer validates full configs and their relative sidecars; all configs stage
1717
+ Writer validation refusals leave both configs unchanged. All configs stage
1663
1718
  before the shared batch commits, restoring earlier originals on a later commit
1664
- failure. The command prints shared config-change lines on stderr and one
1665
- stdout line naming the part, both hashes and the author declaration. Repeated
1719
+ failure. The command prints shared config-change lines on stderr and a receipt
1720
+ line on stdout naming the part, both hashes and the author declaration. Repeated
1666
1721
  identical receipts preserve bytes and report `unchanged`.
1667
1722
 
1668
1723
  The optional `assemble.edited_parts` block (issue #1278, additive) replaces
package/package.json CHANGED
@@ -1,8 +1,12 @@
1
1
  {
2
2
  "name": "@rig-c/parts",
3
- "version": "2.45.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
+ "exports": {
7
+ "./assembly-reading": "./src/assembly-reading.ts",
8
+ "./*": "./*"
9
+ },
6
10
  "bin": {
7
11
  "rig-parts": "./bin/rig-parts.cjs",
8
12
  "spine-parts": "./bin/rig-parts.cjs"
@@ -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 });
@@ -4882,7 +4883,8 @@ function cutLimbs(
4882
4883
  const art = (x: number, y: number): boolean => x >= 0 && y >= 0 && x < W && y < H && own[y * W + x] === li && source.r.data[(y * W + x) * 4 + 3] > OPAQUE_ALPHA_ABOVE;
4883
4884
  const run = limbRun(line, art, [0, 0, W - 1, H - 1]);
4884
4885
  if (run === null && emptyTargets?.has(sg.hybrid.part)) return;
4885
- const width = sg.hybrid.width ?? (run === null ? 0 : 2 * halfWidthAbout(run));
4886
+ const measuredWidth = run === null ? 0 : 2 * halfWidthAbout(run);
4887
+ const width = sg.hybrid.width ?? measuredWidth;
4886
4888
  const upper = places.get(segs[k - 1].bone) as BonePlace;
4887
4889
  const lower = places.get(sg.bone) as BonePlace;
4888
4890
  const reach = (p: readonly number[]): number => Math.abs((p[0] - line.at[0]) * line.axis[0] + (p[1] - line.at[1]) * line.axis[1]);
@@ -4923,7 +4925,11 @@ function cutLimbs(
4923
4925
  if (along < width / 2) { rasters[loAt].data.fill(0, p * 4, p * 4 + 4); regions[loAt].data[p] = 0; }
4924
4926
  }
4925
4927
  const base = parts[loAt].record;
4926
- const geometry = { upper: segs[k - 1].bone, width, radius: (base.cap as CapRecord).radius, at: [...line.at] as [number, number], axis: [...line.axis] as [number, number] };
4928
+ const geometry = {
4929
+ upper: segs[k - 1].bone, width, measured_width: measuredWidth,
4930
+ radius: (base.cap as CapRecord).radius,
4931
+ at: [...line.at] as [number, number], axis: [...line.axis] as [number, number],
4932
+ };
4927
4933
  delete base.cap;
4928
4934
  base.hybrid = { part: sg.hybrid.part, ...geometry };
4929
4935
  capFrom[loAt] = null;
@@ -5225,7 +5231,7 @@ export function checkSingleRun(full: LayerSet, plan: readonly PlanEntry[] | null
5225
5231
 
5226
5232
  /** All output pieces that consume a taken source, including cut-to-limb paths.
5227
5233
  * Painting patches have no source-part edge in the supported Patch schema. */
5228
- 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> {
5229
5235
  const targets = new Set(names);
5230
5236
  const edges = cuts.map(c => ({ from: c.from, into: c.into }));
5231
5237
  for (const limb of Object.values(limbs)) for (const [index, segment] of limb.segments.entries()) {
@@ -6158,9 +6164,11 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6158
6164
  const stackNames = stack.map((q) => q.record.name);
6159
6165
  const drift: DriftBodies[] = [];
6160
6166
  const yields = new Map<string, { mask: Mask; reading: DriftYieldReading }>();
6167
+ const yieldSelection = typeof input.yieldRefused === 'object' ? new Set(input.yieldRefused) : null;
6161
6168
  order.forEach((d, orderIdx) => {
6162
6169
  if ('patch' in d) return;
6163
6170
  const { name, b } = pieceAt(d);
6171
+ const yieldPart = input.yieldRefused === true || yieldSelection?.has(name) === true;
6164
6172
  if (b.st.refusedMask === null) return;
6165
6173
  const refused = newMask(W, H);
6166
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;
@@ -6171,7 +6179,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6171
6179
  if (under[p * 4 + 3] < CORE_ALPHA) continue;
6172
6180
  // The opt-in resolves the actual exposed opaque holder before comparing its colour.
6173
6181
  // Keep the legacy matching-holder diagnostic unchanged when the setting is off.
6174
- if (input.yieldRefused === true) { behindAt[p] = j; continue; }
6182
+ if (yieldPart) { behindAt[p] = j; continue; }
6175
6183
  const dMax = Math.max(
6176
6184
  Math.abs(under[p * 4] - srcr.data[p * 4]),
6177
6185
  Math.abs(under[p * 4 + 1] - srcr.data[p * 4 + 1]),
@@ -6180,7 +6188,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6180
6188
  if (dMax <= DRIFT_LIMIT) behindAt[p] = j;
6181
6189
  }
6182
6190
  }
6183
- if (input.yieldRefused === true) {
6191
+ if (yieldPart) {
6184
6192
  for (let p = 0; p < W * H; p++) {
6185
6193
  if (behindAt[p] < 0) continue;
6186
6194
  const under = stack[behindAt[p]].image.data;
@@ -6195,7 +6203,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6195
6203
  // The refusal belongs to b.key. A copied/ring replacement cannot inherit that source's refusal.
6196
6204
  // "Front" is relative to behindAt, not the fixed global top holder: another run may cover this source.
6197
6205
  let yielded = 0;
6198
- if (input.yieldRefused === true) {
6206
+ if (yieldPart) {
6199
6207
  const mask = newMask(W, H);
6200
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: [] };
6201
6209
  const holders = new Map<string | null, number>();
@@ -6258,10 +6266,10 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6258
6266
  reading.originalHolders = [...holders].map(([part, px]) => ({ part, px }));
6259
6267
  yields.set(name, { mask, reading });
6260
6268
  }
6261
- const found = driftBodies(name, b.key, refused, bodyMinPx(frame), holderAt, stackNames, behindAt, input.yieldRefused === true ? yielded : undefined);
6262
- 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);
6263
6271
  });
6264
- if (input.yieldRefused === true) {
6272
+ if (input.yieldRefused === true || yields.size > 0) {
6265
6273
  const finalAt = new Int32Array(W * H).fill(-1);
6266
6274
  stack.forEach(({ image }, i) => { for (let p = 0; p < W * H; p++) if (image.data[p * 4 + 3] >= CORE_ALPHA) finalAt[p] = i; });
6267
6275
  for (const { mask, reading } of yields.values()) {
@@ -6799,7 +6807,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6799
6807
  uncovered,
6800
6808
  holeKinds: kinds,
6801
6809
  drift,
6802
- ...(input.yieldRefused === true ? { yieldReadings: [...yields.values()].map(q => q.reading) } : {}),
6810
+ ...(input.yieldRefused === true || yieldSelection !== null ? { yieldReadings: [...yields.values()].map(q => q.reading) } : {}),
6803
6811
  ...(occluderUnheldWarnings.length === 0 ? {} : { occluderUnheldWarnings }),
6804
6812
  hidden: [...hiddenUses].map(([layer, readBy]) => ({ layer, readBy })),
6805
6813
  seamRule,
@@ -6824,6 +6832,8 @@ export { edgeSplitLines };
6824
6832
 
6825
6833
  /** A part whose `DRIFT_LIMIT` refusals hold a body, and which parts the draw order puts there. */
6826
6834
  export interface DriftBodies {
6835
+ /** An explicit part list enabled the yield reading for this part. */
6836
+ scopedYield?: true;
6827
6837
  /** The part, and its `<run>:<tag>`. */
6828
6838
  part: string;
6829
6839
  from: string;
@@ -6926,7 +6936,7 @@ export function driftLine(d: DriftBodies): string {
6926
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" +
6927
6937
  (d.yieldedPx === undefined
6928
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'
6929
- : `; 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)`)
6930
6940
  );
6931
6941
  }
6932
6942
 
@@ -7696,24 +7706,19 @@ function unplannedNotes(
7696
7706
  // ---------------------------------------------------------------------------
7697
7707
 
7698
7708
  /**
7699
- * The config fields the stage reads: `seethrough.resolution` and `.head_box`,
7700
- * `assemble.rig_scale`, `.plan`, `.extend_below_crop`, `.patches` and `.cuts` — and
7701
- * nothing of the rig. The CLI hands it a config from
7702
- * `parseEarlyConfig(raw, 'assemble')`; a config the full loader accepted is
7703
- * the same shape with more in it. The head box is refused here rather than by
7704
- * the loader, because `inputs` runs before it exists; `seethrough` too, for a
7705
- * 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.
7706
7712
  */
7707
7713
  export function stageFields(
7708
- cfg: Pick<CharacterConfig, 'seethrough' | 'assemble' | 'scene' | 'motion_seams'> & {
7709
- limbs?: Record<string, Limb>;
7710
- bones?: BoneEntry[];
7711
- meshes?: Record<string, MeshSpec>;
7712
- regions?: Record<string, RegionSpec>;
7713
- constraints?: ConfigConstraint[];
7714
- turn?: TurnSpec;
7715
- motion?: CharacterConfig['motion'];
7716
- },
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,
7717
7722
  single: { w: number; h: number } | null = null,
7718
7723
  ): {
7719
7724
  resolution: number;
@@ -7725,14 +7730,14 @@ export function stageFields(
7725
7730
  cuts: Cut[];
7726
7731
  motion_seams?: MotionSeamDeclaration[];
7727
7732
  scene?: boolean;
7728
- limbs?: Record<string, Limb>;
7733
+ limbs?: Record<string, AssemblyLimb>;
7729
7734
  bones?: BoneEntry[];
7730
7735
  single?: boolean;
7731
7736
  armSplit?: ArmSplit;
7732
7737
  keySkeleton?: ControlSkeleton;
7733
7738
  headFaceUnderfill?: boolean;
7734
7739
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
7735
- yieldRefused?: boolean;
7740
+ yieldRefused?: boolean | readonly string[];
7736
7741
  /** Report-only last-writer sidecar, default off. */
7737
7742
  stageMap?: boolean;
7738
7743
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
@@ -7747,7 +7752,7 @@ export function stageFields(
7747
7752
  turn?: TurnSpec;
7748
7753
  regions?: Record<string, RegionSpec>;
7749
7754
  meshes?: Record<string, MeshSpec>;
7750
- motion?: CharacterConfig['motion'];
7755
+ motion?: AssemblyView['motion'];
7751
7756
  /** `assemble.ground` (issue #996); absent, `plain`. */
7752
7757
  ground?: Ground;
7753
7758
  } {
@@ -7759,8 +7764,8 @@ export function stageFields(
7759
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' });
7760
7765
  }
7761
7766
  refuseIfAny(problems);
7762
- const st = cfg.seethrough as SeeThrough;
7763
- const keySkeleton = controlSkeletonOf(cfg);
7767
+ const st = cfg.seethrough!;
7768
+ const keySkeleton = cfg.keySkeleton;
7764
7769
  const turnMovingPair = turnMovingPartPair(cfg);
7765
7770
  return {
7766
7771
  resolution: st.resolution,
@@ -7784,7 +7789,7 @@ export function stageFields(
7784
7789
  patches: cfg.assemble.patches ?? [],
7785
7790
  cuts: cfg.assemble.cuts ?? [],
7786
7791
  ...(cfg.motion_seams === undefined ? {} : { motion_seams: cfg.motion_seams }),
7787
- ...(cfg.scene === undefined ? {} : { scene: true }),
7792
+ ...(cfg.scene === undefined ? {} : { scene: cfg.scene }),
7788
7793
  ...(cfg.limbs === undefined ? {} : { limbs: cfg.limbs, bones: cfg.bones ?? [] }),
7789
7794
  };
7790
7795
  }