@rig-c/parts 1.24.0 → 1.26.0

package/docs/STABILITY.md

@@ -52,7 +52,7 @@ defaults are the help's too, and none is guessed from the art.
 | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
 | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll` |
 | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`; or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible) |
-| `propose` | `--head-box` with `--full`, `--canvas` |
+| `propose` | `--head-box` with `--full`, `--canvas`; optional `--no-back-hair` |
 | `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`) |
 | `compare` | `--left`, `--right`; optional `--map` |
 | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
@@ -112,7 +112,7 @@ The fields, object by object (a bold path is where the object sits; `<part>` is
 part name, `[i]` an entry of a list):
 
 <!-- stable:config -->
-- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `turn`, `scene`, `cloth`
+- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`, `proposed_rig_scale`
 - **generation** — required: `checkpoint`, `loras`, `trigger`, `identity`, `sampler`, `costume`, `negative_extra`, `style`, `negative_pose`, `latent`, `seed`; optional: `pose`, `control`
 - **generation.loras[i]** — required: `name`, `strength`; optional: `strength_clip`
 - **generation.sampler** — required: `steps`, `cfg`, `sampler`, `scheduler`
@@ -128,7 +128,9 @@ part name, `[i]` an entry of a list):
 - **limbs.&lt;limb&gt;** — required: `segments` (issue #349)
 - **limbs.&lt;limb&gt;.segments[i]** — required: `part`, `from`, `bone`; required below a joint (i > 0): `joint`; optional below a joint: `range`, `cap`, `edge`, `cap_shape`, `cut_band`
 - **bones[i]**, a single bone — required: `name`, `parent`, `at`; optional: `tip`, `inherit`
-- **bones[i]**, a chain — required: `chain`, `parent`, `points`, `tip`
+- **bones[i]**, a chain — required: `chain`, `parent`, `points`, `tip`; optional: `link_inherit`
+- **stops[i]** — required: `chain`, `against`, `at`, `inward`, `outward`; optional: `links`, `lower` (issue #404)
+- **stops[i].lower** — required: `inward`, `outward`
 - **meshes.&lt;part&gt;** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`; optional in every mode: `exponent`, `rule`; optional with `contour` or `auto`: `ribs`; optional with `grid` or `contour`: `influences` (issue #284; beside `auto` it is refused, CONFIG_INFLUENCES_MODE); optional with `grid`: `stray` (issue #303; beside `contour` or `auto` it is refused, CONFIG_STRAY_MODE)
 - **meshes.&lt;part&gt;.influences** — optional, at least one: `maxInfluences` (a whole number, 1 or more, or null for no cap), `floor` ("cut" or "continuous")
 - **meshes.&lt;part&gt;.ribs.&lt;chain&gt;** — required: `stations`
@@ -147,8 +149,8 @@ part name, `[i]` an entry of a list):
 - **meshes.&lt;part&gt;.auto.regions[i]** — required: `name`, `shape`, `maxEdgeLength`, `transition`, `grade`, `minArtSamples`, and `cx`, `cy`, `r` for a circle or `points` for a polygon; optional: `bone`, `band` (both or neither; with neither the region is density only)
 - **meshes.&lt;part&gt;.auto.boundaryRuns** — required: `maxVertices`
 - **meshes.&lt;part&gt;.auto.stimulus**, or each entry of it when a list — required: `chain`, `degrees`
