@rig-c/parts 1.19.0 → 1.20.0

package/src/cloth.ts

@@ -0,0 +1,378 @@
+/**
+ * The cloth and hair recipe (issue #364): what `propose --cloth` drafts for a
+ * `bottomwear` part and for `back hair` and `front hair` when the config's
+ * `cloth` block names that tag — dense trees hung from the attachment bone,
+ * physics on every link, and no idle key on any of them.
+ *
+ * The purpose is the world, not the loop: cloth and hair move because the
+ * body under them moves and because the consumer blows wind or turns gravity
+ * (the owner's direction, 2026-10-13). So each link carries a declared
+ * response — rig-c's physics `wind` and `gravity`, each a scalar multiplier of
+ * the environment the consumer sets (spine-core's skeleton-level `windX/windY`
+ * and `gravityX/gravityY`) — that grows from the root to the tip. The
+ * direction is the consumer's, and nothing here writes one.
+ *
+ * ⭐ Strength does not fall along a chain. A tip reads soft because each
+ * link turns on top of every link above it, so the motion accumulates down
+ * the chain at one strength; only the edge branch is declared softer.
+ *
+ * The rules, each a function of the recipe and the part's art (AUTHORING §3,
+ * *Recipe: cloth and hair that answer the world*):
+ *
+ * - **Trees.** `chains` trees hang across the piece: tree k owns the cell
+ *   [k/N, (k+1)/N] of the art's width in every row (for `back hair`, of each
+ *   side's art, either side of the eye axis), and its links sit at the cell's
+ *   centre in the 24-row band at their row. With `split: {at, into}` the first
+ *   `at` links are the tree's trunk, and the trunk's tip forks into `into`
+ *   branches, each the centre of its share of the cell, down to the tip row.
+ *   Without `split`, each tree is one chain.
+ * - **Lengths.** Every path from root to tip has `links` links, and link j's
+ *   length is the first's times q^j, q = `length_ratio`^(1/(links − 1)), the
+ *   whole spanning the root row to the tip row: the links shorten toward the
+ *   tip.
+ * - **Stiffness.** A trunk link takes `strength.trunk`, a branch link
+ *   `strength.branch`, and the **edge** — the outermost branch on each outer
+ *   side of the piece (without `split`, the outermost tree) — `strength.edge`.
+ *   Every spring is held to the step's stability bound ({@link springStable}).
+ * - **Response.** Link j of a path of n links takes `wind` and `gravity` at
+ *   t = j/(n − 1) of the way from the declared root value to the tip value (a
+ *   single-link path takes the tip value: it is a dangling end).
+ * - **Out of phase.** `alternate_damping`, when declared, is the damping of
+ *   every odd tree; the even ones take `damping`.
+ * - **Translate.** `translate`, when declared, is the `x` and `y` mix of a
+ *   second physics constraint on the last link of every path, beside its
+ *   rotation, with no wind or gravity response ({@link physics} says why).
+ * - **Swing** (`bottomwear` only). `swing.scales` declares one shared pendulum:
+ *   a bone `<prefix>swing` under the attachment at the centre of the root row,
+ *   one link long, with physics; each tree's first link takes the swing's
+ *   rotation times its scale (a transform constraint, local source and target,
+ *   additive) instead of a physics constraint of its own.
+ *
+ * Two numbers have defaults, {@link RECIPE_LENGTH_RATIO} and
+ * {@link RECIPE_STRENGTH}: the recipe's own, chosen and measured on this
+ * package's synthetic fixture (`fixtures/cloth.ts`); each says what was
+ * measured. Every other number is the author's.
+ *
+ * Pure: no clock, no randomness; every value is a function of its inputs.
+ */
+import type { ConfigConstraint, Point } from './config.ts';
+import { pyRound } from './round.ts';
+
+/** The tags a `cloth` recipe may name: the parts the proposer drafts chains on that hang. */
+export const CLOTH_TARGETS = ['bottomwear', 'back hair', 'front hair'] as const;
+export type ClothTarget = (typeof CLOTH_TARGETS)[number];
+
+/** The per-branch stiffness of a tree. */
+export interface ClothStrength {
+  trunk: number;
+  branch: number;
+  edge: number;
+}
+
+/** One target's recipe, as `config.cloth.<tag>` declares it. */
+export interface ClothRecipe {
+  chains: number;
+  links: number;
+  split?: { at: number; into: number };
+  length_ratio?: number;
+  strength?: ClothStrength;
+  damping?: number;
+  alternate_damping?: number;
+  /** `[root, tip]`: the wind response of a path's first link and of its last. */
+  wind: [number, number];
+  /** `[root, tip]`: the gravity response of a path's first link and of its last. */
+  gravity: [number, number];
+  translate?: number;
+  swing?: { scales: number[] };
+}
+
+export type ClothRecipes = Partial<Record<ClothTarget, ClothRecipe>>;
+
+/**
+ * 📐 The default ratio of a path's last link to its first: 0.5, the recipe's
+ * own. Measured on the cloth fixture (fixtures/cloth.ts, rig-c 2.47.1, the
+ * selftest's CK420 build): see AUTHORING §3, *Recipe: cloth and hair*, which
+ * holds the figures. Links halve from root to tip, whatever their count.
+ */
+export const RECIPE_LENGTH_RATIO = 0.5;
+
+/**
+ * 📐 The default stiffness: trunk and branch 100 — rig-c's own default
+ * `strength`, so the trunk and the main branches are as stiff as an
+ * undeclared spring — and the edge 50, half of it: the edge is the one part
+ * declared softer. The recipe's own, measured on the cloth fixture
+ * (AUTHORING §3, *Recipe: cloth and hair*). Each is below the stability bound
+ * at every damping in [0, 1] ({@link springStable}: 100/3600 against at
+ * least 2).
+ */
+export const RECIPE_STRENGTH: Readonly<ClothStrength> = { trunk: 100, branch: 100, edge: 50 };
+
+/** rig-c's default physics `damping` (its `RigPhysicsConstraint` doc: "Defaults: 0.5 / 100 / 0.85 / 1 / 0 / 0 / 1"), which a recipe without `damping` runs at. */
+export const RIGC_DEFAULT_DAMPING = 0.85;
+
+/** rig-c's default physics `fps` (`step = 1/fps`) and `mass` (`massInverse = 1/mass`), neither of which a recipe sets. */
+export const RIGC_DEFAULT_FPS = 60;
+export const RIGC_DEFAULT_MASS = 1;
+
+/**
+ * The stability of one physics spring at its step (A23's inequality). Per step
+ * spine-core does `v += -strength·x·step·massInverse; x += v·step; v *=
+ * d`, d = damping^(60·step). In (x, v·step) that is the matrix
+ * [[1 − k, 1], [−d·k, d]], k = strength·massInverse·step², with trace
+ * 1 − k + d and determinant d; both eigenvalues lie inside the unit circle
+ * exactly when 0 < k < 2(1 + d) (and d < 1; at d = 1 the spring rings without
+ * decay but does not grow). Returns k, the bound and whether k is below it.
+ */
+export function springStable(strength: number, damping: number, fps = RIGC_DEFAULT_FPS, mass = RIGC_DEFAULT_MASS): { k: number; bound: number; ok: boolean } {
+  const step = 1 / fps;
+  const k = (strength / mass) * step * step;
+  const bound = 2 * (1 + damping ** (60 * step));
+  return { k, bound, ok: k > 0 && k < bound };
+}
+
+/** The decimals a drafted physics number is written to: enough for a ramp of a few links, short enough to read. */
+export const CLOTH_DECIMALS = 6;
+
+/** What a link is in its tree, which sets its stiffness. */
+export type LinkRole = 'trunk' | 'branch' | 'edge';
+
+/** One drafted chain of a tree. */
+export interface TreeChain {
+  chain: string;
+  parent: string;
+  points: Point[];
+  tip: Point;
+  /** One rule per point, then the tip's: what each was read off. */
+  why: string[];
+  tipWhy: string;
+  /** Which tree (0-based, across the piece or its side) this chain belongs to. */
+  tree: number;
+  /** The role of each link. */
+  roles: LinkRole[];
+  /** Each link's depth from its tree's root (0 = the root link). */
+  depths: number[];
+  /** Whether each link is the last of its path. */
+  last: boolean[];
+}
+
+/** Which outer sides of the piece are edges: both (a skirt, a lock), or one side of the eye axis (back hair). */
+export type EdgeSides = 'both' | 'r' | 'l';
+
+export interface TreeInput {
+  /** The chains' name prefix: tree k's trunk is `<prefix><k>_`, its branches `<prefix><k><a|b|…>_`. */
+  prefix: string;
+  parent: string;
+  /** The root row (the first link's origin) and the tip row (the last link's tip), rig px, y down. */
+  rootY: number;
+  tipY: number;
+  /** The art's x at row y, `frac` of the way across the cell's frame (0 = the frame's left edge), or null when the band holds no art there. */
+  xAt: (y: number, frac: number) => number | null;
+  /** Where a link falls when its band holds no art. */
+  fallbackX: (frac: number) => number;
+  /** What the cell's frame is, for the rules: "skirt's art", "the r side of back's art". */
+  frame: string;
+  edges: EdgeSides;
+}
+
+/** The rows the n links of a path start at, then its tip's: lengths in the ratio q^j, from root row to tip row. */
+export function linkRows(rootY: number, tipY: number, links: number, ratio: number): number[] {
+  const q = links === 1 ? 1 : ratio ** (1 / (links - 1));
+  const w: number[] = [];
+  for (let j = 0; j < links; j++) w.push(q ** j);
+  const total = w.reduce((a, b) => a + b, 0);
+  const rows = [rootY];
+  let acc = 0;
+  for (let j = 0; j < links; j++) {
+    acc += w[j];
+    rows.push(j === links - 1 ? tipY : rootY + ((tipY - rootY) * acc) / total);
+  }
+  return rows;
+}
+
+const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
+
+/** The trees of one piece, in tree order, each trunk before its branches. */
+export function draftTrees(input: TreeInput, r: ClothRecipe): TreeChain[] {
+  const n = r.chains;
+  const ratio = r.length_ratio ?? RECIPE_LENGTH_RATIO;
+  const rows = linkRows(input.rootY, input.tipY, r.links, ratio);
+  const at = r.split === undefined ? r.links : r.split.at;
+  const into = r.split === undefined ? 1 : r.split.into;
+  const out: TreeChain[] = [];
+  const x = (y: number, f: number): number => input.xAt(y, f) ?? input.fallbackX(f);
+  const pt = (y: number, f: number): Point => [pyRound(x(y, f), 0), pyRound(y, 0)];
+  const rowRule = (j: number): string =>
+    `link ${j}'s row: ${j === 0 ? 'the root row' : `the root row + ${pyRound((rows[j] - rows[0]) / (rows[r.links] - rows[0]), 4)} of the span to the tip row`} (lengths in the ratio ${pyRound(ratio, 6)} last to first)`;
+  const outerSide = (k: number, b: number): boolean => {
+    const left = k === 0 && b === 0;
+    const right = k === n - 1 && b === into - 1;
+    return input.edges === 'both' ? left || right : input.edges === 'r' ? left : right;
+  };
+  for (let k = 0; k < n; k++) {
+    const fc = (k + 0.5) / n;
+    const trunkLinks = Math.min(at, r.links);
+    const trunkEdge = into === 1 && outerSide(k, 0);
+    const trunk: TreeChain = {
+      chain: `${input.prefix}${k}_`,
+      parent: input.parent,
+      points: [],
+      tip: pt(rows[trunkLinks], fc),
+      why: [],
+      tipWhy: `${trunkLinks === r.links ? 'the tip row' : `link ${trunkLinks}'s row, the fork`}, ${pyRound(fc, 6)} of the way across ${input.frame} (tree ${k} of ${n}, the centre of its cell)`,
+      tree: k,
+      roles: [],
+      depths: [],
+      last: [],
+    };
+    for (let j = 0; j < trunkLinks; j++) {
+      trunk.points.push(pt(rows[j], fc));
+      trunk.why.push(`${rowRule(j)}, ${pyRound(fc, 6)} of the way across ${input.frame} in the 24-row band there (tree ${k} of ${n}, the centre of its cell)`);
+      trunk.roles.push(into === 1 ? (trunkEdge ? 'edge' : 'trunk') : 'trunk');
+      trunk.depths.push(j);
+      trunk.last.push(into === 1 && j === trunkLinks - 1);
+    }
+    out.push(trunk);
+    if (into === 1) continue;
+    for (let b = 0; b < into; b++) {
+      const fb = (k + (b + 0.5) / into) / n;
+      const ch: TreeChain = {
+        chain: `${input.prefix}${k}${LETTERS[b]}_`,
+        parent: `${trunk.chain}${trunkLinks - 1}`,
+        points: [],
+        tip: pt(rows[r.links], fb),
+        why: [],
+        tipWhy: `the tip row, ${pyRound(fb, 6)} of the way across ${input.frame} (branch ${b} of ${into} of tree ${k}, the centre of its share of the cell)`,
+        tree: k,
+        roles: [],
+        depths: [],
+        last: [],
+      };
+      const edge = outerSide(k, b);
+      for (let j = trunkLinks; j < r.links; j++) {
+        ch.points.push(j === trunkLinks ? trunk.tip : pt(rows[j], fb));
+        ch.why.push(j === trunkLinks ? `the fork: the trunk ${trunk.chain}'s tip` : `${rowRule(j)}, ${pyRound(fb, 6)} of the way across ${input.frame} in the 24-row band there (branch ${b} of ${into} of tree ${k})`);
+        ch.roles.push(edge ? 'edge' : 'branch');
+        ch.depths.push(j);
+        ch.last.push(j === r.links - 1);
+      }
+      out.push(ch);
+    }
+  }
+  return out;
+}
+
+/** The value t of the way from a `[root, tip]` pair's root to its tip, to {@link CLOTH_DECIMALS}. */
+function ramp(pair: readonly [number, number], t: number): number {
+  return pyRound(pair[0] + t * (pair[1] - pair[0]), CLOTH_DECIMALS);
+}
+
+/** Where link `depth` of a path of `links` links sits on the root-to-tip ramp. */
+export function rampAt(depth: number, links: number): number {
+  return links === 1 ? 1 : depth / (links - 1);
+}
+
+/** The physics constraint name of a bone. */
+export function physicsName(bone: string): string {
+  return `${bone}_physics`;
+}
+
+/** The translate constraint name of a bone (a dangling end's flutter). */
+export function translateName(bone: string): string {
+  return `${bone}_translate`;
+}
+
+/**
+ * A link's physics, its fields in a fixed order: the rotation with the link's
+ * wind and gravity response, and — on the last link of a path, when the recipe
+ * declares `translate` — a second constraint moving x and y by that mix, with
+ * the same stiffness and damping and no response at all.
+ *
+ * ⭐ Why the flutter carries no response: spine-core scales a translate
+ * spring's wind and gravity by the skeleton's reference scale (100 by
+ * default) and a rotation's by the link's length over it, so one response on
+ * both components pushes the end ~100/length times further sideways than it
+ * turns it. Measured on the cloth fixture (fixtures/cloth.ts, its recipe, the
+ * recipe's default strength, rig-c 2.47.1's render under spine-core's default
+ * environment), check's TEXTURE_STRETCH severity (ceiling 1.927) with the
+ * translate mix at 0.2 / 0.5 / 1: split so, 1.382 / 1.388 / 1.398; with the
+ * link's response on the translate too, 1.65 / 3.233 / 3.814.
+ */
+function physics(bone: string, r: ClothRecipe, role: LinkRole, t: number, tree: number, last: boolean): ConfigConstraint[] {
+  const s = r.strength ?? RECIPE_STRENGTH;
+  const damping = tree % 2 === 1 && r.alternate_damping !== undefined ? r.alternate_damping : r.damping;
+  const c: ConfigConstraint = { type: 'physics', name: physicsName(bone), bone, rotate: 1, strength: s[role] };
+  if (damping !== undefined) c.damping = damping;
+  c.wind = ramp(r.wind, t);
+  c.gravity = ramp(r.gravity, t);
+  if (!last || r.translate === undefined) return [c];
+  const tr: ConfigConstraint = { type: 'physics', name: translateName(bone), bone, x: r.translate, y: r.translate, strength: s[role] };
+  if (damping !== undefined) tr.damping = damping;
+  return [c, tr];
+}
+
+/** The swing bone's name for a prefix. */
+export function swingName(prefix: string): string {
+  return `${prefix}_swing`;
+}
+
+/**
+ * The constraints of a piece's trees: with a swing, the swing's physics and
+ * one transform per tree first, then a physics constraint per link in bone
+ * order — a parent's before its child's, so each spring reads its parent's
+ * settled pose. `swingRest` is the swing's setup rotation in its parent's
+ * frame, Spine degrees (y up), which the transform subtracts so the trees take
+ * only the swing's motion.
+ */
+export function treeConstraints(trees: readonly TreeChain[], r: ClothRecipe, swing: { bone: string; rest: number } | null): ConfigConstraint[] {
+  const out: ConfigConstraint[] = [];
+  if (swing !== null && r.swing !== undefined) {
+    out.push(...physics(swing.bone, r, 'trunk', 0, 0, false));
+    const scales = r.swing.scales;
+    for (const t of trees) {
+      if (t.depths[0] !== 0) continue;
+      out.push({
+        type: 'transform',
+        name: `${swing.bone}_${t.tree}`,
+        source: swing.bone,
+        bones: [`${t.chain}0`],
+        localSource: true,
+        localTarget: true,
+        additive: true,
+        properties: { rotate: { offset: swing.rest, to: { rotate: { scale: scales[t.tree] } } } },
+        mixRotate: 1,
+      });
+    }
+  }
+  for (const t of trees) {
+    t.points.forEach((_, i) => {
+      if (swing !== null && t.depths[i] === 0) return;
+      out.push(...physics(`${t.chain}${i}`, r, t.roles[i], rampAt(t.depths[i], r.links), t.tree, t.last[i]));
+    });
+  }
+  return out;
+}
+
+/**
+ * The physics of a chain the recipe does not shape (the fringe's columns,
+ * whose two links the fringe rule places): every link a trunk link of a
+ * one-tree path, an outer column's links the edge's, on the recipe's ramp
+ * over the chain's own links.
+ */
+export function chainConstraints(chain: string, links: number, tree: number, edge: boolean, r: ClothRecipe): ConfigConstraint[] {
+  const out: ConfigConstraint[] = [];
+  for (let i = 0; i < links; i++) out.push(...physics(`${chain}${i}`, r, edge ? 'edge' : 'trunk', rampAt(i, links), tree, i === links - 1));
+  return out;
+}
+
+/** The one note a piece drafted by the recipe gets. */
+export function clothNote(part: string, tag: ClothTarget, trees: readonly TreeChain[], r: ClothRecipe, constraints: number, extra: string): string {
+  const defaults: string[] = [];
+  if (r.length_ratio === undefined) defaults.push(`length_ratio ${RECIPE_LENGTH_RATIO}`);
+  if (r.strength === undefined) defaults.push(`strength ${RECIPE_STRENGTH.trunk}/${RECIPE_STRENGTH.branch}/${RECIPE_STRENGTH.edge}`);
+  const shape = r.split === undefined ? `${r.links} link(s) each` : `a ${r.split.at}-link trunk forking into ${r.split.into} branches, ${r.links} links root to tip`;
+  return (
+    `${part} (${tag}): config.cloth."${tag}" -> ${r.chains} tree(s)${extra}, ${shape} (${trees.map((t) => t.chain).join(', ')}); ` +
+    `${constraints} constraint(s), physics on every link, wind ${r.wind[0]} -> ${r.wind[1]} and gravity ${r.gravity[0]} -> ${r.gravity[1]} root to tip (multipliers of the consumer's environment; no direction is drafted), no idle key` +
+    (defaults.length === 0 ? '' : `; the recipe's own defaults, measured on its synthetic fixture (AUTHORING §3): ${defaults.join(', ')}`)
+  );
+}

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';
@@ -676,6 +678,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 +913,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 +927,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 +969,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 +1027,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 +1181,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);
@@ -2582,6 +2589,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`);