@rig-c/parts 1.36.0 → 1.38.0

package/src/assemble.ts

@@ -99,7 +99,7 @@
  *
  * Pure: no clock, no randomness, no file access. The CLI reads and writes.
  */
-import type { ArmSplit, BoneEntry, CharacterConfig, Cut, EarlyConfig, Extend, Limb, Patch, PlanEntry, Run, SeeThrough } from './config.ts';
+import { type ArmSplit, type BoneEntry, type CharacterConfig, type ControlSkeleton, controlSkeletonOf, type Cut, type EarlyConfig, type Extend, type Limb, type Patch, type PlanEntry, type Run, type SeeThrough } from './config.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { 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';
@@ -123,7 +123,7 @@ import {
   warpAffine,
 } from './raster/index.ts';
 import { pyRound } from './round.ts';
-import { AUTHOR_NO_ROLE, type LayerTagReading, readAuthorTag, readLayerTag } from './tags.ts';
+import { ARM_MERGED_SPLIT_TAGS, AUTHOR_NO_ROLE, type LayerTagReading, readAuthorTag, readLayerTag } from './tags.ts';
 
 const f32 = Math.fround;
 
@@ -234,8 +234,22 @@ export interface Geometry {
   single?: boolean;
   /** `seethrough.arm_split` (issue #439): separates overlapping arms on the full run into `handwear-r` and `handwear-l` in the declared order. */
   armSplit?: ArmSplit;
+  /** `generation.control.skeleton` (issue #490): the pose keypoints on the `latent` canvas, read for merged arm layers (`splitMergedArmRuns`). */
+  keySkeleton?: ControlSkeleton;
+  /** `assemble.head_face_underfill` (issue #492): composite `full:face` under `head:face` on the head canvas to fill transparent bare-skin holes. */
+  headFaceUnderfill?: boolean;
 }
 
+/**
+ * Issue #492: minimum share of the full run's hole-filled `face` silhouette
+ * (mapped onto the head canvas) that the head run's `face` layer must cover
+ * (`alpha > OPAQUE_ALPHA_ABOVE = 8`). Across the 5 public examples the ratio is
+ * `0.804..0.986` and across the 6 non-hollow standees `0.816..0.974`, whereas
+ * the 3 hollow standee runs sit at `0.000..0.486` — a `0.486 ↔ 0.804` gap of
+ * `31.8` percentage points.
+ */
+export const HEAD_FACE_COVERAGE_FLOOR = 0.75;
+
 /**
  * The tags a single run must hold, each as a layer with an opaque pixel
  * (issue #359): `face`, which places the face box, and the eye group
@@ -327,6 +341,10 @@ export interface AssembleInput {
   single?: boolean;
   /** `seethrough.arm_split` (issue #439): separates overlapping arms on the full run into `handwear-r` and `handwear-l` in the declared order. */
   armSplit?: ArmSplit;
+  /** `generation.control.skeleton` (issue #490): the pose keypoints on the `latent` canvas, read for merged arm layers (`splitMergedArmRuns`). */
+  keySkeleton?: ControlSkeleton;
+  /** `assemble.head_face_underfill` (issue #492): composite `full:face` under `head:face` on the head canvas to fill transparent bare-skin holes. */
+  headFaceUnderfill?: boolean;
 }
 
 /** The derived numbers of the two runs' geometry. */
@@ -725,6 +743,335 @@ function armSplitPlan(plan: readonly PlanEntry[], armSplit: ArmSplit | undefined
   return [...plan];
 }
 
