rig-parts 1.50.0 → 1.51.0

package/cli.ts

@@ -30,7 +30,7 @@ import { checkImageSize, choosePerson, KEYPOINTS_SPEC, loadKeypoints, type RigJo
 import { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, HIP_MIN_FRACTION, type DraftLintFinding, lint, lintLine, type PartSet, proposeWithBasis, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
 import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, serializeBasis } from './src/diagnostics.ts';
 import { BEND_DEGREES, BEND_WORST_SHARE, DUST_MAX_PX, DUST_MAX_SHARE, IDLE_BOUND_PX, MESH_DRAFT_REPORT, MESH_DRAFT_SPEC, meshDraftStage, MORE_TRIANGLES_FLAG, relativeConfigPaths, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
-import { clothConfigEdits, editPaths, writtenClothConfig } from './src/clothconfig.ts';
+import { clothConfigEdits, editPaths, previousCount, writtenClothConfig } from './src/clothconfig.ts';
 import { PROVENANCE_FILE, REMESH_SPEC, remeshStage } from './src/remesh.ts';
 import { RETUNE_FILE, RETUNE_SPEC, retuneStage } from './src/retune.ts';
 import { checkPainting } from './src/paintcheck.ts';
@@ -226,7 +226,7 @@ usage:
       a LINT line names each drafted radius and both figures. Without --cloth
       nothing changes.
 
-  rig-parts propose … --cloth <config.json> [--write-config <out.json>]
+  rig-parts propose … --cloth <config.json> [--write-config <out.json> [--from <previous.json>]]
       Also write the --cloth config's own text with what the recipe drafts
       spliced in (issue #537), the way mesh-draft writes its config, so that
       rig --config <out.json> builds it. What is spliced is measured: the
@@ -246,6 +246,14 @@ usage:
       (PROPOSE_WRITE_CONFIG_CONFLICT), or when the spliced text does not
       parse to the config with the sections set, naming the first key
       that moved (PROPOSE_WRITE_CONFIG_SPLICE).
+      --from <previous.json> (issue #571, only with --write-config) names
+      the config the recipe is changed from: its cloth block is read as
+      --cloth's is, the same parts are drafted a third time with it, and an
+      entry equal to that previous recipe's draft is the recipe's, replaced
+      (or removed) as one equal to the draft without the recipe is; an entry
+      equal to none of the three drafts is still refused by name, its field
+      read against the previous recipe's draft. The write line counts the
+      entries the previous draft vouched for. Without --from nothing changes.
 
   rig-parts propose --parts <dir> --source <painting.png> --out <dir> --from-config <config.json>
       Draw the config's CURRENT bones instead (<out>/render/landmarks_config.png
@@ -915,7 +923,7 @@ const TAKES = {
   layers: { valued: ['--export', '--template', '--canvas'], switches: [] },
   sheet: { valued: ['--source', '--layers', '--out', '--cell', '--cols'], switches: [] },
   rig: { valued: ['--config', '--parts', '--out', '--idle-keys', '--page-edges', '--pack-shape'], switches: [] },
-  propose: { valued: ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--head', '--canvas', '--keypoints', '--person', '--wrist-snap', '--grid-rule', '--cloth', '--write-config'], switches: ['--head-box', '--no-back-hair'] },
+  propose: { valued: ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--head', '--canvas', '--keypoints', '--person', '--wrist-snap', '--grid-rule', '--cloth', '--write-config', '--from'], switches: ['--head-box', '--no-back-hair'] },
   compare: { valued: ['--left', '--right', '--map'], switches: [] },
   check: { valued: ['--rig', '--out', '--parts', '--source', '--page-edges', '--pack-shape', '--requirements', '--set', '--environment'], switches: ['--seam-pairs', '--keep-stills', '--all-sets'] },
   loop: { valued: ['--frames', '--out'], switches: ['--palette'] },
@@ -1316,6 +1324,9 @@ function cmdPropose(args: string[]): number {
     const writeArg = flags.get('--write-config');
     if (writeArg !== undefined && flags.has('--from-config')) return usage('--write-config writes what the recipe drafts into its config; --from-config proposes nothing');
     if (writeArg !== undefined && clothArg === undefined) return usage('--write-config writes the --cloth config with what its recipe drafts spliced in; give --cloth <config.json>');
+    // Issue #571: the config the recipe is changed from; an entry equal to its recipe's draft is the recipe's, not a hand edit.
+    const fromArg = flags.get('--from');
+    if (fromArg !== undefined && writeArg === undefined) return usage('--from names the config the recipe is changed from, for --write-config; give --write-config <out.json>');
     if (writeArg !== undefined) {
       const ours = ['proposal.json', BASIS_FILE].map((f) => resolve(out, f));
       if (existsSync(writeArg) || ours.includes(resolve(writeArg))) {
@@ -1323,6 +1334,7 @@ function cmdPropose(args: string[]): number {
       }
     }
     const cloth = clothArg === undefined ? null : loadClothConfig(clothArg).cloth;
+    const previousCloth = fromArg === undefined ? null : loadClothConfig(fromArg).cloth;
     const partsDir = existsSync(partsArg) && statSync(partsArg).isFile() ? dirname(partsArg) : partsArg;
     if (!existsSync(source)) {
       throw new PartsError([{ code: 'PROPOSE_SOURCE_PRESENT', object: source, detail: 'no such file; the painting is drawn under the overlay' }]);
@@ -1366,8 +1378,10 @@ function cmdPropose(args: string[]): number {
         : (() => {
             const text = readFileSync(clothArg, 'utf8');
             // Issue #552: bones, constraints and motion.tracks entry by entry; a hand edit the recipe would drop is refused by name.
-            const edits = clothConfigEdits(drafted, proposeWithBasis(P, joints, wristSnap, gridRule, null).proposal, JSON.parse(text) as unknown);
-            return { at: writeArg, text: writtenClothConfig(clothArg, text, edits), paths: editPaths(edits), relative: relativeConfigPaths(dirname(resolve(clothArg)), JSON.parse(text) as Record<string, unknown>) };
+            // Issue #571: with --from, the same parts drafted a third time with the previous recipe.
+            const previous = previousCloth === null ? null : proposeWithBasis(P, joints, wristSnap, gridRule, previousCloth).proposal;
+            const edits = clothConfigEdits(drafted, proposeWithBasis(P, joints, wristSnap, gridRule, null).proposal, JSON.parse(text) as unknown, false, previous);
+            return { at: writeArg, text: writtenClothConfig(clothArg, text, edits), paths: editPaths(edits), vouched: previousCount(edits), relative: relativeConfigPaths(dirname(resolve(clothArg)), JSON.parse(text) as Record<string, unknown>) };
           })();
     const bfile = basisFile(P, prop, basis, cfg === null || cmpPath === undefined ? null : { where: cmpPath, config: cfg });
     const img = drawLandmarks(P, painting, prop.bones, 'PROPOSAL - CORRECT ME');
@@ -1385,10 +1399,11 @@ function cmdPropose(args: string[]): number {
     printLint(P, prop, joints, draftLint);
     console.log(basisLine(bfile, out));
     if (written !== null && clothArg !== undefined) {
+      const from = fromArg === undefined ? '' : `; --from ${fromArg}: ${written.vouched} ${written.vouched === 1 ? 'entry' : 'entries'} taken as the previous recipe's draft`;
       console.log(
         written.paths.length > 0
-          ? `wrote ${written.at}: ${clothArg}'s text with ${written.paths.join(', ')} spliced in from the draft; every other byte as read`
-          : `wrote ${written.at}: ${clothArg}'s text byte for byte; every entry the recipe drafts is already as drafted`,
+          ? `wrote ${written.at}: ${clothArg}'s text with ${written.paths.join(', ')} spliced in from the draft; every other byte as read${from}`
+          : `wrote ${written.at}: ${clothArg}'s text byte for byte; every entry the recipe drafts is already as drafted${from}`,
       );
       if (written.relative.length > 0 && dirname(resolve(written.at)) !== dirname(resolve(clothArg))) {
         console.log(`note: ${written.relative.map((r) => `${r.at} "${r.value}"`).join(', ')} written as stated; the loader resolves each against the directory the config sits in, ${dirname(written.at)} for ${written.at}, not ${dirname(clothArg)}; put the config beside ${clothArg} or rewrite them`);

package/docs/AUTHORING.md

@@ -128,7 +128,7 @@ read by no CPU stage).
 | `stops` | rig (handed to rig-c as `rig.json`'s `stops`, and moves slots, mesh weights and child bones on stopped links onto `<link>_d`); `propose --from-config` (`LINT stop on <chain> …`) | **authored**, optional (issues #404, #447): `[{chain, links?, against, at, inward, outward, lower?: {inward, outward}}]` — rig-c's leg stops (`RigStop`, rig-c 2.56.0, `rig-c/src/stop.ts`). `chain` is a chain `bones` declares (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `links`, optional, is a non-empty list of links of that chain (`CONFIG_NAME_RESOLVES`, `CONFIG_FIELD_TYPE`), or absent for every link of `chain` in chain order; `against` is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `at` is `[x, y]` in `against`'s local space, as rig-c's stop takes it (`CONFIG_FIELD_TYPE`): since each chain link (`leg_r0`, `leg_r1`) is turned to point along its segment (`+x` from origin to next link or tip, `+y` 90° counter-clockwise in Spine world), `at: [d, n]` sits `d` px from `against`'s origin toward its end and `n` px perpendicular to it; `inward`, `outward` and `lower.inward`, `lower.outward` are finite numbers (`CONFIG_FIELD_TYPE`). Every other stop rule — non-negative bounds, each stopped link written by a constraint, `against` not under the stopped chain, the aim not degenerate, `\|rest\| + outward <= 180°` (`RIG_STOP_BOUNDS`) — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). **Rising-limb / prone geometry (issue #447):** rig-c's `expandStops` aims `<chain>_rest` from `links[0]`'s setup origin at `<chain>_touch` (`at` in `against`'s local frame) and clamps `<link>_d` inside `[rest − inward, rest + outward]`; Spine wraps rotation at `±180°`, so `\|rest\| + outward <= 180°` is required (`RIG_STOP_BOUNDS`). Whenever `<chain>_touch` lies **above** `links[0]`'s root in rig pixels (`ty < y0`, i.e. higher Spine `y` — e.g. stopping a hanging cloth chain against a rising shin `leg_<s1>` in a prone or kneeling pose where the knee sits below `links[0]` and the ankle above it, so positive `at[0]` walks upward along the shin past `links[0]`'s root), `rest` lands in the upper half-plane (`\|rest\| > 90°`) and `\|rest\| + outward` exceeds `180°`. Stop against the descending thigh (`leg_<s0>`), set `links` to start at a link whose root sits above `<chain>_touch`, or omit the stop when the rising shin sits outside the hanging chain's sweep; `propose --from-config` prints `LINT stop on <chain> …` with the exact coordinates and angles when `<chain>_touch` lies above `links[0]`'s root or `\|rest\| + outward > 180°`. For every stopped link `<link>`, the rig stage moves any slot on `<link>`, any mesh weight on `<link>`, and any bone whose parent is `<link>` (a branched cloth tree's branches hanging from `<trunk_last>`, before `--idle-keys ctl` adds `<bone>_ctl` and before `turn` adds `turn_<part>_<bone>`) onto `<link>_d`, the drawn link bone rig-c's `expandStops` creates at `<link>`'s setup frame to carry the clamped rotation. Absent, `rig.json` carries no `stops` and no byte of any output moves |
 | `turn` | rig (adds the turn control) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected: `{pivot, depths, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}}`. `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median, unless it rides another part's bone. With no `face` part, or more than one, the riders keep their own and a note says so. A rider by bone (issue #535) — a part every *ownable* bone of which (a chain link, or a bone no other bone hangs from; `head`, `chest` and any bone with a child are shared and never count on their own) is *hosted* by another carried part, the host of a bone being the carried part that binds it (its region's bone; a mesh's `segments`, `contour` and `auto` regions' bones) with the most `opaque_px`, the earlier in parts.json on a tie, and which hosts no bone itself — is drafted at its host's depth, 0.001 nearer when drawn after the host and 0.001 further when before, and a note names the host, the bones and its own median: a pin, clip or ornament on the back hair's links travels with the back hair, not with its own layer's depth. `propose` reads the proposal's own `bones`, `meshes` and `regions`; the face riders are read by their tag first and never by their bones. A part bound to two hosts' bones rides neither and a note says so. In the rig stage, an authored depth on a rider by bone whose fraction differs from its host's by more than 0.1 of the dial (`TURN_RIDER_APART`, a share of `pivot − nearest`) is refused (`CONFIG_TURN_RIDER_DEPTH`); the host is read off `parts.json`'s `opaque_px`, so the config loader cannot see it. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it requires `config.turn` (`CONFIG_TURN_REQUIRED`, issue #478; `propose --full`/`--head` drafts it), promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening on the trailing side, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). On yaw (`issue #479`), `evalYawFaceSurface` evaluates a **cylinder projection** (`cylinderYawDx`: `Δx(x, θ, R) = R · (sin(clamp(arcsin(clamp(x / R, −1, 1)) − θ, −π/2, π/2)) − clamp(x / R, −1, 1))`) of radius `R` (`turnSurfaceRadius`: `turn.surface.radius ?? turn.radius ?? turn.head.radius`, positive rig px checked by `CONFIG_FIELD_TYPE`, defaulting to half the face plate's opaque width `W / 2`) tapered by a cubic Hermite outline weight (`wOutline = 1` for `\|ux\| <= 0.7`, reaching `0` at `\|ux\| = 1.0`) so features slide across a fixed outline (`iris` shift within `±2%` of `cylinderYawDx`), the trailing cheek strip widens (`>= 1.54×` at `±15°`), and the leading jaw edge holds fixed (`0 px` shift) unless explicit horizontal `turn.deform` overrides (`turn_mid_x`, `turn_lead_compress_x`, `turn_trail_shift_x`) request the flat yaw table. On yaw (`issue #478`), `applyFaceSurfaceDeform` also derives a **head-only pivot** (`headTurnPivot`: `turn.head.pivot` when authored, otherwise the `opaque_px`-weighted mean of `depths[part]` across the head parts `DEFAULT_HEAD_TURN_PARTS` — `face`, `hair_front`, `hair_back`, `ear_r`, `ear_l`, `hairpin` — from `parts.json`, falling back to `turn.pivot`) so a forward torso or arm in `turn.depths` does not pull the head's rotation axis in front of `face`: `hair_back` (`depth_median > headPivot`, negative `headTurnFraction`) and `hairpin` behind `headPivot` translate opposite to the face's turn (`dx = s · turn_face_center_x · W · (headPivot − depth) / (headPivot − nearestHeadDepth)`), emerging on the trailing side to compensate for the leading-cheek foreshortening and keeping the combined head silhouette width near-constant across `±15°` without any same-sign `turn_hair_back_cheek_x` term. Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); `pivot` and `head.pivot` must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
 | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite, and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
-| `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `bones` and `constraints` whole, `meshes.<part>`, `regions.<part>` and `motion.tracks` entry by entry — and every other byte as read (*The config written*, under the recipe below) |
+| `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `meshes.<part>` and `regions.<part>`, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — and every other byte as read; `--from <previous config>` (issue #571) takes an entry equal to the previous recipe's draft as the recipe's (*The config written*, under the recipe below) |
 | `proposed_rig_scale` | assemble, rig, build, `propose --from-config`/`--compare` | **proposed** by `propose` (issue #354): `parts.json`'s `scale_rig_per_source`, the `assemble.rig_scale` the rig sections (`bones`, `meshes`, `limbs`, `motion`) were drafted at. Held equal to `assemble.rig_scale` when present (`CONFIG_PROPOSED_RIG_SCALE`; 0, negative or not a number: `CONFIG_FIELD_TYPE`). Absent on a hand-authored config, where no byte of any output moves |
 | `requirements` | build (read in place of `--requirements` when the flag is not given), and so its check | **authored**, optional, never proposed (issue #556): a path, relative to the config file's directory, to the `spine-parts-requirements/1` file the build's check reads (§7, *Declared requirements*) — so a rig that needs one (a `not_swinging` part, a `may_fold`) rebuilds from its config alone. `build` reads it before assemble, as it reads the flag's file, and `check.json`'s `requirements.file` records it with `path` as declared. Given beside `--requirements`, the two must name the same file once resolved, or a file of the same bytes, and the declaration is read and recorded (a build given both writes what the config alone writes); otherwise `BUILD_REQUIREMENTS_CONFLICT`, naming both. Not a non-empty string: `CONFIG_FIELD_TYPE`; no such file, where the config is read from a path: `CONFIG_FILE_PRESENT`. `check`, `compose`, `mesh-draft`, `remesh` and `retune` do not read it: their `--requirements` is the only door. Absent, nothing is read and no byte of any output moves |
 
@@ -523,13 +523,30 @@ layers, as follows; every step is arithmetic on the declared bones and the layer
   both segments' parts) within half a pixel of the line, the run through the joint (its nearest
   pixel within 1 px of it, neighbours at most 1.5 px apart), first to last plus one pixel, to 3
   places. The tool invents no pixel of it: each is the `cap` image's where that image is not
-  transparent, else the layer's where the limb has art there, else **missing**. The line
-  `assemble` prints for each joint counts all three and gives the cap's box, `[x, y, w, h]` in
-  rig px:
+  transparent, else the layer's where the limb has art there, else the **upper segment's** art
+  there (issue #557 — the shin's pixels where the boot's layer does not reach over the knee, the
+  shin's again for a shoe that starts below the ankle line; until #557 only `cap_shape: "disc"`
+  read it), else **missing**. The line `assemble` prints for each joint counts them and gives the
+  cap's box, `[x, y, w, h]` in rig px (`N px from "<upper>"` only where the upper segment gave a
+  pixel, so a full cap prints what it printed):
 
       limb cap: "arm_r" joint "elbow" at [332, 424], on "forearm_r": a disc of radius 19.9165 px (the limb 39.833 px across the joint line), box [312, 404, 40, 40] — on the upper side of the line 621 px from the layer, 7 px missing — …
 
-  The missing pixels are where the painting hides the limb or where the disc passes its outline.
+  The missing pixels are where no layer of the limb has a pixel: where the painting hides the limb,
+  or where the disc passes its outline — the half-disc is half the limb's width about the bone's
+  origin, so a bone off the limb's middle puts the far side of the disc past the outline (every
+  missing pixel on the public `wind` example is that: 9 to 72 per joint, each on one side, none
+  within the half-width about the joint). **A cap with missing pixels is short** (issue #557): its
+  record carries `short_px: {left, right}` — the missing pixels by side of the limb's axis at the
+  joint line, `left` where a pixel centre's offset across the axis is 0 or above (the side toward
+  smaller x when the limb hangs down the rig), `right` the other, the two adding up to
+  `missing_px` — and `assemble` prints one `LINT` line after its `limb cap:` line:
+
+      LINT "shin_r" cap at [34, 30] (limb "leg_r", joint "knee", radius 4 px): short_px left 0, right 3: no layer gives them — 3 px of the disc on the upper side of the cut, where neither the layer of "boots" nor that of "legs" has a pixel of the limb; the rest of the disc is filled, 17 px from "shin_r"'s layer, 6 px from "thigh_r"; under cap_shape "disc" the disc is the half-width about the joint, 4 px, and 3 of them lie within it
+
+  The last clause, on a cap without `cap_shape`, counts how many of them the disc of the
+  half-width about the joint would still hold: none means `cap_shape: "disc"` closes the
+  shortfall (it does on every `wind` joint). A full cap writes no `short_px` and prints no `LINT`.
   Paint them — and, if the layer's own pixels carry the limb's outline across the cap, the whole
   cap — into a `w`x`h` image whose pixel `(i, j)` is rig pixel `(x + i, y + j)`, and name it in
   the segment's `cap`; its transparent pixels keep the layer's. The record is `parts.json`'s
@@ -542,8 +559,9 @@ layers, as follows; every step is arithmetic on the declared bones and the layer
   the limb's art across the line either way. It is measured, never typed; a joint on the very edge of
   the run has none and is `ASSEMBLE_LIMB_JOINT_ON_ART`. The cap's pixels come from the image, then
   the layer, then **the upper segment's art** where the lower's layer has none (the shin painted down
-  to the ankle is the shoe's cap), and only where no segment has art are they missing. The `limb
-  cap:` line adds `N px from "<upper>"`, and the record `shape` and `upper_px`. The upper piece's
+  to the ankle is the shoe's cap) — the plain cap's order too since issue #557 — and only where no
+  segment has art are they missing. The `limb cap:` line adds `N px from "<upper>"` always, and the
+  record `shape` and `upper_px` (without the shape, `upper_px` only when above 0). 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 no piece takes it, or a stub out of the bent lower piece's outline
   when the lower takes it (pictured in the pull request that added these two fields).
@@ -588,7 +606,9 @@ layers, as follows; every step is arithmetic on the declared bones and the layer
   bar at each, against the same pose with the joint's own art drawn under the limb — so a cap
   that does not cover the turn is a FAIL naming the joint and the angle, where the rest pose
   showed nothing. A joint whose cap is `cap_shape: "disc"` is held to more: no pixel of its disc
-  over 40 at any pose, the disc being the cap's whole claim. `TIP_OVER_ROOT` does not read a limb part (it turns at its joint; it does not
+  over 40 at any pose, the disc being the cap's whole claim. Each pose's row also prints the
+  **contour step** (issue #557), the step the eye sees in the outline where the cut meets it — a
+  reading, never a bar (§7). `TIP_OVER_ROOT` does not read a limb part (it turns at its joint; it does not
   hang), and its row says so.
 
 The first character built this way (the exam-01 test rig, issue #349) read, per joint, 5 to 10
@@ -1667,7 +1687,29 @@ recipe re-drafts or removes that the author changed by hand (it equals neither d
 not dropped: the run is refused, `PROPOSE_WRITE_CONFIG_CONFLICT`, naming the entry
 (`config.constraints[40] "skirt0a_0_physics"` in CL207), the first field the hand edit holds and
 what the draft writes there, every conflict at once and nothing written; take the draft
-by removing the hand edit, or leave the recipe out for that part. A `meshes.<part>` the
+by removing the hand edit, or leave the recipe out for that part. **A changed recipe
+(issue #571).** The draft of the recipe as it stood before a change is neither of the
+two drafts, so a config holding that draft untouched would read as hand-edited at every
+entry the change moves (29 refusals on the public `wind` example with
+`cloth.bottomwear.links` 3 → 4). `--from <previous config>`, given beside
+`--write-config`, names the config the recipe is changed from: its `cloth` block is read
+as `--cloth`'s is (a missing file or a missing `cloth` block is refused by the same
+codes), and the same parts are drafted a third time with it. An entry equal to that
+previous recipe's draft is then the recipe's, as one equal to the draft without the
+recipe is: replaced by the draft, or removed where the draft no longer holds the name
+(a link the change took away). An entry equal to none of the three drafts is still
+refused, `PROPOSE_WRITE_CONFIG_CONFLICT`, the detail reading "it equals neither the draft,
+the draft without the recipe, nor the previous recipe's draft" and naming the first field
+that differs from the previous recipe's draft (the entry a person most likely edited
+from). The write line ends `--from <path>: n entries taken as the previous recipe's
+draft`. `meshes.<part>` and `regions.<part>` are unchanged by `--from`: a mesh the
+recipe drafts is replaced whole already, and one the two drafts agree at is not touched.
+Without `--from` every rule and every byte is the writer's before #571; with a `--from`
+whose recipe equals `--cloth`'s the previous draft is the draft, and the written config
+is byte for byte the one written without it (CL209–CL212 hold each on the cloth fixture,
+CL213–CL215 on `wind`). The written config is the recipe's draft, not a verdict on it: on
+`wind`, `links` 3 → 4 writes the skirt entries of its proposal value for value, and that
+draft fails `CHECK_TIP_OVER_ROOT` on the skirt in `build`; 3 → 2 builds green (CL215). A `meshes.<part>` the
 recipe drafts is still the draft's whole, as a hand-edited lattice does not survive
 `mesh-draft`, and a mesh it does not draft keeps its bytes. Every other byte is the
 input's; a section the input lacks (a config holding only `key` and `cloth`) is
@@ -1681,7 +1723,8 @@ wrote back byte for byte (measured once, when the flag landed). The text is writ
 (`motion.animations_from`, `generation.control.skeleton`) resolves against the directory
 the written config sits in, so the out path belongs beside the input, and when it is not
 a note names each such path. Refused before anything is written: `--write-config`
-without `--cloth` or beside `--from-config` (`USAGE`), an out path that exists or that
+without `--cloth` or beside `--from-config`, and `--from` without `--write-config`
+(`USAGE`), an out path that exists or that
 the run writes itself (`PROPOSE_WRITE_CONFIG_FRESH`), a hand edit to an entry the
 recipe owns (`PROPOSE_WRITE_CONFIG_CONFLICT`), and a text whose splice does not
 parse to the config with the sections set — a key stated twice
@@ -2280,7 +2323,7 @@ move off it (`AS245`).
 | --- | --- | --- | --- |
 | `layers` | the table, then one `author-made: layer "author:<label>" — …` line per layer the author made (group `author` in the table; §5, *A layer the author made*), then the `WARN` lines | every tag the plan will need has opaque pixels; one `face` in the head run; `0 WARN line(s)` | a run whose layer PNG is not its box's size (`LAYERS_PNG_MATCHES_BBOX`); a `WARN  PLAN_LAYER_…` line (§6, *Plausibility*) |
 | `sheet` of both runs | the tile list (and the sheet, if you can see) | eyes, irises, lashes and brows as left/right pairs in the head run | a head box that cut off an ornament: move `head_box`, re-run the head crop |
-| `assemble` | one line per part — its counts (`op=` opaque, `vis=` visible, `src=` taken / candidates, `unproj=` visible but not projected, `drift=<n> (<p>% of core)`, `merged=`, `seam=`; *parts.json*, below). `drift=` is `refused_drift_px` in rig px and its share of the part's candidates, `projected_core_px`, which it is a subset of (issue #314); no bar reads either. On the four public examples the share runs to 94.5 % (`scarf` `hair_back`, 479 of 507) and the count to 26,472 (`scarf` `topwear`, 22.3 %), and the seam override repaints refused top-most pixels afterwards, so a large count says where See-through's colour was not taken, not that the part is unlike the painting: the `drift:` line below is the one that names a body of them another part holds. Then the `pixels:` totals (opaque = visible + occluded; taken; visible but not projected), then `recomposite vs source: mean \|d\|, within 8, error px > 40, uncovered error px`, then `uncovered holes (8-connected): N` and the largest five as `uncovered hole K: <px> px at x,y wxh (between "<part>" <px> px, …)`, then one `uncovered: <n> of the <N> uncovered error px lie on the full run's "<tag>", in a body of <px> px at x,y wxh; <the rule that left it out>` line per full-run layer the plan does not take from the full run whose uncovered error holds a body (5x5-opened, 8-connected, at least 150 full-run px in rig px), then one `drift: "<part>" refuses <n> px of <run>:<tag> (its colour more than 90 off the painting, max channel), in a body of <px> px at x,y wxh (…); by the plan's draw order "<holder>" holds <px> px of it (…), "<holder>" drawn in front of "<part>"` line per part whose drift refusals hold a body (the same opening and bar) that another part holds in the draw order — that layer is not what the painting shows there (none on the five public paintings); and look at `render/recomposite_error_rig.png`. Between the part lines and the totals, one `author-made: part "<part>" (<run>:author:<label>) — …` line per part from a layer the author made (below, *A layer the author made*), then one `cut: "<part>" opaque <n> = "<part>" <kept> + "<piece>" <taken> …` line per part an `assemble.cuts` entry cut (below; it ends `; under <n> px filled, <m> px left empty` when a cut of that part has `under`), then — with `config.limbs` (issue #349) — one `limb cut: "<part>" opaque <n> = "<segment part>" <px> + …` line per part a limb takes and one `limb cap:` line per joint, its cap's pixels from the cap image, from the layer and missing, and its box — under `cap_shape: "disc"` also from the upper segment, under `edge: "feather"` the pixels faded, under `cut_band` the line the cut was placed on and the stroke pixels it and the joint line cross (issue #360) (§3, *Limbs: cut at their joints*), then one `fringe pushed back: "<part>" <px> px, where the painting shows "<holder>" <px> px, …` line per part whose fringe was cleared (below) | on the examples: `reference-sample` 0.83 / 98.0 % / 4,359 / 1,185, 259 holes, the largest 94 px; `reference-demo` 2.34 / 95.8 % / 10,340 / 1,564, 453 holes, the largest 70 px (default rule) — many slivers along part edges, no hole a region could hide | one large hole: part of the figure is in no layer — a plan entry is missing, hair left the head crop sideways (reference-demo's `hair_back` is taken from the full run for that reason), or See-through split one garment into two and left the space between them in neither (a skirt as two trouser legs); the `between` parts say where. When neither run holds it at all, an `assemble.patches` entry cuts it from the painting (below) |
+| `assemble` | one line per part — its counts (`op=` opaque, `vis=` visible, `src=` taken / candidates, `unproj=` visible but not projected, `drift=<n> (<p>% of core)`, `merged=`, `seam=`; *parts.json*, below). `drift=` is `refused_drift_px` in rig px and its share of the part's candidates, `projected_core_px`, which it is a subset of (issue #314); no bar reads either. On the four public examples the share runs to 94.5 % (`scarf` `hair_back`, 479 of 507) and the count to 26,472 (`scarf` `topwear`, 22.3 %), and the seam override repaints refused top-most pixels afterwards, so a large count says where See-through's colour was not taken, not that the part is unlike the painting: the `drift:` line below is the one that names a body of them another part holds. Then the `pixels:` totals (opaque = visible + occluded; taken; visible but not projected), then `recomposite vs source: mean \|d\|, within 8, error px > 40, uncovered error px`, then `uncovered holes (8-connected): N` and the largest five as `uncovered hole K: <px> px at x,y wxh (between "<part>" <px> px, …)`, then one `uncovered: <n> of the <N> uncovered error px lie on the full run's "<tag>", in a body of <px> px at x,y wxh; <the rule that left it out>` line per full-run layer the plan does not take from the full run whose uncovered error holds a body (5x5-opened, 8-connected, at least 150 full-run px in rig px), then one `drift: "<part>" refuses <n> px of <run>:<tag> (its colour more than 90 off the painting, max channel), in a body of <px> px at x,y wxh (…); by the plan's draw order "<holder>" holds <px> px of it (…), "<holder>" drawn in front of "<part>"` line per part whose drift refusals hold a body (the same opening and bar) that another part holds in the draw order — that layer is not what the painting shows there (none on the five public paintings); and look at `render/recomposite_error_rig.png`. Between the part lines and the totals, one `author-made: part "<part>" (<run>:author:<label>) — …` line per part from a layer the author made (below, *A layer the author made*), then one `cut: "<part>" opaque <n> = "<part>" <kept> + "<piece>" <taken> …` line per part an `assemble.cuts` entry cut (below; it ends `; under <n> px filled, <m> px left empty` when a cut of that part has `under`), then — with `config.limbs` (issue #349) — one `limb cut: "<part>" opaque <n> = "<segment part>" <px> + …` line per part a limb takes and one `limb cap:` line per joint, its cap's pixels from the cap image, from the layer and missing, and its box, followed on a short cap by one `LINT "<part>" cap at [x, y] … short_px left <n>, right <m>: no layer gives them …` line (issue #557) — from the upper segment where it gave a pixel (under `cap_shape: "disc"` always), under `edge: "feather"` the pixels faded, under `cut_band` the line the cut was placed on and the stroke pixels it and the joint line cross (issue #360) (§3, *Limbs: cut at their joints*), then one `fringe pushed back: "<part>" <px> px, where the painting shows "<holder>" <px> px, …` line per part whose fringe was cleared (below) | on the examples: `reference-sample` 0.83 / 98.0 % / 4,359 / 1,185, 259 holes, the largest 94 px; `reference-demo` 2.34 / 95.8 % / 10,340 / 1,564, 453 holes, the largest 70 px (default rule) — many slivers along part edges, no hole a region could hide | one large hole: part of the figure is in no layer — a plan entry is missing, hair left the head crop sideways (reference-demo's `hair_back` is taken from the full run for that reason), or See-through split one garment into two and left the space between them in neither (a skirt as two trouser legs); the `between` parts say where. When neither run holds it at all, an `assemble.patches` entry cuts it from the painting (below) |
 | `propose` | `note:` lines, `LINT` lines, the `coverage` lines, `landmarks.png`, `basis.json` | no LINT line: every chain link lies on its mesh's art, and the hip is below the chest and the figure's top quarter; the `coverage:` summary says how many bones that verdict covers — a `not checked` bone was read by no check (its line says why), and a `ratio` or `fallback` bone in `basis.json` is a guess | a link off the art (a bone on the background) — move it onto the layer; `LINT <link> at … runs to … N degrees off the head's down axis …` — a fringe link that does not lean with the head (§3, the fringe in the head's frame): move it along the lock it drives; `LINT hairback_… on mesh '<part>' (side <r\|l>): <N> tree(s) for <M> visible hair mass(es) (mass 0 columns x=<minX>..<maxX>, y=<minY>..<maxY>; …)` — back-hair cloth trees whose count does not match the side's visible hair masses (`max(1, floor(w / (4 * grid)) + 1)` per mass) or whose link or tip leaves its mass's column range (issues #445, #461): omit `chains` on `cloth."back hair"` or draft trees per visible hair mass inside its columns; `LINT <a_limb> and <b_limb> on <part> (<from>) cross at [x, y] with no per-limb split: …` — two limbs sharing one layer cross in an X without a per-limb split (issue #446): declare `config.limbs.<covering>.split` (`{ "line": [[x, y], …] }` or `{ "edge": "painting" }`, §3 *Which limb*); `LINT foot_<s> at [x, y], the <s>_ankle joint and leg_<s>1's tip, lies on none of leg_<s>'s art within 1 px along its joint line (the nearest of it on that line is the pixel [x, y], D px from the joint): …` — an ankle keypoint off its leg's art on the line `assemble` sizes the ankle's cap by (issue #517): `propose` drafts every leg without its ankle cut, the shoe layer stays one part, and nothing is moved onto the art; move that ankle keypoint onto the leg's or the shoe's art and re-run `propose` (`(the line crosses none of it)` when no art lies on that line at all); `LINT stop on <chain> (<firstLink> at [x0, y0]) against <against> (at [ax, ay]) places <chain>_touch at [tx, ty], above <firstLink>'s root (rest R deg, \|rest\| + outward B deg): …` — a stop's contact point `<chain>_touch` lies above `links[0]`'s root in rig px or pushes `\|rest\| + outward` past `180°` (issue #447, §2 `stops`): stop against the descending limb bone below `firstLink`, set `links` to start at a link below `<chain>_touch`, or omit the stop on a rising limb; `LINT hip at [x, y] is not below chest at [x, y]: …` or `LINT hip at [x, y] is above 0.25 of the figure height (figure y T..B, so hip y must be at least L): a hip at the shoulders` — move `hip` down to the waist (and `chest` between it and the neck); a `hanging strand … -- no chain proposed` note — that strand hangs stiff until you add a chain down the x and rows it names (§3); a `no blink: …` or `blink without brows: …` note — the idle will not blink (or its brows will not drop), because no part came from an `eyewhite` (or `eyebrow`) layer; the note names the tags looked for; a `no eyewhite part for eye_<s> …` note — the iris and lash parts it names ride `head` and do not blink, because no `eyewhite-<s>` part made that side's eye bone: take the eyewhite from the other run, or keep them on `head`; a `no face part: face box derived from …` note (always the first) — `head`, `neck` and every face-height scale come from a box guessed off the hair and neck (§3): check `head` and `neck` on `landmarks_head.png` and move them; when it adds `the blink shuts the eyes over no face part`, read `BLINK_NO_HOLE` after `check` — an eye with no face under it can open a hole (the `reference-sample` with only its face removed: 587 px). Under `--keypoints`: the `lint rule set:` line first (joints, or screen and why), then the joint notes — `missing: the rule "…" placed bone X instead` is a bone still guessed; `not used — …` names why an arm's joints did not place its sleeve (for a wrist on no part, the nearest part and the `--wrist-snap` that would bind it); a `wrist snap: …` note is a wrist bound past 15 px by the flag — check that chain's tip on `landmarks.png`; a `one handwear part holds both wrists` note is two chains on one mesh — cut the part with `assemble.cuts` to separate them; `LINT chest at … is not between the neck joint …`, `LINT hip at … is not past chest …`, `LINT hip at … is nearer the neck joint …` and `LINT <chain><i> at … does not advance from <s>_shoulder toward <s>_wrist` are the joint-frame lines: move that bone between, past or along the joints they name |
 | `compare` | one line per pair (origin, parent, tip, length, direction — or SKIP and why), then the per-row summary, the unmapped bones of each side, `required:`, each side's roles and the `controls:` line | proposal against the config you corrected: the rows you changed and no others. Config against the `rig.json` `build` writes for it: measured on both examples, every origin within 6.19e-7 px (the rig's offsets are written to 6 places) and every chain link's tip and length within 4.99e-4 px (`length` is written to 3), printed to three places as `0.000` (a signed figure as `+0.000` or `-0.000`); `parent … is the right's ancestor at depth 2, <bone>_ctl between` for every keyed mesh bone, no `DIFFERENT` and no `NOT MAPPED` | `parent DIFFERENT: left a, right b` — a bone hangs from another parent than the other side's; `frames not related` — a rig with no stage (`skeleton.width`/`height`), two configs at different `rig_scale`: the distance rows SKIP, so declare the frame in a `--map` file if the author knows it; `FAIL  STRUCTURE_REQUIRED_PRESENT` — a bone the map requires is missing through its pairs |
 | `rig` (inside `build`) | one line per mesh: vertices, triangles, bones, influences, `cover`; the `bones` line; the `idle keys` line; then rigc's gate lines (with A15's declared SKIP under `--idle-keys direct`); in `rig.json`, each chain link's (or its `_ctl`'s) `length` and `rotation` | `cover 1.00000` on every mesh, both gate summaries `0 failed` (the compile and the packed pages); every link's `length` the distance to the next link and `rotation` its direction (Spine degrees, counter-clockwise, y up, local to the parent), every offset under it — a child bone's `x, y`, a weight's bind `x, y`, a region's `x, y` — in that turned frame, and a region on a link carrying `rotation` that turns it back upright. Nothing moved: `flattenRig` (`src/rig.ts`) turns every offset back and gives the unturned numbers | `RIG_LATTICE_ONE_LOOP`: change that mesh's `grid` |
@@ -2897,7 +2940,7 @@ says why each requirement exists and what breaks without it.
 | <a id="PROPOSE_CLOTH_DRAFTED"></a>`PROPOSE_CLOTH_DRAFTED` | with `--cloth` (issue #364): the config's `cloth` block holds a recipe for a tag the proposer drafts no chain on — no part has that tag, or every `back hair` part ends above the shoulders (a bun bone, no chain). A `bottomwear` recipe with no `bottomwear` part names every `topwear` part shaped like a skirt (issue #402) | leave that recipe out, or assemble the layer it is for, or declare the named part in `cloth.bottomwear.part` |
 | <a id="PROPOSE_CLOTH_PART"></a>`PROPOSE_CLOTH_PART` | with `--cloth` (issues #402, #437): `cloth.bottomwear.part` (a string) names no part, a part or cut piece whose source is not `topwear` (a `bottomwear` part takes the recipe by its tag already), or a target whose box ends above the hip + 0.25 face heights, the topwear rule's waist line; or `cloth.<tag>.parts` (or `part` as a list, issue #437) names a part not in `parts.json`, a part no link of the drafted tree crosses (`spanCrosses == 0`), or parts out of root-to-tip depth order along the chain | name the `topwear` part or its cut skirt piece that holds the skirt (or leave `part` out), or list only parts in `parts.json` that the drafted tree links cross in root-to-tip order |
 | <a id="PROPOSE_WRITE_CONFIG_FRESH"></a>`PROPOSE_WRITE_CONFIG_FRESH` | with `--write-config` (issue #537): the out path exists, or is a file the run writes itself (`proposal.json`, `basis.json` under `--out`); the config is written to a new file, never over the `--cloth` config or an earlier one | name a file that does not exist yet, beside the `--cloth` config |
-| <a id="PROPOSE_WRITE_CONFIG_CONFLICT"></a>`PROPOSE_WRITE_CONFIG_CONFLICT` | with `--write-config` (issue #552): an entry of `bones`, `constraints` or `motion.tracks` the recipe re-drafts or removes was changed by hand in the `--cloth` config — it equals neither the draft with the recipe nor the draft without it — so the write would drop the hand edit; the object is the entry (`config.constraints[40] "skirt0a_0_physics"` in CL207), the detail names the first field the hand edit holds and what the draft writes there. Also a name the config states twice where the recipe drafts it. Every conflict is named at once and nothing is written | take the draft by removing the hand edit (or the entry), or leave the recipe out for that part (its `cloth` block); state a name once |
+| <a id="PROPOSE_WRITE_CONFIG_CONFLICT"></a>`PROPOSE_WRITE_CONFIG_CONFLICT` | with `--write-config` (issue #552): an entry of `bones`, `constraints` or `motion.tracks` the recipe re-drafts or removes was changed by hand in the `--cloth` config — it equals neither the draft with the recipe nor the draft without it — so the write would drop the hand edit; the object is the entry (`config.constraints[40] "skirt0a_0_physics"` in CL207), the detail names the first field the hand edit holds and what the draft writes there. With `--from <previous config>` (issue #571) an entry equal to the previous recipe's draft is the recipe's too, and the conflict is an entry that equals neither the draft, the draft without the recipe, nor the previous recipe's draft: the detail says so and reads the first differing field against the previous recipe's draft. Also a name the config states twice where the recipe drafts it. Every conflict is named at once and nothing is written | take the draft by removing the hand edit (or the entry), or leave the recipe out for that part (its `cloth` block); state a name once |
 | <a id="PROPOSE_WRITE_CONFIG_SPLICE"></a>`PROPOSE_WRITE_CONFIG_SPLICE` | with `--write-config` (issue #537): the `--cloth` config's text with the drafted sections spliced in does not parse to that config with them set, and the message names the first key that moved — the text states a key twice, so the splice lands on the first and the parse keeps the last | state each key once in the `--cloth` config |
 | <a id="PROPOSE_CLOTH_BACK_HAIR_CHAINS"></a>`PROPOSE_CLOTH_BACK_HAIR_CHAINS` | with `--cloth` (issues #390, #445, #461): `cloth."back hair".chains` exceeds what the narrower side's opaque width at the eye-line root row holds at the part's mesh grid (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`), or places a tree root outside the 15 px dilated art mask of the `back hair` part (e.g. an inner twin-tail root over the face where the hair has no pixel); the message names the part, each side's root-row width, the grid spacing, and any off-art root with its pixel alpha | lower `cloth."back hair".chains` to at most the max fit named in the message, or omit `chains` so `propose --cloth` derives the tree count per visible hair mass on each side from its root-row width |
 | <a id="PROPOSE_ACCESSORY_BODY"></a>`PROPOSE_ACCESSORY_BODY` | an accessory has nothing above its pendant rows to hang its bone on | that part's plan entry, or author its bones by hand |
@@ -3336,7 +3379,7 @@ the two examples [observed]:
 | <a id="FEET_STAY_LEVEL"></a>`FEET_STAY_LEVEL` | issue #348. Each `footwear` part whose slot's bone hangs from another bone (rig.json's `parent`; a part on `root` hangs from nothing and is not read), over every animation, the idle included, from the same `rigc render --folds` run, which then also writes `--geometry`: on each frame where a bone above the part's bone — its parent or any bone over that — has a world rotation other than its setup pose's (no threshold; the nearest is named), the drawing's turn: the least-squares rotation carrying the attachment's setup-pose vertices onto the frame's, both centred (a region's four corners turn exactly with its bone). **This is the reading of "the sole's angle"**: no rig data marks a sole, so level is the drawing's setup angle, the painting's own; a declared sole line would replace it if one ever exists | every read foot within ±10 degrees — HQ's line (rig-c/parts#347 ruling 4), not a figure measured here | not written: the shoes ride `root` | not written: the shoes ride `root` | SKIP when no frame turns a bone above any read foot (not counted as measured); not written at all when no `footwear` part hangs from a bone, or `motion.json` holds no animation, so the examples' `check.json` keep their keys |
 | <a id="STRESS_OFF_CHAIN"></a>`STRESS_OFF_CHAIN` | each mesh from a See-through `handwear` layer whose weights ride exactly one chain the idle keys: the chain's first link turned 90°, −90° and 180° from its setup rotation (interim, issue #347: until a config block declares each limb and its joint's range), one `rigc build --profile spine` and one `rigc render --geometry` of a copy with its physics constraints left out; per turn, the part's worst edge as max(ratio, 1/ratio) against the setup pose, at four places, and the bones it is weighted to off the chain. A part riding two chains, or none, or not a weighted mesh, is listed under `not_read` with the reason, and so is a part a `config.limbs` segment made (issue #349): `LIMB_ONE_BONE` holds it to its one bone, so it turns rigidly by construction | 1.0000 — the part turning rigidly with its chain; float32 noise on rigid sleeves measured at most 1.0000090 | SKIP: `sleeves` rides 2 chains | SKIP: `sleeves` rides 2 chains | no part comes from a `handwear` layer or the motion has no idle (the line is not written); every `handwear` part not read (SKIP, each reason) |
 | <a id="LIMB_ONE_BONE"></a>`LIMB_ONE_BONE` | issue #349. Each part `parts.json` records as a limb segment's (`limb`), read off `rig.json` alone, nothing rendered: the bones its attachments are bound to — a mesh's weights, or its slot's bone for a region — against its segment's bone (under `config.turn`, that bone's leaf twin counts as the bone) | every limb part bound to its one bone alone, weight 1 | not written: no limbs | not written: no limbs | never: written only when `parts.json` holds a limb part, so the examples' `check.json` keep their keys |
-| <a id="SEAM_OVER_RANGE"></a>`SEAM_OVER_RANGE` | issue #360. Each limb part `parts.json` records with a `range` (`config.limbs.<limb>.segments[k].range`): a copy of the rig with its physics constraints left out, its joint's bone keyed `rotate` to the range's min, its middle and its max (each angle once, rigc's sense, counter-clockwise on screen), one `rigc build --profile spine` and two `rigc render`s on one grid — one with the joint's own art drawn under the limb (the limb's parts at rest inside the cap's disc, one pixel in from every edge of what is opaque there, on the bone the joint's bone hangs from), one with it hidden (`--hide`); per pose, the seam figures of the second against the first | the rest-pose seam's: mean \|d\| ≤ 1.0 and ≤ 50 rig px over 40 at every pose; a `cap_shape: "disc"` joint also 0 frame px over 40 | not written: no limbs | not written: no limbs | never: written only when `parts.json` holds a limb record with a `range`, so the examples' `check.json` keep their keys |
+| <a id="SEAM_OVER_RANGE"></a>`SEAM_OVER_RANGE` | issue #360. Each limb part `parts.json` records with a `range` (`config.limbs.<limb>.segments[k].range`): a copy of the rig with its physics constraints left out, its joint's bone keyed `rotate` to the range's min, its middle and its max (each angle once, rigc's sense, counter-clockwise on screen), one `rigc build --profile spine` and two `rigc render`s on one grid — one with the joint's own art drawn under the limb (the limb's parts at rest inside the cap's disc, one pixel in from every edge of what is opaque there, on the bone the joint's bone hangs from), one with it hidden (`--hide`); per pose, the seam figures of the second against the first. Issue #557: per pose also the **contour step**, a reading and never a bar — on the frame with the joint's art hidden, lines across the upper segment (perpendicular to its bone's direction at the setup pose, origin to the joint) one frame pixel apart, from one cap radius before the joint line to one past it; on each, from the axis outward on each side, the outline's extent (the first sample within 40 of the background, out to two radii); the step on a side is the largest change between adjacent lines, in rig px, `left` and `right` as the cap's `short_px` names them. A limb whose outline the bend keeps reads one frame pixel, 1 / s rig px (1.161 at the synthetic fixtures' s 0.861413); the unfilled two-layer knee of the selftest reads 11.609 on the opening side at ±15° and the filled one 1.161. The row prints it; `check.json` carries it (`step_px` on each pose) only for a joint whose cap record carries `short_px` | the rest-pose seam's: mean \|d\| ≤ 1.0 and ≤ 50 rig px over 40 at every pose; a `cap_shape: "disc"` joint also 0 frame px over 40 | not written: no limbs | not written: no limbs | never: written only when `parts.json` holds a limb record with a `range`, so the examples' `check.json` keep their keys |
 
 **`TIP_OVER_ROOT` is measured from geometry, not pixels (issue #118).** Until #118 the
 line rendered each part alone at `--max 640` and took, per half of its frame box, the

package/docs/STABILITY.md

@@ -53,7 +53,7 @@ defaults are the help's too, and none is guessed from the art.
 | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll` |
 | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`; or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454) |
 | `propose` | `--head-box` with `--full`, `--canvas`; optional `--no-back-hair` |
-| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (a new file, with `--cloth` and not with `--from-config`, issue #537 — additive: without it nothing `propose` writes changes) |
+| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`), `--write-config` (a new file, with `--cloth` and not with `--from-config`, issue #537 — additive: without it nothing `propose` writes changes), `--from` (the config the recipe is changed from, only with `--write-config`, issue #571 — additive: without it nothing `--write-config` writes changes) |
 | `compare` | `--left`, `--right`; optional `--map` |
 | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
 | `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills`, `--set` or `--all-sets` (issue #454), `--environment` (issue #538, additive) |
@@ -190,15 +190,15 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 
 | file | written by | what is stable |
 | --- | --- | --- |
-| `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, then `shape` and `upper_px` under the segment's `cap_shape`, and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
+| `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
 | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
 | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones` (the sorted names the attachment's weights bind in the written `rig.json`, in every mode — since 1.49.1 (issue #536) a rig with `turn` or `stops` names the twins and `<link>_d` bones there, where the row named the segment bones they replace: a fix of a wrong name, not a format change; a rig with neither writes the bytes it wrote), `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
-| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40` — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493, a warning and not a bar: `status` — `WARN`, `CLEAR` or `SKIP` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
+| `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493, a warning and not a bar: `status` — `WARN`, `CLEAR` or `SKIP` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `layers.json`, `<index>_<name>.png` | `layers --export` | the wrapper form `layers` reads (issue #359): `width`, `height`, then `layers` — each `name`, `filename`, `left`, `top`, `right`, `bottom`, `depth_median` (the input's own; `null` for a PSD, the manifest's order then being the draw order) — drawn layers in draw order, then the hidden-art layers; a PNG's name is its index and its layer's name, and the manifest, not the file name, says which layer it is |
 | the template `.psd` | `layers --template` | one empty layer per name `templateLayerNames` (`src/layers.ts`) holds, bottom first; the same canvas writes the same bytes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `constraints` with `--cloth` (issue #364: a physics constraint per tree link named `<bone>_physics`, a dangling end's `<bone>_translate`, and a skirt swing's transforms `<swing>_<tree>`), `turn` with `--full`/`--head`, `proposed_rig_scale` (issue #354), and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |
-| the `--write-config` file | `propose --cloth … --write-config` | the `--cloth` config read, byte for byte, but for the entries the recipe drafts (issue #537), measured against the same parts drafted without it: `meshes.<part>` and `regions.<part>` for each part the recipe moves, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — an entry the recipe drafts replaced or inserted, one it replaces removed, every other entry kept with its bytes and its place, and a hand edit to an entry the recipe owns refused by name (`PROPOSE_WRITE_CONFIG_CONFLICT`) rather than dropped; a section the input lacks is inserted |
+| the `--write-config` file | `propose --cloth … --write-config` | the `--cloth` config read, byte for byte, but for the entries the recipe drafts (issue #537), measured against the same parts drafted without it: `meshes.<part>` and `regions.<part>` for each part the recipe moves, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — an entry the recipe drafts replaced or inserted, one it replaces removed, every other entry kept with its bytes and its place, and a hand edit to an entry the recipe owns refused by name (`PROPOSE_WRITE_CONFIG_CONFLICT`) rather than dropped; a section the input lacks is inserted; with `--from <previous config>` (issue #571) an entry equal to the previous recipe's draft is the recipe's as well |
 | `config.json`, `mesh_draft.json` | `mesh-draft` | `config.json` is the config read, byte for byte, but for each drafted part's `meshes` entry; `mesh_draft.json` is spec `rig-parts-mesh-draft/1`: `rules`, `lattice_check`, `draft_check`, `figure_overdraw`, and per lattice part `part`, `mode`, `lattice`, `candidate` (with `bridges` — `units`, `joins` of `span` and `area_px2`, `area_px2`, `overdraw`, and `faint` only when an island was left out as faint — only when the candidate is a bridged one, issue #326), `delta` (under `--more-triangles` only), `readings`, `gate` (each line's `reading`, `pass`, `text`, `margin`), `note`; and `not_compared` (issue #307), only when the config holds an `auto` or `contour` entry: per such entry, in config order, `part`, `mode` and `note` — the part was neither drafted nor compared, and a config of lattices alone writes no such key |
 | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `remesh.json` | `remesh` | the input revision's files, `rig.json` and `mesh_report.json` with the part's attachment and row replaced (under `--delta` the row is the input's with its counts, `bones` and influences recomputed and `mode` "delta"), every other file byte for byte; `remesh.json` is spec `rig-parts-remesh/1`: `request` (`part`, `mesh`, `mesh_sha256`, `idle_keys`, `page_edges`, `pack_shape`; under `--delta`, issue #526: `part`, `delta` — the mesh edit as read — `delta_sha256`, `ops`, `applied` — `moved`, `added`, `removed`, `constrained` — `idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `baseline` (`reproduced`, `not_compared`; under `--delta` `reproduced` holds one sentence: no config is built, the input is the baseline), `target` (`before`, `after`: `vertices`, `triangles`, `hull`), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-remesh/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `scope`) |
 | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `retune.json` | `retune` | the input revision's files, `rig.json` with `constraints` and `invariants.detached` replaced and `motion.json` with `animations.idle` replaced by the config's build, every other file byte for byte; `retune.json` is spec `rig-parts-retune/1`: `request` (`idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `held` (`compared`, `not_compared`), `changed` (`constraints` — each `name`, `type`, `fields` — `added`, `removed`, `idle`: `tracks_changed`, `duration` as before and after), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-retune/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `scope`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {

package/src/assemble.ts

@@ -2701,7 +2701,18 @@ export interface LimbCount {
   before: number;
   shares: Array<{ part: string; px: number }>;
   /** The joints whose cap this part's segments carry, in `config.limbs` order. */
-  joints: Array<{ limb: string; joint: string; part: string; upper: string; cap: CapRecord }>;
+  joints: Array<{
+    limb: string;
+    joint: string;
+    part: string;
+    upper: string;
+    cap: CapRecord;
+    /** Issue #557: the parts the lower and the upper segment take, the half-width about the joint, and the short pixels within it. */
+    from?: string;
+    upperFrom?: string;
+    half?: number;
+    shortInHalf?: number;
+  }>;
 }
 
 /**
@@ -2720,6 +2731,41 @@ function cutPhrase(k: CapRecord, upper: string, lower: string): string {
   return `cut_band ${k.cut_band ?? 0}: the cut ${where}, through [${(k.cut_at ?? k.at).join(', ')}], crosses ${k.cut_crossed ?? 0} stroke px; the joint line crosses ${k.joint_crossed ?? 0} (${stroke})`;
 }
 
+/**
+ * Issue #557: the `LINT` line of a short cap — one whose disc, on the upper
+ * side of the cut, holds pixels no layer of the limb gives (`short_px`, by
+ * side of the limb's axis: `left` where a pixel centre's offset across the
+ * axis is 0 or above, the side toward smaller x when the limb hangs down the
+ * rig, `right` the other) — naming the limb, the joint, the part, both
+ * figures, the radius and what filled the rest; with the half-disc, how many
+ * of them `cap_shape: "disc"` would keep. Null for a cap that is not short.
+ */
+export function shortCapLint(j: LimbCount['joints'][number]): string | null {
+  const k = j.cap;
+  if (k.short_px === undefined) return null;
+  const n = k.short_px.left + k.short_px.right;
+  const where =
+    j.from === undefined || j.upperFrom === undefined || j.upperFrom === j.from
+      ? `the layer of "${j.from ?? j.part}" has no pixel of the limb`
+      : `neither the layer of "${j.from}" nor that of "${j.upperFrom}" has a pixel of the limb`;
+  const filled = [
+    ...(k.image_px === undefined ? [] : [`${k.image_px} px from ${k.image_layer === undefined ? 'the cap image' : `the hidden-art layer ${k.image_layer}`}`]),
+    `${k.layer_px} px from "${j.part}"'s layer`,
+    `${k.upper_px ?? 0} px from "${j.upper}"`,
+  ].join(', ');
+  const half = j.half ?? 0;
+  const disc =
+    k.shape === 'disc' || j.shortInHalf === undefined
+      ? ''
+      : j.shortInHalf === 0
+        ? `; under cap_shape "disc" the disc is the half-width about the joint, ${half} px, and none of them lies within it`
+        : `; under cap_shape "disc" the disc is the half-width about the joint, ${half} px, and ${j.shortInHalf} of them lie within it`;
+  return (
+    `  LINT "${j.part}" cap at [${k.at[0]}, ${k.at[1]}] (limb "${j.limb}", joint "${j.joint}", radius ${k.radius} px): short_px left ${k.short_px.left}, right ${k.short_px.right}: ` +
+    `no layer gives them — ${n} px of the disc on the upper side of the cut, where ${where}; the rest of the disc is filled, ${filled}${disc}`
+  );
+}
+
 /**
  * The lines `assemble` prints for the limbs (issue #349), one per part a limb
  * took — `  limb cut: "<of>" opaque <n> = "<part>" <px> + …` — and one per
@@ -2733,7 +2779,8 @@ export function limbLines(counts: readonly LimbCount[]): string[] {
       const k = j.cap;
       const base = k.image_px === undefined ? `${k.layer_px} px from the layer` : `${k.image_px} px from ${k.image_layer === undefined ? 'the cap image' : `the hidden-art layer ${k.image_layer}`}, ${k.layer_px} px from the layer`;
       // Issue #360: what cap_shape "disc" and edge "feather" did, said only when declared, so a limb without them prints what it did.
-      const from = k.shape === undefined ? base : `${base}, ${k.upper_px ?? 0} px from "${j.upper}"`;
+      // Issue #557: the half-disc says it only when the neighbouring segment gave a pixel, so a full cap prints what it printed.
+      const from = k.upper_px === undefined ? base : `${base}, ${k.upper_px} px from "${j.upper}"`;
       const radius =
         k.shape === undefined
           ? `a disc of radius ${k.radius} px (the limb ${k.width} px across the joint line)`
@@ -2749,6 +2796,8 @@ export function limbLines(counts: readonly LimbCount[]): string[] {
       out.push(
         `  limb cap: "${j.limb}" joint "${j.joint}" at [${k.at[0]}, ${k.at[1]}], on "${j.part}": ${radius}, box [${k.box.join(', ')}] — on the upper side of the line ${from}, ${miss}${shaped.map((q) => `; ${q}`).join('')}`,
       );
+      const lint = shortCapLint(j);
+      if (lint !== null) out.push(lint);
     }
   }
   return out;
@@ -3051,6 +3100,11 @@ function cutLimbs(
       let imagePx = 0;
       let upperPx = 0;
       let missing = 0;
+      // Issue #557: the cap's shortfall by side of the limb's axis (left: across >= 0), and how much of it lies within
+      // the half-width about the joint, the disc cap_shape "disc" would keep.
+      let shortLeft = 0;
+      let shortRight = 0;
+      let shortInHalf = 0;
       for (let y = Math.max(0, box[1]); y < Math.min(H, box[1] + box[3]); y++) {
         for (let x = Math.max(0, box[0]); x < Math.min(W, box[0] + box[2]); x++) {
           if (!inDisc(line.at, radius, x, y) || pastJoint(cut, x, y)) continue;
@@ -3062,11 +3116,18 @@ function cutLimbs(
           } else if (ownLower[p] === li && lowerSrc.r.data[p * 4 + 3] > 0) {
             lower.data.set(lowerSrc.r.data.subarray(p * 4, p * 4 + 4), p * 4);
             layerPx++;
-          } else if (disc && upper.data[p * 4 + 3] > 0) {
+          } else if (upper.data[p * 4 + 3] > 0) {
             // Issue #360: the disc is filled from the art — the upper segment's, where the lower's layer has none.
+            // Issue #557: under either shape — the half-disc too takes the neighbouring segment's pixels, so a cap is
+            // short only where no layer of the limb gives a pixel.
             lower.data.set(upper.data.subarray(p * 4, p * 4 + 4), p * 4);
             upperPx++;
-          } else missing++;
+          } else {
+            missing++;
+            if (jointOffsets(line, x, y).across >= 0) shortLeft++;
+            else shortRight++;
+            if (inDisc(line.at, half, x, y)) shortInHalf++;
+          }
         }
       }
       if (img !== null && imagePx === 0 && hidden === null) {
@@ -3111,7 +3172,8 @@ function cutLimbs(
         ...(img === null ? {} : { image_px: imagePx }),
         ...(hidden === null ? {} : { image_layer: hidden.layer }),
         missing_px: missing,
-        ...(disc ? { shape: 'disc' as const, upper_px: upperPx } : {}),
+        ...(missing === 0 ? {} : { short_px: { left: shortLeft, right: shortRight } }),
+        ...(disc ? { shape: 'disc' as const, upper_px: upperPx } : upperPx === 0 ? {} : { upper_px: upperPx }),
         ...(sg.edge === 'feather' ? { edge: 'feather' as const, feather_radius: band, feathered_px: featheredPx } : {}),
         ...(placed === undefined
           ? {}
@@ -3128,7 +3190,7 @@ function cutLimbs(
       if (hidden !== null) readHidden(hidden.layer, `config.limbs.${l}.segments[${k}].cap (part "${sg.part}")`);
       parts[at].record.cap = cap;
       const c = counts.find((q) => q.of === sg.from);
-      if (c !== undefined) c.joints.push({ limb: l, joint: String(sg.joint), part: sg.part, upper: segs[k - 1].part, cap });
+      if (c !== undefined) c.joints.push({ limb: l, joint: String(sg.joint), part: sg.part, upper: segs[k - 1].part, cap, from: sg.from, upperFrom: upFrom, half: pyRound(half, 3), shortInHalf });
     });
   }
   refuseIfAny(problems);

package/src/build.ts

@@ -1504,14 +1504,18 @@ export function limbCheckLines(line: LimbLine): string[] {
  * The seam over the range (issue #360) as the console prints it: the status, what was posed and the bar, then each
  * joint at each angle on a line of its own — its status and the seam figures there — or, not read, why.
  */
-export function sweepCheckLines(line: SweepLine): string[] {
+export function sweepCheckLines(line: SweepLine, steps: ReadonlyMap<string, { left: number; right: number }> = new Map()): string[] {
   const s = line.frame_scale;
   return [
     `${SWEEP_LINE}: ${line.status} — ${line.joints.length} joint(s) bent to their declared range's ends and middle${line.physics_left_out === 0 ? '' : `, ${line.physics_left_out} physics constraint(s) left out`}; at each, the pose against the same pose with the joint's own art drawn under the limb, on the rest-pose seam's bar (mean |d| <= ${line.bar.mean.toFixed(1)}, <= ${line.bar.rig_px_over_40} rig px over ${line.bar.level})${s === null ? '' : ` at frame scale ${s}`}`,
     ...line.joints.flatMap((j) => {
       const head = `joint "${j.joint}" (${j.limb}, "${j.part}" on "${j.bone}", range [${j.range.join(', ')}]${j.shape === 'disc' ? `, cap_shape "disc": no pixel over ${line.bar.level} in the disc` : ''})`;
       if (j.unread !== undefined) return [`${head}: FAIL — not read: ${j.unread}`];
-      return j.poses.map((p) => `${head} at ${p.degrees}°: ${p.status} — mean |d| ${p.mean}/255, ${p.px_over_40} frame px over ${line.bar.level} (${p.px_over_80} over ${SEAM_PX_LEVEL_HIGH}), ${p.rig_px_over_40.toFixed(2)} rig px`);
+      // Issue #557: the contour step, a reading on every row (check.json carries it only for a short cap).
+      return j.poses.map((p) => {
+        const st = p.step_px ?? steps.get(`${j.part} ${p.degrees}`);
+        return `${head} at ${p.degrees}°: ${p.status} — mean |d| ${p.mean}/255, ${p.px_over_40} frame px over ${line.bar.level} (${p.px_over_80} over ${SEAM_PX_LEVEL_HIGH}), ${p.rig_px_over_40.toFixed(2)} rig px${st === undefined ? '' : `; contour step ${st.left} px left, ${st.right} px right (a reading)`}`;
+      });
     }),
   ];
 }
@@ -1610,7 +1614,7 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   const limbs = fig[LIMB_LINE];
   if (limbs !== undefined) for (const [i, l] of limbCheckLines(limbs).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   const sweep = fig[SWEEP_LINE];
-  if (sweep !== undefined) for (const [i, l] of sweepCheckLines(sweep).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
+  if (sweep !== undefined) for (const [i, l] of sweepCheckLines(sweep, r.sweepSteps).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const [i, l] of motionSeamLines(r.motionSeam).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const [i, l] of clothLines(r.cloth).entries()) log(`  ${i === 0 ? '' : '  '}${l}`);
   for (const name of REPORTED_LINES) log(`  ${judgementLine(name, fig[name])}`);

package/src/check.ts

@@ -2141,6 +2141,11 @@ export interface CheckReport {
   motionSeam: MotionSeamLine;
   /** `CLOTH_SETTLES` (issue #501): a warning, never a bar — in `check.json` only when the rig declares a physics constraint and has an idle; its SKIP is printed either way. */
   cloth: ClothLine;
+  /**
+   * Issue #557: the contour step at each pose `SEAM_OVER_RANGE` read, by `<part> <degrees>` ({@link contourStep}) —
+   * printed on every row; `check.json` carries it only for a joint whose cap is short ({@link SweepPose}).
+   */
+  sweepSteps?: Map<string, { left: number; right: number }>;
 }
 
 /**
@@ -2980,6 +2985,10 @@ export interface SweepJoint {
   radius: number;
   /** Issue #360: the cap's record says `shape: "disc"` — the disc is held to no pixel uncovered ({@link sweepLine}). */
   disc?: true;
+  /** Issue #557: the upper segment's bone (the limb record one segment up), whose direction the contour step is read across; null when parts.json has none. */
+  upperBone?: string | null;
+  /** Issue #557: the cap's record carries `short_px` — the step is then written into check.json ({@link SweepPose}). */
+  short?: { left: number; right: number };
 }
 
 /** Every limb record in `parts.json` that declares a `range`, in `parts.json`'s order. */
@@ -2988,7 +2997,20 @@ export function sweepJoints(parts: PartsFile): SweepJoint[] {
   for (const p of parts.parts) {
     const l = p.limb;
     if (l === undefined || l.range === undefined || l.cap === undefined || l.joint === undefined) continue;
-    out.push({ part: p.name, limb: l.name, segment: l.segment, joint: l.joint, bone: l.bone, range: [l.range[0], l.range[1]], at: [l.cap.at[0], l.cap.at[1]], radius: l.cap.radius, ...(l.cap.shape === 'disc' ? { disc: true as const } : {}) });
+    const up = parts.parts.find((q) => q.limb?.name === l.name && q.limb.segment === l.segment - 1)?.limb?.bone ?? null;
+    out.push({
+      part: p.name,
+      limb: l.name,
+      segment: l.segment,
+      joint: l.joint,
+      bone: l.bone,
+      range: [l.range[0], l.range[1]],
+      at: [l.cap.at[0], l.cap.at[1]],
+      radius: l.cap.radius,
+      ...(l.cap.shape === 'disc' ? { disc: true as const } : {}),
+      upperBone: up,
+      ...(l.cap.short_px === undefined ? {} : { short: { left: l.cap.short_px.left, right: l.cap.short_px.right } }),
+    });
   }
   return out;
 }
@@ -3052,6 +3074,90 @@ export function sweepUnread(j: SweepJoint, rig: Record<string, unknown>, limbSlo
   return null;
 }
 
+/** The setup pose's world transform of every bone `rig.json` declares (rigc's `computeExactFrameTransforms`, through `src/coords.ts`). */
+function setupWorld(rig: Record<string, unknown>): Map<string, BoneTransform> {
+  const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord);
+  const posable: Parameters<typeof computeExactFrameTransforms>[0][number][] = bones.map((b) => ({
+    name: String(b.name),
+    ...(typeof b.parent === 'string' && b.parent !== '' ? { parent: b.parent } : {}),
+    ...Object.fromEntries((['x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY'] as const).filter((k) => typeof b[k] === 'number').map((k) => [k, b[k] as number])),
+    ...(typeof b.inherit === 'string' ? { inherit: b.inherit } : {}),
+  }));
+  return computeExactFrameTransforms(posable);
+}
+
+/**
+ * Issue #557: the direction the contour step is read across — the upper
+ * segment's, from its bone's origin to the joint's bone's origin at the setup
+ * pose (the first of the two directions `src/limbs.ts` `jointLine` sums), as a
+ * unit vector in rig px, y down: the Spine world's difference with its y
+ * turned. The upper segment does not move while the joint bends, so lines
+ * across it are the same lines at every pose. Null when either bone is not in
+ * `rig.json` or the two origins coincide.
+ */
+export function sweepAxis(rig: Record<string, unknown>, j: Pick<SweepJoint, 'bone' | 'upperBone'>): [number, number] | null {
+  if (j.upperBone === undefined || j.upperBone === null) return null;
+  const world = setupWorld(rig);
+  const up = world.get(j.upperBone);
+  const me = world.get(j.bone);
+  if (up === undefined || me === undefined) return null;
+  const dx = me.worldX - up.worldX;
+  const dy = up.worldY - me.worldY;
+  const l = edgeLength(dx, dy);
+  return l === 0 ? null : [dx / l, dy / l];
+}
+
+/** Issue #557: how far the contour step's lines run out from the axis, in cap radii — past the limb's edge on either side, which lies at one radius. */
+export const STEP_REACH_RADII = 2;
+
+/**
+ * Issue #557: the contour step at a bent pose — the step the eye sees in the
+ * limb's outline where the cut meets it. On the frame `image` (rigc's render,
+ * over `background`), lines across the limb perpendicular to `axis` (rig px,
+ * unit, y down) at every frame pixel along it from one cap radius before the
+ * joint line to one radius past it; on each, from the axis outward on each
+ * side, the silhouette's extent: the distance, in rig px, of the first sample
+ * whose largest channel lies within {@link SEAM_PX_LEVEL} of the background
+ * (samples one frame pixel apart, out to {@link STEP_REACH_RADII} radii; a
+ * sample is the frame pixel `map` carries the rig point onto, nearest). The
+ * step on a side is the largest change in that extent between two adjacent
+ * lines, to 3 places. `left` is the side the cap's `short_px` calls left
+ * (across the axis at or above 0, `src/limbs.ts` `jointOffsets`), `right` the
+ * other. A straight full limb reads about one frame pixel — the sampling's
+ * own; a notch the bend opens in the outline reads its depth.
+ */
+export function contourStep(image: Raster, background: readonly number[], map: ScaleTranslate, at: readonly [number, number], axis: readonly [number, number], radius: number): { left: number; right: number } {
+  const d = 1 / map.sx;
+  const across: [number, number] = [-axis[1], axis[0]];
+  const solid = (px: number, py: number): boolean => {
+    const fx = Math.round(map.sx * (px - 0.5) + map.tx);
+    const fy = Math.round(map.sy * (py - 0.5) + map.ty);
+    if (fx < 0 || fy < 0 || fx >= image.width || fy >= image.height) return false;
+    const o = (fy * image.width + fx) * 4;
+    return Math.max(Math.abs(image.data[o] - background[0]), Math.abs(image.data[o + 1] - background[1]), Math.abs(image.data[o + 2] - background[2])) > SEAM_PX_LEVEL;
+  };
+  const along = Math.floor(radius * map.sx);
+  const out = Math.ceil(STEP_REACH_RADII * radius * map.sx);
+  const extent = (k: number, side: 1 | -1): number => {
+    const cx = at[0] + k * d * axis[0];
+    const cy = at[1] + k * d * axis[1];
+    let m = 0;
+    while (m <= out && solid(cx + side * m * d * across[0], cy + side * m * d * across[1])) m++;
+    return m * d;
+  };
+  const step = (side: 1 | -1): number => {
+    let best = 0;
+    let prev = extent(-along, side);
+    for (let k = -along + 1; k <= along; k++) {
+      const e = extent(k, side);
+      best = Math.max(best, Math.abs(e - prev));
+      prev = e;
+    }
+    return round3(best);
+  };
+  return { left: step(1), right: step(-1) };
+}
+
 /**
  * The throwaway copy (see {@link SWEEP_LINE}): `rig` with one underlay slot per
  * read joint — a region on the parent of the joint's bone, centred on its box
@@ -3076,13 +3182,7 @@ export function sweepCopy(
   files: ReadonlySet<string> = new Set(),
 ): { rig: Record<string, unknown>; motion: Record<string, unknown>; slots: string[]; images: Array<[string, Raster]> } {
   const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord);
-  const posable: Parameters<typeof computeExactFrameTransforms>[0][number][] = bones.map((b) => ({
-    name: String(b.name),
-    ...(typeof b.parent === 'string' && b.parent !== '' ? { parent: b.parent } : {}),
-    ...Object.fromEntries((['x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY'] as const).filter((k) => typeof b[k] === 'number').map((k) => [k, b[k] as number])),
-    ...(typeof b.inherit === 'string' ? { inherit: b.inherit } : {}),
-  }));
-  const world = computeExactFrameTransforms(posable);
+  const world = setupWorld(rig);
   const slots = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).map((s) => ({ ...s }));
   const skins = isRecord(rig.skins) ? rig.skins : {};
   const skin: Record<string, unknown> = { ...(isRecord(skins.default) ? skins.default : {}) };
@@ -3119,6 +3219,13 @@ export interface SweepPose {
   px_over_40: number;
   px_over_80: number;
   rig_px_over_40: number;
+  /**
+   * Issue #557, written only for a joint whose cap record carries `short_px`:
+   * the contour step at this pose ({@link contourStep}), rig px, per side of
+   * the limb. A reading, never a bar; a full cap's row prints it and writes
+   * what it wrote.
+   */
+  step_px?: { left: number; right: number };
 }
 
 /** One joint's row: its limb record, its disc, how many of the joint's own art pixels the disc holds, and each pose — or, not read, why. */
@@ -3163,6 +3270,8 @@ export function sweepLine(
   frames: (animation: string) => { under: FrameSet; bare: FrameSet },
   physicsLeftOut: number,
   problems: Problem[],
+  step: (j: SweepJoint, bare: FrameSet) => { left: number; right: number } | null = () => null,
+  printed: Map<string, { left: number; right: number }> = new Map(),
 ): SweepLine {
   const seen: { grid: FrameSet | null } = { grid: null };
   const rows: SweepRow[] = joints.map((j, i) => {
@@ -3212,7 +3321,10 @@ export function sweepLine(
             `mean <= ${SEAM_MEAN_BAR.toFixed(1)} and <= ${SEAM_PX_BAR} rig px over ${SEAM_PX_LEVEL} are required, the rest-pose seam's bar — the bend uncovers the joint, and a cap that covers the turn (the limb's art within that radius on the upper side of the joint line, carried by "${j.part}") keeps it covered`,
         });
       }
-      return { degrees: a, status: fail ? 'FAIL' : 'PASS', mean, px_over_40: f.over40, px_over_80: f.over80, rig_px_over_40: Number(seamRigPxText(f.over40, scale)) };
+      // Issue #557: the contour step on the bent frame — a reading, recorded only where the cap is short.
+      const st = step(j, bare);
+      if (st !== null) printed.set(`${j.part} ${a}`, st);
+      return { degrees: a, status: fail ? 'FAIL' : 'PASS', mean, px_over_40: f.over40, px_over_80: f.over80, rig_px_over_40: Number(seamRigPxText(f.over40, scale)), ...(st === null || j.short === undefined ? {} : { step_px: st }) };
     });
     return { ...head, status: poses.some((p) => p.status === 'FAIL') ? 'FAIL' : 'PASS', poses };
   });
@@ -4068,6 +4180,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   // joints' own art under the limbs, physics left out, rendered twice by rigc on one grid — none without a range
   let sweep: SweepLine | null = null;
   const sweepProblems: Problem[] = [];
+  const sweepSteps = new Map<string, { left: number; right: number }>();
   const joints = inp.parts === null ? [] : sweepJoints(inp.parts);
   if (joints.length > 0) {
     const parts = inp.parts as PartsFile;
@@ -4126,7 +4239,13 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
           }
         });
       }
-      sweep = sweepLine(joints, under.map((u) => u.px), unread, (a) => sets.get(a) as { under: FrameSet; bare: FrameSet }, stripped === null ? 0 : stripped.physics.length, sweepProblems);
+      // Issue #557: the contour step, read across the upper segment on each bent frame without the underlays.
+      const axes = joints.map((j) => sweepAxis(base, j));
+      const stepOf = (j: SweepJoint, bare: FrameSet): { left: number; right: number } | null => {
+        const axis = axes[joints.indexOf(j)];
+        return axis === null ? null : contourStep(bare.frames[0].image, bare.background, rigToFrameMap(inp.stage, parts.rig_size[1], bare.viewport), j.at, axis, j.radius);
+      };
+      sweep = sweepLine(joints, under.map((u) => u.px), unread, (a) => sets.get(a) as { under: FrameSet; bare: FrameSet }, stripped === null ? 0 : stripped.physics.length, sweepProblems, stepOf, sweepSteps);
     } finally {
       rmSync(sweepDir, { recursive: true, force: true });
     }
@@ -4450,6 +4569,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     besideIdle: named,
     motionSeam,
     cloth,
+    ...(sweepSteps.size === 0 ? {} : { sweepSteps }),
   };
 }
 

package/src/clothconfig.ts

@@ -39,6 +39,8 @@ function canon(v: unknown): string {
 /** One edit `--write-config` makes, with the words the write line prints for it. */
 export interface ClothEdit extends ConfigEdit {
   label: string;
+  /** Issue #571: the input's entry was the previous recipe's draft (`--from`), and only that made it the recipe's. */
+  previous?: true;
 }
 
 /**
@@ -95,31 +97,44 @@ function shown(v: unknown): string {
  * - removed (P present, D absent — the recipe replaced a plain chain with its trees): `I` equal to `P` is removed;
  * - every other input entry is kept, bytes and order;
  * - an owned or removed `I` that is none of those — changed by hand — is a conflict, as is a name the input states twice.
+ *
+ * With `V`, the previous recipe's draft (`previous`, issue #571 — `--from`; null without it): `I` equal to `V` is the
+ * recipe's as `I` equal to `P` is — an owned name is replaced, and a name in `V` and not in `D` is removed — and a
+ * conflict is an `I` equal to none of `D`, `P` and `V`, its first differing field read against `V` where `V` holds the
+ * name. Without `previous` every rule, and every word of the refusal, is the one above.
  */
-function entryEdits(path: readonly string[], identity: (e: unknown) => string | null, drafted: readonly unknown[], plain: readonly unknown[], input: readonly unknown[], conflicts: Problem[]): ClothEdit[] {
+function entryEdits(path: readonly string[], identity: (e: unknown) => string | null, drafted: readonly unknown[], plain: readonly unknown[], input: readonly unknown[], conflicts: Problem[], previous: readonly unknown[] | null): ClothEdit[] {
   const section = path.join('.');
   const D = byName(drafted, identity, 'drafted', section);
   const P = byName(plain, identity, 'plain', section);
+  const V = previous === null ? null : byName(previous, identity, 'previous', section);
   const keys = input.map(identity);
   const where = new Map<string, number[]>();
   keys.forEach((k, i) => {
     if (k !== null) where.set(k, [...(where.get(k) ?? []), i]);
   });
   const owned = [...D.keys()].filter((k) => !P.has(k) || canon(P.get(k)) !== canon(D.get(k)));
-  const removed = [...P.keys()].filter((k) => !D.has(k));
+  const removed = [...P.keys(), ...(V === null ? [] : [...V.keys()].filter((k) => !P.has(k)))].filter((k) => !D.has(k));
   const replace: string[] = [];
   const remove: string[] = [];
+  const vouched = new Set<string>();
   const conflict = (k: string, i: number, drafts: boolean): void => {
     const author = input[i];
-    const field = firstField(author, P.has(k) ? P.get(k) : D.get(k));
+    const prev = V !== null && V.has(k) ? V.get(k) : undefined;
+    const field = firstField(author, prev !== undefined ? prev : P.has(k) ? P.get(k) : D.get(k));
     const fieldOf = (e: unknown, f: string): string => (isPlain(e) && e[f] !== undefined ? `${f} ${shown(e[f])}` : `no ${f}`);
     const held = field === null ? `the entry ${shown(author)}` : fieldOf(author, field);
     const draft = D.get(k);
     const draftSays = !drafts ? 'the draft removes the entry (the recipe drafts that part afresh)' : field === null ? `the draft writes ${shown(draft)}` : `the draft writes ${fieldOf(draft, field)}`;
+    // Issue #571: with --from, the entry equals none of the three drafts; the field is read against the previous recipe's, the draft a person edited from.
+    const says =
+      V === null
+        ? `it holds ${held} where ${draftSays}`
+        : `it equals neither the draft, the draft without the recipe, nor the previous recipe's draft: it holds ${held} where ${prev === undefined ? 'the previous recipe\'s draft has no such entry' : `the previous recipe's draft writes ${field === null ? shown(prev) : fieldOf(prev, field)}`} and ${draftSays}`;
     conflicts.push({
       code: 'PROPOSE_WRITE_CONFIG_CONFLICT',
       object: `config.${section}[${i}] "${k}"`,
-      detail: `${section} entry "${k}" is the recipe's, and it was changed by hand: it holds ${held} where ${draftSays}, so the write would drop the hand edit; take the draft by removing the hand edit (or the entry), or leave the recipe out for that part (its config.cloth block)`,
+      detail: `${section} entry "${k}" is the recipe's, and it was changed by hand: ${says}, so the write would drop the hand edit; take the draft by removing the hand edit (or the entry), or leave the recipe out for that part (its config.cloth block)`,
     });
   };
   for (const k of [...owned, ...removed]) {
@@ -134,19 +149,27 @@ function entryEdits(path: readonly string[], identity: (e: unknown) => string |
     }
     if (at.length === 0) continue;
     const I = canon(input[at[0]]);
+    const isPrevious = V !== null && V.has(k) && I === canon(V.get(k));
     if (D.has(k)) {
       if (I === canon(D.get(k))) continue;
       if (P.has(k) && I === canon(P.get(k))) replace.push(k);
-      else conflict(k, at[0], true);
-    } else if (I === canon(P.get(k))) remove.push(k);
-    else conflict(k, at[0], false);
+      else if (isPrevious) {
+        replace.push(k);
+        vouched.add(k);
+      } else conflict(k, at[0], true);
+    } else if (P.has(k) && I === canon(P.get(k))) remove.push(k);
+    else if (isPrevious) {
+      remove.push(k);
+      vouched.add(k);
+    } else conflict(k, at[0], false);
   }
+  const mark = (k: string): { previous?: true } => (vouched.has(k) ? { previous: true } : {});
   const edits: ClothEdit[] = [];
   const work = [...keys];
-  for (const k of replace) edits.push({ path: [...path, work.indexOf(k)], value: D.get(k), label: `${section}["${k}"] replaced` });
+  for (const k of replace) edits.push({ path: [...path, work.indexOf(k)], value: D.get(k), label: `${section}["${k}"] replaced`, ...mark(k) });
   for (const k of remove) {
     const i = work.indexOf(k);
-    edits.push({ path: [...path, i], value: undefined, label: `${section}["${k}"] removed` });
+    edits.push({ path: [...path, i], value: undefined, label: `${section}["${k}"] removed`, ...mark(k) });
     work.splice(i, 1);
   }
   const order = [...D.keys()];
@@ -174,27 +197,53 @@ function entryEdits(path: readonly string[], identity: (e: unknown) => string |
  * the input holds it as an array, and any other section, or one the input lacks, whole. Every conflict is collected and
  * refused in one throw, `PROPOSE_WRITE_CONFIG_CONFLICT`, before anything is written.
  *
+ * `previous` (issue #571, `propose --write-config --from <config>`) is the same parts drafted a third time, with the
+ * recipe of the config the recipe is changed from: an array entry equal to its draft is the recipe's ({@link entryEdits}),
+ * and an array section the two drafts agree at is read entry by entry where the previous draft differs from them. An
+ * object entry (`meshes.<part>`, `regions.<part>`) the recipe drafts is replaced whole already, so `previous` changes
+ * nothing there. Null — no `--from` — is the writer before #571, rule for rule and byte for byte.
+ *
  * `whole` is the selftest's mutant only (issue #552): `bones`, `constraints` and `motion.tracks` replaced whole, as
  * the #537 writer did; no flag or environment reaches it.
  */
-export function clothConfigEdits(drafted: Proposal, plain: Proposal, input: unknown, whole = false): ClothEdit[] {
+export function clothConfigEdits(drafted: Proposal, plain: Proposal, input: unknown, whole = false, previous: Proposal | null = null): ClothEdit[] {
   const edits: ClothEdit[] = [];
   const conflicts: Problem[] = [];
   const d = JSON.parse(JSON.stringify(drafted)) as Record<string, unknown>;
   const p = JSON.parse(JSON.stringify(plain)) as Record<string, unknown>;
+  const v = previous === null || whole ? null : (JSON.parse(JSON.stringify(previous)) as Record<string, unknown>);
+  const arrayOf = (path: readonly string[]): (typeof ARRAY_SECTIONS)[number] | undefined => (whole ? undefined : ARRAY_SECTIONS.find((x) => x.path.join('.') === path.join('.')));
+  const prevAt = (path: readonly string[]): unknown[] | null => {
+    if (v === null) return null;
+    const c = valueAt(v, path);
+    return Array.isArray(c) ? c : [];
+  };
   const one = (path: readonly string[], a: unknown, b: unknown): void => {
-    const s = whole ? undefined : ARRAY_SECTIONS.find((x) => x.path.join('.') === path.join('.'));
+    const s = arrayOf(path);
     const mine = valueAt(input, path);
-    if (s !== undefined && Array.isArray(b) && (a === undefined || Array.isArray(a)) && Array.isArray(mine)) edits.push(...entryEdits(path, s.identity, b, Array.isArray(a) ? a : [], mine, conflicts));
+    if (s !== undefined && Array.isArray(b) && (a === undefined || Array.isArray(a)) && Array.isArray(mine)) edits.push(...entryEdits(path, s.identity, b, Array.isArray(a) ? a : [], mine, conflicts, prevAt(path)));
     else edits.push({ path, value: b, label: path.join('.') });
   };
+  // Issue #571: an array section the two drafts agree at, where the previous draft differs — its entries the previous recipe drafted and this one does not.
+  const prevOnly = (path: readonly string[], b: unknown): void => {
+    const s = arrayOf(path);
+    const mine = valueAt(input, path);
+    const c = valueAt(v, path);
+    if (v === null || s === undefined || !Array.isArray(b) || !Array.isArray(mine) || canon(c) === canon(b)) return;
+    edits.push(...entryEdits(path, s.identity, b, b, mine, conflicts, prevAt(path)));
+  };
   for (const section of PROPOSAL_CONFIG_SECTIONS) {
     const a = p[section];
     const b = d[section];
-    if (JSON.stringify(a) === JSON.stringify(b)) continue;
+    if (JSON.stringify(a) === JSON.stringify(b)) {
+      if (isPlain(b)) for (const k of Object.keys(b)) prevOnly([section, k], b[k]);
+      else prevOnly([section], b);
+      continue;
+    }
     if (isPlain(a) && isPlain(b)) {
       for (const k of [...Object.keys(b), ...Object.keys(a).filter((k) => !(k in b))]) {
         if (JSON.stringify(a[k]) !== JSON.stringify(b[k])) one([section, k], a[k], b[k]);
+        else prevOnly([section, k], b[k]);
       }
     } else one([section], a, b);
   }
@@ -221,6 +270,11 @@ export function writtenClothConfig(where: string, text: string, edits: readonly
   return r.text;
 }
 
+/** Issue #571: how many edits the previous recipe's draft vouched for — an entry that equalled it, and only it. */
+export function previousCount(edits: readonly ClothEdit[]): number {
+  return edits.filter((e) => e.previous === true).length;
+}
+
 /** What each edit names, in order: what the write line prints. */
 export function editPaths(edits: readonly ClothEdit[]): string[] {
   return edits.map((e) => e.label);

package/src/parts.ts

@@ -152,11 +152,21 @@ 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 #557, written only when `missing_px` is above 0: the missing pixels
+   * — the disc's on the upper side of the cut that no layer of the limb gives
+   * — by side of the limb's axis at the joint line, `left` where a pixel
+   * centre's offset across the axis (`jointOffsets` in `src/limbs.ts`) is 0 or
+   * above (the side toward smaller x when the limb hangs down the rig) and
+   * `right` the other; the two add up to `missing_px`. A full cap writes no key.
+   */
+  short_px?: { left: number; right: 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`.
+   * joint, at most half of `width`. Issue #557: without the shape the half-disc
+   * takes them too, and `upper_px` is written there only when above 0.
    */
   shape?: 'disc';
   upper_px?: number;
@@ -197,6 +207,7 @@ const CAP_KEYS = [
   'image_px',
   'image_layer',
   'missing_px',
+  'short_px',
   'shape',
   'upper_px',
   'edge',
@@ -609,7 +620,9 @@ function checkParts(raw: unknown, path: string): PartsFile {
           (!('image_px' in co) || isCount(co.image_px)) &&
           (!('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)) &&
+          ('shape' in co ? co.shape === 'disc' && isCount(co.upper_px) : !('upper_px' in co) || (isCount(co.upper_px) && co.upper_px > 0)) &&
+          // Issue #557: the shortfall by side, when written, adds up to the missing pixels, and is never written for none.
+          (!('short_px' in co) || shortSides(co.short_px, co.missing_px)) &&
           ('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)) &&
           // Issue #360 (item 14): a placed cut carries its band, line and counts, the line inside the band; none of them rides alone.
           ('cut_band' in co
@@ -628,7 +641,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
           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), cut_band? (with cut_offset inside the band, cut_at, cut_crossed at most joint_crossed, band_px, stroke_luma_max? 0..255)} is required`,
+            `is ${show(c)}; {at: [x, y], width, radius, box: [x, y, w, h], layer_px, image_px?, image_layer? (with image_px), missing_px, short_px? ({left, right}, adding up to missing_px, above 0), shape? ("disc", with upper_px; without it upper_px? above 0), edge? ("feather", with feather_radius and feathered_px), cut_band? (with cut_offset inside the band, cut_at, cut_crossed at most joint_crossed, band_px, stroke_luma_max? 0..255)} is required`,
           );
         }
       }
@@ -659,6 +672,12 @@ function checkParts(raw: unknown, path: string): PartsFile {
 }
 
 const isCount = (v: unknown): v is number => Number.isInteger(v) && (v as number) >= 0;
+/** Issue #557: a cap's `short_px` — `{left, right}`, two counts and no other key, adding up to `missing`, above 0. */
+function shortSides(v: unknown, missing: unknown): boolean {
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) return false;
+  const o = v as Record<string, unknown>;
+  return Object.keys(o).sort().join(',') === 'left,right' && isCount(o.left) && isCount(o.right) && o.left + o.right === missing && o.left + o.right > 0;
+}
 
 /**
  * The `single_run_pad` block (issue #366): every key known and present, each