@rig-c/parts 1.36.0 → 1.37.0

package/src/build.ts

@@ -492,6 +492,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
         ...(Object.keys(altLimbs).length > 0 ? { limbs: altLimbs, bones: altBones } : {}),
         ...(fields.scene === undefined ? {} : { scene: fields.scene }),
         ...(fields.armSplit !== undefined && altPlan.some((e) => e[1] === 'full' && (e[2] === 'handwear-r' || e[2] === 'handwear-l')) ? { armSplit: fields.armSplit } : {}),
+        ...(fields.headFaceUnderfill === undefined ? {} : { headFaceUnderfill: fields.headFaceUnderfill }),
         seamRule: input.seam,
         projectRule: input.project,
       });
@@ -569,10 +570,11 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   const pad = result.parts.single_run_pad;
   if (pad !== undefined) log(singleRunPadLine(input.full, pad));
   for (const p of result.parts.parts) {
+    const underfillSuffix = p.from === 'head:face' && (result.headFaceUnderfillPx ?? 0) > 0 ? ` underfill=${result.headFaceUnderfillPx}px(full:face)` : '';
     log(
       `  ${p.name.padEnd(11)} ${p.from.padEnd(16)} ${`${p.w}x${p.h}`.padEnd(9)} @${String(p.x).padStart(4)},${String(p.y).padStart(4)} ` +
         `op=${String(p.opaque_px).padStart(6)} vis=${String(p.visible_px).padStart(6)} src=${String(p.source_px_taken).padStart(6)}/${String(p.projected_core_px).padStart(6)} ` +
-        `unproj=${String(p.visible_not_projected_px).padStart(5)} drift=${String(p.refused_drift_px).padStart(5)} ${driftShare(p.refused_drift_px, p.projected_core_px)} merged=${p.merged_px} seam=${p.seam_override_px}`,
+        `unproj=${String(p.visible_not_projected_px).padStart(5)} drift=${String(p.refused_drift_px).padStart(5)} ${driftShare(p.refused_drift_px, p.projected_core_px)} merged=${p.merged_px} seam=${p.seam_override_px}${underfillSuffix}`,
     );
   }
   // Issue #256: one line per part from an author-made layer, so it never reads as See-through's. None without one.

package/src/config.ts

@@ -92,7 +92,7 @@ import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { edgeLength } from './length.ts';
-import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
+import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, scaledPoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
 import { acceptedTagNames, AUTHOR_LABEL_RULE, AUTHOR_PREFIX, readLayerTag } from './tags.ts';
 import { EAR_DEPTH_RANGE, FACE_DEFORM_FRACTIONS, FACE_DEFORM_RANGES, type FaceDeformKey, FACE_RATED_PITCH_BAND, FACE_RATED_YAW_BAND, TURN_BONE, type TurnSpec, turnNearest } from './turn.ts';
 import { FLOOR_FORMS, type FloorForm, type MeshInfluences } from './weights.ts';