-- **cloth.&lt;tag&gt;**, the tag bottomwear, back hair or front hair (issue #364; read by propose --cloth only) — required: `chains`, `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only), `part` (on bottomwear only)
-- **cloth.&lt;tag&gt;.split** — required: `at`, `into`
+- **cloth.&lt;tag&gt;**, the tag bottomwear, back hair or front hair (issue #364; read by propose --cloth only) — required: `chains` (optional on `back hair`, issue #390), `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only), `part` (on bottomwear only)
+- **cloth.&lt;tag&gt;.split** — required: `at`, `into`; optional: `hold_tip`
 - **cloth.&lt;tag&gt;.strength** — required: `trunk`, `branch`, `edge`
 - **cloth.&lt;tag&gt;.swing** — required: `scales`
 - **regions.&lt;part&gt;** — a bone name
@@ -161,7 +163,7 @@ part name, `[i]` an entry of a list):
 - **turn** — required: `pivot`, `depths`
 - **turn.depths.&lt;part&gt;** — a See-through depth
 - **scene** — no field (`{}`; a record or an annotation only)
-- **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `limbs` under `--keypoints` where an arm or a leg is drafted from its joints (issue #349), `motion` under the rules above, `turn` with `--full`/`--head`, and `notes`
+- **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `limbs` under `--keypoints` where an arm or a leg is drafted from its joints (issue #349), `stops` when supplied, `motion` under the rules above, `turn` with `--full`/`--head`, `proposed_rig_scale` (issue #354), and `notes`
 <!-- /stable:config -->
 
 `TY14` holds the set of field names in backticks above to the set of names the
@@ -181,10 +183,10 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | `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`, then `shape` and `upper_px` under the segment's `cap_shape`, 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`, `seam_override_px`, and `fringe_pushed_back` when not empty); `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); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
 | `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) |
 | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `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` "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) |
-| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `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 (issue #320: `status`, `animations`, `fps`, `physics_left_out`, `folding`, `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 `unread` on a joint not read), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
+| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `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 `unread` on a joint not read), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `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 |
 | the template `.psd` | `layers --template` | one empty layer per name `templateLayerNames` (`src/layers.ts`) holds, bottom first; the same canvas writes the same bytes |
-| `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `constraints` with `--cloth` (issue #364: a physics constraint per tree link named `<bone>_physics`, a dangling end's `<bone>_translate`, and a skirt swing's transforms `<swing>_<tree>`), `turn` with `--full`/`--head`, and `notes` |
+| `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `constraints` with `--cloth` (issue #364: a physics constraint per tree link named `<bone>_physics`, a dangling end's `<bone>_translate`, and a skirt swing's transforms `<swing>_<tree>`), `turn` with `--full`/`--head`, `proposed_rig_scale` (issue #354), and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |
 | `config.json`, `mesh_draft.json` | `mesh-draft` | `config.json` is the config read, byte for byte, but for each drafted part's `meshes` entry; `mesh_draft.json` is spec `rig-parts-mesh-draft/1`: `rules`, `lattice_check`, `draft_check`, `figure_overdraw`, and per lattice part `part`, `mode`, `lattice`, `candidate` (with `bridges` — `units`, `joins` of `span` and `area_px2`, `area_px2`, `overdraw`, and `faint` only when an island was left out as faint — only when the candidate is a bridged one, issue #326), `delta` (under `--more-triangles` only), `readings`, `gate` (each line's `reading`, `pass`, `text`, `margin`), `note`; and `not_compared` (issue #307), only when the config holds an `auto` or `contour` entry: per such entry, in config order, `part`, `mode` and `note` — the part was neither drafted nor compared, and a config of lattices alone writes no such key |
 | the scene report | `compose` | spec `spine-parts-scene-report/1` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {
@@ -61,7 +61,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "rig-c": "^2.54.0"
+    "rig-c": "^2.57.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/skills/rig-parts/SKILL.md

@@ -85,7 +85,7 @@ under that.
    gap See-through left (a skirt split into two legs), fixed in the plan or the layers,
    not in the rig. Then `rig-parts propose --parts work/rig
    --source <painting> --out work` → copy `bones`, `meshes`, `regions`, `limbs`,
-   `motion`, `constraints`, `turn` from `proposal.json` into the config, each it
+   `motion`, `constraints`, `turn`, `proposed_rig_scale` from `proposal.json` into the config, each it
    wrote (`limbs` only with `--keypoints`, `constraints` only with `--cloth`, `turn`
    only with `--full`/`--head`; a `limbs` block left out is refused at the next step). `assemble` needs the plan and none of
    those sections; do not stub them to get past it (AUTHORING §4 says what each step

package/src/assemble.ts

@@ -104,7 +104,7 @@ import { type Problem, refuseIfAny } from './errors.ts';
 import { figuresPhrase, implausibleRules, type Layer, type LayerFigures, layerFigures, type LayerSet, NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE, ruleSummary } from './layers.ts';
 import { padToSquare, squarePad } from './inputs.ts';
 import { type CapRecord, type LimbRecord, PAINTING_RUN, type PartRecord, type PartsFile, type RecompositeRecord, type SceneRecord, type SingleRunPad } from './parts.ts';
-import { type BonePlace, bonePlaces, capBox, coveredRadius, type CutPlacement, featherWeight, halfWidthAbout, inDisc, jointLine, type JointLine, jointOffsets, limbPolyline, limbRun, luma601, nearestLimb, pastJoint, placeCut, segmentOf } from './limbs.ts';
+import { assignOverlappingHands, type BonePlace, bonePlaces, capBox, coveredRadius, type CutPlacement, featherWeight, halfWidthAbout, inDisc, jointLine, type JointLine, jointOffsets, limbPolyline, limbRun, luma601, nearestLimb, pastJoint, placeCut, segmentOf } from './limbs.ts';
 import {
   alphaComposite,
   connectedComponents,
@@ -1561,6 +1561,61 @@ export function holeLines(f: RecompositeFigures, scene: string | null = null): s
   ];
 }
 
+/** One kind of uncovered error pixel (issue #351): total pixel count, 8-connected component count, and largest component box. */
+export interface HoleKindSummary {
+  px: number;
+  count: number;
+  largest: { px: number; x: number; y: number; w: number; h: number } | null;
+}
+
+/**
+ * The partition of uncovered error pixels into two disjoint causes (issue #351):
+ * - `noLayer`: pixels where no See-through layer in either run has `alpha > OPAQUE_ALPHA_ABOVE` (an `assemble.patches` box from the painting is the only repair).
+ * - `betweenLayers`: pixels where at least one See-through layer has `alpha > OPAQUE_ALPHA_ABOVE`, but no placed part covers the pixel at `alpha > COVERED_ALPHA`.
+ */
+export interface HoleKinds {
+  noLayer: HoleKindSummary;
+  betweenLayers: HoleKindSummary;
+}
+
+function summarizeKindMask(mask: Mask): HoleKindSummary {
+  let px = 0;
+  for (let p = 0; p < mask.data.length; p++) px += mask.data[p];
+  if (px === 0) return { px: 0, count: 0, largest: null };
+  const cc = connectedComponents(mask, 8);
+  const all = cc.stats.slice(1).filter((s) => s.area > 0);
+  all.sort((a, b) => b.area - a.area || a.top - b.top || a.left - b.left);
+  const s = all[0];
+  return { px, count: all.length, largest: s === undefined ? null : { px: s.area, x: s.left, y: s.top, w: s.width, h: s.height } };
+}
+
+export function holeKinds(err: Uint8Array, covered: Uint8Array, anyLayer: Uint8Array, W: number, H: number): HoleKinds {
+  const noLayerMask = newMask(W, H);
+  const betweenMask = newMask(W, H);
+  for (let p = 0; p < W * H; p++) {
+    if (err[p] !== 1 || covered[p] !== 0) continue;
+    if (anyLayer[p] === 0) noLayerMask.data[p] = 1;
+    else betweenMask.data[p] = 1;
+  }
+  return { noLayer: summarizeKindMask(noLayerMask), betweenLayers: summarizeKindMask(betweenMask) };
+}
+
+/**
+ * The summary line under `holeLines` (issue #351): partitions `uncoveredErrorPx`
+ * into pixels where no See-through layer has `alpha > 8` (`noLayer`, repaired
+ * only by `assemble.patches`) and pixels where a layer has `alpha > 8` (`betweenLayers`).
+ */
+export function holeKindsLine(k: HoleKinds, scene: string | null = null): string {
+  const fmt = (s: HoleKindSummary): string =>
+    s.px === 0 || s.largest === null
+      ? '0 px'
+      : `${s.px} px in ${s.count} component(s) (largest ${s.largest.px} px at ${s.largest.x},${s.largest.y} ${s.largest.w}x${s.largest.h})`;
+  return (
+    `${scene === null ? '' : `${scene}: `}uncovered error by cause: no layer (alpha <= ${OPAQUE_ALPHA_ABOVE} on every layer; only assemble.patches from the painting can cover): ${fmt(k.noLayer)}; ` +
+    `on a layer (alpha > ${OPAQUE_ALPHA_ABOVE} on a layer, below covered alpha ${COVERED_ALPHA} in the parts): ${fmt(k.betweenLayers)}`
+  );
+}
+
 /** The `parts.json` `recomposite` block: the four figures, the limits they were measured at, and the listed holes. */
 export function recompositeRecord(f: RecompositeFigures): RecompositeRecord {
   return {
@@ -2054,16 +2109,35 @@ function cutLimbs(
         placements.set(`${l}/${k}`, placed);
       });
     }
+    const segOverride = new Int32Array(W * H).fill(-1);
+    const segAt = (l: string, x: number, y: number): number => {
+      const segs = limbs[l].segments;
+      const first = segs.findIndex((sg) => sg.from === src);
+      let last = first;
+      while (last + 1 < segs.length && segs[last + 1].from === src) last++;
+      return segmentOf(cutLines.get(l) as Array<JointLine | null>, first, last, x, y);
+    };
+    // Issue #400: when two forearm segments share `src` and their hand regions overlap, the overlap goes to the front
+    // piece (the limb later in config.limbs) in one piece, and the back piece ends at its cuff.
+    const forearms = on.flatMap((l) => {
+      const li = names.indexOf(l);
+      return limbs[l].segments.flatMap((sg, k) => {
+        if (k === 0 || sg.joint !== 'elbow' || sg.from !== src) return [];
+        const me = places.get(sg.bone) as BonePlace;
+        return me.end === null ? [] : [{ limb: li, seg: k, elbow: me.at, wrist: me.end, isSeg: (x: number, y: number): boolean => segAt(l, x, y) === k }];
+      });
+    });
+    for (let i = 0; i < forearms.length; i++) {
+      for (let j = i + 1; j < forearms.length; j++) {
+        assignOverlappingHands(forearms[i], forearms[j], W, H, own, segOverride);
+      }
+    }
     for (let y = 0; y < H; y++) {
       for (let x = 0; x < W; x++) {
         const p = y * W + x;
         if (b.r.data[p * 4 + 3] === 0) continue;
         const l = names[own[p]];
-        const segs = limbs[l].segments;
-        const first = segs.findIndex((sg) => sg.from === src);
-        let last = first;
-        while (last + 1 < segs.length && segs[last + 1].from === src) last++;
-        const k = segmentOf(cutLines.get(l) as Array<JointLine | null>, first, last, x, y);
+        const k = segOverride[p] >= 0 ? segOverride[p] : segAt(l, x, y);
         const at = parts.findIndex((q) => q.limb === l && q.segment === k);
         rasters[at].data.set(b.r.data.subarray(p * 4, p * 4 + 4), p * 4);
         if (b.region === null || b.region.data[p] === 1) regions[at].data[p] = 1;
@@ -2259,6 +2333,8 @@ export interface AssembleResult {
   limbs: LimbCount[];
   /** The full-run layers the plan does not take from the full run whose uncovered error holds a body (`uncoveredErrorLayers`); empty otherwise. */
   uncovered: UncoveredErrorLayer[];
+  /** The partition of uncovered error pixels into no-layer and on-a-layer components (`holeKinds`, issue #351). */
+  holeKinds: HoleKinds;
   /** The parts whose `DRIFT_LIMIT` refusals hold a body another part holds in the draw order (`driftBodies`), in draw order; empty otherwise. */
   drift: DriftBodies[];
   /** Every hidden-art layer of the runs read (issue #359) and what read it (`hiddenLines`); empty when the runs hold none. */
@@ -2773,13 +2849,26 @@ export function assemble(input: AssembleInput): AssembleResult {
   });
   const stackNames = stack.map((q) => q.record.name);
   const drift: DriftBodies[] = [];
-  order.forEach((d) => {
+  order.forEach((d, orderIdx) => {
     if ('patch' in d) return;
     const { name, b } = pieceAt(d);
     if (b.st.refusedMask === null) return;
     const refused = newMask(W, H);
     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;
-    const found = driftBodies(name, b.key, refused, bodyMinPx(frame), holderAt, stackNames);
+    const behindAt = new Int32Array(W * H).fill(-1);
+    for (let j = 0; j < orderIdx; j++) {
+      const under = stack[j].image.data;
+      for (let p = 0; p < W * H; p++) {
+        if (under[p * 4 + 3] < CORE_ALPHA) continue;
+        const dMax = Math.max(
+          Math.abs(under[p * 4] - srcr.data[p * 4]),
+          Math.abs(under[p * 4 + 1] - srcr.data[p * 4 + 1]),
+          Math.abs(under[p * 4 + 2] - srcr.data[p * 4 + 2]),
+        );
+        if (dMax <= DRIFT_LIMIT) behindAt[p] = j;
+      }
+    }
+    const found = driftBodies(name, b.key, refused, bodyMinPx(frame), holderAt, stackNames, behindAt);
     if (found !== null) drift.push(found);
   });
   const pushedOf: FringePushed[][] = plan.map(() => []);
@@ -2861,11 +2950,16 @@ export function assemble(input: AssembleInput): AssembleResult {
   const inside = input.scene === true ? sceneFigure([...rig.entries()].filter(([k]) => k.startsWith('full:')).map(([, r]) => r), W, H) : null;
   const sceneRecord: SceneRecord | null = inside === null ? null : { figure_alpha_above: OPAQUE_ALPHA_ABOVE, figure_px: inside.reduce((a, b) => a + b, 0), figure_mask: FIGURE_MASK_FILE };
   const figures = measureRecomposite(can, srcr, placed, inside);
+  const covered = coveredMask(placed, W, H);
+  const err = errorMask(can, srcr, inside);
+  const anyLayer = new Uint8Array(W * H);
+  for (const r of rig.values()) for (let p = 0; p < W * H; p++) if (r.data[p * 4 + 3] > OPAQUE_ALPHA_ABOVE) anyLayer[p] = 1;
+  const kinds = holeKinds(err, covered, anyLayer, W, H);
   const fullRig = fullTags.map((tag) => ({ tag, rig: rig.get(`full:${tag}`) as Raster }));
   const uncovered = uncoveredErrorLayers(
     fullRig,
-    coveredMask(placed, W, H),
-    errorMask(can, srcr, inside),
+    covered,
+    err,
     figures.uncoveredErrorPx,
     plan,
     extend,
@@ -2892,6 +2986,7 @@ export function assemble(input: AssembleInput): AssembleResult {
     cuts: cutCounts,
     limbs: lim.counts,
     uncovered,
+    holeKinds: kinds,
     drift,
     hidden: [...hiddenUses].map(([layer, readBy]) => ({ layer, readBy })),
     seamRule,
@@ -2920,11 +3015,18 @@ export interface DriftBodies {
    * (`seamCandidates`) — with its pixel count, most first, then by name.
    */
   holders: Array<{ part: string; px: number }>;
+  /**
+   * Over every pixel of the bodies, the top-most part drawn behind `part` at
+   * alpha >= `CORE_ALPHA` whose colour is within `DRIFT_LIMIT` of the painting
+   * (issue #351), with its pixel count, most first, then by name.
+   */
+  behind?: Array<{ part: string; px: number }>;
 }
 
 /**
  * A part's refused bodies that another part holds in the draw order (issue
- * #255).
+ * #255) or that a part drawn behind it matches within `DRIFT_LIMIT` of the
+ * painting (issue #351).
  *
  * ⚖️ Invariant: `refused` is the part's projection core pixels whose layer
  * colour is more than `DRIFT_LIMIT` off the painting (`projectSource`'s
@@ -2934,32 +3036,36 @@ export interface DriftBodies {
  * uncovered layer's, and the stage passes the same bar (`bodyMinPx`).
  * `holderAt` is, per rig pixel, the index into `names` of the top-most part
  * at alpha >= `CORE_ALPHA` in draw order (-1: none), as the seam pass reads a
- * holder. The result is non-null exactly when the bodies hold a pixel whose
- * holder is another part: the plan draws that part over the body, which is
- * the signature of "this layer is not the owner here".
- *
- * Not every body: a body the part holds itself, with nothing drawn over it,
- * is See-through's colour for the part's own pixels disagreeing with the
- * painting, and on four of the five public paintings it holds bodies of
- * hundreds to tens of thousands of pixels that no other part touches (the
- * pull request that added this has the figures); a line there would name no
- * owner, which is what the line exists to name.
- */
-export function driftBodies(part: string, from: string, refused: Mask, minPx: number, holderAt: Int32Array, names: readonly string[]): DriftBodies | null {
+ * holder. `behindAt` (optional) is, per rig pixel, the index into `names` of
+ * the top-most part drawn behind `part` at alpha >= `CORE_ALPHA` whose colour
+ * is within `DRIFT_LIMIT` of the painting (-1: none). The result is non-null
+ * exactly when the bodies hold a pixel whose holder is another part or whose
+ * `behindAt` names a part drawn behind `part` that matches the painting.
+ */
+export function driftBodies(part: string, from: string, refused: Mask, minPx: number, holderAt: Int32Array, names: readonly string[], behindAt?: Int32Array): DriftBodies | null {
   let refusedPx = 0;
   for (let p = 0; p < refused.data.length; p++) refusedPx += refused.data[p];
   if (refusedPx === 0) return null;
   const { bodies, pixels } = bodiesWithPixels(refused, minPx);
   if (bodies.length === 0) return null;
   const count = new Map<string, number>();
+  const behindCount = new Map<string, number>();
   for (let p = 0; p < pixels.data.length; p++) {
-    if (pixels.data[p] === 0 || holderAt[p] < 0) continue;
-    const n = names[holderAt[p]];
-    count.set(n, (count.get(n) ?? 0) + 1);
+    if (pixels.data[p] === 0) continue;
+    if (holderAt[p] >= 0) {
+      const n = names[holderAt[p]];
+      count.set(n, (count.get(n) ?? 0) + 1);
+    }
+    if (behindAt !== undefined && behindAt[p] >= 0) {
+      const b = names[behindAt[p]];
+      if (b !== part) behindCount.set(b, (behindCount.get(b) ?? 0) + 1);
+    }
   }
-  if (![...count.keys()].some((n) => n !== part)) return null;
+  const hasFront = [...count.keys()].some((n) => n !== part);
+  if (!hasFront && behindCount.size === 0) return null;
   const holders = [...count.entries()].map(([q, px]) => ({ part: q, px })).sort((a, b) => b.px - a.px || (a.part < b.part ? -1 : a.part > b.part ? 1 : 0));
-  return { part, from, refusedPx, minPx, bodies, holders };
+  const behind = [...behindCount.entries()].map(([q, px]) => ({ part: q, px })).sort((a, b) => b.px - a.px || (a.part < b.part ? -1 : a.part > b.part ? 1 : 0));
+  return { part, from, refusedPx, minPx, bodies, holders, ...(behind.length > 0 ? { behind } : {}) };
 }
 
 /**
@@ -2969,15 +3075,22 @@ export function driftBodies(part: string, from: string, refused: Mask, minPx: nu
  * off the painting, max channel), in a body of 196 px at 16,12 14x14 (at
  * least 150 px past a 5x5 opening); by the plan's draw order "face" holds 196
  * px of it (the top-most part at alpha >= 250), drawn in front of "topwear"`.
+ * When `behind` is non-empty (issue #351), names the part(s) drawn behind
+ * `part` whose colour is within `DRIFT_LIMIT` of the painting.
  */
 export function driftLine(d: DriftBodies): string {
   const total = d.bodies.reduce((a, b) => a + b.px, 0);
   const big = d.bodies[0];
   const held = d.bodies.length > 1 ? `${d.bodies.length} bodies of ${total} px, the largest ${big.px} px at ${bodyBox(big)}` : `a body of ${big.px} px at ${bodyBox(big)}`;
   const others = d.holders.filter((h) => h.part !== d.part).map((h) => `"${h.part}"`);
+  const frontClause = others.length > 0 ? `, ${others.join(', ')} drawn in front of "${d.part}"` : '';
+  const behindClause =
+    d.behind !== undefined && d.behind.length > 0
+      ? `; the painting is within ${DRIFT_LIMIT} of ${d.behind.map((h) => `"${h.part}" (${h.px} px at alpha >= ${CORE_ALPHA}, drawn behind "${d.part}")`).join(', ')}`
+      : '';
   return (
     `drift: "${d.part}" refuses ${d.refusedPx} px of ${d.from} (its colour more than ${DRIFT_LIMIT} off the painting, max channel), in ${held} (at least ${fmtPx(d.minPx)} px past a ${BODY_KERNEL}x${BODY_KERNEL} opening); ` +
-    `by the plan's draw order ${d.holders.map((h) => `"${h.part}" holds ${h.px} px`).join(', ')} of it (the top-most part at alpha >= ${CORE_ALPHA}), ${others.join(', ')} drawn in front of "${d.part}"`
+    `by the plan's draw order ${d.holders.map((h) => `"${h.part}" holds ${h.px} px`).join(', ')} of it (the top-most part at alpha >= ${CORE_ALPHA})${frontClause}${behindClause}`
   );
 }
 

package/src/automesh.ts

@@ -212,6 +212,7 @@ export function sourceWeights(
   spec: AutoSpec,
   exponent: number = DISTANCE_EXPONENT,
   heat: HeatField | null = null,
+  segsAt: (wy: number) => readonly Segment[] = () => segs,
 ): { weights: Influence[][]; local: LocalInfluence[] } | { overlap: RegionOverlap; vertex: number; at: Point } {
   const all = spec.regions ?? [];
   const index: number[] = [];
@@ -225,7 +226,7 @@ export function sourceWeights(
   const local: LocalInfluence[] = [];
   for (let v = 0; v < vertices.length; v++) {
     const at: Point = [vertices[v][0] + ox, vertices[v][1] + oy];
-    const li = localInfluences(at, segs, r, regions, spec.influences, exponent, heat === null ? undefined : heatInfluences(heat, [vertices[v][0], vertices[v][1]], spec.influences));
+    const li = localInfluences(at, segsAt(at[1]), r, regions, spec.influences, exponent, heat === null ? undefined : heatInfluences(heat, [vertices[v][0], vertices[v][1]], spec.influences));
     if ('first' in li) return { overlap: { ...li, first: index[li.first], second: index[li.second] }, vertex: v, at };
     weights.push(li.influences.map((e) => ({ bone: e.bone, weight: e.weight })));
     local.push(li.region < 0 ? li : { ...li, region: index[li.region] });

package/src/build.ts

@@ -43,7 +43,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, hiddenLines, SINGLE_RUN_FACE_TAGS, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, hiddenLines, SINGLE_RUN_FACE_TAGS, driftLine, limbLines, FIGURE_MASK_FILE, figuresLine, holeKindsLine, holeLines, type ProjectRule, scenePhrase, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, sourceSelfFailure, stimulusMotion, withStimulus } from './automotion.ts';
@@ -237,11 +237,12 @@ export function readCaps(configPath: string, limbs: Readonly<Record<string, Limb
 
 /** Read, assemble, and write only after every refusal has had its chance. Throws a PartsError on a refusal, having written nothing. */
 export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs, log: Log): AssembleResult {
-  const src = readSource(input.source);
-  const runs = readRuns(input.full, input.head);
   // The early door: assemble runs before propose has drafted bones, meshes,
   // regions and motion, so it requires only what it reads (issue #20).
-  const fields = stageFields(loadEarlyConfig(input.config, 'assemble'), runs.single ? { w: src.width, h: src.height } : null);
+  const cfg = loadEarlyConfig(input.config, 'assemble');
+  const src = readSource(input.source);
+  const runs = readRuns(input.full, input.head);
+  const fields = stageFields(cfg, runs.single ? { w: src.width, h: src.height } : null);
   const under = readUnders(input.config, fields.cuts);
   const caps = fields.limbs === undefined ? undefined : readCaps(input.config, fields.limbs);
   const result = assemble({ source: src, full: runs.full, head: runs.head, ...fields, under, ...(caps === undefined ? {} : { caps }), seamRule: input.seam, projectRule: input.project });
@@ -292,6 +293,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   const scene = result.parts.scene === undefined ? null : scenePhrase(result.parts.scene, W * H);
   log(figuresLine(result.figures, scene));
   for (const l of holeLines(result.figures, scene)) log(l);
+  if (result.figures.uncoveredErrorPx > 0) log(holeKindsLine(result.holeKinds, scene));
   for (const u of result.uncovered) log(uncoveredLine(u, scene));
   for (const d of result.drift) log(driftLine(d));
   log(`wrote ${outs.partsJson}, ${result.images.length} PNG(s) in ${outs.partsDir}, ${outs.recomposite}, ${outs.errorMap} (uncovered error px red, covered error px blue, the painting grey)${figurePath === null ? '' : `, ${figurePath} (the figure, white, the recomposite was read inside)`}`);
@@ -1088,17 +1090,29 @@ export function judgementLine(name: string, line: JudgementLine | ReportedLine):
 }
 
 /**
- * The fold line (issues #320, #333) as the console prints it: the status, what was
- * read and at what rate, and then each folding mesh on a line of its own,
- * rigc's own words, with the declaration's why where `may_fold` takes it.
+ * The fold line (issues #320, #333, #363) as the console prints it: the status,
+ * what was read and at what rate, and then each folding mesh on a line of its
+ * own, with physics on and off side by side (and its physics constraints named
+ * when only physics folds it), rigc's own words, and the declaration's why
+ * where `may_fold` takes it.
  */
 export function foldsLines(line: FoldsLine): string[] {
-  const physics = line.physics_left_out === 0 ? '' : `, its ${line.physics_left_out} physics constraint(s) left out`;
+  const physics = line.physics_left_out === 0 ? '' : `, with its ${line.physics_left_out} physics constraint(s) on and off`;
   const head =
     `${FOLD_LINE}: ${line.status} — ${line.animations.length} animation(s) read by rigc render --folds at ${line.fps} fps${physics} (${line.animations.join(', ')}): ` +
     `${line.folding.length} folding mesh(es), ${line.folding_undeclared} not declared in may_fold (<= ${line.bar})` +
     (line.declared_not_folding.length === 0 ? '' : `; may_fold declares ${line.declared_not_folding.map((d) => `slot "${d.slot}" in "${d.animation}"`).join(', ')}, which do(es) not fold`);
-  return [head, ...line.folding.map((r) => `  folds  ${r.line}${r.declared === null ? '' : ` — declared in may_fold: ${r.declared}`}`)];
+  return [
+    head,
+    ...line.folding.map((r) => {
+      const side =
+        line.physics_left_out === 0
+          ? ''
+          : ` — physics on: ${r.physics_on === null ? '0 frame(s)' : `${r.physics_on.frames} frame(s), worst frame ${r.physics_on.worst_frame} (${r.physics_on.worst_triangles}/${r.triangles} triangle(s))`}; physics off: ${r.physics_off === null ? '0 frame(s)' : `${r.physics_off.frames} frame(s), worst frame ${r.physics_off.worst_frame} (${r.physics_off.worst_triangles}/${r.triangles} triangle(s))`}` +
+            (r.physics_constraints.length === 0 ? '' : `; physics constraint(s): ${r.physics_constraints.join(', ')}`);
+      return `  folds  ${r.line}${side}${r.declared === null ? '' : ` — declared in may_fold: ${r.declared}`}`;
+    }),
+  ];
 }
 
 /**