+/**
+ * Issue #490: the minimum Euclidean RGB distance between the sleeve above the
+ * wrist and the non-skin overgarment drape extending more than one forearm
+ * length below the wrist for `splitMergedArmRuns` to split the merged
+ * `handwear-r` / `handwear-l` layer into `drape-<s>`, `handwear-<s>` and
+ * `hand-<s>` instead of refusing with `SEETHROUGH_ARM_RUN_MERGED`.
+ *
+ * Measured across the 9-standee corpus (issue #490, `forearm = 211.3` run px):
+ * the 6 clean standees hold `spanBelowWrist <= 94.9` px (`<= 0.45x` forearm) and
+ * the 3 merged standees hold `264.9..425.9` px (`1.25x..2.02x` forearm), placing
+ * the `1.0x` forearm threshold inside the `0.45x..1.25x` gap; on the 3 merged
+ * standees (`780..4,787` skin hand px vs the `GHOST_MIN_AREA = 40` px floor),
+ * the two with distinct sleeve and drape colours measure Euclidean RGB distance
+ * `103.6 / 106.9` (`standee-1`) and `215.7 / 236.0` (`standee-2`), while the
+ * one whose outer robe shares the sleeve's colour measures `20.8 / 28.2`
+ * (`standee-5`), placing `80` between `28.2` and `103.6`.
+ */
+export const ARM_DRAPE_COLOR_DISTANCE = 80;
+
+function medianChannelRgb(pixels: ReadonlyArray<readonly [number, number, number]>): [number, number, number] | null {
+  if (pixels.length === 0) return null;
+  const rs = pixels.map((p) => p[0]).sort((a, b) => a - b);
+  const gs = pixels.map((p) => p[1]).sort((a, b) => a - b);
+  const bs = pixels.map((p) => p[2]).sort((a, b) => a - b);
+  const mid = Math.floor(pixels.length / 2);
+  return [rs[mid], gs[mid], bs[mid]];
+}
+
+function rgbDist(a: readonly [number, number, number], b: readonly [number, number, number]): number {
+  const dr = a[0] - b[0];
+  const dg = a[1] - b[1];
+  const db = a[2] - b[2];
+  return Math.sqrt(dr * dr + dg * dg + db * db);
+}
+
+function faceMedianRgb(set: LayerSet, resolution: number): [number, number, number] {
+  const face = set.layers.find((l) => l.name === 'face');
+  if (face === undefined) return [250, 225, 210];
+  const { canvas } = cleanGhosts(placeLayer(face, resolution));
+  const px: Array<[number, number, number]> = [];
+  for (let i = 0; i < resolution * resolution; i++) {
+    const a = canvas.data[i * 4 + 3];
+    if (a < CORE_ALPHA) continue;
+    const r = canvas.data[i * 4];
+    const g = canvas.data[i * 4 + 1];
+    const b = canvas.data[i * 4 + 2];
+    if (Math.min(r, g, b) > NEAR_WHITE_MIN) continue;
+    px.push([r, g, b]);
+  }
+  return medianChannelRgb(px) ?? [250, 225, 210];
+}
+
+/**
+ * Issue #490: inspect `handwear-r` and `handwear-l` in the full run against the
+ * pose keypoints (`generation.control.skeleton`). When an arm layer holds a
+ * skin-coloured hand cluster at `<s>_wrist` (`>= GHOST_MIN_AREA` = `40` opaque
+ * run px) and its non-skin pixels reach more than `1.0x` the forearm length
+ * (`|wrist - elbow|`) below `<s>_wrist`, See-through merged the sleeve, the
+ * hand and the overgarment drape into one arm layer.
+ *
+ * - When the Euclidean RGB distance between the sleeve above the wrist and the
+ *   drape below the wrist is at least {@link ARM_DRAPE_COLOR_DISTANCE} (`80`),
+ *   splits `handwear-<s>` into three layers in draw order (back to front):
+ *   `drape-<s>` (overgarment below the cut), `handwear-<s>` (the sleeve above
+ *   the cut) and `hand-<s>` (the skin hand cluster at the wrist).
+ * - When that distance is below {@link ARM_DRAPE_COLOR_DISTANCE}, refuses with
+ *   `SEETHROUGH_ARM_RUN_MERGED` naming the layer, the span below the wrist vs
+ *   the forearm length, the sleeve and drape RGBs and their Euclidean distance.
+ */
+export function splitMergedArmRunsWithNotes(
+  set: LayerSet,
+  resolution: number,
+  frame: Pick<Frame, 'fullPad' | 'fullPadTop' | 'fullK'>,
+  sourceW: number,
+  sourceH: number,
+  keySkeleton: ControlSkeleton,
+): { set: LayerSet; notes: string[] } {
+  const [latentW, latentH] = keySkeleton.latent;
+  const sx = sourceW / latentW;
+  const sy = sourceH / latentH;
+  const toRun = (pt: readonly [number, number]): { x: number; y: number } => ({
+    x: (pt[0] * sx + frame.fullPad) / frame.fullK,
+    y: (pt[1] * sy + frame.fullPadTop) / frame.fullK,
+  });
+  const fRGB = faceMedianRgb(set, resolution);
+  const problems: Problem[] = [];
+  const notes: string[] = [];
+  const replacements = new Map<'handwear-r' | 'handwear-l', Layer[]>();
+
+  for (const s of ['r', 'l'] as const) {
+    const tag = `handwear-${s}` as const;
+    const hwLayer = set.layers.find((l) => l.name === tag);
+    if (hwLayer === undefined) continue;
+    const { canvas: cleaned } = cleanGhosts(placeLayer(hwLayer, resolution));
+    const sh = toRun(keySkeleton.points[`${s}_shoulder`]);
+    const el = toRun(keySkeleton.points[`${s}_elbow`]);
+    const wr = toRun(keySkeleton.points[`${s}_wrist`]);
+    const fdx = wr.x - el.x;
+    const fdy = wr.y - el.y;
+    const forearm = Math.sqrt(fdx * fdx + fdy * fdy);
+    if (!(forearm > 0)) continue;
+
+    // 1. Skin-coloured hand cluster in the wrist window.
+    const skinRaw = newMask(resolution, resolution);
+    const winX0 = Math.max(0, Math.floor(wr.x - 0.45 * forearm));
+    const winX1 = Math.min(resolution - 1, Math.ceil(wr.x + 0.45 * forearm));
+    const winY0 = Math.max(0, Math.floor(wr.y - 0.65 * forearm));
+    const winY1 = Math.min(resolution - 1, Math.ceil(wr.y + 0.35 * forearm));
+    for (let y = winY0; y <= winY1; y++) {
+      for (let x = winX0; x <= winX1; x++) {
+        const idx = (y * resolution + x) * 4;
+        const a = cleaned.data[idx + 3];
+        if (a <= OPAQUE_ALPHA_ABOVE) continue;
+        const r = cleaned.data[idx];
+        const g = cleaned.data[idx + 1];
+        const b = cleaned.data[idx + 2];
+        if (Math.min(r, g, b) > NEAR_WHITE_MIN) continue;
+        const fDist = rgbDist([r, g, b], fRGB);
+        const warmOrder = r >= g && g >= b && r - b >= 12 && g - b <= 45;
+        if (warmOrder && (fDist < 65 || (r > 145 && g > 95 && b > 55 && r - b <= 95))) {
+          skinRaw.data[y * resolution + x] = 1;
+        }
+      }
+    }
+    const skinClosed = fillHoles(morphClose(skinRaw, CORE_KERNEL));
+    const cc = connectedComponents(skinClosed, 8);
+    const keepHand = new Uint8Array(cc.count);
+    for (let c = 1; c < cc.count; c++) {
+      const st = cc.stats[c];
+      if (st.area < GHOST_MIN_AREA) continue;
+      const dx = wr.x < st.left ? st.left - wr.x : wr.x > st.left + st.width - 1 ? wr.x - (st.left + st.width - 1) : 0;
+      const dy = wr.y < st.top ? st.top - wr.y : wr.y > st.top + st.height - 1 ? wr.y - (st.top + st.height - 1) : 0;
+      if (Math.sqrt(dx * dx + dy * dy) <= 0.35 * forearm) keepHand[c] = 1;
+    }
+    const handMask = newMask(resolution, resolution);
+    let handPx = 0;
+    let handMinY = resolution;
+    let handMaxY = -1;
+    for (let y = 0; y < resolution; y++) {
+      for (let x = 0; x < resolution; x++) {
+        const i = y * resolution + x;
+        if (keepHand[cc.labels[i]] === 1 && cleaned.data[i * 4 + 3] > OPAQUE_ALPHA_ABOVE) {
+          handMask.data[i] = 1;
+          handPx++;
+          if (y < handMinY) handMinY = y;
+          if (y > handMaxY) handMaxY = y;
+        }
+      }
+    }
+    if (handPx < GHOST_MIN_AREA) continue;
+
+    // 2. Non-skin span below the wrist vs forearm length.
+    let nonSkinMaxY = -1;
+    for (let y = 0; y < resolution; y++) {
+      for (let x = 0; x < resolution; x++) {
+        const i = y * resolution + x;
+        if (cleaned.data[i * 4 + 3] > OPAQUE_ALPHA_ABOVE && handMask.data[i] === 0) {
+          if (y > nonSkinMaxY) nonSkinMaxY = y;
+        }
+      }
+    }
+    const spanBelowWrist = nonSkinMaxY - wr.y;
+    if (!(spanBelowWrist > forearm)) continue;
+
+    // 3. Sleeve vs drape colour distance.
+    const midArmY = Math.round((sh.y + wr.y) / 2);
+    const band1Px: Array<[number, number, number]> = [];
+    const band2Px: Array<[number, number, number]> = [];
+    const drapePx: Array<[number, number, number]> = [];
+    const wrFloor = Math.floor(wr.y);
+    const drapeStart = Math.floor(wr.y + 0.15 * forearm);
+    for (let y = 0; y < resolution; y++) {
+      for (let x = 0; x < resolution; x++) {
+        const i = y * resolution + x;
+        if (handMask.data[i] === 1) continue;
+        const a = cleaned.data[i * 4 + 3];
+        if (a < CORE_ALPHA) continue;
+        const r = cleaned.data[i * 4];
+        const g = cleaned.data[i * 4 + 1];
+        const b = cleaned.data[i * 4 + 2];
+        if (Math.min(r, g, b) > NEAR_WHITE_MIN) continue;
+        if (y <= wrFloor) {
+          if (y < midArmY) band1Px.push([r, g, b]);
+          else band2Px.push([r, g, b]);
+        } else if (y >= drapeStart) {
+          drapePx.push([r, g, b]);
+        }
+      }
+    }
+    const c1 = medianChannelRgb(band1Px);
+    const c2 = medianChannelRgb(band2Px);
+    const drapeRGB = medianChannelRgb(drapePx);
+    const d1 = c1 !== null && drapeRGB !== null ? rgbDist(c1, drapeRGB) : 0;
+    const d2 = c2 !== null && drapeRGB !== null ? rgbDist(c2, drapeRGB) : 0;
+    const bestDist = Math.max(d1, d2);
+    const sleeveRGB = (d1 >= d2 ? c1 ?? c2 : c2 ?? c1) ?? [0, 0, 0];
+    const drapeShown = drapeRGB ?? [0, 0, 0];
+
+    if (drapeRGB === null || (c1 === null && c2 === null) || bestDist < ARM_DRAPE_COLOR_DISTANCE) {
+      problems.push({
+        code: 'SEETHROUGH_ARM_RUN_MERGED',
+        object: `the full run (${set.source}) layer "${tag}"`,
+        detail:
+          `merges the sleeve, the hand (${handPx} skin px around ${s}_wrist at (${Math.round(wr.x)}, ${Math.round(wr.y)}), rows y=${handMinY}..${handMaxY}) and the overgarment into one arm layer: non-skin pixels reach y=${nonSkinMaxY}, ${spanBelowWrist.toFixed(1)} px (${(spanBelowWrist / forearm).toFixed(2)}x the forearm length ${forearm.toFixed(1)} px from ${s}_elbow to ${s}_wrist) below ${s}_wrist, and the sleeve above ${s}_wrist (rgb(${sleeveRGB.join(', ')})) and the drape below ${s}_wrist (rgb(${drapeShown.join(', ')})) have Euclidean RGB distance ${bestDist.toFixed(1)} (< ${ARM_DRAPE_COLOR_DISTANCE}); ` +
+          `non-skin pixels reaching at most 1.0x the forearm length (${forearm.toFixed(1)} px) below ${s}_wrist, or a sleeve-to-drape Euclidean RGB distance of at least ${ARM_DRAPE_COLOR_DISTANCE} so the stage can split "${tag}" into "drape-${s}", "${tag}" and "hand-${s}", is required — re-seed config.seethrough.seed, split the merged layer into author: layers in the full run, or cut the overgarment from the sleeve in config.assemble.cuts`,
+      });
+      continue;
+    }
+
+    // 4. Split into drape-<s>, handwear-<s> and hand-<s> (back to front).
+    const cutY = Math.max(Math.round(wr.y), handMaxY);
+    const elY = Math.round(el.y);
+    const drapeCanvas = newRaster(resolution, resolution);
+    const sleeveCanvas = newRaster(resolution, resolution);
+    const handCanvas = newRaster(resolution, resolution);
+    for (let y = 0; y < resolution; y++) {
+      for (let x = 0; x < resolution; x++) {
+        const i = y * resolution + x;
+        const p = i * 4;
+        if (cleaned.data[p + 3] === 0) continue;
+        if (handMask.data[i] === 1) {
+          handCanvas.data.set(cleaned.data.subarray(p, p + 4), p);
+        } else if (y > cutY) {
+          drapeCanvas.data.set(cleaned.data.subarray(p, p + 4), p);
+        } else if (d2 < ARM_DRAPE_COLOR_DISTANCE && y > elY) {
+          const px: [number, number, number] = [cleaned.data[p], cleaned.data[p + 1], cleaned.data[p + 2]];
+          const dst = rgbDist(px, drapeRGB) < rgbDist(px, sleeveRGB) ? drapeCanvas.data : sleeveCanvas.data;
+          dst.set(cleaned.data.subarray(p, p + 4), p);
+        } else {
+          sleeveCanvas.data.set(cleaned.data.subarray(p, p + 4), p);
+        }
+      }
+    }
+    const buildSplitLayer = (name: string, canvas: Raster): Layer | null => {
+      let opaque = 0;
+      let x0 = resolution;
+      let y0 = resolution;
+      let x1 = -1;
+      let y1 = -1;
+      for (let y = 0; y < resolution; y++) {
+        for (let x = 0; x < resolution; x++) {
+          const a = canvas.data[(y * resolution + x) * 4 + 3];
+          if (a > OPAQUE_ALPHA_ABOVE) opaque++;
+          if (a > 0) {
+            if (x < x0) x0 = x;
+            if (x > x1) x1 = x;
+            if (y < y0) y0 = y;
+            if (y > y1) y1 = y;
+          }
+        }
+      }
+      if (opaque === 0 || x1 < x0) return null;
+      return {
+        name,
+        tag: readLayerTag(name) as LayerTagReading,
+        file: hwLayer.file,
+        pixels: crop(canvas, x0, y0, x1 - x0 + 1, y1 - y0 + 1),
+        left: x0,
+        top: y0,
+        right: x1 + 1,
+        bottom: y1 + 1,
+        depth: hwLayer.depth,
+        drawOrder: 0,
+        opaquePx: opaque,
+      };
+    };
+    const drapeLayer = buildSplitLayer(`drape-${s}`, drapeCanvas);
+    const sleeveLayer = buildSplitLayer(tag, sleeveCanvas);
+    const handLayer = buildSplitLayer(`hand-${s}`, handCanvas);
+    if (drapeLayer !== null && sleeveLayer !== null && handLayer !== null) {
+      replacements.set(tag, [drapeLayer, sleeveLayer, handLayer]);
+      notes.push(
+        `${tag}: merged arm layer (${handPx} skin hand px at ${s}_wrist y=${handMinY}..${handMaxY}, non-skin reaching y=${nonSkinMaxY}, ${(spanBelowWrist / forearm).toFixed(2)}x forearm ${forearm.toFixed(1)} px; sleeve rgb(${sleeveRGB.join(', ')}) vs drape rgb(${drapeRGB.join(', ')}) Euclidean distance ${bestDist.toFixed(1)} >= ${ARM_DRAPE_COLOR_DISTANCE}) -> split into drape-${s} (${drapeLayer.opaquePx} px), ${tag} (${sleeveLayer.opaquePx} px) and hand-${s} (${handLayer.opaquePx} px)`,
+      );
+    }
+  }
+
+  refuseIfAny(problems);
+  if (replacements.size === 0) return { set, notes };
+
+  const nextLayers: Layer[] = [];
+  for (const l of set.layers) {
+    const rep = (l.name === 'handwear-r' || l.name === 'handwear-l') ? replacements.get(l.name) : undefined;
+    if (rep !== undefined) nextLayers.push(...rep);
+    else nextLayers.push({ ...l });
+  }
+  nextLayers.forEach((l, i) => {
+    l.drawOrder = i;
+  });
+  return { set: { ...set, layers: nextLayers }, notes };
+}
+
+export function splitMergedArmRuns(
+  set: LayerSet,
+  resolution: number,
+  frame: Pick<Frame, 'fullPad' | 'fullPadTop' | 'fullK'>,
+  sourceW: number,
+  sourceH: number,
+  keySkeleton: ControlSkeleton,
+): LayerSet {
+  return splitMergedArmRunsWithNotes(set, resolution, frame, sourceW, sourceH, keySkeleton).set;
+}
+
+/**
+ * Issue #490: when `splitMergedArmRuns` split `full:handwear-<s>` into
+ * `drape-<s>`, `handwear-<s>` and `hand-<s>`, expand a lone `full:handwear-<s>`
+ * row in `assemble.plan` (when `drape-<s>` and `hand-<s>` are not already in
+ * `plan`) into `[["drape_<s>", "full", "drape-<s>"], [name, "full", "handwear-<s>"], ["hand_<s>", "full", "hand-<s>"]]`.
+ */
+export function mergedArmSplitPlan(plan: readonly PlanEntry[], full: LayerSet): PlanEntry[] {
+  const fullTags = new Set(full.layers.map((l) => l.name));
+  const plannedFullTags = new Set(plan.filter(([, run]) => run === 'full').map(([, , tag]) => tag));
+  const out: PlanEntry[] = [];
+  for (const entry of plan) {
+    const [name, run, tag] = entry;
+    if (run === 'full' && (tag === 'handwear-r' || tag === 'handwear-l')) {
+      const s = tag === 'handwear-r' ? 'r' : 'l';
+      const drapeTag = `drape-${s}`;
+      const handTag = `hand-${s}`;
+      if (fullTags.has(drapeTag) && fullTags.has(handTag) && !plannedFullTags.has(drapeTag) && !plannedFullTags.has(handTag)) {
+        out.push([aliasOf(drapeTag), 'full', drapeTag], [name, 'full', tag], [aliasOf(handTag), 'full', handTag]);
+        continue;
+      }
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // step 2 — resample into rig space
 // ---------------------------------------------------------------------------
@@ -782,6 +1129,208 @@ export function layerToRig(canvas: Raster, frame: Frame, run: Run): Raster {
   return out;
 }
 
+/**
+ * Issue #492: warp a full-run layer (`resolution x resolution`) onto the head
+ * run's `resolution x resolution` canvas using the same premultiplied float32
+ * `warpAffine` round-trip as {@link layerToRig} (`head = (fullK / headK) * full
+ * - (headBox + fullPad) / headK`).
+ */
+export function fullLayerToHead(
+  canvas: Raster,
+  frame: Pick<Frame, 'fullK' | 'fullPad' | 'fullPadTop' | 'headBox' | 'headK'>,
+  resolution: number,
+): Raster {
+  const n = canvas.width * canvas.height;
+  let any = false;
+  for (let i = 0; i < n && !any; i++) if (canvas.data[i * 4 + 3] !== 0) any = true;
+  if (!any) return newRaster(resolution, resolution);
+  const pre = newFloatImage(canvas.width, canvas.height, 4);
+  for (let i = 0; i < n; i++) {
+    const a = canvas.data[i * 4 + 3];
+    const af = f32(a / 255);
+    for (let c = 0; c < 3; c++) pre.data[i * 4 + c] = f32(canvas.data[i * 4 + c] * af);
+    pre.data[i * 4 + 3] = a;
+  }
+  const k = frame.fullK / frame.headK;
+  const sx = f32(k);
+  const tx = f32(-(frame.headBox[0] + frame.fullPad) / frame.headK);
+  const ty = frame.fullPadTop === 0 && frame.headBox[1] === 0 ? 0 : f32(-(frame.headBox[1] + frame.fullPadTop) / frame.headK);
+  const wr = warpAffine(pre, { sx, sy: sx, tx, ty }, resolution, resolution, k < 1 ? 'bilinear' : 'bicubic');
+  const out = newRaster(resolution, resolution);
+  const eps = f32(1e-3);
+  const clip = (v: number): number => (v < 0 ? 0 : v > 255 ? 255 : v);
+  for (let i = 0; i < resolution * resolution; i++) {
+    const a = f32(clip(wr.data[i * 4 + 3]));
+    for (let c = 0; c < 3; c++) {
+      const v = f32(clip(wr.data[i * 4 + c]));
+      out.data[i * 4 + c] = a > 0 ? Math.trunc(clip(f32(f32(v * 255) / Math.max(a, eps)))) : 0;
+    }
+    out.data[i * 4 + 3] = Math.trunc(a);
+  }
+  return out;
+}
+
+/**
+ * Issue #492: compare the head run's `face` layer against the full run's
+ * hole-filled `face` silhouette on the head canvas (`resolution x resolution`),
+ * optionally compositing `full:face` under `head:face` when
+ * `config.assemble.head_face_underfill: true` is declared and the head run
+ * provides a `face` outline (`opaqueRunPx >= minPx`), and refusing with
+ * `SEETHROUGH_HEAD_RUN_HOLLOW` when the head run's `face` covers less than
+ * {@link HEAD_FACE_COVERAGE_FLOOR} (`0.75`) of the full run's face silhouette.
+ */
+function prepareHeadFace(
+  full: LayerSet,
+  head: LayerSet,
+  frame: Pick<Frame, 'fullK' | 'fullPad' | 'fullPadTop' | 'headBox' | 'headK'>,
+  resolution: number,
+  underfill: boolean,
+  minPx = PROPOSE_MIN_PX,
+): { head: LayerSet; underfillPx: number; underfillNote: string | null } {
+  if (full.source !== '' && full.source === head.source) return { head, underfillPx: 0, underfillNote: null };
+  const fullFaceLayer = full.layers.find((l) => l.name === 'face');
+  if (fullFaceLayer === undefined) return { head, underfillPx: 0, underfillNote: null };
+  const cleanedFull = cleanGhosts(placeLayer(fullFaceLayer, resolution));
+  let fullOpaqueRunPx = 0;
+  for (let i = 3; i < cleanedFull.canvas.data.length; i += 4) {
+    if (cleanedFull.canvas.data[i] > OPAQUE_ALPHA_ABOVE) fullOpaqueRunPx++;
+  }
+  if (fullOpaqueRunPx < minPx) return { head, underfillPx: 0, underfillNote: null };
+
+  const warpedFull = fullLayerToHead(cleanedFull.canvas, frame, resolution);
+  const rawFullMask = newMask(resolution, resolution);
+  for (let p = 0; p < resolution * resolution; p++) {
+    if (warpedFull.data[p * 4 + 3] > OPAQUE_ALPHA_ABOVE) rawFullMask.data[p] = 1;
+  }
+  const fullSil = fillHoles(rawFullMask);
+  let fullPx = 0;
+  let minY = resolution;
+  let maxY = -1;
+  for (let y = 0; y < resolution; y++) {
+    for (let x = 0; x < resolution; x++) {
+      if (fullSil.data[y * resolution + x] === 1) {
+        fullPx++;
+        if (y < minY) minY = y;
+        if (y > maxY) maxY = y;
+      }
+    }
+  }
+  if (fullPx < minPx) return { head, underfillPx: 0, underfillNote: null };
+
+  const headFaceLayer = head.layers.find((l) => l.name === 'face');
+  const cleanedHead =
+    headFaceLayer === undefined
+      ? { canvas: newRaster(resolution, resolution), ghostPx: 0 }
+      : cleanGhosts(placeLayer(headFaceLayer, resolution));
+  let headRawOpaquePx = 0;
+  for (let i = 3; i < cleanedHead.canvas.data.length; i += 4) {
+    if (cleanedHead.canvas.data[i] > OPAQUE_ALPHA_ABOVE) headRawOpaquePx++;
+  }
+
+  const measureCoverage = (canvas: Raster): { headOv: number; cov: number; upCov: number; loCov: number } => {
+    const midY = (minY + maxY) / 2;
+    let fullUpPx = 0;
+    let fullLoPx = 0;
+    let headOv = 0;
+    let headUpOv = 0;
+    let headLoOv = 0;
+    for (let y = minY; y <= maxY; y++) {
+      for (let x = 0; x < resolution; x++) {
+        const p = y * resolution + x;
+        if (fullSil.data[p] !== 1) continue;
+        if (y <= midY) fullUpPx++;
+        else fullLoPx++;
+        if (canvas.data[p * 4 + 3] > OPAQUE_ALPHA_ABOVE) {
+          headOv++;
+          if (y <= midY) headUpOv++;
+          else headLoOv++;
+        }
+      }
+    }
+    return {
+      headOv,
+      cov: headOv / fullPx,
+      upCov: fullUpPx > 0 ? headUpOv / fullUpPx : 0,
+      loCov: fullLoPx > 0 ? headLoOv / fullLoPx : 0,
+    };
+  };
+
+  const rawStats = measureCoverage(cleanedHead.canvas);
+  let activeHead = head;
+  let activeCanvas = cleanedHead.canvas;
+  let underfillPx = 0;
+  let underfillNote: string | null = null;
+
+  if (underfill && headFaceLayer !== undefined && headRawOpaquePx >= minPx) {
+    const comp = newRaster(resolution, resolution);
+    let compOpaquePx = 0;
+    let x0 = resolution;
+    let y0 = resolution;
+    let x1 = -1;
+    let y1 = -1;
+    for (let y = 0; y < resolution; y++) {
+      for (let x = 0; x < resolution; x++) {
+        const p = y * resolution + x;
+        const i = p * 4;
+        const ta = cleanedHead.canvas.data[i + 3];
+        const ua = warpedFull.data[i + 3];
+        const a = Math.max(ta, ua);
+        if (a === 0) continue;
+        const tf = ta / 255;
+        for (let c = 0; c < 3; c++) {
+          comp.data[i + c] = Math.trunc(cleanedHead.canvas.data[i + c] * tf + warpedFull.data[i + c] * (1 - tf));
+        }
+        comp.data[i + 3] = a;
+        if (ta <= OPAQUE_ALPHA_ABOVE && a > OPAQUE_ALPHA_ABOVE) underfillPx++;
+        if (a > OPAQUE_ALPHA_ABOVE) compOpaquePx++;
+        if (x < x0) x0 = x;
+        if (y < y0) y0 = y;
+        if (x > x1) x1 = x;
+        if (y > y1) y1 = y;
+      }
+    }
+    if (x1 >= x0 && y1 >= y0) {
+      activeCanvas = comp;
+      const postStats = measureCoverage(comp);
+      const replacedLayer: Layer = {
+        ...headFaceLayer,
+        pixels: crop(comp, x0, y0, x1 - x0 + 1, y1 - y0 + 1),
+        left: x0,
+        top: y0,
+        right: x1 + 1,
+        bottom: y1 + 1,
+        opaquePx: compOpaquePx,
+      };
+      activeHead = {
+        ...head,
+        layers: head.layers.map((l) => (l.name === 'face' ? replacedLayer : l)),
+      };
+      if (underfillPx > 0) {
+        underfillNote = `face: head_face_underfill composited full:face under head:face on the head canvas, filling ${underfillPx} transparent px (${rawStats.headOv} / ${fullPx} px, ${(rawStats.cov * 100).toFixed(1)}% -> ${postStats.headOv} / ${fullPx} px, ${(postStats.cov * 100).toFixed(1)}%)`;
+      }
+    }
+  }
+
+  const finalStats = activeCanvas === cleanedHead.canvas ? rawStats : measureCoverage(activeCanvas);
+  if (finalStats.cov < HEAD_FACE_COVERAGE_FLOOR) {
+    const covStr = `${finalStats.headOv} / ${fullPx} px (${(finalStats.cov * 100).toFixed(1)}%, upper half ${(finalStats.upCov * 100).toFixed(1)}%, lower half ${(finalStats.loCov * 100).toFixed(1)}%)`;
+    const floorStr = `${(HEAD_FACE_COVERAGE_FLOOR * 100).toFixed(1)}% (HEAD_FACE_COVERAGE_FLOOR = ${HEAD_FACE_COVERAGE_FLOOR})`;
+    const detail =
+      headFaceLayer === undefined || headRawOpaquePx < minPx
+        ? `${headFaceLayer === undefined ? 'holds no layer "face"' : `holds ${headRawOpaquePx} opaque px (alpha > ${OPAQUE_ALPHA_ABOVE}, below PROPOSE_MIN_PX = ${minPx})`}, covering ${covStr} of the full run's "face" silhouette on the head canvas (${fullOpaqueRunPx} full-run px); at least ${floorStr} is required — the head run omitted the face layer (so config.assemble.head_face_underfill cannot supply a jawline); re-run See-through with a different config.seethrough.seed`
+        : `covers ${covStr} of the full run's "face" silhouette on the head canvas (${headRawOpaquePx} head-run px vs ${fullOpaqueRunPx} full-run px) — See-through left bare skin inside the face silhouette transparent; at least ${floorStr} is required — re-run See-through with a different config.seethrough.seed, or set "head_face_underfill": true in config.assemble to composite full:face under head:face on the head canvas`;
+    refuseIfAny([
+      {
+        code: 'SEETHROUGH_HEAD_RUN_HOLLOW',
+        object: `the head run (${head.source}) layer "face"`,
+        detail,
+      },
+    ]);
+  }
+
+  return { head: activeHead, underfillPx, underfillNote };
+}
+
 /**
  * The painting in rig space: `PIL.Image.resize(..., LANCZOS)` of its RGB, as
  * an opaque raster. (`src/raster/resize.ts` `lanczos3` is PIL's, bit-exact;
@@ -2614,6 +3163,8 @@ export interface AssembleResult {
   hidden: HiddenArtUse[];
   seamRule: SeamRule;
   projectRule: ProjectRule;
+  /** Issue #492: head-canvas pixels filled by `config.assemble.head_face_underfill: true` when > 0. */
+  headFaceUnderfillPx?: number;
 }
 
 /** A hidden-art layer of a run (issue #359) and what read it: `cuts[i].under`, or a limb segment's cap; none is said. */
@@ -2769,9 +3320,19 @@ export function assemble(input: AssembleInput): AssembleResult {
   // Issue #366: one run's file, padded to the resolution square; read as both runs, as before.
   const fullPadded = single ? padSingleRun(input.full, frame, input.resolution) : input.full;
   // Issue #439: when seethrough.arm_split is declared, split the full run's overlapping handwear into handwear-r and handwear-l.
-  const full = input.armSplit === undefined ? fullPadded : applyArmSplit(fullPadded, input.resolution, input.armSplit);
-  const head = single ? full : input.head;
-  const plan = armSplitPlan(input.plan, input.armSplit);
+  const fullArmSplit = input.armSplit === undefined ? fullPadded : applyArmSplit(fullPadded, input.resolution, input.armSplit);
+  // Issue #490: when generation.control.skeleton is present, split merged arm layers (or refuse when sleeve and drape share one colour).
+  const full = input.keySkeleton === undefined ? fullArmSplit : splitMergedArmRuns(fullArmSplit, input.resolution, frame, source.width, source.height, input.keySkeleton);
+  const plan = mergedArmSplitPlan(armSplitPlan(input.plan, input.armSplit), full);
+  // Issue #492: in two-run mode, check that head:face covers >= 75% of full:face's silhouette on the head canvas
+  // (after applying head_face_underfill when declared). Skip only on a single-run subset (a mouth-only or clothes-only alternate).
+  const checkHeadFace =
+    !single &&
+    (plan.some(([, r, t]) => r === 'head' && t === 'face') || (plan.some(([, r]) => r === 'full') && plan.some(([, r]) => r === 'head')));
+  const headFacePrep = checkHeadFace
+    ? prepareHeadFace(full, input.head, frame, input.resolution, input.headFaceUnderfill === true)
+    : { head: single ? full : input.head, underfillPx: 0, underfillNote: null };
+  const head = headFacePrep.head;
   const padRecord = singleRunPadRecord(single, source.width, source.height, input.resolution, frame);
   if (single) checkSingleRun(full, plan, extend);
   checkPlanAgainstRuns(plan, extend, full, head);
@@ -3268,6 +3829,7 @@ export function assemble(input: AssembleInput): AssembleResult {
     hidden: [...hiddenUses].map(([layer, readBy]) => ({ layer, readBy })),
     seamRule,
     projectRule,
+    ...(headFacePrep.underfillPx > 0 ? { headFaceUnderfillPx: headFacePrep.underfillPx } : {}),
   };
 }
 
@@ -3761,8 +4323,16 @@ export function proposePlan(full0: LayerSet, head0: LayerSet, g: Geometry, minPx
   // Issue #366: one run's file, padded to the resolution square as the stage pads it.
   const fullPadded = g.single === true ? padSingleRun(full0, frame, g.resolution) : full0;
   // Issue #439: when seethrough.arm_split is declared, split the full run's overlapping handwear into handwear-r and handwear-l.
-  const full = g.armSplit === undefined ? fullPadded : applyArmSplit(fullPadded, g.resolution, g.armSplit);
-  const head = g.single === true ? full : head0;
+  const fullArmSplit = g.armSplit === undefined ? fullPadded : applyArmSplit(fullPadded, g.resolution, g.armSplit);
+  // Issue #490: when generation.control.skeleton is present, split merged arm layers (or refuse when sleeve and drape share one colour).
+  const mergedSplit = g.keySkeleton === undefined ? { set: fullArmSplit, notes: [] as string[] } : splitMergedArmRunsWithNotes(fullArmSplit, g.resolution, frame, g.sourceW, g.sourceH, g.keySkeleton);
+  const full = mergedSplit.set;
+  // Issue #492: check (and when head_face_underfill: true, repair) a hollow head-run face against full:face mapped into the head canvas.
+  const headFacePrep =
+    g.single === true
+      ? { head: full, underfillPx: 0, underfillNote: null as string | null }
+      : prepareHeadFace(full, head0, frame, g.resolution, g.headFaceUnderfill === true, minPx);
+  const head = headFacePrep.head;
   const runs = { full: runLayers(full, g.resolution), head: runLayers(head, g.resolution) };
   const find = (run: Run, tag: string): RunLayer | undefined => runs[run].find((l) => l.tag === tag);
   const figures: Record<Run, LayerFigures[]> = { full: layerFigures(full), head: layerFigures(head) };
@@ -3781,7 +4351,8 @@ export function proposePlan(full0: LayerSet, head0: LayerSet, g: Geometry, minPx
   };
   const ok = (run: Run, tag: string): boolean => {
     const l = find(run, tag);
-    return tag !== 'nose' && l !== undefined && l.opaqueRunPx >= minPx && !implausible(run, tag, 'not proposed');
+    const floor = ARM_MERGED_SPLIT_TAGS.some((p) => tag === `${p}-r` || tag === `${p}-l`) ? 1 : minPx;
+    return tag !== 'nose' && l !== undefined && l.opaqueRunPx >= floor && !implausible(run, tag, 'not proposed');
   };
   const body = runs.full.filter((l) => !PROPOSE_HEAD_TAGS.includes(l.tag) && ok('full', l.tag)).map((l) => l.tag);
   // Issue #256: an author-made layer is proposed from the run that holds it, at its place in that run's draw order,
@@ -3807,7 +4378,7 @@ export function proposePlan(full0: LayerSet, head0: LayerSet, g: Geometry, minPx
     }
     plan.push([t.startsWith('handwear') && hw.length === 1 ? 'sleeves' : aliasOf(t), 'full', t]);
   }
-  const notes: string[] = [];
+  const notes: string[] = [...mergedSplit.notes, ...(headFacePrep.underfillNote === null ? [] : [headFacePrep.underfillNote])];
   const headArea = (frame.headK * frame.S) ** 2;
   const fullArea = (frame.fullK * frame.S) ** 2;
   for (const t of ['headwear', 'earwear']) {
@@ -4013,6 +4584,8 @@ export function stageFields(
   bones?: BoneEntry[];
   single?: boolean;
   armSplit?: ArmSplit;
+  keySkeleton?: ControlSkeleton;
+  headFaceUnderfill?: boolean;
 } {
   const problems: Problem[] = [];
   if (cfg.seethrough === undefined) {
@@ -4023,11 +4596,14 @@ export function stageFields(
   }
   refuseIfAny(problems);
   const st = cfg.seethrough as SeeThrough;
+  const keySkeleton = controlSkeletonOf(cfg);
   return {
     resolution: st.resolution,
     headBox: single !== null ? singleRunHeadBox(single.w, single.h, st.resolution) : (st.head_box as [number, number, number, number]),
     ...(single !== null ? { single: true } : {}),
     ...(st.arm_split === undefined ? {} : { armSplit: st.arm_split }),
+    ...(keySkeleton === undefined ? {} : { keySkeleton }),
+    ...(cfg.assemble.head_face_underfill === undefined ? {} : { headFaceUnderfill: cfg.assemble.head_face_underfill }),
     rigScale: cfg.assemble.rig_scale,
     plan: cfg.assemble.plan,
     extend: cfg.assemble.extend_below_crop ?? [],
@@ -4048,16 +4624,19 @@ export function stageFields(
 export function proposeFields(
   cfg: EarlyConfig,
   single: { w: number; h: number } | null = null,
-): { resolution: number; headBox: [number, number, number, number]; rigScale: number; single?: boolean; armSplit?: ArmSplit } {
+): { resolution: number; headBox: [number, number, number, number]; rigScale: number; single?: boolean; armSplit?: ArmSplit; keySkeleton?: ControlSkeleton; headFaceUnderfill?: boolean } {
   const armSplit = cfg.seethrough.arm_split === undefined ? {} : { armSplit: cfg.seethrough.arm_split };
+  const keySkeleton = controlSkeletonOf(cfg);
+  const skelField = keySkeleton === undefined ? {} : { keySkeleton };
+  const underfillField = cfg.assemble.head_face_underfill === undefined ? {} : { headFaceUnderfill: cfg.assemble.head_face_underfill };
   if (single !== null) {
     refuseIfAny(singleRunHeadBoxProblems(cfg.seethrough));
-    return { resolution: cfg.seethrough.resolution, headBox: singleRunHeadBox(single.w, single.h, cfg.seethrough.resolution), rigScale: cfg.assemble.rig_scale, single: true, ...armSplit };
+    return { resolution: cfg.seethrough.resolution, headBox: singleRunHeadBox(single.w, single.h, cfg.seethrough.resolution), rigScale: cfg.assemble.rig_scale, single: true, ...armSplit, ...skelField, ...underfillField };
   }
   if (cfg.seethrough.head_box === undefined) {
     refuseIfAny([{ code: 'ASSEMBLE_FIELD_PRESENT', object: 'config.seethrough.head_box', detail: 'is absent; the plan is proposed from both runs, and the head run cannot be placed on the painting without the box it was cropped from — run `propose --head-box` first' }]);
   }
-  return { resolution: cfg.seethrough.resolution, headBox: cfg.seethrough.head_box as [number, number, number, number], rigScale: cfg.assemble.rig_scale, ...armSplit };
+  return { resolution: cfg.seethrough.resolution, headBox: cfg.seethrough.head_box as [number, number, number, number], rigScale: cfg.assemble.rig_scale, ...armSplit, ...skelField, ...underfillField };
 }
 
 /**