@rig-c/parts 1.29.0 → 1.31.0

package/src/parts.ts

@@ -241,6 +241,23 @@ export interface RecompositeRecord {
   holes: HoleRecord[];
 }
 
+export interface AlternateSetMap {
+  slots: Record<string, string>;
+  hides?: string[];
+}
+
+export interface AlternatePartsRecord {
+  name: string;
+  parts?: string[];
+  hides?: string[];
+  slots: Record<string, string>;
+  records: PartRecord[];
+  ghost_px: Record<string, number>;
+  recomposite: RecompositeRecord;
+  scene?: SceneRecord;
+  single_run_pad?: SingleRunPad;
+}
+
 export interface PartsFile {
   rig_size: [number, number];
   scale_rig_per_source: number;
@@ -252,6 +269,8 @@ export interface PartsFile {
   scene?: SceneRecord;
   /** Written only for one run whose file is not the resolution square (issue #366): where the file sat on the run's square; absent otherwise. */
   single_run_pad?: SingleRunPad;
+  /** Written only when alternate painting sets were assembled (issue #454); absent otherwise. */
+  alternates?: AlternatePartsRecord[];
 }
 
 /**
@@ -286,8 +305,8 @@ export interface SceneRecord {
   figure_mask: string;
 }
 
-const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad'] as const;
-const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad');
+const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad', 'alternates'] as const;
+const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad' && k !== 'alternates');
 export const SINGLE_RUN_PAD_KEYS = ['file_size', 'side', 'left', 'top'] as const;
 export const SCENE_KEYS = ['figure_alpha_above', 'figure_px', 'figure_mask'] as const;
 export const RECOMPOSITE_KEYS = ['mean_abs', 'within_limit', 'within_share', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed', 'holes'] as const;
@@ -346,24 +365,43 @@ export function tagOf(from: string): string | null {
   return f === null || f.run === 'painting' ? null : f.tag;
 }
 
+function serializePartList(parts: readonly PartRecord[]): Array<Record<string, unknown>> {
+  return parts.map((p) =>
+    Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : p[k]])),
+  );
+}
+
+function serializeRecomposite(r: RecompositeRecord): Record<string, unknown> {
+  return {
+    ...Object.fromEntries(RECOMPOSITE_KEYS.filter((k) => k !== 'holes').map((k) => [k, r[k]])),
+    holes: r.holes.map((h) => ({ ...Object.fromEntries(HOLE_KEYS.filter((k) => k !== 'borders').map((k) => [k, h[k]])), borders: h.borders.map((b) => ({ part: b.part, px: b.px })) })),
+  };
+}
+
 export function serializeParts(file: PartsFile): string {
   const ordered = {
     rig_size: file.rig_size,
     scale_rig_per_source: file.scale_rig_per_source,
-    parts: file.parts.map((p) =>
-      Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : p[k]])),
-    ),
+    parts: serializePartList(file.parts),
     ghost_px: Object.fromEntries(Object.keys(file.ghost_px).sort().map((k) => [k, file.ghost_px[k]])),
-    ...(file.recomposite === undefined
+    ...(file.recomposite === undefined ? {} : { recomposite: serializeRecomposite(file.recomposite) }),
+    ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
+    ...(file.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (file.single_run_pad as SingleRunPad)[k]])) }),
+    ...(file.alternates === undefined
       ? {}
       : {
-          recomposite: {
-            ...Object.fromEntries(RECOMPOSITE_KEYS.filter((k) => k !== 'holes').map((k) => [k, (file.recomposite as RecompositeRecord)[k]])),
-            holes: file.recomposite.holes.map((h) => ({ ...Object.fromEntries(HOLE_KEYS.filter((k) => k !== 'borders').map((k) => [k, h[k]])), borders: h.borders.map((b) => ({ part: b.part, px: b.px })) })),
-          },
+          alternates: file.alternates.map((a) => ({
+            name: a.name,
+            ...(a.parts === undefined ? {} : { parts: a.parts }),
+            ...(a.hides === undefined ? {} : { hides: a.hides }),
+            slots: a.slots,
+            records: serializePartList(a.records),
+            ghost_px: Object.fromEntries(Object.keys(a.ghost_px).sort().map((k) => [k, a.ghost_px[k]])),
+            recomposite: serializeRecomposite(a.recomposite),
+            ...(a.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (a.scene as SceneRecord)[k]])) }),
+            ...(a.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (a.single_run_pad as SingleRunPad)[k]])) }),
+          })),
         }),
-    ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
-    ...(file.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (file.single_run_pad as SingleRunPad)[k]])) }),
   };
   return `${JSON.stringify(ordered, null, 2)}\n`;
 }
@@ -596,6 +634,9 @@ function checkParts(raw: unknown, path: string): PartsFile {
     const names = Array.isArray(o.parts) ? new Set(o.parts.map((p) => (typeof p === 'object' && p !== null ? (p as Record<string, unknown>).name : undefined)).filter((n): n is string => typeof n === 'string')) : new Set<string>();
     checkRecomposite(o.recomposite, path, size as [number, number], names, fail);
   }
+  if ('alternates' in o && !Array.isArray(o.alternates)) {
+    fail('PARTS_FIELD_TYPE', `${path} field "alternates"`, `is ${show(o.alternates)}; an array of alternate set records is required`);
+  }
   refuseIfAny(problems);
   return raw as PartsFile;
 }

package/src/propose.ts

@@ -127,7 +127,8 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { drawText, GLYPH_H } from 'rig-c/tools/font5x7.ts';
-import { type BoneEntry, type ConfigConstraint, type Limb, type MeshSpec, parseConfig, type Point, type Segment, type SkeletonSections } from './config.ts';
+import { type BoneEntry, type ConfigConstraint, type ConfigStop, type Limb, type MeshSpec, parseConfig, type Point, type Segment, type SkeletonSections } from './config.ts';
+import { computeExactFrameTransforms, cropToSpineY, normaliseDegrees, toWorld } from './coords.ts';
 import { PartsError, type Problem, refuseIfAny } from './errors.ts';
 import { eyeLineDegrees, type FrameFeature, headAxes, type HeadAxes, headFrame, type HeadFrame } from './headframe.ts';
 import { type LayerSet, OPAQUE_ALPHA_ABOVE } from './layers.ts';
@@ -148,7 +149,7 @@ import { TURN_BONE, TURN_CARRIER_TAG, TURN_PLACES, TURN_RIDER_OFFSET, TURN_RIDER
 import { edgeLength } from './length.ts';
 import { bonePlaces, limbCrossing, limbPolyline, limbWidth } from './limbs.ts';
 import { type BranchSqueezeFinding, branchSqueezes, chainSqueezes, type SqueezeFinding } from './squeeze.ts';
-import { backHairMasses, type BackHairMass, RECIPE_BACK_HAIR_CHAINS, RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, spanCrosses, swingName, type Tail, tailOverlap, type TailOverlap, type TailSpan, treeConstraints, type TreeChain, type TreeInput, type TreeMassInput } from './cloth.ts';
+import { backHairMasses, type BackHairMass, backHairMassTrees, RECIPE_BACK_HAIR_CHAINS, RECIPE_LENGTH_RATIO, chainConstraints, clothNote, type ClothRecipe, type ClothRecipes, type ClothTarget, CLOTH_TARGETS, draftTrees, spanCrosses, swingName, type Tail, tailOverlap, type TailOverlap, type TailSpan, treeConstraints, type TreeChain, type TreeInput, type TreeMassInput } from './cloth.ts';
 import { TEXTURE_STRETCH_CEILING } from './check.ts';
 
 // ---------------------------------------------------------------------------
@@ -1848,12 +1849,29 @@ export function proposeWithBasis(
     const all: TreeChain[] = [];
     let n = 0;
     const partNamesLabel = list.map((q) => q.name).join(' -> ');
+    const sideTreeCounts: number[] = [];
     for (const [side] of activeSides) {
       const prefix = prefixOf(side);
       const sideMasses = massesBySide.get(side) ?? [];
       if (useMasses && sideMasses.length === 0) continue;
-      const sideRcp: ClothRecipe = { ...rawRcp, chains: useMasses ? sideMasses.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)) };
       const frame = `${partNamesLabel}'s art on the ${side} side of the eye axis (no art there in the band: the eye axis x)`;
+      const sideMassInputs: TreeMassInput[] | undefined = useMasses
+        ? sideMasses.flatMap((m): TreeMassInput[] => {
+            const count = backHairMassTrees(m, g);
+            return Array.from({ length: count }, (_, t): TreeMassInput => ({
+              rootY: m.minY <= y0 ? eyeY : m.minY,
+              tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
+              xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
+              fallbackX: m.minY <= y0 && sideMasses.length === 1 && count === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
+              frame,
+              treeInMass: t,
+              treesInMass: count,
+            }));
+          })
+        : undefined;
+      const sideCount = sideMassInputs !== undefined ? sideMassInputs.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit));
+      sideTreeCounts.push(sideCount);
+      const sideRcp: ClothRecipe = { ...rawRcp, chains: sideCount };
       const trees = T(list, 'back hair', sideRcp, {
         prefix,
         parent: 'head',
@@ -1863,15 +1881,7 @@ export function proposeWithBasis(
         fallbackX: () => axis,
         frame,
         edges: side,
-        masses: useMasses
-          ? sideMasses.map((m): TreeMassInput => ({
-              rootY: m.minY <= y0 ? eyeY : m.minY,
-              tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
-              xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
-              fallbackX: m.minY <= y0 && sideMasses.length === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
-              frame,
-            }))
-          : undefined,
+        masses: sideMassInputs,
       });
       const made = treeConstraints(trees, sideRcp, null);
       clothConstraints.push(...made);
@@ -1880,7 +1890,7 @@ export function proposeWithBasis(
     }
     const rcp: ClothRecipe = {
       ...rawRcp,
-      chains: useMasses ? Math.max(1, ...(activeSides.map(([s]) => (massesBySide.get(s) ?? []).length))) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
+      chains: useMasses ? Math.max(1, ...sideTreeCounts) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
     };
     const spans: Array<TailSpan & { depth: number }> = [{ bone: 'head', a: rnd(head), b: rnd([axis, top + 13]), link: false, depth: -1 }];
     for (const t of all) {
@@ -2036,12 +2046,32 @@ export function proposeWithBasis(
       const segs: Segment[] = [['head', rnd(head), rnd([axis, top + 13])]];
       const all: TreeChain[] = [];
       let n = 0;
+      const treeCountBySide = new Map<'r' | 'l', number>([
+        ['r', 0],
+        ['l', 0],
+      ]);
       for (const [side] of SIDES) {
         const prefix = prefixOf(side);
         const sideMasses = massesBySide.get(side) ?? [];
         if (useMasses && sideMasses.length === 0) continue;
-        const sideRcp: ClothRecipe = { ...rawRcp, chains: useMasses ? sideMasses.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)) };
         const frame = `${p.name}'s art on the ${side} side of the eye axis (no art there in the band: the eye axis x)`;
+        const sideMassInputs: TreeMassInput[] | undefined = useMasses
+          ? sideMasses.flatMap((m): TreeMassInput[] => {
+              const count = backHairMassTrees(m, g);
+              return Array.from({ length: count }, (_, t): TreeMassInput => ({
+                rootY: m.minY <= y0 ? eyeY : m.minY,
+                tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
+                xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
+                fallbackX: m.minY <= y0 && sideMasses.length === 1 && count === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
+                frame,
+                treeInMass: t,
+                treesInMass: count,
+              }));
+            })
+          : undefined;
+        const sideCount = sideMassInputs !== undefined ? sideMassInputs.length : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit));
+        treeCountBySide.set(side, sideCount);
+        const sideRcp: ClothRecipe = { ...rawRcp, chains: sideCount };
         const trees = T(p, 'back hair', sideRcp, {
           prefix,
           parent: 'head',
@@ -2051,15 +2081,7 @@ export function proposeWithBasis(
           fallbackX: () => axis,
           frame,
           edges: side,
-          masses: useMasses
-            ? sideMasses.map((m): TreeMassInput => ({
-                rootY: m.minY <= y0 ? eyeY : m.minY,
-                tipY: m.maxY >= bot - 12 ? bot - 4 : Math.max(m.minY + 4, m.maxY - 3),
-                xAt: (y, f) => bandX(m.mask, y, { frac: f, side, axis }),
-                fallbackX: m.minY <= y0 && sideMasses.length === 1 ? () => axis : (f) => pyRound(m.minX + f * (m.maxX - m.minX)),
-                frame,
-              }))
-            : undefined,
+          masses: sideMassInputs,
         });
         for (const t of trees) segs.push(t.chain);
         const made = treeConstraints(trees, sideRcp, null);
@@ -2067,11 +2089,14 @@ export function proposeWithBasis(
         n += made.length;
         all.push(...trees);
       }
-      const sameSideCounts = !useMasses || rMasses.length === lMasses.length;
+      const rTreeCount = treeCountBySide.get('r') ?? 0;
+      const lTreeCount = treeCountBySide.get('l') ?? 0;
+      const sameSideCounts = !useMasses || rTreeCount === lTreeCount;
       const noteRcp: ClothRecipe = {
         ...rawRcp,
-        chains: useMasses ? (sameSideCounts ? rMasses.length : rMasses.length + lMasses.length) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
+        chains: useMasses ? (sameSideCounts ? rTreeCount : rTreeCount + lTreeCount) : (rawRcp.chains ?? Math.min(RECIPE_BACK_HAIR_CHAINS, maxFit)),
       };
+      const massReason = rTreeCount === rMasses.length && lTreeCount === lMasses.length ? 'one per visible hair mass' : 'across the visible hair masses by root-row width';
       notes.push(
         clothNote(
           p.name,
@@ -2081,7 +2106,7 @@ export function proposeWithBasis(
           n,
           sameSideCounts
             ? ' per side of the eye axis, from head, rooted on the eye line and tipped 4 px above its bottom'
-            : ` (${rMasses.length} on the r side and ${lMasses.length} on the l side of the eye axis, one per visible hair mass), from head, rooted on each mass's top row and tipped 4 px above its bottom`,
+            : ` (${rTreeCount} on the r side and ${lTreeCount} on the l side of the eye axis, ${massReason}), from head, rooted on each mass's top row and tipped 4 px above its bottom`,
         ),
       );
       meshes[p.name] = { grid: g, r: rawRcp.split?.hold_tip === true ? Math.max(r, g) : r, segments: segs };
@@ -3471,7 +3496,10 @@ function artDistance(m: Mask, at: readonly [number, number]): number {
  * carries one: a part left to the rule beside parts placed from joints would
  * be read by two rules at once. Sides come from the joints, not from the eye
  * axis, so a figure seen from behind or lying across the axis is paired by
- * where its wrists are.
+ * where its wrists are. Issue #458: when pre-separated `handwear-r` and
+ * `handwear-l` parts cross so that `<s>_wrist` lies on the opaque art of its
+ * own side's `handwear-<s>` part and also within 15 px of the opposite side's
+ * `handwear-<other>` part, it resolves to its own side's part.
  *
  * Issue #199: a wrist on no part within that tolerance is measured to every
  * part by the same Chebyshev distance ({@link artDistance}). With
@@ -3498,7 +3526,18 @@ function armsFromJoints(P: PartSet, hw: readonly PartRecord[], joints: RigJoints
   const near = new Map(hw.map((p) => [p, dilate(P.alpha(p), 2 * WRIST_ON_PART_PX + 1)]));
   const arms: JointArm[] = [];
   for (const a of complete) {
-    const on = hw.filter((p) => isOn(near.get(p) as Mask, a.wrist[0], a.wrist[1]));
+    const raw = hw.filter((p) => isOn(near.get(p) as Mask, a.wrist[0], a.wrist[1]));
+    const ownTag = `handwear-${a.side}`;
+    const oppTag = `handwear-${a.side === 'r' ? 'l' : 'r'}`;
+    const own =
+      raw.length > 1 &&
+      raw.every((p) => {
+        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]))
+        : [];
+    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 });
@@ -4166,6 +4205,23 @@ export interface CrossedLimbsFinding {
   at: [number, number];
 }
 
+/**
+ * Issue #447: a stop's contact point `<chain>_touch` (`at` in `against`'s local frame) lies above the first stopped
+ * link's root (`links[0]` at `[x0, y0]`) in rig pixels (`ty < y0`, i.e. higher Spine y), so `<chain>_rest` aims
+ * upward into the upper half-plane (`|rest| > 90°`) and `|rest| + outward > 180°` wraps past ±180° (`RIG_STOP_BOUNDS`).
+ */
+export interface StopTouchAboveRootFinding {
+  kind: 'stop-touch-above-root';
+  chain: string;
+  firstLink: string;
+  rootAt: [number, number];
+  against: string;
+  at: [number, number];
+  touchAt: [number, number];
+  rest: number;
+  outward: number;
+}
+
 export type LintFinding =
   | OffArtFinding
   | OffLockFinding
@@ -4179,7 +4235,8 @@ export type LintFinding =
   | NearEmptyHandFinding
   | BackHairMassesFinding
   | OverlappingArmsFinding
-  | CrossedLimbsFinding;
+  | CrossedLimbsFinding
+  | StopTouchAboveRootFinding;
 
 /** Which rule set read the torso and the sleeve chains, under `--keypoints`. */
 export interface LintBasis {
@@ -4279,7 +4336,7 @@ export function coverageOutcome(c: BoneCoverage): CoverageOutcome {
  */
 export function lint(
   P: PartSet,
-  spec: { bones: readonly BoneEntry[]; meshes: Readonly<Record<string, MeshSpec>>; regions?: Readonly<Record<string, string>>; motion?: SkeletonSections['motion']; constraints?: readonly ConfigConstraint[]; limbs?: Readonly<Record<string, Limb>> },
+  spec: { bones: readonly BoneEntry[]; meshes: Readonly<Record<string, MeshSpec>>; regions?: Readonly<Record<string, string>>; motion?: SkeletonSections['motion']; constraints?: readonly ConfigConstraint[]; limbs?: Readonly<Record<string, Limb>>; stops?: readonly ConfigStop[] },
   joints?: RigJoints,
 ): LintResult {
   const { byName } = expand(spec.bones);
@@ -4552,11 +4609,12 @@ export function lint(
             .sort((a, b) => Number(trunkRe.exec(a.chain)![1]) - Number(trunkRe.exec(b.chain)![1]));
           if (sideTrunks.length === 0) continue;
           const masses = backHairMasses(mask, side, axis, y0, shoulderLine, g);
+          const massSlots = masses.flatMap((x) => Array.from({ length: backHairMassTrees(x, g) }, () => x));
           const outside: Array<{ point: string; at: [number, number]; minX: number; maxX: number }> = [];
           const sideMinX = masses.length > 0 ? Math.min(...masses.map((x) => x.minX)) : 0;
           const sideMaxX = masses.length > 0 ? Math.max(...masses.map((x) => x.maxX)) : P.W - 1;
           sideTrunks.forEach((tr, k) => {
-            const target = k < masses.length ? masses[k] : null;
+            const target = k < massSlots.length ? massSlots[k] : null;
             const minX = target !== null ? target.minX : sideMinX;
             const maxX = target !== null ? target.maxX : sideMaxX;
             const treeBase = tr.chain.slice(0, -1);
@@ -4573,7 +4631,7 @@ export function lint(
               if (tx < minX || tx > maxX) outside.push({ point: `${c.chain} tip`, at: [tx, ty], minX, maxX });
             }
           });
-          if (sideTrunks.length !== masses.length || outside.length > 0) {
+          if (sideTrunks.length !== massSlots.length || outside.length > 0) {
             findings.push({
               kind: 'back-hair-masses',
               mesh: groupParts.map((q) => q.name).join(' -> '),
@@ -4648,6 +4706,61 @@ export function lint(
       }
     }
   }
+  // Issue #447: when a stop's contact point `<chain>_touch` (`at` in `against`'s local frame) lies above the first
+  // stopped link's root (`links[0]`) in rig pixels (`ty < y0`, i.e. higher Spine y), `<chain>_rest` aims into the
+  // upper half-plane (`|rest| > 90°`) and `|rest| + outward > 180°` wraps past ±180° (`RIG_STOP_BOUNDS`).
+  if (spec.stops !== undefined && spec.stops.length > 0) {
+    const boneEnds = new Map<string, Point>();
+    const chainLinks = new Map<string, string[]>();
+    for (const e of spec.bones) {
+      if ('chain' in e) {
+        const names = e.points.map((_, k) => `${e.chain}${k}`);
+        chainLinks.set(e.chain, names);
+        e.points.forEach((_, k) => {
+          boneEnds.set(names[k], k + 1 < e.points.length ? e.points[k + 1] : e.tip);
+        });
+      } else if (e.tip !== undefined) {
+        boneEnds.set(e.name, e.tip);
+      }
+    }
+    for (const s of spec.stops) {
+      const links = s.links ?? chainLinks.get(s.chain) ?? [];
+      if (links.length === 0) continue;
+      const firstLink = links[0];
+      const rootBone = byName.get(firstLink);
+      const againstBone = byName.get(s.against);
+      if (rootBone === undefined || againstBone === undefined) continue;
+      const againstEnd = boneEnds.get(s.against);
+      let againstRot = 0;
+      if (againstEnd !== undefined) {
+        const dx = againstEnd[0] - againstBone.x;
+        const dy = cropToSpineY(againstEnd[1], P.H) - cropToSpineY(againstBone.y, P.H);
+        if (dx !== 0 || dy !== 0) againstRot = (Math.atan2(dy, dx) * 180) / Math.PI;
+      }
+      const frame = computeExactFrameTransforms([
+        { name: s.against, x: againstBone.x, y: cropToSpineY(againstBone.y, P.H), rotation: againstRot },
+      ]).get(s.against)!;
+      const [wx, wy] = toWorld(frame, s.at[0], s.at[1]);
+      const touchAt: [number, number] = [pyRound(wx * 10) / 10, pyRound(cropToSpineY(wy, P.H) * 10) / 10];
+      const aimDx = wx - rootBone.x;
+      const aimDy = wy - cropToSpineY(rootBone.y, P.H);
+      if (aimDx === 0 && aimDy === 0) continue;
+      const rest = pyRound(normaliseDegrees((Math.atan2(aimDy, aimDx) * 180) / Math.PI) * 100) / 100;
+      if (touchAt[1] < rootBone.y || Math.abs(rest) + s.outward > 180) {
+        findings.push({
+          kind: 'stop-touch-above-root',
+          chain: s.chain,
+          firstLink,
+          rootAt: [rootBone.x, rootBone.y],
+          against: s.against,
+          at: [s.at[0], s.at[1]],
+          touchAt,
+          rest,
+          outward: s.outward,
+        });
+      }
+    }
+  }
   // Issue #314: every pair of keyed chains a lattice mesh names, swung on the rig stage's own lattice and weights, held
   // to check's TEXTURE_STRETCH bar (src/squeeze.ts). Only with a motion: without one nothing swings.
   const partImages = new Map(P.recs.filter((p) => P.images.has(p.name)).map((p) => [p.name, { x: p.x, y: p.y, image: P.images.get(p.name) as Raster }]));
@@ -4686,6 +4799,7 @@ function findingBones(f: LintFinding, bones: readonly BoneEntry[]): string[] {
     case 'near-empty-hand':
     case 'overlapping-arms':
     case 'crossed-limbs':
+    case 'stop-touch-above-root':
       return [];
     case 'back-hair-masses': {
       const out = new Set<string>();
@@ -4878,6 +4992,8 @@ export function lintLine(f: LintFinding): string {
       return `LINT ${f.part} (${f.from}) holds both arms in one ${f.opaquePx} px component (r_wrist at ${fmtAt(f.rAt)}, l_wrist at ${fmtAt(f.lAt)}): declare config.seethrough.arm_split (x or line, and order: ["handwear-r", "handwear-l"] or ["handwear-l", "handwear-r"]) to separate the overlapping arms into two layers`;
     case 'crossed-limbs':
       return `LINT ${f.a} and ${f.b} on ${f.part}${f.from === '' ? '' : ` (${f.from})`} cross at ${fmtAt(f.at)} with no per-limb split: nearest-bone splitting cuts a straight line through the crossing; declare config.limbs.<covering>.split (line: [[x, y], ...] or edge: "painting") on the covering limb so the seam follows the limb`;
+    case 'stop-touch-above-root':
+      return `LINT stop on ${f.chain} (${f.firstLink} at ${fmtAt(f.rootAt)}) against ${f.against} (at ${fmtAt(f.at)}) places ${f.chain}_touch at ${fmtAt(f.touchAt)}, above ${f.firstLink}'s root (rest ${pyFixed(f.rest, 2)} deg, |rest| + outward ${pyFixed(Math.abs(f.rest) + f.outward, 2)} deg): stop against the descending limb bone below ${f.firstLink}, set links to start at a link below ${f.chain}_touch, or omit the stop on a rising limb`;
     case 'back-hair-masses': {
       const massDesc =
         f.masses.length === 0

package/src/rig.ts

@@ -166,7 +166,7 @@ import { type ContourChainRibs, type ContourReport, contourMesh, type ContourReg
 import { type LocalInfluence, localInfluences } from './localweights.ts';
 import { artCoverage, ART_ALPHA, latticeMesh, latticeStray, ONE_LOOP_PASSES } from './mesh.ts';
 import { bindFaceSurfaceDeform, BLINK, blinkHoldMisses, blinkSpan, CONTROL_SUFFIX, controlledBones, IDLE_FPS, idleMotion, type MotionSpec, moveKeysToControls } from './motion.ts';
-import { PAINTING_RUN, type PartsFile, readFrom, tagOf } from './parts.ts';
+import { type AlternateSetMap, PAINTING_RUN, type PartsFile, readFrom, tagOf } from './parts.ts';
 import { EYE_GROUP_TAGS } from './propose.ts';
 import { alphaAbove, crop, pad, type Raster } from './raster/index.ts';
 import { pyRound } from './round.ts';
@@ -896,6 +896,20 @@ export interface AutoMeshReport {
   motion_report?: unknown;
 }
 
+export const SETS_SPEC = 'rig-parts-sets/1';
+export const SETS_FILE = 'sets.json';
+
+/**
+ * `sets.json` (issue #454): the machine-readable map from each alternate
+ * painting set to its `<set>_<part>` attachment on each slot it covers and
+ * the slots it hides. Written beside `rig.json` only when `parts.json` carries
+ * `alternates`.
+ */
+export interface AttachmentSetsFile {
+  spec: typeof SETS_SPEC;
+  sets: Record<string, AlternateSetMap>;
+}
+
 export interface RigOutput {
   rig: RigSpec;
   motion: MotionSpec;
@@ -915,6 +929,8 @@ export interface RigOutput {
   faceAxis: FaceAxis;
   /** The turn control's parts (issue #251), in parts.json order; null when the config has no `turn`. */
   turn: TurnRow[] | null;
+  /** `sets.json` (issue #454), present only when `parts.alternates` is non-empty. */
+  sets?: AttachmentSetsFile;
 }
 
 /**
@@ -1966,6 +1982,93 @@ export function buildRig(
     });
   }
   refuseIfAny(problems);
+  // ---- alternate painting sets (issue #454) -------------------------------
+  // Only when `parts.alternates` is present: each alternate set's `<set>_<part>`
+  // attachments are added to `skins.default[<part>]` on the existing bones and
+  // slots before `applyStops` and `applyTurn`, so stopped links and turn twins
+  // carry the alternate attachments alongside the base ones.
+  let sets: AttachmentSetsFile | undefined;
+  if (parts.alternates !== undefined && parts.alternates.length > 0) {
+    const setEntries: Record<string, AlternateSetMap> = {};
+    for (const alt of parts.alternates) {
+      for (const p of alt.records) {
+        const attName = `${alt.name}_${p.name}`;
+        const rawImg = images.get(attName);
+        if (rawImg === undefined) continue;
+        const img = pad(rawImg, PAD, PAD, PAD, PAD, [0, 0, 0, 0]);
+        const file = `${attName}.png`;
+        outImages.push([file, img]);
+        const mesh = cfg.meshes[p.name];
+        if (mesh === undefined) {
+          const bone = B.get(cfg.regions[p.name]) as Bone;
+          skin[p.name][attName] = region(file, bone.name, p.x + p.w / 2, p.y + p.h / 2);
+          continue;
+        }
+        const fullSegs = meshSegments.get(p.name) as Segment[];
+        const baseAtt = skin[p.name]?.[p.name];
+        const baseBones = baseAtt !== undefined && 'type' in baseAtt ? new Set(baseAtt.weights.flatMap((v) => v.map((e) => e.bone))) : null;
+        const filteredSegs = baseBones !== null && baseBones.size > 0 ? fullSegs.filter((s) => baseBones.has(s.bone)) : fullSegs;
+        const segs = filteredSegs.length > 0 ? filteredSegs : fullSegs;
+        const allArt = alphaAbove(img, ART_ALPHA);
+        const strayVal = 'auto' in mesh ? mesh.auto.source.stray : ('contour' in mesh ? mesh.contour.stray : mesh.stray);
+        const stray = strayVal === undefined ? null : latticeStray(allArt, strayVal);
+        const art = stray === null ? allArt : stray.art;
+        const grid = 'grid' in mesh ? mesh.grid : 28;
+        const r = 'r' in mesh ? mesh.r : 80;
+        const lm = latticeMesh(attName, art, grid, maxLoopPasses);
+        if ('code' in lm) {
+          skin[p.name][attName] = region(file, segs[0].bone, p.x + p.w / 2, p.y + p.h / 2);
+          continue;
+        }
+        const ox = p.x - PAD;
+        const oy = p.y - PAD;
+        const w = img.width;
+        const h = img.height;
+        const limits: InfluenceLimits = meshLimits('influences' in mesh ? mesh.influences : undefined);
+        const segsAt = dressSegsAt(p, segs);
+        const exponent = mesh.exponent ?? DISTANCE_EXPONENT;
+        const rawShares: Influence[][] = [];
+        for (const [vx0, vy0] of lm.vertices) {
+          const wx = vx0 + ox;
+          const wy = vy0 + oy;
+          const vSegs = segsAt(wy);
+          let shares = influences([wx, wy], vSegs, r, limits, exponent);
+          if (shares.length === 0) {
+            shares = influences([wx, wy], vSegs, Infinity, { maxInfluences: 1, minWeight: 0 }, exponent);
+          }
+          rawShares.push(limits.floor === 'continuous' ? roundShares(shares) : latticeShares(shares));
+        }
+        const weights: WeightEntry[][] = [];
+        for (const [vi, [vx0, vy0]] of lm.vertices.entries()) {
+          const wx = vx0 + ox;
+          const wy = vy0 + oy;
+          const ent: WeightEntry[] = rawShares[vi].map(({ bone, weight }) => {
+            const [x, y] = toBoneLocal(world.get(bone) as BoneTransform, spineX(wx), spineY(wy));
+            return { bone, x: places(x), y: places(y), weight };
+          });
+          weights.push(ent);
+        }
+        const uvs: number[] = [];
+        for (const [x, y] of lm.vertices) uvs.push(pyRound(x / w, 6), pyRound(y / h, 6));
+        skin[p.name][attName] = { type: 'mesh', image: file, width: w, height: h, uvs, triangles: lm.triangles, hull: lm.hull, weights };
+      }
+      const slotMap: Record<string, string> = {};
+      for (const [slotName, att] of Object.entries(alt.slots)) slotMap[slotName] = att;
+      const hideList: string[] = [];
+      for (const h of alt.hides ?? []) {
+        if (!hideList.includes(h)) hideList.push(h);
+        if (stills[h] !== undefined && !hideList.includes(`${h}${STILL_SUFFIX}`)) hideList.push(`${h}${STILL_SUFFIX}`);
+      }
+      for (const slotName of Object.keys(alt.slots)) {
+        if (stills[slotName] !== undefined && !hideList.includes(`${slotName}${STILL_SUFFIX}`)) hideList.push(`${slotName}${STILL_SUFFIX}`);
+      }
+      setEntries[alt.name] = {
+        slots: slotMap,
+        ...(hideList.length > 0 ? { hides: hideList } : {}),
+      };
+    }
+    sets = { spec: SETS_SPEC, sets: setEntries };
+  }
   // ---- leg stops (issue #404) --------------------------------------------
   // Only when the config has `stops`: each link after the first (and any bone hanging from a stopped link) hangs
   // from the drawn link `<link>_d` above it, and slots and weights on a stopped link bind `<link>_d`.
@@ -2007,7 +2110,20 @@ export function buildRig(
       overrides: cfg.turn?.deform,
     });
   });
-  return { rig, motion, meshReport, images: outImages, controls, meshKeyed, idleKeys, loopPasses, autoMotion, faceAxis, turn: turned?.rows ?? null };
+  return {
+    rig,
+    motion,
+    meshReport,
+    images: outImages,
+    controls,
+    meshKeyed,
+    idleKeys,
+    loopPasses,
+    autoMotion,
+    faceAxis,
+    turn: turned?.rows ?? null,
+    ...(sets === undefined ? {} : { sets }),
+  };
 }
 
 /**