@rig-c/parts 1.19.0 → 1.21.0

package/src/config.ts

@@ -87,6 +87,8 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
+import { pyRound } from './round.ts';
+import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING, springStable } from './cloth.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
 import { type Problem, refuseIfAny } from './errors.ts';
 import { isSkeletonName, KEYPOINT_NAMES, type KeypointName, type PosePoints, SKELETON_NAMES, type SkeletonName } from './skeleton.ts';
@@ -211,6 +213,16 @@ export interface Cut {
    * pixels; it is read nowhere else. Absent: the base keeps only its band.
    */
   under?: string;
+  /**
+   * Issue #360 (item 11), optional, one value: `"colour"` — where the under
+   * fills a removed pixel, the base takes the under's colour and keeps the
+   * alpha the cut removed there, so the part's silhouette is the uncut
+   * layer's and never grows. The under is `under`'s image or the part's
+   * hidden-art layer (issue #359); a cut with neither is refused by the
+   * assemble stage (`ASSEMBLE_UNDER_FILL_SOURCE`). Absent: the base takes the
+   * under's colour and alpha, issue #193's rule.
+   */
+  under_fill?: 'colour';
 }
 
 export interface Assemble {
@@ -641,9 +653,15 @@ export interface ConfigConstraint {
  * pixels it takes (`from`: a plan part or a cut's piece), and the one bone it
  * rides with weight 1. Every segment after the first sits below a joint at
  * its bone's origin: `joint` names it, `range` is the bend the joint may take
- * from rest, `[min, max]` degrees (metadata: read by the stress readers, not
- * by rig-c), and `cap` an image, relative to the config's directory, of the
- * cap that overlaps the joint (`limbCaps` in `src/assemble.ts`).
+ * from rest, `[min, max]` degrees (carried into `parts.json` and posed by
+ * `check`'s `SEAM_OVER_RANGE`, issue #360; not read by rig-c), and `cap` an
+ * image, relative to the config's directory, of the cap that overlaps the
+ * joint (`limbCaps` in `src/assemble.ts`). Two opt-in fields shape the cut at
+ * the joint (issue #360, `src/limbs.ts`): `edge: "feather"` fades the upper
+ * piece out across the cap, and `cap_shape: "disc"` sizes the cap by the
+ * limb's half-width about the joint and fills it from the art, the upper
+ * segment's included. Absent, the cut
+ * is hard and the cap the layer's half-disc of half the limb's width.
  */
 export interface LimbSegment {
   part: string;
@@ -652,6 +670,8 @@ export interface LimbSegment {
   joint?: string;
   range?: [number, number];
   cap?: string;
+  edge?: 'feather';
+  cap_shape?: 'disc';
 }
 
 /** A limb (issue #349): its segments, upper first; each segment's bone is the child of the one before. */
@@ -676,6 +696,8 @@ export interface CharacterConfig {
   turn?: TurnSpec;
   /** The painting is a scene (issue #242): absent, no byte of any output moves. */
   scene?: SceneSpec;
+  /** The cloth and hair recipe `propose --cloth` drafts from (issue #364, `src/cloth.ts`): read by propose only, so no byte of any rig output moves with it. */
+  cloth?: ClothRecipes;
 }
 
 /** `config.scene` (issue #242): the declaration that the painting is a scene. It holds no field today. */
@@ -909,7 +931,7 @@ export function loadConfigAndAnimations(path: string): { config: CharacterConfig
 export type EarlyDoor = 'paint' | 'layers' | 'assemble';
 
 /** Every loader: the three early doors, and `full` — `parseConfig`, in front of `rig`, `build` and `propose --from-config`/`--compare`. */
-export type ConfigDoor = EarlyDoor | 'full';
+export type ConfigDoor = EarlyDoor | 'full' | 'cloth';
 
 /**
  * 🔒 The one statement of what each loader requires, as dotted field paths.
@@ -923,6 +945,7 @@ export const CONFIG_REQUIRES: Readonly<Record<ConfigDoor, readonly string[]>> =
   layers: ['key', 'seethrough', 'assemble.rig_scale'],
   assemble: ['key', 'seethrough', 'assemble.rig_scale', 'assemble.plan'],
   full: ['key', 'assemble.rig_scale', 'assemble.plan', 'bones', 'meshes', 'regions', 'motion'],
+  cloth: ['key', 'cloth'],
 };
 
 /** The top-level keys a loader requires, in `CONFIG_REQUIRES` order. */
@@ -964,7 +987,7 @@ export interface AssembleConfig {
   bones?: BoneEntry[];
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene', 'cloth'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -1022,6 +1045,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null):
       checkLimbs(c, t.limbs, made, names);
     }
   }
+  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 };
@@ -1175,6 +1199,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
   if ('turn' in t) checkTurn(c, t.turn, attachedParts(t.meshes, t.regions), names.bones);
   if ('scene' in t) checkScene(c, t.scene);
+  if ('cloth' in t) checkCloth(c, t.cloth);
   const from = isPlainObject(t.motion) ? t.motion.animations_from : undefined;
   const animations = base !== null && typeof from === 'string' && from !== '' ? readAnimationsFrom(c, resolve(base, from)) : null;
   if (base !== null) poseBeside(c, t.generation, base);
@@ -1333,25 +1358,36 @@ export interface SkeletonSections {
 
 /**
  * A `proposal.json` as `propose` writes it — `bones`, `meshes`, `regions`,
- * `motion` and `notes` (strings) — under the full loader's own rules for the
- * four rig sections (issue #85). There is no plan to hold the meshes and
- * regions against, so the coverage rule (every plan part exactly one of a
- * mesh or a region) is the one rule not run; `propose` held its proposal to
- * it before writing (`checkProposal`). A key the loader would not take is
+ * `motion` and `notes` (strings), `limbs` when `propose --keypoints` drafted
+ * them (issue #349) and `constraints` when `propose --cloth` did (issue #364;
+ * both read here since issue #372, whose `wind` example tracks such a
+ * proposal) — under the full loader's own rules for those sections (issue
+ * #85). There is no plan to hold the meshes, regions and limbs against, so
+ * the coverage rule (every plan part exactly one of a mesh or a region) is
+ * not run, and a limb segment's `from` is held to no plan part (the parts
+ * the limbs take are the ones they name); `propose` held its proposal to
+ * both before writing (`checkProposal`). A key the loader would not take is
  * refused by name, as in a config. Refusals name the fields `proposal.…`.
  */
-export function parseProposalSections(raw: Json): SkeletonSections {
+export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[] } {
   const c = new Check();
-  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes']);
+  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints']);
   if (top !== null) {
     const names = 'bones' in top ? checkBones(c, top.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
+    if ('limbs' in top) {
+      const taken = isPlainObject(top.limbs)
+        ? Object.values(top.limbs).flatMap((l) => (isPlainObject(l) && Array.isArray(l.segments) ? l.segments.flatMap((sg) => (isPlainObject(sg) && typeof sg.from === 'string' ? [sg.from] : [])) : []))
+        : [];
+      checkLimbs(c, top.limbs, { parts: [...new Set(taken)], patches: [], cuts: [] }, names);
+    }
     if ('meshes' in top) checkMeshes(c, top.meshes, names.bones, names.chains);
     if ('regions' in top) checkRegions(c, top.regions, names.bones);
     if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
+    if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
     if ('notes' in top && c.array('config.notes', top.notes, false)) (top.notes as Json[]).forEach((n, i) => c.string(`config.notes[${i}]`, n, false));
   }
   refuseIfAny(c.problems.map((p) => ({ ...p, object: p.object.replace(/^config\b/, 'proposal') })));
-  return raw as SkeletonSections;
+  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[] };
 }
 
 /**
@@ -1541,7 +1577,9 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
 /**
  * `assemble.cuts` (issue #170): each entry `{from, into, polygon, draw, overlap}`
  * and optionally `under` (issue #193, a non-empty path string; the assemble
- * stage reads the file), refused field by field. `from` must be a plan part — a cut of a patch or of
+ * stage reads the file) and `under_fill` (issue #360, the one value
+ * `"colour"`; whether the cut has an under to fill with is the assemble
+ * stage's to judge, since a hidden-art layer can be one), refused field by field. `from` must be a plan part — a cut of a patch or of
  * another cut's piece is refused, so every piece's provenance is one layer and
  * one polygon. `into` is a new part name: not a plan part, not a patch, not
  * another cut's. Returns the names the cuts make, in order.
@@ -1553,11 +1591,14 @@ function checkCuts(c: Check, v: Json, plan: string[], patches: string[]): string
   const seen = new Map<string, number>();
   (v as Json[]).forEach((entry, i) => {
     const at = `${p}[${i}]`;
-    const e = c.object(at, entry, ['from', 'into', 'polygon', 'draw', 'overlap'], ['under']);
+    const e = c.object(at, entry, ['from', 'into', 'polygon', 'draw', 'overlap'], ['under', 'under_fill']);
     if (e === null) return;
     if ('under' in e && !(typeof e.under === 'string' && e.under !== '')) {
       c.fail('CONFIG_FIELD_TYPE', `${at}.under`, `is ${show(e.under)}; a non-empty path to a PNG is required, relative to the config's directory — the image of what lies under the piece, in rig pixels over the polygon's bounding box`);
     }
+    if ('under_fill' in e && e.under_fill !== 'colour') {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.under_fill`, `is ${show(e.under_fill)}; "colour" is required — the base takes the under's colour and keeps the alpha the cut removed, so its silhouette does not grow; leave under_fill out for the under's colour and alpha`);
+    }
     if ('overlap' in e && !(typeof e.overlap === 'number' && Number.isInteger(e.overlap) && e.overlap >= 0)) {
       c.fail('CONFIG_FIELD_TYPE', `${at}.overlap`, `is ${show(e.overlap)}; a non-negative integer of rig pixels is required — the band inside the cut's edge the part keeps under the piece, 0 for none`);
     }
@@ -2158,7 +2199,10 @@ interface LimbNames {
  * the joint, its origin); the first segment has no joint, every other names
  * one (`CONFIG_KEY_KNOWN`, `CONFIG_FIELD_PRESENT`); `range` two finite
  * degrees `[min, max]` with `min <= 0 <= max` (`CONFIG_LIMB_RANGE`: the range
- * is measured from rest, so rest is in it); `cap` a non-empty path. A limb
+ * is measured from rest, so rest is in it); `cap` a non-empty path; `edge`
+ * `"feather"` and `cap_shape` `"disc"` (issue #360), each the one value its
+ * field takes — absent is the hard cut and the layer's half-disc
+ * (`CONFIG_FIELD_TYPE` on any other). A limb
  * has two segments or more. With `names` null (no `bones`), bones are not
  * resolved. Returns the limb parts and the parts the limbs take.
  */
@@ -2183,13 +2227,13 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
     const bones: Array<string | null> = [];
     segs.forEach((entry, i) => {
       const sat = `${at}.segments[${i}]`;
-      const e = c.object(sat, entry, ['part', 'from', 'bone'], ['joint', 'range', 'cap']);
+      const e = c.object(sat, entry, ['part', 'from', 'bone'], ['joint', 'range', 'cap', 'edge', 'cap_shape']);
       froms.push(null);
       bones.push(null);
       if (e === null) return;
       // The upper segment sits below no joint; every other sits below one, which it names.
       if (i === 0) {
-        for (const k of ['joint', 'range', 'cap'].filter((q) => q in e)) c.fail('CONFIG_KEY_KNOWN', `${sat}.${k}`, `is not a field on the upper segment; it sits below no joint, so ${k} belongs to the segment below the joint it names (segments[1] and on)`);
+        for (const k of ['joint', 'range', 'cap', 'edge', 'cap_shape'].filter((q) => q in e)) c.fail('CONFIG_KEY_KNOWN', `${sat}.${k}`, `is not a field on the upper segment; it sits below no joint, so ${k} belongs to the segment below the joint it names (segments[1] and on)`);
       } else if (!('joint' in e)) c.fail('CONFIG_FIELD_PRESENT', `${sat}.joint`, 'is absent and required; a segment after the first sits below a joint, at its bone\'s origin, and names it');
       if ('part' in e && c.string(`${sat}.part`, e.part)) {
         const name = e.part;
@@ -2227,6 +2271,13 @@ function checkLimbs(c: Check, v: Json, made: { parts: string[]; patches: string[
       if ('cap' in e && !(typeof e.cap === 'string' && e.cap !== '')) {
         c.fail('CONFIG_FIELD_TYPE', `${sat}.cap`, `is ${show(e.cap)}; a non-empty path to a PNG is required, relative to the config's directory — the cap's image over the box assemble's limb line prints`);
       }
+      // Issue #360: the cut's geometry at the joint, each field one value; absent is the hard cut and the layer's half-disc.
+      if ('edge' in e && e.edge !== 'feather') {
+        c.fail('CONFIG_FIELD_TYPE', `${sat}.edge`, `is ${show(e.edge)}; "feather" is required — the upper piece fades out across the cap instead of stopping at the joint line; leave edge out for the hard cut`);
+      }
+      if ('cap_shape' in e && e.cap_shape !== 'disc') {
+        c.fail('CONFIG_FIELD_TYPE', `${sat}.cap_shape`, `is ${show(e.cap_shape)}; "disc" is required — the cap a disc of the limb's half-width about the joint, filled from the art, the upper segment's included; leave cap_shape out for the layer's half-disc of half the limb's width`);
+      }
     });
     froms.forEach((f, i) => {
       if (f === null || i === 0 || froms[i - 1] === f) return;
@@ -2582,6 +2633,136 @@ function attachedParts(meshes: Json, regions: Json): Set<string> {
  * declaration. Not `true`: an object is what a later field can be added to
  * without changing what an existing config means.
  */
+/**
+ * `config.cloth` (issue #364): a recipe per tag `propose --cloth` drafts trees
+ * for. Every field is checked here, and every combination that would draft
+ * something other than what it says is refused by name:
+ *
+ * - a tag that is not one of {@link CLOTH_TARGETS} (`CONFIG_KEY_KNOWN`);
+ * - `split.at` at or past `links` — no link would be left for the branches
+ *   (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`);
+ * - a `wind` or `gravity` pair whose tip is below its root: the response is
+ *   growing toward the tip (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`);
+ * - `alternate_damping` without `damping`, or equal to it: neighbouring trees
+ *   are declared out of phase, and an alternate that alternates nothing is
+ *   not a declaration (`CONFIG_CLOTH_ALTERNATE_DIFFERS`);
+ * - `swing` on a tag other than `bottomwear`, or `swing.scales` not one per
+ *   tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`);
+ * - a strength, declared or the recipe's default, whose spring is unstable at
+ *   a damping the recipe runs at — k = strength·massInverse·step² at or past
+ *   2(1 + damping^(60·step)), rig-c's default fps 60 and mass 1, the damping
+ *   `damping`, `alternate_damping` or rig-c's default 0.85
+ *   (`CONFIG_CLOTH_SPRING_STABLE`, {@link springStable}).
+ */
+function checkCloth(c: Check, v: Json): void {
+  const at = 'config.cloth';
+  if (!isPlainObject(v)) {
+    c.fail('CONFIG_FIELD_TYPE', at, `is ${show(v)}; an object is required — one recipe per tag, ${CLOTH_TARGETS.map((t) => `"${t}"`).join(', ')}`);
+    return;
+  }
+  // The keys are tags, not fields: read here rather than by c.object, whose lists are field names.
+  for (const key of Object.keys(v)) {
+    if (isRecordKey(key) || (CLOTH_TARGETS as readonly string[]).includes(key)) continue;
+    if (key === 'note' || key.endsWith('_note')) {
+      if (typeof v[key] !== 'string') c.fail('CONFIG_FIELD_TYPE', `${at}.${key}`, `is ${show(v[key])}; an annotation is a string`);
+      continue;
+    }
+    c.fail('CONFIG_KEY_KNOWN', `${at}.${JSON.stringify(key)}`, `is not a tag a recipe is drafted for; known: ${CLOTH_TARGETS.map((t) => `"${t}"`).join(', ')} — ${DOORS}`);
+  }
+  if (Object.keys(v).filter((k) => (CLOTH_TARGETS as readonly string[]).includes(k)).length === 0) {
+    c.fail('CONFIG_FIELD_PRESENT', at, `names no tag; one recipe per tag, ${CLOTH_TARGETS.map((t) => `"${t}"`).join(', ')}, is required (leave cloth out for none)`);
+  }
+  for (const tag of CLOTH_TARGETS) {
+    if (!(tag in v)) continue;
+    const path = `${at}.${JSON.stringify(tag)}`;
+    const r = c.object(path, v[tag], ['chains', 'links', 'wind', 'gravity'], ['split', 'length_ratio', 'strength', 'damping', 'alternate_damping', 'translate', 'swing']);
+    if (r === null) continue;
+    const chains = 'chains' in r && c.int(`${path}.chains`, r.chains, 1) ? (r.chains as number) : null;
+    const links = 'links' in r && c.int(`${path}.links`, r.links, 1) ? (r.links as number) : null;
+    if ('split' in r) {
+      const sp = c.object(`${path}.split`, r.split, ['at', 'into'], []);
+      if (sp !== null) {
+        const sAt = 'at' in sp && c.int(`${path}.split.at`, sp.at, 1) ? (sp.at as number) : null;
+        if ('into' in sp) c.int(`${path}.split.into`, sp.into, 2);
+        if (sAt !== null && links !== null && sAt >= links) {
+          c.fail('CONFIG_CLOTH_SPLIT_BEFORE_TIP', `${path}.split.at`, `is ${sAt} and links is ${links}; the trunk's ${sAt} link(s) would leave no link for the branches — split.at below links is required`);
+        }
+      }
+    }
+    if ('length_ratio' in r) c.number(`${path}.length_ratio`, r.length_ratio, 'positive');
+    if ('strength' in r) {
+      const st = c.object(`${path}.strength`, r.strength, ['trunk', 'branch', 'edge'], []);
+      if (st !== null) for (const k of ['trunk', 'branch', 'edge'] as const) if (k in st) c.number(`${path}.strength.${k}`, st[k], 'positive');
+    }
+    const damping = 'damping' in r && c.number(`${path}.damping`, r.damping, 'unit') ? (r.damping as number) : null;
+    if ('alternate_damping' in r && c.number(`${path}.alternate_damping`, r.alternate_damping, 'unit')) {
+      if (!('damping' in r)) c.fail('CONFIG_CLOTH_ALTERNATE_DIFFERS', `${path}.alternate_damping`, 'is declared and damping is absent; the odd trees take alternate_damping in place of the even trees\' damping, so damping is required beside it');
+      else if (damping !== null && damping === r.alternate_damping) c.fail('CONFIG_CLOTH_ALTERNATE_DIFFERS', `${path}.alternate_damping`, `is ${damping}, the same as damping; neighbouring trees are declared out of phase, so a different value is required (or leave alternate_damping out)`);
+    }
+    const st = isPlainObject(r.strength) ? r.strength : null;
+    const strengths = (['trunk', 'branch', 'edge'] as const).map((k) => [k, st === null ? RECIPE_STRENGTH[k] : st[k]] as const).filter((e): e is readonly ['trunk' | 'branch' | 'edge', number] => typeof e[1] === 'number' && Number.isFinite(e[1]) && e[1] > 0);
+    const dampings = [damping ?? RIGC_DEFAULT_DAMPING, ...(typeof r.alternate_damping === 'number' && r.alternate_damping >= 0 && r.alternate_damping <= 1 ? [r.alternate_damping] : [])];
+    for (const [k, value] of strengths) {
+      for (const d of dampings) {
+        const b = springStable(value, d);
+        if (!b.ok) {
+          c.fail(
+            'CONFIG_CLOTH_SPRING_STABLE',
+            `${path}.strength.${k}`,
+            `is ${value}${st === null ? " (the recipe's default)" : ''}; at damping ${d}, rig-c's default fps 60 and mass 1, k = strength·massInverse·step² = ${pyRound(b.k, 6)}, and a spring is stable only below 2(1 + damping^(60·step)) = ${pyRound(b.bound, 6)} — lower the strength`,
+          );
+        }
+      }
+    }
+    for (const k of ['wind', 'gravity'] as const) {
+      if (!(k in r)) continue;
+      const pair = r[k];
+      if (!Array.isArray(pair) || pair.length !== 2 || !pair.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)) {
+        c.fail('CONFIG_FIELD_TYPE', `${path}.${k}`, `is ${show(pair)}; [root, tip], two numbers at or above 0 — the ${k} response of a path's first link and of its last — is required`);
+        continue;
+      }
+      if ((pair[1] as number) < (pair[0] as number)) {
+        c.fail('CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP', `${path}.${k}`, `is [${pair[0]}, ${pair[1]}]; the response grows from the root to the tip, where the motion accumulates down the chain, so tip >= root is required`);
+      }
+    }
+    if ('translate' in r && c.number(`${path}.translate`, r.translate, 'unit') && r.translate === 0) {
+      c.fail('CONFIG_FIELD_TYPE', `${path}.translate`, 'is 0; a mix above 0 and at most 1 is required (leave translate out for none)');
+    }
+    if ('swing' in r) {
+      if (tag !== 'bottomwear') {
+        c.fail('CONFIG_CLOTH_SWING_SCALE_PER_TREE', `${path}.swing`, `is declared on "${tag}"; the shared swing is the skirt's (bottomwear) — leave it out here`);
+      } else {
+        const sw = c.object(`${path}.swing`, r.swing, ['scales'], []);
+        if (sw !== null && 'scales' in sw && c.array(`${path}.swing.scales`, sw.scales, true)) {
+          const scales = sw.scales as Json[];
+          scales.forEach((n, i) => c.number(`${path}.swing.scales[${i}]`, n, 'positive'));
+          if (chains !== null && scales.length !== chains) {
+            c.fail('CONFIG_CLOTH_SWING_SCALE_PER_TREE', `${path}.swing.scales`, `holds ${scales.length} scale(s) and chains is ${chains}; one scale per tree, in tree order across the piece, is required`);
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * `propose --cloth`'s loader (issue #364): the `cloth` door — `key` and
+ * `cloth`, under the full loader's rules for each — and nothing else read.
+ * Every other key must still be one a config knows.
+ */
+export function loadClothConfig(path: string): { key: string; cloth: ClothRecipes } {
+  const raw = readConfigFile(path);
+  const c = new Check();
+  const required = topRequired('cloth');
+  const top = c.object('config', raw, required, TOP_KEYS.filter((k) => !required.includes(k)));
+  if (top === null) refuseIfAny(c.problems);
+  const t = top as Record<string, Json>;
+  if ('key' in t) c.string('config.key', t.key);
+  if ('cloth' in t) checkCloth(c, t.cloth);
+  refuseIfAny(c.problems);
+  return raw as { key: string; cloth: ClothRecipes };
+}
+
 function checkScene(c: Check, v: Json): void {
   if (!isPlainObject(v)) {
     c.fail('CONFIG_FIELD_TYPE', 'config.scene', `is ${show(v)}; an object is required — {} declares the painting a scene`);

package/src/limbs.ts

@@ -41,6 +41,27 @@
  *   shows no gap. The tool invents none of them: each is the config's cap
  *   image's where that image is not transparent, else the layer's where the
  *   limb has art there, else missing — counted, and named in the limb line.
+ * - **`cap_shape: "disc"`** (issue #360, items 10 and 12; opt-in on the
+ *   segment below the joint). The radius is the limb's half-width about the
+ *   joint, not half its width: the distance from the joint to the nearer end
+ *   of the same run along the joint line, each end half a pixel past its
+ *   centre ({@link halfWidthAbout}) — so the disc lies on the limb's art
+ *   across the line however far off the run's middle the bone sits. The cap
+ *   takes, after the image's and the layer's, the upper segment's art at a
+ *   pixel the lower's layer has none of: the whole half-disc comes from the
+ *   art. The upper piece's corner at the cut is kept where it is: on a joint
+ *   off the limb's middle, a corner trimmed to the disc leaves a notch at
+ *   rest when nothing takes it, or a stub out of the bent lower piece's
+ *   outline when the lower takes it (issue #360, unit B's sheets).
+ * - **`edge: "feather"`** (issue #360, item 9; opt-in on the segment below the
+ *   joint). The overlap band is the disc about the joint that the lower
+ *   piece covers at every turn ({@link coveredRadius}: the cap's disc, less
+ *   any pixel the cap is missing and a bilinear sample's reach). Inside it,
+ *   on the upper side of the line, the upper piece's alpha is scaled by
+ *   {@link featherWeight}: 0 on the line, 1 on the band's arc. The band fades
+ *   out across its width over art that stays opaque under it at any angle,
+ *   so at rest the two pieces composite to what they did and a bend never
+ *   shows through it what lies behind the limb.
  */
 import type { BoneEntry, Limb } from './config.ts';
 
@@ -144,11 +165,12 @@ export function segmentOf(lines: ReadonlyArray<JointLine | null>, first: number,
 }
 
 /**
- * The limb's width at a joint (module comment): `art(x, y)` says whether the
- * limb has art at a pixel; the box `[x0, y0, x1, y1]` (inclusive) bounds the
- * search. Null when no pixel of the run lies within 1 px of the joint.
+ * The limb's run of art along a joint line (module comment): the offsets
+ * along the line, from the joint, of the first and the last pixel centre of
+ * the run through the joint, `[first, last]` with `first <= last`. Null when
+ * no pixel of the run lies within 1 px of the joint.
  */
-export function limbWidth(line: JointLine, art: (x: number, y: number) => boolean, box: readonly [number, number, number, number]): number | null {
+export function limbRun(line: JointLine, art: (x: number, y: number) => boolean, box: readonly [number, number, number, number]): [number, number] | null {
   const [ax, ay] = line.axis;
   const ts: number[] = [];
   for (let y = box[1]; y <= box[3]; y++) {
@@ -170,7 +192,67 @@ export function limbWidth(line: JointLine, art: (x: number, y: number) => boolea
   let hi = near;
   while (lo > 0 && ts[lo] - ts[lo - 1] <= 1.5) lo--;
   while (hi + 1 < ts.length && ts[hi + 1] - ts[hi] <= 1.5) hi++;
-  return ts[hi] - ts[lo] + 1;
+  return [ts[lo], ts[hi]];
+}
+
+/** The limb's width at a joint (module comment): its run's first to last pixel centre, plus one pixel. Null with no run. */
+export function limbWidth(line: JointLine, art: (x: number, y: number) => boolean, box: readonly [number, number, number, number]): number | null {
+  const r = limbRun(line, art, box);
+  return r === null ? null : r[1] - r[0] + 1;
+}
+
+/**
+ * The limb's half-width about the joint (issue #360, `cap_shape: "disc"`): the
+ * distance from the joint to the nearer end of its run, each end half a pixel
+ * past its centre — `min(last + 0.5, 0.5 - first)`. Half the width when the
+ * joint sits in the middle of the run; less when it sits off it. Zero or below
+ * when the joint sits on the run's edge.
+ */
+export function halfWidthAbout(run: readonly [number, number]): number {
+  return Math.min(run[1] + 0.5, 0.5 - run[0]);
+}
+
+/** Where a pixel's centre lies from a joint: `along` the axis (above 0 past the line), and `across` it (the run's offset). */
+export function jointOffsets(line: JointLine, px: number, py: number): { along: number; across: number } {
+  const dx = px + 0.5 - line.at[0];
+  const dy = py + 0.5 - line.at[1];
+  return { along: dx * line.axis[0] + dy * line.axis[1], across: -dx * line.axis[1] + dy * line.axis[0] };
+}
+
+/**
+ * The radius the feathered edge fades over (issue #360, `edge: "feather"`):
+ * the disc about the joint the lower piece covers at every turn. It is the
+ * distance from the joint to the nearest pixel centre the lower piece does not
+ * hold at alpha 255 (`opaque` false; searched out to `radius` + 2), less
+ * sqrt(2), the farthest a bilinear sample reaches to its four texels — so a
+ * pixel within it, turned by any angle about the joint, still samples only
+ * the lower's opaque art — and at most `radius`. Zero or below: no pixel is
+ * covered at every turn, and nothing is feathered.
+ */
+export function coveredRadius(at: Pt, radius: number, opaque: (x: number, y: number) => boolean): number {
+  const [x0, y0, w, h] = capBox(at, radius + 2);
+  let near = radius + 2;
+  for (let y = y0; y < y0 + h; y++) {
+    for (let x = x0; x < x0 + w; x++) {
+      if (opaque(x, y)) continue;
+      const d = Math.sqrt((x + 0.5 - at[0]) ** 2 + (y + 0.5 - at[1]) ** 2);
+      if (d < near) near = d;
+    }
+  }
+  return Math.min(radius, near - Math.SQRT2);
+}
+
+/**
+ * The feathered edge's weight on the upper piece (issue #360, `edge:
+ * "feather"`) at a pixel inside the joint's disc on the upper side of its line:
+ * its distance above the line over the disc's height there,
+ * `-along / sqrt(radius² - across²)` — 0 on the line, 1 on the disc's arc, so
+ * the overlap band fades out across its width. 1 where the disc has no height.
+ */
+export function featherWeight(radius: number, along: number, across: number): number {
+  const h2 = radius * radius - across * across;
+  if (h2 <= 0) return 1;
+  return Math.max(0, Math.min(1, -along / Math.sqrt(h2)));
 }
 
 /** The box `[x, y, w, h]` (rig px) of the pixels whose centre lies within `radius` of `at`: the cap image's size and place. */

package/src/parts.ts

@@ -45,7 +45,8 @@
  * 1.6.0 has none, and still reads. `limb`, written only on a part a
  * `config.limbs` segment made (issue #349), names the limb, the segment's
  * index (0 the upper), the part it was cut from (`of`), the one bone it rides
- * and, below a joint, the joint and its cap ({@link LimbRecord}).
+ * and, below a joint, the joint, its declared `range` when there is one
+ * (issue #360) and its cap ({@link LimbRecord}).
  *
  * ⭐ **A patch is 100 % source.** Every pixel of a `painting:` part is the
  * painting's own, so it is all visible (the painting shows it; nothing of it
@@ -118,7 +119,9 @@ export interface PartRecord {
 /**
  * A limb segment's provenance (issue #349): the limb, the segment's index
  * (0 the upper), the part its pixels were cut from (`of`), the bone it rides
- * with weight 1, and, on a segment below a joint, the joint's name and its cap.
+ * with weight 1, and, on a segment below a joint, the joint's name, the
+ * `range` its config segment declares (issue #360: `[min, max]` degrees from
+ * rest, written only when declared; `check` poses the joint there) and its cap.
  */
 export interface LimbRecord {
   name: string;
@@ -126,6 +129,7 @@ export interface LimbRecord {
   of: string;
   bone: string;
   joint?: string;
+  range?: [number, number];
   cap?: CapRecord;
 }
 
@@ -147,10 +151,27 @@ export interface CapRecord {
   /** Issue #359: with `image_px`, the hidden-art layer the cap's image came from (`<run>:<layer>:hidden`), when it came from one rather than the config's cap file. */
   image_layer?: string;
   missing_px: number;
+  /**
+   * Issue #360, written only under the segment's `cap_shape: "disc"`: the
+   * shape; the cap's pixels taken from the upper segment's art where the
+   * lower's layer had none (`upper_px`). `radius` is then the half-width about the
+   * joint, at most half of `width`.
+   */
+  shape?: 'disc';
+  upper_px?: number;
+  /**
+   * Issue #360, written only under the segment's `edge: "feather"`: the edge,
+   * the radius of the band it fades over (the disc the lower piece covers at
+   * every turn, `coveredRadius` in `src/limbs.ts`), and the upper piece's
+   * pixels whose alpha it lowered.
+   */
+  edge?: 'feather';
+  feather_radius?: number;
+  feathered_px?: number;
 }
 
-const LIMB_KEYS = ['name', 'segment', 'of', 'bone', 'joint', 'cap'] as const;
-const CAP_KEYS = ['at', 'width', 'radius', 'box', 'layer_px', 'image_px', 'image_layer', 'missing_px'] as const;
+const LIMB_KEYS = ['name', 'segment', 'of', 'bone', 'joint', 'range', 'cap'] as const;
+const CAP_KEYS = ['at', 'width', 'radius', 'box', 'layer_px', 'image_px', 'image_layer', 'missing_px', 'shape', 'upper_px', 'edge', 'feather_radius', 'feathered_px'] as const;
 
 /** The limb record with its keys in the fixed order, so two runs write the same bytes. */
 function orderedLimb(l: LimbRecord): Record<string, unknown> {
@@ -470,6 +491,14 @@ function checkParts(raw: unknown, path: string): PartsFile {
       const below = isCount(q.segment) && q.segment > 0;
       if (below !== ('joint' in q) || below !== ('cap' in q)) fail('PARTS_FIELD_PRESENT', object, `segment ${show(q.segment)} with${'joint' in q ? '' : 'out'} a joint and with${'cap' in q ? '' : 'out'} a cap; a segment below a joint (index above 0) has both, the upper segment neither`);
       if ('joint' in q && !(typeof q.joint === 'string' && q.joint !== '')) fail('PARTS_FIELD_TYPE', `${object} "joint"`, `is ${show(q.joint)}; the joint's name is required`);
+      // Issue #360: a declared range rides below a joint only, and holds the loader's rule — two degrees, rest in it.
+      if ('range' in q) {
+        const r = q.range;
+        if (!below) fail('PARTS_FIELD_PRESENT', `${object} "range"`, `is on segment ${show(q.segment)}; a range is the bend of a joint, so only a segment below one (index above 0) carries it`);
+        else if (!(Array.isArray(r) && r.length === 2 && r.every((n) => typeof n === 'number' && Number.isFinite(n)) && (r[0] as number) <= 0 && 0 <= (r[1] as number))) {
+          fail('PARTS_FIELD_TYPE', `${object} "range"`, `is ${show(r)}; [min, max], two finite degrees from rest with min <= 0 <= max, is required — config.limbs' rule (CONFIG_LIMB_RANGE)`);
+        }
+      }
       if ('cap' in q) {
         const c = q.cap;
         const co = typeof c === 'object' && c !== null && !Array.isArray(c) ? (c as Record<string, unknown>) : null;
@@ -484,8 +513,17 @@ function checkParts(raw: unknown, path: string): PartsFile {
           isCount(co.layer_px) &&
           isCount(co.missing_px) &&
           (!('image_px' in co) || isCount(co.image_px)) &&
-          (!('image_layer' in co) || ('image_px' in co && typeof co.image_layer === 'string' && co.image_layer !== ''));
-        if (!ok) fail('PARTS_FIELD_TYPE', `${object} "cap"`, `is ${show(c)}; {at: [x, y], width, radius, box: [x, y, w, h], layer_px, image_px?, image_layer? (with image_px), missing_px} is required`);
+          (!('image_layer' in co) || ('image_px' in co && typeof co.image_layer === 'string' && co.image_layer !== '')) &&
+          // Issue #360: a disc cap carries its count, a feathered edge its band and count, and neither carries them alone.
+          ('shape' in co ? co.shape === 'disc' && isCount(co.upper_px) : !('upper_px' in co)) &&
+          ('edge' in co ? co.edge === 'feather' && typeof co.feather_radius === 'number' && Number.isFinite(co.feather_radius) && co.feather_radius >= 0 && isCount(co.feathered_px) : !('feather_radius' in co) && !('feathered_px' in co));
+        if (!ok) {
+          fail(
+            'PARTS_FIELD_TYPE',
+            `${object} "cap"`,
+            `is ${show(c)}; {at: [x, y], width, radius, box: [x, y, w, h], layer_px, image_px?, image_layer? (with image_px), missing_px, shape? ("disc", with upper_px), edge? ("feather", with feather_radius and feathered_px)} is required`,
+          );
+        }
       }
     }
   }