@rig-c/parts 1.24.0 → 1.25.0

package/cli.ts

@@ -27,7 +27,7 @@ import { makeInputs } from './src/inputs.ts';
 import { idleKeysOf, isIdleKeys } from './src/rig.ts';
 import { depthSkipLine, exportLayers, figuresPhrase, hiddenLayerLine, implausibleRules, layerFigures, type LayerSet, layerSetDiff, pct, readLayers, readWrapperLayers, ruleSummary, templateLayerNames, templatePsdBytes, times } from './src/layers.ts';
 import { checkImageSize, choosePerson, KEYPOINTS_SPEC, loadKeypoints, type RigJoints, toRigJoints } from './src/keypoints.ts';
-import { basisLines, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, HIP_MIN_FRACTION, lint, lintLine, type PartSet, proposeWithBasis, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
+import { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, HIP_MIN_FRACTION, 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, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
 import { checkPainting } from './src/paintcheck.ts';
@@ -1064,6 +1064,7 @@ function printLint(P: PartSet, spec: { bones: CharacterConfig['bones']; meshes:
   for (const m of res.unknownMeshes) console.log(`note: mesh ${JSON.stringify(m)} names no part in parts.json, so it was not linted`);
   for (const w of res.lockUnread) console.log(`note: off-lock not read: ${w}`);
   for (const w of res.squeezeUnread) console.log(`note: squeeze not read: ${w}`);
+  for (const b of res.branchSqueezes) console.log(branchSqueezeLine(b));
   for (const b of res.missingTorsoBones) {
     console.log(
       res.basis?.torso.read === true

package/docs/AUTHORING.md

@@ -121,6 +121,7 @@ read by no CPU stage).
 | `motion.blink.still` | rig | **proposed** only for a lash `propose` notes (below), then checked: `{<part>: {row, bone}}` — the rows of that region part above `row` (rig px, y down) are drawn by a second slot `<part>_still` on `bone` and do not blink; rows from `row` down keep the part's slot and blink. The part must be a region on a bone `eyes` names, `bone` one it does not (`CONFIG_STILL_OFF_THE_BLINK`), and `row` a row of the part with no art across its whole width (`RIG_STILL_ROW_CLEAR`) |
 | `motion.animations_from` | rig; check (named; read for folds) | optional, never proposed (issue #183): a path, relative to the config file's directory, to a file in rig-c's motion-spec shape, `{"spec": "rigc-motion/1", "animations": {"<name>": {"duration": …, "tracks": [...]}, …}}` — an expression, a gesture, anything beside the idle. On every `rig` and `build` each of its animations is written into `rig/motion.json` after `idle`, as read: nothing added, re-keyed or judged here, and each is rigc's to accept or refuse at the rig stage's gate, in rigc's words. It may name what `motion.json` already holds — the bones `bones` declares, the easings `shut` and `open`, the groups `eyes` and `brows` when the blink writes them — and nothing else from the file reaches it. The loader refuses, every problem at once: no such file or one that cannot be read (`CONFIG_FILE_PRESENT`), text that is not JSON (`CONFIG_IS_JSON`), a file that is not an object, a `spec` other than `"rigc-motion/1"`, an `animations` that is not a table of objects (`CONFIG_FIELD_TYPE`), any other key — rig-c's `easings`, `groups`, `setup`, `physics`, `mix`, `archetype` and `cut` included, which would be read and not written (`CONFIG_KEY_KNOWN`), an animation named `idle` (`CONFIG_ANIMATION_NAME_FREE`), and a key written twice in one object of the file, which JSON would fold into its last value without a word (`CONFIG_KEY_UNIQUE`). `check` names the others on one line (`beside the idle: …`) and reads each for folds, with the idle — `ANIMATIONS_DO_NOT_FOLD` (§7, issues #320, #333); every other bar reads the idle. Absent, `motion.json` holds the idle alone, byte for byte as before, and `check` reads that idle for folds |
 | `constraints` | rig (handed to rig-c as `rig.json`'s `constraints`); `compare` and the coverage lines (roles) | **authored**, optional; `propose` writes none, but with `--cloth` (issue #364), where it writes the recipe's physics and swing transforms (*Recipe: cloth and hair that answer the world*, below). A list of constraints in **rig-c's own rig-spec shape** (`RigConstraint`: `ik`, `transform`, `path`, `physics`, `slider` — rig-c's `src/rig.ts` documents every field), in the order rigc applies them. The loader checks only what this package owns: each entry is an object with a `type` rigc names (`CONFIG_CONSTRAINT_TYPE_KNOWN`) and a non-empty `name`, unique within its kind as rigc finds constraints (`CONFIG_CONSTRAINT_NAME_UNIQUE`; an ik and a transform may share one); every bone it names — `bones`, an ik's `target`, a transform's `source`, a physics or slider constraint's `bone` — is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`); the bone a constraint follows does not sit under a bone it drives (`CONFIG_CONSTRAINT_TARGET_DETACHED`). Every other field (`mix`, `softness`, `properties`, a path's `slot`, a slider's `animation`) and every value is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`) — an ik's `bones` as a shape too: from rig-c 2.15.0 rigc refuses an ik over more than two bones, or over a pair whose second bone is not the first's child (issue #103; this loader refused both itself until then). A note and an `x-` record may ride on an entry; the rig stage leaves them out of what it hands rigc. Under the default `--idle-keys ctl` a two-bone ik whose child link the idle keys is split by that link's control, and rigc refuses the pair: run `rig --idle-keys direct` or `build --idle-keys direct` (the rig stage adds that sentence, naming the flag on the command that ran, to rigc's line; `build` forwards it to its rig stage, issue #95). Each bone a constraint follows is declared to rigc as `invariants.detached` from every bone it drives, which rigc's gate rule `A25` checks |
+| `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`) | **authored**, optional (issue #404): `[{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`); `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 — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). 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}`. `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. With no `face` part, or more than one, the riders keep their own and a note says so. 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. 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 field has a default (`CONFIG_FIELD_PRESENT`); the 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?}`. `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 name: the `topwear` part that holds a skirt See-through returned inside it (a dress), which takes the skirt's trees as well (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 |
@@ -1583,13 +1584,13 @@ What each rule drafts (`src/cloth.ts` holds them):
 | rule | drafts | from |
 | --- | --- | --- |
 | where | `bottomwear`: from `hip`, the root row 20 px below hip's y (the keyed chains' row), the tip row 4 px above the part's bottom. `back hair` that reaches below the shoulders: from `head`, per side of the eye axis (twin tails are a side each), the eye line to 4 px above its bottom. `front hair`: each strand that hangs below the chin (the lock rule's), from `head`, 0.22 face heights above the eye line to 5 px below the strand; the fringe's three columns keep their two links and their places | the keyed chains' own rows, which these replace |
-| trees | tree k of `chains` owns the cell k/N .. (k+1)/N of the art's width in every row, and its links sit at the cell's centre in the 24-row band there, so a piece that widens fans its trees. With `split`, the trunk's tip is the fork, and branch b of `into` follows the centre of its share of the cell. Chains are named `<prefix><k>_` (trunk) and `<prefix><k><a, b, …>_` (branches): `skirt`, `hairback_r`/`hairback_l`, `lockt` | `chains`, `links`, `split` |
+| trees | tree k of `chains` owns the cell k/N .. (k+1)/N of the art's width in every row, and its links sit at the cell's centre in the 24-row band there, so a piece that widens fans its trees. With `split`, the trunk's tip is the fork, and branch b of `into` follows the centre of its share of the cell. Chains are named `<prefix><k>_` (trunk) and `<prefix><k><a, b, …>_` (branches): `skirt`, `hairback_r`/`hairback_l`, `lockt`. With `split.hold_tip: true` (issue #403), sibling branches keep `strength.branch` across the fork and the mesh's `r` is raised to `grid`, holding the triangles where two branches' cells meet | `chains`, `links`, `split` |
 | lengths | link j's length is the first's times q^j, q = `length_ratio`^(1/(links − 1)), the whole spanning root row to tip row: the links shorten toward the tip | `length_ratio` (default 0.5, below) |
-| stiffness | a trunk link takes `strength.trunk`, a branch link `strength.branch`, and the edge — the outermost branch on each outer side of the piece (both sides of a skirt or a strand; the outer side of each back-hair side), or without `split` the outermost tree — `strength.edge`; a fringe column is a trunk, its outer two the edge. **Strength does not fall along a chain**: a tip reads soft because each link turns on top of every link above it, so the motion accumulates down the chain at one strength. Only the edge is declared softer | `strength` (default trunk 100, branch 100, edge 50, below) |
+| stiffness | a trunk link takes `strength.trunk`, a branch link `strength.branch`, and the edge — the outermost branch on each outer side of the piece (both sides of a skirt or a strand; the outer side of each back-hair side; or, under `split.hold_tip: true`, kept at `strength.branch` so a fork's sibling branches do not pull apart at 2:1 stiffness), or without `split` the outermost tree — `strength.edge`; a fringe column is a trunk, its outer two the edge. **Strength does not fall along a chain**: a tip reads soft because each link turns on top of every link above it, so the motion accumulates down the chain at one strength. Only the edge is declared softer | `strength` (default trunk 100, branch 100, edge 50, below) |
 | response | link j of an n-link path takes `wind` and `gravity` at j/(n − 1) of the way from the root value to the tip value; a single-link path takes the tip value. Each is a scalar **multiplier** of the environment the consumer sets (spine-core's skeleton `windX, windY`, `gravityX, gravityY`; rig-c 2.52.0's live track `setEnvironment`, rig-play 1.10.0's `environment()`): no direction is drafted | `wind`, `gravity` |
 | out of phase | the odd trees take `alternate_damping`, the even ones `damping` | `damping`, `alternate_damping` |
 | flutter | the last link of every path gets a second physics constraint, `<bone>_translate`, moving x and y by `translate`, with the link's stiffness and damping and **no** wind or gravity response. spine-core scales a translate spring's response by the skeleton's reference scale (100) and a rotation's by the link's length over it, so one response on both pushes an end about 100/length times further than it turns it (the table below) | `translate` |
-| part | `bottomwear` only (issue #402): the named `topwear` part takes the skirt's rule as the `bottomwear` parts do — trees from `hip` over its art below the hip, its waist line, and, as its art reaches above the chest, the chest segment the long-robe `bottomwear` keeps — in place of the two robe chains the topwear rule drafts; the prefix is `skirt` when it is the only skirt, `skirt_<part>` beside another | `part` |
+| part | `bottomwear` only (issue #402): the named `topwear` part takes the skirt's rule as the `bottomwear` parts do — trees from `hip` over its art below the hip, its waist line, and, as its art reaches above the chest, the chest segment the long-robe `bottomwear` keeps — in place of the two robe chains the topwear rule drafts; the prefix is `skirt` when it is the only skirt, `skirt_<part>` beside another. A `bottomwear` part lying on the named part's tree links rides them and drafts no trees of its own (issue #416, *What rides a dress* below) | `part` |
 | swing | `bottomwear` only: a bone `<prefix>_swing` under `hip` at the centre of the root row, one link long, straight down, with physics (the trunk's stiffness, the root's response); each tree's first link takes the swing's rotation times its scale — a transform `<swing>_<k>`, local source and target, additive, the swing's setup rotation in hip's frame (−90: hip is drafted unturned) subtracted — and no physics of its own | `swing.scales` |
 
 Every link but a swing-driven first link gets `<bone>_physics` (`rotate` 1), and no
@@ -1623,6 +1624,26 @@ Since issue #411 the bar reads the breath alone, and on that fixture the breath
 the dress 0.106 and the robe-chained dress 2.62: both fail, and the 3.9 was the robe
 chains' keyed swing below the hip, not the breath (the CK502 and CK503 controls).
 
+**What rides a dress** (issue #416). With `part` declared, a `bottomwear` part lying on
+the dress — a ruffle hem See-through returned as a layer of its own — rides the dress's
+tree links by the rule a part wrapped round a tail does (*What rides a tail*, below): each
+of its pixels over the dress's art is given to the span of the dress's mesh nearest it
+(a fixed segment, chest or the waist line, or one tree link), and the part rides when one
+of those spans is a link. Its mesh's segments are then the spans it lies on, it drafts
+no trees of its own, and a note names each span with its pixel count; a `bottomwear` part
+over no link keeps its own trees. Before, the hem took the skirt's recipe by its tag as
+well, so one skirt carried two sets of trees, each on its own physics. Measured once on
+the selftest's dress fixture with a 112x26 hem across its last tier (`fixtures/cloth.ts`,
+`HEM`; the hip from joints at y 164; rig-c 2.54.0, `check`'s idle, physics on), before
+this rule and with it: the trees drafted went from four (`skirt_hem0_`, `skirt_hem1_`,
+`skirt_dress0_`, `skirt_dress1_`) to two (`skirt0_`, `skirt1_`), and their physics
+constraints from 8 to 4; `TEXTURE_STRETCH` read 1.275 both ways (its worst mesh is the
+back hair), the hem's own mesh 1.034 with its own trees and 1.045 riding, and the largest
+opening of the hem's seam with the dress 0.502 and 0.432 px (CK510 holds the one set and
+the pass). The hip rule still reads a `bottomwear` part's top edge as the waist, so a
+hem and no hip joints put the hip at the hem: on the same fixture without joints, y 277,
+and the dress's trees run up from y 297 to 286. Without `part` nothing here runs.
+
 **What rides a tail** (issue #391). An accessory wrapped round a tail the `back hair`
 recipe drafts — a ribbon, in See-through's `headwear` or `earwear` layer — rides that
 tail's links, not `head`: under the recipe the tail moves by the world, and a part left on

package/docs/STABILITY.md

@@ -112,7 +112,7 @@ The fields, object by object (a bold path is where the object sits; `<part>` is
 part name, `[i]` an entry of a list):
 
 <!-- stable:config -->
-- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `turn`, `scene`, `cloth`
+- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`
 - **generation** — required: `checkpoint`, `loras`, `trigger`, `identity`, `sampler`, `costume`, `negative_extra`, `style`, `negative_pose`, `latent`, `seed`; optional: `pose`, `control`
 - **generation.loras[i]** — required: `name`, `strength`; optional: `strength_clip`
 - **generation.sampler** — required: `steps`, `cfg`, `sampler`, `scheduler`
@@ -129,6 +129,8 @@ part name, `[i]` an entry of a list):
 - **limbs.&lt;limb&gt;.segments[i]** — required: `part`, `from`, `bone`; required below a joint (i > 0): `joint`; optional below a joint: `range`, `cap`, `edge`, `cap_shape`, `cut_band`
 - **bones[i]**, a single bone — required: `name`, `parent`, `at`; optional: `tip`, `inherit`
 - **bones[i]**, a chain — required: `chain`, `parent`, `points`, `tip`
+- **stops[i]** — required: `chain`, `against`, `at`, `inward`, `outward`; optional: `links`, `lower` (issue #404)
+- **stops[i].lower** — required: `inward`, `outward`
 - **meshes.&lt;part&gt;** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`; optional in every mode: `exponent`, `rule`; optional with `contour` or `auto`: `ribs`; optional with `grid` or `contour`: `influences` (issue #284; beside `auto` it is refused, CONFIG_INFLUENCES_MODE); optional with `grid`: `stray` (issue #303; beside `contour` or `auto` it is refused, CONFIG_STRAY_MODE)
 - **meshes.&lt;part&gt;.influences** — optional, at least one: `maxInfluences` (a whole number, 1 or more, or null for no cap), `floor` ("cut" or "continuous")
 - **meshes.&lt;part&gt;.ribs.&lt;chain&gt;** — required: `stations`
@@ -148,7 +150,7 @@ part name, `[i]` an entry of a list):
 - **meshes.&lt;part&gt;.auto.boundaryRuns** — required: `maxVertices`
 - **meshes.&lt;part&gt;.auto.stimulus**, or each entry of it when a list — required: `chain`, `degrees`
 - **cloth.&lt;tag&gt;**, the tag bottomwear, back hair or front hair (issue #364; read by propose --cloth only) — required: `chains`, `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only), `part` (on bottomwear only)
-- **cloth.&lt;tag&gt;.split** — required: `at`, `into`
+- **cloth.&lt;tag&gt;.split** — required: `at`, `into`; optional: `hold_tip`
 - **cloth.&lt;tag&gt;.strength** — required: `trunk`, `branch`, `edge`
 - **cloth.&lt;tag&gt;.swing** — required: `scales`
 - **regions.&lt;part&gt;** — a bone name
@@ -161,7 +163,7 @@ part name, `[i]` an entry of a list):
 - **turn** — required: `pivot`, `depths`
 - **turn.depths.&lt;part&gt;** — a See-through depth
 - **scene** — no field (`{}`; a record or an annotation only)
-- **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `limbs` under `--keypoints` where an arm or a leg is drafted from its joints (issue #349), `motion` under the rules above, `turn` with `--full`/`--head`, and `notes`
+- **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `limbs` under `--keypoints` where an arm or a leg is drafted from its joints (issue #349), `stops` when supplied, `motion` under the rules above, `turn` with `--full`/`--head`, and `notes`
 <!-- /stable:config -->
 
 `TY14` holds the set of field names in backticks above to the set of names the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.24.0",
+  "version": "1.25.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": {
@@ -61,7 +61,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "rig-c": "^2.54.0"
+    "rig-c": "^2.57.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/src/assemble.ts

@@ -104,7 +104,7 @@ import { type Problem, refuseIfAny } from './errors.ts';
 import { figuresPhrase, implausibleRules, type Layer, type LayerFigures, layerFigures, type LayerSet, NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE, ruleSummary } from './layers.ts';
 import { padToSquare, squarePad } from './inputs.ts';
 import { type CapRecord, type LimbRecord, PAINTING_RUN, type PartRecord, type PartsFile, type RecompositeRecord, type SceneRecord, type SingleRunPad } from './parts.ts';
-import { type BonePlace, bonePlaces, capBox, coveredRadius, type CutPlacement, featherWeight, halfWidthAbout, inDisc, jointLine, type JointLine, jointOffsets, limbPolyline, limbRun, luma601, nearestLimb, pastJoint, placeCut, segmentOf } from './limbs.ts';
+import { assignOverlappingHands, type BonePlace, bonePlaces, capBox, coveredRadius, type CutPlacement, featherWeight, halfWidthAbout, inDisc, jointLine, type JointLine, jointOffsets, limbPolyline, limbRun, luma601, nearestLimb, pastJoint, placeCut, segmentOf } from './limbs.ts';
 import {
   alphaComposite,
   connectedComponents,
@@ -2054,16 +2054,35 @@ function cutLimbs(
         placements.set(`${l}/${k}`, placed);
       });
     }
+    const segOverride = new Int32Array(W * H).fill(-1);
+    const segAt = (l: string, x: number, y: number): number => {
+      const segs = limbs[l].segments;
+      const first = segs.findIndex((sg) => sg.from === src);
+      let last = first;
+      while (last + 1 < segs.length && segs[last + 1].from === src) last++;
+      return segmentOf(cutLines.get(l) as Array<JointLine | null>, first, last, x, y);
+    };
+    // Issue #400: when two forearm segments share `src` and their hand regions overlap, the overlap goes to the front
+    // piece (the limb later in config.limbs) in one piece, and the back piece ends at its cuff.
+    const forearms = on.flatMap((l) => {
+      const li = names.indexOf(l);
+      return limbs[l].segments.flatMap((sg, k) => {
+        if (k === 0 || sg.joint !== 'elbow' || sg.from !== src) return [];
+        const me = places.get(sg.bone) as BonePlace;
+        return me.end === null ? [] : [{ limb: li, seg: k, elbow: me.at, wrist: me.end, isSeg: (x: number, y: number): boolean => segAt(l, x, y) === k }];
+      });
+    });
+    for (let i = 0; i < forearms.length; i++) {
+      for (let j = i + 1; j < forearms.length; j++) {
+        assignOverlappingHands(forearms[i], forearms[j], W, H, own, segOverride);
+      }
+    }
     for (let y = 0; y < H; y++) {
       for (let x = 0; x < W; x++) {
         const p = y * W + x;
         if (b.r.data[p * 4 + 3] === 0) continue;
         const l = names[own[p]];
-        const segs = limbs[l].segments;
-        const first = segs.findIndex((sg) => sg.from === src);
-        let last = first;
-        while (last + 1 < segs.length && segs[last + 1].from === src) last++;
-        const k = segmentOf(cutLines.get(l) as Array<JointLine | null>, first, last, x, y);
+        const k = segOverride[p] >= 0 ? segOverride[p] : segAt(l, x, y);
         const at = parts.findIndex((q) => q.limb === l && q.segment === k);
         rasters[at].data.set(b.r.data.subarray(p * 4, p * 4 + 4), p * 4);
         if (b.region === null || b.region.data[p] === 1) regions[at].data[p] = 1;

package/src/automesh.ts

@@ -212,6 +212,7 @@ export function sourceWeights(
   spec: AutoSpec,
   exponent: number = DISTANCE_EXPONENT,
   heat: HeatField | null = null,
+  segsAt: (wy: number) => readonly Segment[] = () => segs,
 ): { weights: Influence[][]; local: LocalInfluence[] } | { overlap: RegionOverlap; vertex: number; at: Point } {
   const all = spec.regions ?? [];
   const index: number[] = [];
@@ -225,7 +226,7 @@ export function sourceWeights(
   const local: LocalInfluence[] = [];
   for (let v = 0; v < vertices.length; v++) {
     const at: Point = [vertices[v][0] + ox, vertices[v][1] + oy];
-    const li = localInfluences(at, segs, r, regions, spec.influences, exponent, heat === null ? undefined : heatInfluences(heat, [vertices[v][0], vertices[v][1]], spec.influences));
+    const li = localInfluences(at, segsAt(at[1]), r, regions, spec.influences, exponent, heat === null ? undefined : heatInfluences(heat, [vertices[v][0], vertices[v][1]], spec.influences));
     if ('first' in li) return { overlap: { ...li, first: index[li.first], second: index[li.second] }, vertex: v, at };
     weights.push(li.influences.map((e) => ({ bone: e.bone, weight: e.weight })));
     local.push(li.region < 0 ? li : { ...li, region: index[li.region] });

package/src/check.ts

@@ -155,7 +155,8 @@ import {
   type SeamPair,
   stretchRequirementLine,
 } from './requirements.ts';
-import { RIG_BONE_INHERIT } from 'rig-c/src/rig.ts';
+import { RIG_BONE_INHERIT, type RigSpec as RigcRigSpec } from 'rig-c/src/rig.ts';
+import { expandStops } from 'rig-c/src/stop.ts';
 import { alphaComposite } from './raster/composite.ts';
 import { readPng, writePng } from './raster/png.ts';
 import { newFloatImage, newRaster, type Raster } from './raster/types.ts';
@@ -1068,9 +1069,11 @@ export function withoutPhysics(rig: Record<string, unknown>, motion: Record<stri
   const table = isRecord(motion.physics) ? motion.physics : null;
   if (table !== null) for (const [name, e] of Object.entries(table)) physics.push({ name, bone: isRecord(e) ? String(e.bone) : '', in: 'motion.json' });
   if (physics.length === 0) return null;
-  const r: Record<string, unknown> = { ...rig };
-  if (constraints !== null) {
-    const kept = constraints.filter((c) => !(isRecord(c) && c.type === 'physics'));
+  const expanded = Array.isArray(rig.stops) ? (expandStops(rig as unknown as RigcRigSpec, 'rig.json') as unknown as Record<string, unknown>) : rig;
+  const r: Record<string, unknown> = { ...expanded };
+  delete r.stops;
+  if (Array.isArray(r.constraints)) {
+    const kept = r.constraints.filter((c) => !(isRecord(c) && c.type === 'physics'));
     if (kept.length > 0) r.constraints = kept;
     else delete r.constraints;
   }

package/src/cloth.ts

@@ -48,6 +48,9 @@
  *   hip, by the skirt's own rule, in place of the robe chains the topwear rule
  *   drafts; its art above the hip stays on the chest. The proposer never picks
  *   such a part by itself: it names a candidate, and the author declares it.
+ *   A `bottomwear` part lying on that part's tree links (a hem returned as a
+ *   layer of its own) rides them, as a layer on a tail does ({@link tailOverlap}),
+ *   and gets no trees of its own (issue #416): one skirt, one set of trees.
  * - **Swing** (`bottomwear` only). `swing.scales` declares one shared pendulum:
  *   a bone `<prefix>swing` under the attachment at the centre of the root row,
  *   one link long, with physics; each tree's first link takes the swing's
@@ -81,7 +84,7 @@ export interface ClothStrength {
 export interface ClothRecipe {
   chains: number;
   links: number;
-  split?: { at: number; into: number };
+  split?: { at: number; into: number; hold_tip?: boolean };
   length_ratio?: number;
   strength?: ClothStrength;
   damping?: number;
@@ -257,7 +260,7 @@ export function draftTrees(input: TreeInput, r: ClothRecipe): TreeChain[] {
         depths: [],
         last: [],
       };
-      const edge = outerSide(k, b);
+      const edge = r.split?.hold_tip === true ? false : outerSide(k, b);
       for (let j = trunkLinks; j < r.links; j++) {
         ch.points.push(j === trunkLinks ? trunk.tip : pt(rows[j], fb));
         ch.why.push(j === trunkLinks ? `the fork: the trunk ${trunk.chain}'s tip` : `${rowRule(j)}, ${pyRound(fb, 6)} of the way across ${input.frame} in the 24-row band there (branch ${b} of ${into} of tree ${k})`);
@@ -383,7 +386,7 @@ export function clothNote(part: string, tag: ClothTarget, trees: readonly TreeCh
   const defaults: string[] = [];
   if (r.length_ratio === undefined) defaults.push(`length_ratio ${RECIPE_LENGTH_RATIO}`);
   if (r.strength === undefined) defaults.push(`strength ${RECIPE_STRENGTH.trunk}/${RECIPE_STRENGTH.branch}/${RECIPE_STRENGTH.edge}`);
-  const shape = r.split === undefined ? `${r.links} link(s) each` : `a ${r.split.at}-link trunk forking into ${r.split.into} branches, ${r.links} links root to tip`;
+  const shape = r.split === undefined ? `${r.links} link(s) each` : `a ${r.split.at}-link trunk forking into ${r.split.into} branches${r.split.hold_tip === true ? ' (tip held)' : ''}, ${r.links} links root to tip`;
   return (
     `${part} (${via === undefined ? tag : `${via}, which config.cloth."${tag}".part names`}): config.cloth."${tag}" -> ${r.chains} tree(s)${extra}, ${shape} (${trees.map((t) => t.chain).join(', ')}); ` +
     `${constraints} constraint(s), physics on every link, wind ${r.wind[0]} -> ${r.wind[1]} and gravity ${r.gravity[0]} -> ${r.gravity[1]} root to tip (multipliers of the consumer's environment; no direction is drafted), no idle key` +

package/src/config.ts

@@ -86,7 +86,7 @@
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey } from 'rig-c/src/rig.ts';
+import { RIG_BONE_INHERIT, RIG_SKIN_CONSTRAINT_KEYS, type RigBoneInherit, type RigConstraint, type RigSkinConstraintKey, type RigStop } from 'rig-c/src/rig.ts';
 import { pyRound } from './round.ts';
 import { CLOTH_TARGETS, type ClothRecipes, RECIPE_STRENGTH, RIGC_DEFAULT_DAMPING, springStable } from './cloth.ts';
 import { GRID, MAX_SIDE } from './contour.ts';
@@ -648,6 +648,26 @@ export interface ConfigConstraint {
   [field: string]: unknown;
 }
 
+/**
+ * One entry of `config.stops` (issue #404): rig-c's `RigStop` (`rig-c` 2.56.0),
+ * a cloth chain's rotation clamped against a leg bone so the skirt cannot swing
+ * into the leg. `chain` names a chain declared in `config.bones`; `links` is
+ * the stopped links along it (when omitted, every link of `chain` in link
+ * order); `against` is the leg bone the point rides on; `at` is `[x, y]` in
+ * `against`'s local space; `inward` and `outward` are the first link's clamp
+ * bounds in degrees (positive away from `against`), and `lower` the lower
+ * links' bounds when more than one link is stopped.
+ */
+export interface ConfigStop {
+  chain: string;
+  links?: string[];
+  against: string;
+  at: Point;
+  inward: number;
+  outward: number;
+  lower?: { inward: number; outward: number };
+}
+
 /**
  * One segment of a limb (issue #349): the part it makes, the part whose
  * pixels it takes (`from`: a plan part or a cut's piece), and the one bone it
@@ -697,6 +717,8 @@ export interface CharacterConfig {
   regions: Record<string, string>;
   motion: Motion;
   constraints?: ConfigConstraint[];
+  /** Leg stops (issue #404, rig-c 2.56.0's `RigStop`): absent, no stop is added and no byte of any output moves. */
+  stops?: ConfigStop[];
   /** The turn control (issue #251, `src/turn.ts`): absent, no control is added and no byte of any output moves. */
   turn?: TurnSpec;
   /** The painting is a scene (issue #242): absent, no byte of any output moves. */
@@ -760,6 +782,23 @@ export function constraintForRig(c: ConfigConstraint): Record<string, unknown> {
   return out;
 }
 
+/**
+ * A stop as the rig stage hands it to rigc (issue #404): its fields in
+ * `RigStop` order, `links` expanded from `chain` when omitted, and any records
+ * (`x-…`) or annotations (`note`, `…_note`) left out.
+ */
+export function stopForRig(s: ConfigStop, links: readonly string[]): RigStop {
+  return {
+    chain: s.chain,
+    links: [...links],
+    against: s.against,
+    at: [s.at[0], s.at[1]],
+    inward: s.inward,
+    outward: s.outward,
+    ...(s.lower === undefined ? {} : { lower: { inward: s.lower.inward, outward: s.lower.outward } }),
+  };
+}
+
 /** The single-value bone properties a sine track may drive — rigc's one-channel bone timelines. */
 export const SINGLE_PROPS = ['rotate', 'translatex', 'translatey', 'scalex', 'scaley', 'shearx', 'sheary'] as const;
 export type SingleProp = (typeof SINGLE_PROPS)[number];
@@ -992,7 +1031,7 @@ export interface AssembleConfig {
   bones?: BoneEntry[];
 }
 
-const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'turn', 'scene', 'cloth'] as const;
+const TOP_KEYS = ['key', 'generation', 'seethrough', 'assemble', 'limbs', 'bones', 'meshes', 'regions', 'motion', 'constraints', 'stops', 'turn', 'scene', 'cloth'] as const;
 
 /**
  * The one partial entry point. It validates exactly what its door requires —
@@ -1202,6 +1241,7 @@ function parseConfigFrom(raw: Json, base: string | null): { config: CharacterCon
   if ('meshes' in t && 'regions' in t && 'assemble' in t) checkCoverage(c, [...parts, ...cuts], patches, t.meshes, t.regions, limbs);
   if ('motion' in t) checkMotion(c, t.motion, names.bones, names.chains, 'regions' in t ? t.regions : undefined);
   if ('constraints' in t) checkConstraints(c, t.constraints, names.bones, names.parents);
+  if ('stops' in t) checkStops(c, t.stops, names.bones, names.chains);
   if ('turn' in t) checkTurn(c, t.turn, attachedParts(t.meshes, t.regions), names.bones);
   if ('scene' in t) checkScene(c, t.scene);
   if ('cloth' in t) checkCloth(c, t.cloth);
@@ -1374,9 +1414,9 @@ export interface SkeletonSections {
  * both before writing (`checkProposal`). A key the loader would not take is
  * refused by name, as in a config. Refusals name the fields `proposal.…`.
  */
-export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[] } {
+export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[] } {
   const c = new Check();
-  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints']);
+  const top = c.object('config', raw, ['bones', 'meshes', 'regions', 'motion'], ['notes', 'limbs', 'constraints', 'stops']);
   if (top !== null) {
     const names = 'bones' in top ? checkBones(c, top.bones) : { bones: new Set<string>([ROOT_BONE]), chains: new Map<string, number>(), parents: new Map<string, string>() };
     if ('limbs' in top) {
@@ -1389,10 +1429,11 @@ export function parseProposalSections(raw: Json): SkeletonSections & { limbs?: R
     if ('regions' in top) checkRegions(c, top.regions, names.bones);
     if ('motion' in top) checkMotion(c, top.motion, names.bones, names.chains, 'regions' in top ? top.regions : undefined);
     if ('constraints' in top) checkConstraints(c, top.constraints, names.bones, names.parents);
+    if ('stops' in top) checkStops(c, top.stops, names.bones, names.chains);
     if ('notes' in top && c.array('config.notes', top.notes, false)) (top.notes as Json[]).forEach((n, i) => c.string(`config.notes[${i}]`, n, false));
   }
   refuseIfAny(c.problems.map((p) => ({ ...p, object: p.object.replace(/^config\b/, 'proposal') })));
-  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[] };
+  return raw as SkeletonSections & { limbs?: Record<string, Limb>; constraints?: ConfigConstraint[]; stops?: ConfigStop[] };
 }
 
 /**
@@ -2614,6 +2655,65 @@ function checkConstraints(c: Check, v: Json, bones: Set<string>, parents: Map<st
   });
 }
 
+/**
+ * `config.stops` (issue #404): rig-c 2.56.0's `RigStop` entries, each holding
+ * a swinging chain off a leg bone (`against`). `chain` resolves against the
+ * chains `config.bones` declares; `links` (when given) and `against` resolve
+ * against the bones `config.bones` declares (`CONFIG_NAME_RESOLVES`).
+ */
+function checkStops(c: Check, v: Json, bones: Set<string>, chains: Map<string, number>): void {
+  const p = 'config.stops';
+  if (!c.array(p, v, false)) return;
+  const declaredBones = [...bones].join(', ');
+  const declaredChains = [...chains.keys()].join(', ') || 'none';
+  (v as Json[]).forEach((entry, i) => {
+    const at = `${p}[${i}]`;
+    const o = c.object(at, entry, ['chain', 'against', 'at', 'inward', 'outward'], ['links', 'lower']);
+    if (o === null) return;
+    let chainLinks: number | undefined;
+    if ('chain' in o && c.string(`${at}.chain`, o.chain)) {
+      chainLinks = chains.get(o.chain);
+      if (chainLinks === undefined) {
+        c.fail('CONFIG_NAME_RESOLVES', `${at}.chain`, `names "${o.chain}", which config.bones does not declare as a chain; the chains that exist: ${declaredChains}`);
+      }
+    }
+    let linkCount = chainLinks ?? 0;
+    if ('links' in o && c.array(`${at}.links`, o.links, true)) {
+      const list = o.links as Json[];
+      linkCount = list.length;
+      list.forEach((l, k) => {
+        if (c.string(`${at}.links[${k}]`, l) && !bones.has(l)) {
+          c.fail('CONFIG_NAME_RESOLVES', `${at}.links[${k}]`, `names "${l}", which config.bones does not declare; the bones that exist: ${declaredBones}`);
+        }
+      });
+    }
+    if ('against' in o && c.string(`${at}.against`, o.against) && !bones.has(o.against)) {
+      c.fail('CONFIG_NAME_RESOLVES', `${at}.against`, `names "${o.against}", which config.bones does not declare; the bones that exist: ${declaredBones}`);
+    }
+    if ('at' in o) c.point(`${at}.at`, o.at);
+    const inward = 'inward' in o && c.number(`${at}.inward`, o.inward) ? (o.inward as number) : null;
+    const outward = 'outward' in o && c.number(`${at}.outward`, o.outward) ? (o.outward as number) : null;
+    if (inward !== null && outward !== null && inward > outward) {
+      c.fail('CONFIG_FIELD_TYPE', `${at}.inward`, `is ${inward}, above outward ${outward}; inward <= outward is required`);
+    }
+    if ('lower' in o) {
+      const lo = c.object(`${at}.lower`, o.lower, ['inward', 'outward'], []);
+      if (lo !== null) {
+        const li = 'inward' in lo && c.number(`${at}.lower.inward`, lo.inward) ? (lo.inward as number) : null;
+        const loOut = 'outward' in lo && c.number(`${at}.lower.outward`, lo.outward) ? (lo.outward as number) : null;
+        if (li !== null && loOut !== null && li > loOut) {
+          c.fail('CONFIG_FIELD_TYPE', `${at}.lower.inward`, `is ${li}, above lower.outward ${loOut}; inward <= outward is required`);
+        }
+      }
+      if (linkCount === 1) {
+        c.fail('CONFIG_FIELD_TYPE', `${at}.lower`, `is ${show(o.lower)} on a 1-link stop; lower holds the links below the first, so leave lower out when links has 1 bone`);
+      }
+    } else if (linkCount > 1) {
+      c.fail('CONFIG_FIELD_PRESENT', `${at}.lower`, `is absent and required when the stop holds ${linkCount} links (more than 1); state lower: { inward, outward } for the links below the first`);
+    }
+  });
+}
+
 /** The parts `meshes` and `regions` attach, read off whatever they hold; `turn.depths` may name only these. */
 function attachedParts(meshes: Json, regions: Json): Set<string> {
   const out = new Set<string>();
@@ -2700,10 +2800,11 @@ function checkCloth(c: Check, v: Json): void {
     const chains = 'chains' in r && c.int(`${path}.chains`, r.chains, 1) ? (r.chains as number) : null;
     const links = 'links' in r && c.int(`${path}.links`, r.links, 1) ? (r.links as number) : null;
     if ('split' in r) {
-      const sp = c.object(`${path}.split`, r.split, ['at', 'into'], []);
+      const sp = c.object(`${path}.split`, r.split, ['at', 'into'], ['hold_tip']);
       if (sp !== null) {
         const sAt = 'at' in sp && c.int(`${path}.split.at`, sp.at, 1) ? (sp.at as number) : null;
         if ('into' in sp) c.int(`${path}.split.into`, sp.into, 2);
+        if ('hold_tip' in sp && typeof sp.hold_tip !== 'boolean') c.fail('CONFIG_FIELD_TYPE', `${path}.split.hold_tip`, `is ${show(sp.hold_tip)}; true or false is required`);
         if (sAt !== null && links !== null && sAt >= links) {
           c.fail('CONFIG_CLOTH_SPLIT_BEFORE_TIP', `${path}.split.at`, `is ${sAt} and links is ${links}; the trunk's ${sAt} link(s) would leave no link for the branches — split.at below links is required`);
         }