@@ -267,6 +267,8 @@ export interface Assemble {
   patches?: Patch[];
   cuts?: Cut[];
   alternates?: AlternateSetConfig[];
+  /** Issue #492: composite full:face under head:face on the head canvas to fill transparent holes inside the face silhouette. */
+  head_face_underfill?: boolean;
 }
 
 export interface SingleBone {
@@ -1140,7 +1142,7 @@ export interface PaintConfig {
 export interface EarlyConfig {
   key: string;
   seethrough: SeeThrough;
-  assemble: { rig_scale: number };
+  assemble: { rig_scale: number; head_face_underfill?: boolean };
 }
 
 /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
@@ -1199,8 +1201,13 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if (door === 'layers') {
     if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
     if ('assemble' in t) {
-      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates']);
-      if (a !== null && 'rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
+      const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill']);
+      if (a !== null) {
+        if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
+        if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
+          c.fail('CONFIG_FIELD_TYPE', 'config.assemble.head_face_underfill', `is ${show(a.head_face_underfill)}; true or false is required`);
+        }
+      }
     }
   }
   if (door === 'assemble') {
@@ -1223,7 +1230,10 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
   if ('cloth' in t) checkCloth(c, t.cloth);
   const pose = base === null ? null : poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
-  return { config: raw as PaintConfig | EarlyConfig | AssembleConfig, pose };
+  const config = raw as PaintConfig | EarlyConfig | AssembleConfig;
+  const controlSkel = resolveControlSkeleton(t.generation, pose);
+  if (controlSkel !== undefined) controlSkeletons.set(config, controlSkel);
+  return { config, pose };
 }
 
 export function loadEarlyConfig(path: string, door: 'paint'): PaintConfig;
@@ -1243,6 +1253,40 @@ export function loadPaintConfig(path: string): { config: PaintConfig; pose: Cont
   return { config: config as PaintConfig, pose };
 }
 
+/**
+ * Issue #490: the control skeleton `config.generation.control.skeleton` names,
+ * with its points on the `generation.latent` canvas (`[w, h]`, x right, y down).
+ */
+export interface ControlSkeleton {
+  latent: readonly [number, number];
+  points: PosePoints;
+}
+
+const controlSkeletons = new WeakMap<object, ControlSkeleton>();
+
+function resolveControlSkeleton(gen: Json, pose: ControlPose | null): ControlSkeleton | undefined {
+  if (!isPlainObject(gen) || !isPlainObject(gen.control)) return undefined;
+  const l = gen.latent;
+  if (!(Array.isArray(l) && l.length === 2 && typeof l[0] === 'number' && typeof l[1] === 'number' && l[0] > 0 && l[1] > 0)) return undefined;
+  const latent: readonly [number, number] = [l[0], l[1]];
+  if (pose !== null) return { latent, points: pose.points };
+  const skel = gen.control.skeleton;
+  if (isSkeletonName(skel)) return { latent, points: scaledPoints(skel, latent[0], latent[1]) };
+  return undefined;
+}
+
+/**
+ * Return the {@link ControlSkeleton} resolved for a loaded or parsed config
+ * (`loadEarlyConfig`, `loadConfig`, `parseEarlyConfig`, `parseConfig`), or
+ * computed from an inline `generation.control.skeleton` built-in when present.
+ */
+export function controlSkeletonOf(cfg: object): ControlSkeleton | undefined {
+  const cached = controlSkeletons.get(cfg);
+  if (cached !== undefined) return cached;
+  const gen = (cfg as { generation?: unknown }).generation;
+  return resolveControlSkeleton(gen, null);
+}
+
 /** The pose file a checked `generation` block's control names, read relative to `base`; null for a built-in, an absent control, or a block already refused. */
 function poseBeside(c: Check, gen: Json, base: string): ControlPose | null {
   if (!isPlainObject(gen) || !isPlainObject(gen.control)) return null;
@@ -1388,9 +1432,12 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
     checkFaceAnimationBand(c, animations, hasAltFace, t.turn, attached);
     checkAnimationSetKeys(c, animations, t.assemble, new Set<string>([...parts, ...patches, ...cuts, ...(limbs?.parts.keys() ?? [])]));
   }
-  if (base !== null) poseBeside(c, t.generation, base);
+  const pose = base === null ? null : poseBeside(c, t.generation, base);
   refuseIfAny(c.problems);
-  return { config: raw as CharacterConfig, animations };
+  const config = raw as CharacterConfig;
+  const controlSkel = resolveControlSkeleton(t.generation, pose);
+  if (controlSkel !== undefined) controlSkeletons.set(config, controlSkel);
+  return { config, animations };
 }
 
 /**
@@ -1791,13 +1838,16 @@ function checkRunTag(c: Check, path: string, run: Json, tag: Json): void {
  */
 function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
   const required = sectionRequired(door, 'assemble');
-  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates']);
+  const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill']);
   if (a === null) return { parts: [], patches: [], cuts: [] };
   if (required.includes('plan') && !('plan' in a)) {
     c.fail('CONFIG_FIELD_PRESENT', 'config.assemble.plan', 'is absent and required; `assemble --propose-plan` prints one from the two runs — paste its plan and extend_below_crop into config.assemble');
   }
   const p = 'config.assemble';
   if ('rig_scale' in a) c.number(`${p}.rig_scale`, a.rig_scale, 'positive');
+  if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
+    c.fail('CONFIG_FIELD_TYPE', `${p}.head_face_underfill`, `is ${show(a.head_face_underfill)}; true or false is required`);
+  }
   const parts: string[] = [];
   if ('plan' in a && c.array(`${p}.plan`, a.plan, true)) {
     const seenPart = new Map<string, number>();

package/src/propose.ts

@@ -1364,8 +1364,15 @@ const SIDES = [
  * which rule stood in; without it every value and note is the one this
  * function wrote before the parameter existed.
  */
-export function propose(P: PartSet, joints?: RigJoints, wristSnap: number | null = null, gridRule: GridRule = DEFAULT_GRID_RULE, cloth: ClothRecipes | null = null): Proposal {
-  return proposeWithBasis(P, joints, wristSnap, gridRule, cloth).proposal;
+export function propose(
+  P: PartSet,
+  joints?: RigJoints,
+  wristSnap: number | null = null,
+  gridRule: GridRule = DEFAULT_GRID_RULE,
+  cloth: ClothRecipes | null = null,
+  chainRule = true,
+): Proposal {
+  return proposeWithBasis(P, joints, wristSnap, gridRule, cloth, chainRule).proposal;
 }
 
 /**
@@ -1384,6 +1391,7 @@ export function proposeWithBasis(
   wristSnap: number | null = null,
   gridRule: GridRule = DEFAULT_GRID_RULE,
   cloth: ClothRecipes | null = null,
+  chainRule = true,
 ): { proposal: Proposal; basis: ProposalBasis } {
   // Issue #230: a piece is not given its base's rule a second time, which
   // needs to know which part is the piece. A file that cannot say is refused
@@ -2537,7 +2545,7 @@ export function proposeWithBasis(
   // Issue #75: arms from joints, when every handwear part carries the wrist of
   // an arm whose shoulder, elbow and wrist are all given; otherwise the rule
   // below places every sleeve chain, and the notes say why.
-  const armPlan = joints !== undefined && clasped === null && hw.length > 0 ? armsFromJoints(P, hw, joints, wristSnap) : null;
+  const armPlan = joints !== undefined && clasped === null && hw.length > 0 ? armsFromJoints(P, hw, joints, wristSnap, chainRule) : null;
   let sleeveRule = '';
   if (clasped !== null) {
     sleeveRule = 'the clasped-hands rule (the handwear is a region on hip, with no sleeve chain)';
@@ -2547,7 +2555,9 @@ export function proposeWithBasis(
     for (const p of hw) regions[p.name] = 'hip';
     notes.push(clasped);
   } else if (armPlan !== null && armPlan.arms !== null) {
-    // Each chain runs shoulder -> elbow with its tip at the wrist: two links,
+    // Each chain runs shoulder -> elbow with its tip at the wrist (or, when
+    // the wrist fell outside the arm layer onto a skirt or top layer, at the
+    // arm layer's bottom extent, issue #491): two links,
     // the upper arm and the forearm, each with the amplitude the two-blob rule
     // gives its link of the same index. Its part's mesh takes the chain alone,
     // as the two-blob rule's does since issue #347 (no chest stub: a stub on
@@ -2555,7 +2565,14 @@ export function proposeWithBasis(
     for (const a of armPlan.arms) {
       const sgn = a.side === 'r' ? 1 : -1;
       const used = (n: KeypointName): Placement => placement('joint', `the ${n} joint, ${usedAs((joints as RigJoints).joints[n])}`, { joints: [jointRef(n)] });
-      C(`sleeve_${a.side}`, 'chest', [a.shoulder, a.elbow], a.wrist, [used(`${a.side}_shoulder`), used(`${a.side}_elbow`)], used(`${a.side}_wrist`));
+      const tipWhy =
+        a.offLayer === null
+          ? used(`${a.side}_wrist`)
+          : placement('mask', `3 px above ${a.part.name}'s bottom row, at its centroid x in the band 6 px above that row`, {
+              parts: [a.part.name],
+              fallback: a.tipFallback,
+            });
+      C(`sleeve_${a.side}`, 'chest', [a.shoulder, a.elbow], a.tip, [used(`${a.side}_shoulder`), used(`${a.side}_elbow`)], tipWhy);
       tracks.push({ chain: `sleeve_${a.side}`, amps: [sgn * 0.2, sgn * 0.6], period: 4.0, phase: 0.22 + (a.side === 'l' ? 0.05 : 0), lag: 0.08 });
     }
     // Issue #349: each arm is a limb — the upper arm on link 0 and the forearm (with the hand) on link 1, each rigid on
@@ -2662,6 +2679,15 @@ export function proposeWithBasis(
     }
     if (hw.length === 1) notes.push(`handwear is one blob (${hw[0].name}): both sleeves in one mesh, split at the eye axis x=${pyFixed(axis, 0)}`);
   }
+  for (const [s] of SIDES) {
+    const sc = bones.find((b): b is Extract<BoneEntry, { chain: string }> => 'chain' in b && b.chain === `sleeve_${s}`);
+    if (sc === undefined) continue;
+    const bone = `sleeve_${s}${sc.points.length - 1}`;
+    for (const hp of P.byTag(`hand-${s}`)) {
+      regions[hp.name] = bone;
+      notes.push(`${hp.name} (${hp.from}): split hand -> region on ${bone}, the tip link of sleeve_${s}`);
+    }
+  }
 
   // Issue #402: the topwear part config.cloth.bottomwear.part names takes the skirt's rule and recipe below; every
   // other topwear shaped like a skirt is named in a note when a recipe is in play, never drafted on by its shape.
@@ -3460,8 +3486,14 @@ interface JointArm {
   shoulder: [number, number];
   elbow: [number, number];
   wrist: [number, number];
+  tip: [number, number];
+  tipFallback: string | undefined;
   part: PartRecord;
   snap: number | null;
+  offLayer: {
+    distance: number;
+    landedOn: readonly PartRecord[];
+  } | null;
 }
 
 /**
@@ -3507,11 +3539,27 @@ function artDistance(m: Mask, at: readonly [number, number]): number {
  * `wristSnap` (an integer above {@link WRIST_ON_PART_PX}, the CLI's to hold)
  * it is bound to the one nearest part when that part is at most `wristSnap`
  * px away; two parts tied nearest bind neither, as a wrist on two parts
- * does not. Otherwise the why names the nearest part and its distance, the
- * tolerance that would have bound it.
+ * does not.
+ *
+ * Issue #491: when a hanging arm's wrist keypoint falls outside its handwear
+ * layer's mask (`elbow[1] > shoulder[1]`, `wrist[1] > elbow[1]`, the elbow lies
+ * within {@link WRIST_ON_PART_PX} of that side's handwear part, and the part's
+ * bottom extent `bot - 3` reaches at least {@link WRIST_ON_PART_PX} below the
+ * elbow — e.g. when a skin-coloured wrist read lands on a light skirt or top
+ * layer below a hanging sleeve), the arm binds its handwear part with its
+ * chain tip placed at the layer's bottom extent `[bandX(mask, bot - 6), bot - 3]`
+ * so `limbs.arm_<s>` cuts at the elbow from the limb chain (`PROPOSE_WRIST_OFF_LAYER`).
+ * Otherwise the why names the nearest part and its distance, the tolerance
+ * that would have bound it.
  */
-function armsFromJoints(P: PartSet, hw: readonly PartRecord[], joints: RigJoints, wristSnap: number | null): { arms: JointArm[] | null; why: string | null } {
-  const complete: Array<Omit<JointArm, 'part' | 'snap'>> = [];
+function armsFromJoints(
+  P: PartSet,
+  hw: readonly PartRecord[],
+  joints: RigJoints,
+  wristSnap: number | null,
+  chainRule = true,
+): { arms: JointArm[] | null; why: string | null } {
+  const complete: Array<Omit<JointArm, 'tip' | 'tipFallback' | 'part' | 'snap' | 'offLayer'>> = [];
   const gaps: string[] = [];
   for (const s of ['r', 'l'] as const) {
     const sh = joints.joints[`${s}_shoulder`].at;
@@ -3524,7 +3572,18 @@ function armsFromJoints(P: PartSet, hw: readonly PartRecord[], joints: RigJoints
     else complete.push({ side: s, shoulder: sh, elbow: el, wrist: wr });
   }
   if (complete.length === 0) return { arms: null, why: `no arm has its shoulder, elbow and wrist all given (${gaps.join('; ')})` };
-  const near = new Map(hw.map((p) => [p, dilate(P.alpha(p), 2 * WRIST_ON_PART_PX + 1)]));
+  const armAlpha = new Map(
+    hw.map((p) => {
+      const tag = splitFrom(p.from)[1];
+      const side = tag === 'handwear-r' ? 'r' : tag === 'handwear-l' ? 'l' : null;
+      let m = P.alpha(p);
+      if (side !== null) {
+        for (const h of P.byTag(`hand-${side}`)) m = union(m, P.alpha(h));
+      }
+      return [p, m] as const;
+    }),
+  );
+  const near = new Map(hw.map((p) => [p, dilate(armAlpha.get(p) as Mask, 2 * WRIST_ON_PART_PX + 1)]));
   const arms: JointArm[] = [];
   for (const a of complete) {
     const raw = hw.filter((p) => isOn(near.get(p) as Mask, a.wrist[0], a.wrist[1]));
@@ -3536,21 +3595,46 @@ function armsFromJoints(P: PartSet, hw: readonly PartRecord[], joints: RigJoints
         const t = splitFrom(p.from)[1];
         return t === ownTag || t === oppTag;
       })
-        ? raw.filter((p) => splitFrom(p.from)[1] === ownTag && isOn(P.alpha(p), a.wrist[0], a.wrist[1]))
+        ? raw.filter((p) => splitFrom(p.from)[1] === ownTag && isOn(armAlpha.get(p) as Mask, a.wrist[0], a.wrist[1]))
         : [];
     const on = own.length === 1 ? own : raw;
     if (on.length > 1) return { arms: null, why: `${a.side}_wrist at ${fmtAt(a.wrist)} lies on the art of ${on.length} handwear parts (${on.map((p) => p.name).join(', ')}), so it does not say which sleeve it ends` };
     if (on.length === 1) {
-      arms.push({ ...a, part: on[0], snap: null });
+      arms.push({ ...a, tip: a.wrist, tipFallback: undefined, part: on[0], snap: null, offLayer: null });
       continue;
     }
-    const far = hw.map((p) => ({ p, d: artDistance(P.alpha(p), a.wrist) }));
+    const far = hw.map((p) => ({ p, d: artDistance(armAlpha.get(p) as Mask, a.wrist) }));
     const d = Math.min(...far.map((q) => q.d));
     const nearest = far.filter((q) => q.d === d).map((q) => q.p);
     if (wristSnap !== null && d <= wristSnap && nearest.length === 1) {
-      arms.push({ ...a, part: nearest[0], snap: d });
+      arms.push({ ...a, tip: a.wrist, tipFallback: undefined, part: nearest[0], snap: d, offLayer: null });
       continue;
     }
+    if (chainRule) {
+      const byTag = hw.filter((p) => splitFrom(p.from)[1] === ownTag);
+      const byElbow = hw.filter((p) => isOn(near.get(p) as Mask, a.elbow[0], a.elbow[1]));
+      const sidePart =
+        byTag.length === 1 && isOn(near.get(byTag[0]) as Mask, a.elbow[0], a.elbow[1])
+          ? byTag[0]
+          : byElbow.length === 1
+            ? byElbow[0]
+            : null;
+      if (sidePart !== null) {
+        const m = armAlpha.get(sidePart) as Mask;
+        const ys = rowsAny(m);
+        const bot = ys[ys.length - 1];
+        if (bot !== undefined && a.elbow[1] > a.shoulder[1] && a.wrist[1] > a.elbow[1] && bot - 3 - a.elbow[1] >= WRIST_ON_PART_PX) {
+          const bx = bandX(m, bot - 6);
+          const tipX = or(bx, a.elbow[0]);
+          const tipFallback = bx === null || bx === 0 ? `no art in the band: the ${a.side}_elbow joint's x` : undefined;
+          const tip: [number, number] = [pyRound(tipX), bot - 3];
+          const landedOn = P.layered().filter((p) => p !== sidePart && isOn(P.alpha(p), a.wrist[0], a.wrist[1]));
+          const partDist = artDistance(m, a.wrist);
+          arms.push({ ...a, tip, tipFallback, part: sidePart, snap: null, offLayer: { distance: partDist, landedOn } });
+          continue;
+        }
+      }
+    }
     const gap = 'by the larger of the x and y gaps';
     const reach = wristSnap === null ? `--wrist-snap ${Math.max(d, WRIST_ON_PART_PX + 1)} would bind it` : `beyond --wrist-snap ${wristSnap}`;
     const nearestIs =
@@ -3727,7 +3811,25 @@ function jointNotes(joints: RigJoints, f: JointNoteFacts): string[] {
       [`${s}_wrist`, 'the tip'],
     ] as const) {
       const j = J[joint];
-      const on = arm === null ? '' : arm.snap === null ? `the wrist lies on ${arm.part.name}` : `the wrist is bound to ${arm.part.name} by --wrist-snap`;
+      if (arm !== null && arm.offLayer !== null && joint === `${s}_wrist`) {
+        const landed =
+          arm.offLayer.landedOn.length > 0
+            ? `, on ${arm.offLayer.landedOn.map((p) => `${p.name} (${p.from})`).join(', ')}`
+            : '';
+        tell(
+          joint,
+          `${said(joint, j)}: not used — ${s}_wrist at ${fmtAt(arm.wrist)} lies outside ${arm.part.name} (${arm.part.from})'s mask (${arm.offLayer.distance} px from its art by the larger of the x and y gaps${landed}); chain sleeve_${s}'s tip is placed at ${arm.part.name}'s bottom extent [${arm.tip[0]}, ${arm.tip[1]}] instead`,
+        );
+        continue;
+      }
+      const on =
+        arm === null
+          ? ''
+          : arm.offLayer !== null
+            ? `the elbow lies on ${arm.part.name}; ${s}_wrist lies outside ${arm.part.name}'s mask, so sleeve_${s}'s tip is ${arm.part.name}'s bottom extent [${arm.tip[0]}, ${arm.tip[1]}]`
+            : arm.snap === null
+              ? `the wrist lies on ${arm.part.name}`
+              : `the wrist is bound to ${arm.part.name} by --wrist-snap`;
       if (arm !== null) tell(joint, `${said(joint, j)}: ${usedAs(j)} for chain sleeve_${s}, ${role} (${on})`);
       else if (j.at !== null && f.armWhy !== null) tell(joint, `${said(joint, j)}: not used — ${f.armWhy}; ${standIn}`);
       else if (j.at !== null) tell(joint, `${said(joint, j)}: not used — ${standIn}`);
@@ -3739,6 +3841,17 @@ function jointNotes(joints: RigJoints, f: JointNoteFacts): string[] {
         `wrist snap: ${s}_wrist at ${fmtAt(arm.wrist)} lies on no handwear part within ${WRIST_ON_PART_PX} px; --wrist-snap ${f.wristSnap} bound it to ${arm.part.name}, the nearest, ${arm.snap} px from its art by the larger of the x and y gaps`,
       );
     }
+    // Issue #491: when the wrist keypoint lies outside the arm layer's mask, name the wrist, the arm layer, where it
+    // landed, the chain tip at the layer's bottom extent, and the chain-derived elbow cut position.
+    if (arm !== null && arm.offLayer !== null) {
+      const landed =
+        arm.offLayer.landedOn.length > 0
+          ? `, on ${arm.offLayer.landedOn.map((p) => `${p.name} (${p.from})`).join(', ')}`
+          : '';
+      out.push(
+        `PROPOSE_WRIST_OFF_LAYER: ${s}_wrist at ${fmtAt(arm.wrist)} lies outside ${arm.part.name} (${arm.part.from})'s mask (${arm.offLayer.distance} px from its art by the larger of the x and y gaps${landed}); chain sleeve_${s} places its tip at ${arm.part.name}'s bottom extent [${arm.tip[0]}, ${arm.tip[1]}] instead of ${s}_wrist, and limb arm_${s} places the elbow cut at [${pyRound(arm.elbow[0])}, ${pyRound(arm.elbow[1])}] (${fmtAt(arm.elbow)}) from the limb chain (${s}_shoulder [${pyRound(arm.shoulder[0])}, ${pyRound(arm.shoulder[1])}] -> ${s}_elbow [${pyRound(arm.elbow[0])}, ${pyRound(arm.elbow[1])}] -> [${arm.tip[0]}, ${arm.tip[1]}])`,
+      );
+    }
   }
   // Issue #199: two chains on one part are said, not left to share its mesh unremarked.
   const both = f.arms !== null && f.arms.length === 2 && f.arms[0].part === f.arms[1].part ? f.arms[0].part.name : null;

package/src/tags.ts

@@ -74,7 +74,11 @@ export const HEAD_TAGS = [
   'mouth',
 ] as const;
 
-export type BaseTag = (typeof BODY_TAGS)[number] | (typeof HEAD_TAGS)[number];
+/** The tags `splitMergedArmRuns` (issue #490) splits out of a merged `handwear-r` / `handwear-l` layer: `<tag>-r` / `<tag>-l`. */
+export const ARM_MERGED_SPLIT_TAGS = ['hand', 'drape'] as const;
+export type ArmMergedSplitTag = (typeof ARM_MERGED_SPLIT_TAGS)[number];
+
+export type BaseTag = (typeof BODY_TAGS)[number] | (typeof HEAD_TAGS)[number] | ArmMergedSplitTag;
 
 /** The tags upstream splits into `-r` / `-l` halves. */
 export const SPLIT_TAGS = ['handwear', 'eyewhite', 'irides', 'eyelash', 'eyebrow', 'ears'] as const;
@@ -97,10 +101,11 @@ export interface TagReading {
 /**
  * Read a layer name as a v3 tag, or `null` when it is not one.
  *
- * Accepted: any of the 24 base tags, and `<tag>-r` / `<tag>-l` for the six
- * split tags. A suffix on a tag upstream never splits (`topwear-l`) is not a
- * tag — upstream cannot have produced it, so accepting it would be accepting a
- * layer somebody renamed.
+ * Accepted: any of the 24 base tags, `<tag>-r` / `<tag>-l` for the six
+ * split tags, and `<tag>-r` / `<tag>-l` for the merged-arm split tags
+ * (`hand-r`, `hand-l`, `drape-r`, `drape-l`, issue #490). A suffix on a tag
+ * upstream never splits (`topwear-l`) is not a tag — upstream cannot have
+ * produced it, so accepting it would be accepting a layer somebody renamed.
  */
 export function readTag(name: string): TagReading | null {
   const split = /^(.+)-([rl])$/.exec(name);
@@ -108,6 +113,10 @@ export function readTag(name: string): TagReading | null {
     const base = split[1] as SplitTag;
     return { name, base, side: split[2] as Side, group: groupOf(base) };
   }
+  if (split !== null && (ARM_MERGED_SPLIT_TAGS as readonly string[]).includes(split[1])) {
+    const base = split[1] as ArmMergedSplitTag;
+    return { name, base, side: split[2] as Side, group: 'body' };
+  }
   if ((V3_TAGS as readonly string[]).includes(name)) {
     const base = name as BaseTag;
     return { name, base, side: null, group: groupOf(base) };
@@ -122,7 +131,7 @@ function groupOf(tag: BaseTag): 'body' | 'head' {
 /** Every name `readTag` accepts, sorted — what a refusal quotes as "required". */
 export function acceptedTagNames(): string[] {
   const names = new Set<string>(V3_TAGS);
-  for (const t of SPLIT_TAGS) {
+  for (const t of [...SPLIT_TAGS, ...ARM_MERGED_SPLIT_TAGS]) {
     names.add(`${t}-r`);
     names.add(`${t}-l`);
   }