rig-parts 1.2.0 → 1.3.0

package/README.md

@@ -306,8 +306,10 @@ These are limits of the approach, stated so nobody reads more into a green run:
   layer that is in front of another in one place and behind it in another is drawn
   right in the still (the painting's own pixels are projected onto it) and wrong once
   it moves.
-- **No expression or lip-sync.** The mouth is one layer; there is no mouth-shape set
-  and no expression axis.
+- **No expression or lip-sync, and no jiggle.** The mouth is one layer; there is no
+  mouth-shape set and no expression axis, and nothing here proposes, keys or judges a
+  soft region. An expression that moves the face's parts, and a jiggle, can be built on
+  the rig it writes ([below](#what-can-be-built-on-top)); lip-sync cannot.
 - **Occluded pixels are See-through's synthesis**, not the artist's. How much of a rig
   that is, is below.
 - **No success rate is claimed.** Ten characters have been measured stage by stage
@@ -331,6 +333,25 @@ These are limits of the approach, stated so nobody reads more into a green run:
   measures is a hanging strand on a headwear or earwear layer: each gets a pendulum
   chain, and a strand it cannot chain is named in a note rather than left stiff.
 
+### What can be built on top
+
+This package makes no expression and no jiggle, but the rig it writes is the material for
+both, and the config has a field for each. [docs/AUTHORING.md](docs/AUTHORING.md) has a recipe
+for each — a config fragment, the `check` lines it passes with, and its limit:
+
+- [**Expressions and other named animations**](docs/AUTHORING.md#recipe-expressions-and-other-named-animations):
+  the face's parts are bones; animations written over them in rig-c's motion-spec shape and
+  named by `motion.animations_from` are built and gated beside the idle on every build. One
+  attachment per slot, so a part moves, turns and scales but is never swapped for another
+  image; `check` measures the idle alone.
+- [**A soft region driven by physics**](docs/AUTHORING.md#recipe-a-soft-region-driven-by-physics)
+  (a bust, the hips): a bone the config authors, a contour-mode region that hands it the patch,
+  and a `physics` constraint on it; `examples/sample` carries one. Under the sample's slow
+  4 s idle the bust moves at most 0.066 rig px and the hips not at all: the spring answers
+  faster keys on the body. The sample's `hop`, a named animation keying only `hip`, moves the
+  bust up to 6.583 and the hips up to 4.432 rig px; the region's `band` caps how far a patch may
+  go before the texture-stretch ceiling, and `check` measures the idle alone.
+
 ### How much of a rig the model painted
 
 `parts.json` splits each part's opaque pixels (`opaque_px`) into `visible_px` — no

package/cli.ts

@@ -326,14 +326,18 @@ usage:
       <out>/render/recomposite_rig.png and <out>/render/${ERROR_MAP_FILE} (the error
       map: uncovered error px red, covered error px blue, the rest the painting in
       light grey). Reads config.seethrough.head_box and
-      .resolution and config.assemble.rig_scale, .plan, .extend_below_crop and
+      .resolution and config.assemble.rig_scale, .plan, .extend_below_crop,
       .patches — extra parts cut from the painting itself over a rig-pixel box
       (alpha "silhouette": the painting's figure inside it; "box": all of it),
       drawn "back", "front" or {"before": <plan part>}, recorded in parts.json
-      as from "painting:<name>" and counted 100 % source — and no rig section:
+      as from "painting:<name>" and counted 100 % source — and .cuts — a plan
+      part's pixels inside a rig-pixel polygon taken into a new part, drawn the
+      same way, recorded with the plan part's from — and no rig section:
       bones, meshes, regions and motion need not exist yet, because propose
       drafts them from these parts (AUTHORING §4, the table).
-      Prints one line per part, the seam override counts, the \`pixels:\` totals
+      Prints one line per part, one \`cut:\` line per part a cut split (its
+      opaque pixels = what it kept + what each cut took), the seam override
+      counts, the \`pixels:\` totals
       (opaque = visible + occluded; taken from the painting; visible but not
       projected), and \`recomposite vs source\` (mean |d| and % within 8 over the
       mean channel; error px: max channel > 40; uncovered: of those, where no
@@ -435,7 +439,9 @@ usage:
       shared, so a character whose idle keys it, or whose constraint names it,
       is refused. The plate is a region on bone "${PLATE}" under
       root, drawn first, its image at canvas (0, 0). One idle holds every
-      character's tracks. Refused by name, every problem at once: an id
+      character's tracks; an animation beside a character's idle (its
+      config's motion.animations_from) rides along as "<id>:<name>",
+      prefixed as the idle is and scheduled by nothing. Refused by name, every problem at once: an id
       repeated, empty or holding ":" (or "/", "\\", a leading "."); a build
       missing a file or whose own check is not green; characters built at
       different rig_scale; a character whose parts' boxes, placed, leave the

package/docs/AUTHORING.md

@@ -82,9 +82,11 @@ read by no CPU stage).
 | `assemble.plan` | assemble; also the list every `meshes`/`regions` key must come from | **proposed** by `assemble --propose-plan`. `[part name, "full" \| "head", See-through tag]`, in draw order back to front. Names are free; roles come from the tag |
 | `assemble.extend_below_crop` | assemble | **proposed** with the plan: `{part, run, tag}` — a head-run part that reaches the bottom of the head crop is continued from a full-run layer, whole connected components |
 | `assemble.patches` | assemble; `meshes`/`regions` keys may name them too | **authored**, optional: `[{name, box, alpha, draw}]` — an extra part cut from the **painting** itself, for figure no See-through layer holds (a hem both runs dropped). `box` is `[x0, y0, x1, y1]` in **rig** pixels, `x1`/`y1` exclusive — the space of `parts.json` and `recomposite_rig.png`, where the hole is found; `alpha` is `"silhouette"` (the painting's figure silhouette inside the box, the one `--seam silhouette` uses) or `"box"` (the whole box); `draw` is `"back"`, `"front"` or `{"before": "<plan part>"}`. A patch is always a region: its bone is `regions.<name>`, in the one place every region's bone lives, and a `meshes` entry for it is refused. See §5 for how to place one |
+| `assemble.cuts` | assemble; `meshes`/`regions` keys may name the new parts too, and must (each is a part like any other) | **authored**, optional (issue #170): `[{from, into, polygon, draw, overlap}]` — a plan part's layer cut by a polygon the author draws: the pixels of plan part `from` whose **centre** lies inside `polygon` (even-odd; a centre exactly on an edge is outside) leave `from` and make the new part `into`, colour and alpha, so every pixel of the layer ends in exactly one of the two. `polygon` is `[[x, y], …]`, at least three points, non-negative integer **rig** pixels — the space of `parts.json` and of the patches' boxes. The file that shows the layer in those coordinates is `assemble`'s own `rig/parts/<from>.png`, placed at its `parts.json` `x`, `y` (the PNG's pixel `(i, j)` is rig pixel `(x + i, y + j)`), or `render/recomposite_rig.png`, the whole rig 1:1; the contact sheets (`sheet`) are scaled and carry no coordinates. `draw` is `"back"`, `"front"` or `{"before": "<plan part>"}`, as for a patch (to keep the setup pose, put it beside `from`: `{"before": "<from>"}`, or before the plan part after it). `from` must be a plan part (`CONFIG_NAME_RESOLVES`; a patch or another cut's piece is refused), `into` a new name (`CONFIG_PART_UNIQUE`), the polygon three or more integer points (`CONFIG_FIELD_TYPE`). The piece's `parts.json` record carries `from`'s `<run>:<tag>` and its own counts, each split from the layer's by where the pixel lies; it is a mesh or a region under its own name, and the coverage rule holds it like a plan part. What the config cannot know the stage refuses: a polygon point past the rig (`ASSEMBLE_CUT_INSIDE`), two cuts of one part sharing a pixel (`ASSEMBLE_CUT_OVERLAP`), a cut that takes none of the layer's opaque pixels or leaves `from` none (`ASSEMBLE_CUT_PIXELS`). `overlap` is required, a non-negative integer of rig pixels with no default (`CONFIG_FIELD_TYPE`): the **band** — the polygon's pixels within `overlap` px of its edge by Chebyshev distance (the polygon's mask less its erosion by a `2 * overlap + 1` square) — stays in `from` as well as going to the piece, so the piece's resampled edge has art under it; the counts stay a strict partition and the band is the base's extra copy, printed on the `cut:` line. At `0` the two abut and `check`'s seam bar judges the edge between them (`CHECK_SEAM_WITHIN_BAR`, §5). A band only covers the edge at rest: a piece that swings well clear of where it was painted shows the hole it leaves, and a thin piece's band shows a ghost of the piece — an authored fill for what lies under a piece is issue #193 |
 | `bones` | rig; `propose --from-config` | **proposed** by `propose`, then corrected. A single bone `{name, parent, at, tip?}` or a chain `{chain, parent, points, tip}` whose links are named `<chain>0 … <chain>n`. Parents come before children. In `rig.json` each link is **turned along its chain** — `rotation` is the direction from its origin to the next link's (the last link's to `tip`) and `length` that distance (issue #73), so a physics constraint added downstream finds a lever; under `--idle-keys ctl` the link's `<link>_ctl` carries the turn and the length and the link sits at local rotation 0 beneath it. A single bone is never turned; one whose parent is a link is turned back upright |
 | `meshes.<part>` | rig | **proposed**, then corrected. Exactly one of `grid` (the lattice: cell size, px — what `propose` writes), `contour` (the outline mode, authored; the next row and "A contour mesh" below) or `auto` (the automatic mode, authored; "An automatic mesh" below) — two, or none, is `CONFIG_MESH_MODE`. In every mode: `r` (added to every distance before weighting: `w = 1/(d + r)²`), `segments` (a chain name, a bone name with a `tip`, or `[bone, [x0,y0], [x1,y1]]`), and, **authored**, optional, `exponent` (issue #161): a number above 0 that replaces the 2 in that rule, `w = 1/(d + r)^exponent` — a larger one hands each vertex more fully to its nearest bone; absent is 2 and changes no byte, a value that is not a number above 0 is `CONFIG_FIELD_TYPE` at `meshes.<part>.exponent`, and a declared one is echoed as `exponent` in the mesh's `mesh_report.json` row; the exponent is the distance rule's, so declared beside `rule: "heat"` it is refused (`CONFIG_FIELD_TYPE` at `meshes.<part>.exponent`). The segment list is the one authored decision about a layer: which bones may pull it. The slot's bone is the first segment's. Optional `rule` (issue #161): `"distance"` — the rule above, and what an absent `rule` means (every byte is the same) — or `"heat"`, bone heat over the part's own silhouette, in every mode: the lattice's art (alpha above 8) with holes filled, or for `contour` and `auto` the silhouette their outline is traced from (that mode's art — alpha above 8 for `contour`, alpha 1 and above for `auto` — less any island a declared `stray` left out, holes filled, grown by its `margin`); each bound bone's sources are the silhouette pixels whose centre lies within 0.75 px of its segment (a pixel two bones reach goes to the nearer, a tie to the first listed), held at 1 for that bone and 0 for the others; the field is solved by row-major Gauss–Seidel over-relaxation to a sweep change under 1e-7 within 20000 sweeps; a vertex reads the nearest silhouette pixel and takes the same cap and floor (and `regions`) as the distance rule; `r` is not read. The mesh's `mesh_report.json` row gains `heat` (the constants, each bone's sources and sweeps, the residual). Any other value is `CONFIG_FIELD_TYPE`; a bound bone with no source pixel is `RIG_HEAT_BONE_SOURCE`, an island no bone has a source in `RIG_HEAT_ISLAND_SOURCE`, a solve past its sweep bound `RIG_HEAT_CONVERGED` — none is weighted 0 |
 | `meshes.<part>.contour` | rig | **authored**, optional (issue #84): `{tolerance, margin, spacing, budget?, stray?, regions?}`. `tolerance` — rig-c's Douglas–Peucker tolerance on the traced outline, px, 0 or more; `margin` — how far the silhouette grows before it is traced, px: 0, or 1 or more (a pixel joins when its centre lies within `margin` of an art pixel's centre; a value above 0 and below 1 adds nothing and is refused, `CONFIG_FIELD_TYPE`); `spacing` — the background interior spacing, px, above 0; `budget` — the most vertices the mesh may have (refused above it, nothing thinned); `stray` — the largest island, in art pixels, that may be left out of the mesh (absent: none is); `regions` — local deformation regions, each `{name, shape, bone, spacing, band}` with `shape` `"circle"` (`cx, cy, r`) or `"polygon"` (`points`, 3 or more): `bone` is the region's control bone (any bone `bones` declares), `spacing` the interior spacing inside the region and its band, `band` the width the bone's weight falls across. Every length and position is **rig px**, like every other in the config; the part image is the rig less `(x − 4, y − 4)` (its box less the pad), a translation, so a length is the same number in both. A region's `cx`, `cy`, `r`, `band` and `points` are multiples of 1/256 px (`CONFIG_FIELD_TYPE` otherwise); region names are unique per mesh (`CONFIG_REGION_NAME_UNIQUE`). The alpha threshold is not a field: art is alpha above 8, the lattice's and `check`'s |
+| `meshes.<part>.ribs` | rig | **authored**, optional (issue #188), in the `contour` and `auto` modes: `{<chain>: {stations}, …}`, each key a chain this mesh's `segments` name. Each link of the chain gets a row of vertices across the part at its origin and at `stations` points evenly between its origin and its end (`stations`, a whole number, 0 or more, required; a chain of L links carries L × (stations + 1) ribs) — so a strand can fold where its chain bends; the rule is "Ribs along a chain" under "A contour mesh". Absent places none and changes no byte. Refused: a lattice mesh with ribs (`CONFIG_RIBS_MODE` — its vertices are its grid's corners), a key that is not one of the mesh's chains (`CONFIG_NAME_RESOLVES`), an object naming no chain or a `stations` that is not a whole number from 0 (`CONFIG_FIELD_TYPE`); at the rig stage `CONTOUR_RIB_ART`, `CONTOUR_RIB_LINK`, `CONTOUR_RIB_CROSSING`, `CONTOUR_RIB_EDGE` (the contour refusals). The mesh's `mesh_report.json` row gains `ribs` — the declaration, the ribs placed and the vertices they hold — and its contour report (the source's, in `auto`) lists each rib's vertices |
 | `regions.<part>` | rig | **proposed**: the bone a rigid part rides. Every plan part is exactly one of a mesh or a region (`CONFIG_PART_ATTACHED`) |
 | `motion.duration` | rig; check (the loop is measured at this time) | proposed as 4 s; a whole number of 1/12 s ticks, because `check` renders at 12 fps |
 | `motion.tracks` | rig | **proposed**, then tuned. Single `{bone, prop, amp, period, phase, base?}` or chain `{chain, amps, period, phase, lag}` — one amplitude per link, link `i` at phase `phase + lag·i`. Every `period` must divide `duration` (`CONFIG_PERIOD_DIVIDES_DURATION`). A bone property is keyed by one track (`CONFIG_BONE_PROPERTY_KEYED_ONCE`): a chain keys `rotate` on every link, the blink's `eyes` group `scaley` and its `brows` group `translatey` on every member, so a single track on any of those is a second track on it — rigc would refuse it one stage later, `animation "idle" has two tracks on eye.scaley`. A chain link is turned along its chain (the `bones` row), so a `translatex`/`translatey` key on a bone whose parent is a turned link, or a `scale`/`shear` key on a turned link, would move or stretch along the link and not along the picture's axis: the rig stage refuses it (`RIG_KEY_FRAME_UNTURNED`); `rotate` is keyed on any bone |
@@ -364,6 +366,42 @@ contour refusal in a run is listed together; nothing falls back to the lattice:
 | `CONTOUR_PART_HAS_ART` | no pixel above alpha 8 | re-run assemble |
 | `CONTOUR_PARAMETER` | a parameter `src/contour.ts` cannot run at: a margin above 0 and below 1 px (it would add no pixel), a spacing whose keep radius (half of it) snaps to 0, a polygon whose band folds it, a part over 32768 px | the named field |
 | `RIG_CONTOUR_REGIONS_OVERLAP` | a vertex two regions both reach (`g > 0`); the detail names the vertex and both regions | move the regions apart or narrow a band |
+| `CONTOUR_RIB_ART` | a rib's point (a link origin or a station) is not on the part's art (its pixel at or below the threshold) or not inside the outline, or a point between its ends falls within 1/256 px of the outline — a rib that leaves the art | move the chain onto the part, or leave the chain out of `ribs` |
+| `CONTOUR_RIB_LINK` | a chain link shorter than the outline's `tolerance` (or of no length), or a joint where the chain turns straight back on itself; the detail names the chain, the link and the tolerance field | fewer, longer links, or a lower `tolerance` |
+| `CONTOUR_RIB_CROSSING` | two ribs cross, touch or share an end (both named, with their ends) | fewer `stations`, or a chain that bends less sharply inside a wide part |
+| `CONTOUR_RIB_EDGE` | a rib's consecutive vertices could not be joined by an edge (no edge across them could be flipped) — a guard: the rule keeps every other point off a rib | report it |
+
+**Ribs along a chain** (`meshes.<part>.ribs`, issue #188). A long thin part that hangs from a
+chain — a tie, a strand of hair, a scarf end — bends at the chain's joints, and a mesh with no
+row of vertices across the strand there cannot fold at the joint: the bend is taken up by
+whatever triangles happen to span it. For each chain `ribs` names, `src/contour.ts`
+(`placeRibs`) places, in part-image px:
+
+- **where**: on each link k (from `points[k]` to `points[k + 1]`, the last to the tip) a rib at
+  its origin and at `points[k] + m/(stations + 1) · (end − origin)`, m = 1..`stations`; the tip
+  carries none;
+- **across**: along n = (−d_y, d_x)/|d|, d the link's direction — at a joint between two links
+  the sum of their unit directions, the bend's bisector;
+- **clipped to the art**: the point must be on the part's art (its pixel above the mode's
+  threshold) and inside the outline; from it the line runs both ways to the first point where it
+  meets the outline the mode traced (art, holes filled, grown by `margin`, simplified at
+  `tolerance`), and those two points, on the 1/256 px grid, are the rib's ends. Each end joins
+  the hull on the edge it lands on (or is that edge's vertex), moved off the edge by at most
+  1/512 px; coverage, overshoot and self-intersection then read the outline with them;
+- **between**: the point itself (so the joint is a vertex), and each half from an end to the
+  point cut into ⌈half / spacing⌉ equal parts at the mode's background `spacing`
+  (`auto.source.spacing` in the automatic mode);
+- **kept a row**: no other interior point is kept within half a spacing of a rib, every
+  consecutive pair of a rib is made an edge of the triangulation (edges across it are flipped
+  until it is one) and locked, as an outline edge is — so `nonDelaunayEdges` does not count it.
+
+Nothing reads a weight: every vertex is weighted as any other at its point. The rib on a strand
+painted inside a wider layer runs across the whole opaque run there, sleeve and body included —
+cutting the strand out is #170's. In the automatic mode every rib vertex is added to
+`protect.vertices` (after the author's, as written) and each rib is sent to rig-c's
+`reduceMesh` as a named line (`lines`, rig-c 2.33.0; `maxDeviation` 0), so the reduction keeps
+every rib vertex and its post-pass flips no rib edge; the result's measurement carries one
+`MQ_LINE_DEVIATION` row per rib.
 
 **The window between coverage and overshoot**, measured in #106 (`tools/contour_survey.ts`, five
 generated shapes, margins 0, 1, 1.5, 2, 2.5, 3): the smallest margin that covered every art
@@ -844,6 +882,123 @@ boundary stays held, and an edge from the region to a vertex further out than it
 that crosses the region with no point of it inside to split at — is still stopped by name
 (`AUTO_MESH_ACCEPTED`, the detail naming P16).
 
+### Recipe: expressions and other named animations
+
+The package proposes no expression and keys nothing but the idle; what it gives is a rig whose
+face is bones (`eye_r`, `eye_l`, `brow_r`, `brow_l`, `mouth` on `sample`) and one door for
+animations you write over them, `motion.animations_from` (the row above, issue #183). Write a
+file in rig-c's motion-spec shape beside the config and name it:
+
+```jsonc
+// config.json
+"motion": { "duration": 4.0, "tracks": [ … ], "blink": { … },
+            "animations_from": "expressions.json" }
+
+// expressions.json — the bones the config declares, keyed as rig-c keys them
+{ "spec": "rigc-motion/1",
+  "animations": {
+    "surprised": { "duration": 0.5, "tracks": [
+      { "bone": "brow_r", "property": "translatey", "keys": [ { "t": 0, "v": [0] }, { "t": 0.25, "v": [2] }, { "t": 0.5, "v": [0] } ] },
+      { "bone": "brow_l", "property": "translatey", "keys": [ { "t": 0, "v": [0] }, { "t": 0.25, "v": [2] }, { "t": 0.5, "v": [0] } ] },
+      { "bone": "mouth",  "property": "scaley",     "keys": [ { "t": 0, "v": [1] }, { "t": 0.25, "v": [1.4] }, { "t": 0.5, "v": [1] } ] } ] } } }
+```
+
+`build` writes `surprised` into `rig/motion.json` after `idle`, gates it with the rig, and
+`check` names it on a line of its own (`examples/sample` carries one, `animations.json` with `hop`, the
+recipe below). With exactly this file beside `examples/sample`'s config in its place,
+`build` printed (this tree, rig-c as `package.json` pins it):
+
+```
+[rig]   animations beside the idle, from …/expressions.json as written: surprised
+[check]   beside the idle: 1 animation(s), surprised — built and gated by rigc with the rig, not measured: every bar here reads the idle
+[check] check: PASS; 9 of 9 bar(s) measured, 0 skipped
+```
+
+A bone the rig lacks is rigc's refusal at the rig stage, in rigc's words (`RIG_RIGC_GREEN`); a
+fault in the file itself is the loader's (the row above names each one).
+
+**Limits.** Every slot holds one attachment, the part's own image, so an expression moves,
+turns and scales the face's parts and never swaps one for another: there is no second mouth
+shape to key, and no lip-sync. `check` measures the idle alone: an animation beside it has
+passed rigc's gate and nothing else — no seam, stretch or hole bar has read it.
+
+### Recipe: a soft region driven by physics
+
+A jiggle (a bust, the hips) is a patch of one part that lags behind the body. The package
+proposes none and judges none; what it gives is the three pieces to build one, all in the
+config. `examples/sample` carries a worked one (issue #183, PR #187), and its config is the
+fragment below, cut to the bust:
+
+```jsonc
+"bones": [ …,
+  { "name": "chest_jiggle", "parent": "chest", "at": [419, 320] }, … ],
+"meshes": { "topwear": {
+  "contour": { "tolerance": 1, "margin": 1, "spacing": 18, "stray": 4,
+    "regions": [ { "name": "bust", "shape": "circle", "cx": 419, "cy": 320, "r": 28,
+                   "bone": "chest_jiggle", "spacing": 6, "band": 16 } ] },
+  "r": 8, "segments": [ ["chest", [419, 223], [419, 437]], ["hip", [419, 437], [419, 557]] ] } },
+"constraints": [
+  { "type": "physics", "name": "bust_phys", "bone": "chest_jiggle",
+    "x": 0.5, "y": 1, "inertia": 0.25, "strength": 120, "damping": 0.92, "mass": 1, "mix": 1 } ]
+```
+
+- **A bone the config authors**, under the bone the patch rides on. `propose` writes no such
+  bone and no constraint; it is yours, and nothing keys it — the constraint moves it.
+- **A region in a `contour` (or `auto`) mesh** that hands the patch to that bone: weight 1
+  inside the shape, falling to 0 across `band` (*A contour mesh*, above). A `grid` mesh carries
+  no region, so the part moves from the lattice to the outline mode first; `sample` traced
+  `topwear` at its former grid spacing (18) and `bottomwear` at 28. Place the shape on the
+  patch alone: on `sample` one circle at the hip centre reached the clasped hands, painted
+  inside `bottomwear`, so the hips are two side circles (`hip_r`, `hip_l`) on one bone.
+- **A `physics` constraint** on that bone in `constraints`, in rig-c's shape; every field but
+  the bone is rigc's to accept.
+
+`build` on `sample` as tracked (PR #187; the values above are the ones tuned for its `hop`, issue #183):
+
+```
+check: PASS; 9 of 9 bar(s) measured, 0 skipped
+loop physics: 2 physics constraint(s) left out of the loop's frames, reported, not judged — "bust_phys" on bone "chest_jiggle" (rig.json), "hip_phys" on bone "hip_jiggle" (rig.json)
+loop: idle 49 frame(s) at 12 fps, f0000 vs f0048 (t = 4s): max |d| 0 (0 required)
+```
+
+The `loop physics:` line is the loop bar saying what it did not read (§7, *loop*): rig-c's
+render resets physics at frame 0 and steps it, so the idle's last frame differs from its first
+by whatever the spring is still doing; the bar is read off the same rig with every physics
+constraint left out, and the constraints left out are listed, reported and not judged
+(`check.json`'s `loop_physics`, PR #184). It is not a measure of the jiggle.
+
+**Limits.** The idle drives the spring, and a slow idle barely moves it. Measured on `sample`
+(PR #187, rig-c `render --geometry`, the physics build against the same build with
+`constraints` removed): under its 4 s breath (`chest` `translatey` amplitude 1.3 px), the bust
+moves at most 0.155 rig px (idle frame 3, t 0.25 s); the hips move 0.000 at all 49 frames,
+because the idle keys `chest` and never `hip`, so a child of `hip` receives no motion. A spring
+of strength 100 trails a parent moving at about 2 px/s by the order of speed over its angular
+frequency, about 0.2 px (PR #187, from the definition): no setting makes a 4 s breath read as a
+jiggle (with the values tracked now, `bust_phys` inertia 0.25, strength 120, damping 0.92, the
+idle moves the bust at most 0.066 rig px, idle frame 2). Faster keys on the parent bone — a hop,
+a turn, in a named animation (the recipe above) or a consumer's own — are what the spring
+answers. `sample`'s `animations.json` holds one, `hop` (1 s: `hip` `translate` y down 5, up 24,
+landing at -6 at 0.45 s, settling at 0.55 s; nothing keys the jiggle bones): rendered at 30 fps
+against the same build without its constraints, the bust moves at most 6.583 rig px and the hips
+(`hip_phys` inertia 0.2, strength 160, damping 0.88, mass 1.5) at most 4.432 (frame 13, the fall
+into the landing), and both overshoot after it, 3.38 and 1.38 rig px (frames 21 and 22;
+`docs/evidence/sample-hop.png`). No bar here judges the jiggle, and two limits follow from that:
+
+- **The region's `band` caps the displacement.** The patch moves as one piece and the band is
+  where the mesh stretches to follow it, so physics values that carry the patch further than
+  its band absorbs squeeze or stretch the band's triangles past the texture-stretch ceiling.
+  `check` reads the idle alone and does not see it; check's own reading applied to `hop`'s
+  geometry with PR #187's values (inertia 0.5, strength 100, damping 0.85, mass 1, a bone
+  displacement of 9.85 rig px against bands of 16 and 12) gives
+  `CHECK_TEXTURE_STRETCH: mesh "bottomwear" triangle 13 (vertices 5 183 6), edge 6-5, idle frame 13 — the edge is 0.233 times its rest length (max(ratio, 1/ratio) 4.29); <= 1.926544 is required`
+  and `topwear` 2.597; with the values tracked now it reads 1.697 (`topwear`) and 1.566
+  (`bottomwear`). Tune the constraint against the animation that drives it, not the idle.
+- **An added animation can move the idle's figures.** The render's viewport is fitted over
+  every animation, and the idle frames share it, so an animation that travels further than the
+  idle redraws the idle at another size: adding `hop` to `sample` narrowed the idle render from
+  201 to 198 px wide and moved `check.json`'s `BREATH_VISIBLE` `torso_heat_mean` from 7.8 to
+  7.705, every status unchanged, although `check` reads the idle alone.
+
 ## 4. The command order
 
 Two steps are external: the See-through runs (by any route; the optional `comfy seethrough` adapter is only a client for a ComfyUI box). Everything else is this tool.
@@ -978,7 +1133,7 @@ proposal in as the steps above say (`RL01`); every step must exit 0.
 | --- | --- | --- | --- |
 | `layers` | the table, 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, 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, …)`; and look at `render/recomposite_error_rig.png`. Between the part lines and the totals, 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: `sample` 0.83 / 98.0 % / 4,359 / 1,185, 259 holes, the largest 94 px; `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 (the 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, 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, …)`; and look at `render/recomposite_error_rig.png`. Between the part lines and the totals, one `cut: "<part>" opaque <n> = "<part>" <kept> + "<piece>" <taken> …` line per part an `assemble.cuts` entry cut (below), 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: `sample` 0.83 / 98.0 % / 4,359 / 1,185, 259 holes, the largest 94 px; `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 (the 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 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 `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; `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` |
@@ -1179,9 +1334,31 @@ leave a resampled edge between them in the render. The patch is config, so every
 and read `uncovered error px` again: a patch covering `n` of the uncovered error
 pixels lowers it by exactly `n` (the selftest's `AS17` plants that and counts it).
 
+**Cutting a piece out of a layer.** When one See-through layer holds two things that
+must move apart — a scarf end painted into the sweater's `topwear`, both arms in one
+`handwear` — add an `assemble.cuts` entry (§3): open `rig/parts/<part>.png` from an
+earlier `assemble`, add its `parts.json` `x`, `y` to a pixel's column and row to get
+rig pixels, and draw the polygon round the piece. The stage prints, between the part
+lines and the `fringe pushed back` lines, one line per cut part in the `pixels:`
+line's shape, counted when the cut is made (before the fringe push-back and the seam
+pass, which the records are counted after):
+
+    cut: "topwear" opaque 134452 = "topwear" 118973 + "scarf" 15479; band 593 px held by both
+
+Give the piece a `meshes` entry over the bones that should carry it, and take those
+bones out of the part it left: on the public `scarf`, the scarf end `robe_r` runs down,
+cut out of `topwear` into its own mesh on `robe_r` (and `robe_r` dropped from `topwear`'s
+segments) leaves every `topwear` vertex still at wind 6 where the uncut mesh moved
+one by 101.5 px [observed, `docs/evidence/scarf-cut.png`]. Where the cut runs through
+opaque art, `overlap` decides the seam: at 0 the pieces abut, each edge is resampled
+against transparency, and on that cut the seam bar read 170 px over 40 against 50
+allowed (`CHECK_SEAM_WITHIN_BAR`); at 1 it read 8, at 2 it read 3, at 4 it read 2
+(the uncut build reads 2) [observed].
+
 `parts.json` holds one record per part, in draw order: the plan's, with each patch
-where its `draw` puts it (`"back"` patches first in their own order, each
-`{"before": X}` patch immediately behind `X`, `"front"` patches last). Its counts:
+and each cut's piece where its `draw` puts it (`"back"` patches first in their own
+order, then `"back"` pieces; each `{"before": X}` patch, then each such piece,
+immediately behind `X`; `"front"` patches last, then `"front"` pieces). Its counts:
 
 | field | counts |
 | --- | --- |
@@ -1197,7 +1374,8 @@ where its `draw` puts it (`"back"` patches first in their own order, each
 
 A part's `from` is `<full|head>:<tag>` — the See-through run and tag, which every
 role (`propose`) and every judgement-line region (`check`) is read from — or, for a
-patch, `painting:<its own name>`. **A patch is 100 % source**: every pixel is the
+patch, `painting:<its own name>`; a cut's piece carries the `<run>:<tag>` of the part
+it was cut from, so two records may share one. **A patch is 100 % source**: every pixel is the
 painting's, so it is all visible and all taken — `visible_px`, `projected_core_px`
 and `source_px_taken` equal `opaque_px`, and `occluded_px`,
 `visible_not_projected_px`, `refused_drift_px` and `merged_px` are 0. The reader
@@ -1316,10 +1494,11 @@ See-through with another seed.
 | `CONFIG_FILE_PRESENT`, `CONFIG_IS_JSON` | no such file, or not JSON | `--config` |
 | `CONFIG_KEY_KNOWN`, `CONFIG_KEY_RETIRED`, `CONFIG_FIELD_PRESENT`, `CONFIG_FIELD_TYPE` | an unknown key (a retired one says what replaces it), a missing one, a wrong type; a project's own record under a plain key, or an annotation (`note`, `<name>_note`) holding something other than a string | the named field; a record goes under a key beginning `x-` (any JSON, read by nothing), a remark under `note` or `<name>_note` (a string) — §3 |
 | `CONFIG_HEAD_BOX_SQUARE` | `seethrough.head_box` is not a non-empty square | `head_box` — take `propose --head-box`'s |
-| `CONFIG_TAG_KNOWN`, `CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` | a plan entry names no v3 tag, a part name that is not a file name, or a part or layer twice — a patch named like a plan part or another patch included | `assemble.plan`, `assemble.patches` |
-| `CONFIG_NAME_RESOLVES` | a parent, segment, region, track, blink member, blink still part or bone, extend part or patch `draw.before` names nothing declared above it; or a constraint's `bones`, `target`, `source` or `bone` names a bone `bones` does not declare (the detail names the constraint and lists the bones that exist) | the named reference, or the declaration it needs |
+| `CONFIG_TAG_KNOWN`, `CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` | a plan entry names no v3 tag, a part name that is not a file name, or a part or layer twice — a patch named like a plan part or another patch, and a cut's `into` named like a plan part, a patch or another cut's, included | `assemble.plan`, `assemble.patches`, `assemble.cuts` |
+| `CONFIG_NAME_RESOLVES` | a parent, segment, region, track, blink member, blink still part or bone, extend part, patch or cut `draw.before`, or cut `from` names nothing declared above it (a cut's `from` must be a plan part); or a constraint's `bones`, `target`, `source` or `bone` names a bone `bones` does not declare (the detail names the constraint and lists the bones that exist) | the named reference, or the declaration it needs |
 | `CONFIG_BONE_UNIQUE` | a bone or chain declared twice, or `root` declared | `bones` |
-| `CONFIG_PART_ATTACHED` | a plan part with neither or both of a mesh and a region; a patch with a mesh, or with no region | `meshes` / `regions` |
+| `CONFIG_PART_ATTACHED` | a plan part or a cut's piece with neither or both of a mesh and a region; a patch with a mesh, or with no region | `meshes` / `regions` |
+| `CONFIG_RIBS_MODE` | `meshes.<part>.ribs` on a lattice (`grid`) mesh: its vertices are its grid's corners, which no row can move (issue #188) | put the part in `contour` or `auto`, or remove `ribs` |
 | `CONFIG_PATCH_BOX` | an `assemble.patches` box with `x1 <= x0` or `y1 <= y0` | that patch's `box` (`x1`, `y1` are exclusive) |
 | `CONFIG_AMPS_MATCH_CHAIN` | a chain track's `amps` is not one per link | that track's `amps` |
 | `CONFIG_PERIOD_DIVIDES_DURATION` | a period that is not a whole fraction of the idle — the loop could not close | that track's `period`, or `motion.duration` |
@@ -1363,7 +1542,10 @@ See-through with another seed.
 | `ASSEMBLE_PART_OPAQUE` | a part ended with no opaque pixel | drop the entry, or take the tag from the other run |
 | `ASSEMBLE_PATCH_BOX_INSIDE` | a patch's box reaches past the rig (the painting times `rig_scale`; the detail gives the size) | that patch's `box` — it is in rig pixels, not painting pixels |
 | `ASSEMBLE_PATCH_OPAQUE` | a patch takes no pixel: a `"silhouette"` patch whose box holds none of the figure | move the box onto the figure, or `"alpha": "box"` |
-| `ASSEMBLE_COUNTS_ADD_UP` | a part's visible and occluded counts do not add up to its opaque pixels, or a projected pixel is not visible — an assembler bug, not an input problem | report it with the part named; nothing was written |
+| `ASSEMBLE_CUT_INSIDE` | a cut's polygon has a point past the rig (the detail gives the points and the size) | that cut's `polygon` — it is in rig pixels, not painting pixels |
+| `ASSEMBLE_CUT_OVERLAP` | two cuts of one part share a rig pixel (the detail gives the count and the first, `x,y`) | one of the two polygons: a pixel goes to one part |
+| `ASSEMBLE_CUT_PIXELS` | a cut takes none of its part's opaque pixels (alpha above 8), or a part's cuts leave it none | draw the polygon over the art; to move the whole layer, rename the plan part instead |
+| `ASSEMBLE_COUNTS_ADD_UP` | a part's visible and occluded counts do not add up to its opaque pixels, or a projected pixel is not visible, or a cut part's pieces do not add up to it — an assembler bug, not an input problem | report it with the part named; nothing was written |
 
 ### propose
 
@@ -1842,6 +2024,13 @@ What is composed:
   duration. Constraints are carried in character order with their
   `invariants.detached`; `invariants.idleDrivesMeshes` once, when any character
   declares it.
+- **Every animation beside a character's idle** — what `motion.animations_from`
+  wrote into its `motion.json` (§3) — rides along as `<id>:<name>` after the idle,
+  its tracks' bones, groups and easings prefixed as the idle's are and every other
+  value as written; the scene schedules none of them, they are the consumer's to
+  play. Each is read with the idle's own key lists, so a key compose does not know
+  how to prefix is `SCENE_BUILD_FIELD_KNOWN`, as it is on the idle, and a track of
+  one that keys `root` is `SCENE_ROOT_SHARED` (issue #183).
 - **Gated as `rig` gates its own:** `rigc build --profile spine-html --pack`, the
   compile and the packed pages on disk, in a scratch directory; `--out` receives
   `rig/` (`rig.json`, `motion.json`, `images/`) and `scene.json` only when it is

package/docs/STABILITY.md

@@ -105,13 +105,16 @@ part name, `[i]` an entry of a list):
 - **generation.sampler** — required: `steps`, `cfg`, `sampler`, `scheduler`
 - **generation.control** — required: `skeleton`, `strength`, `end_percent`; optional: `model`
 - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`
-- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `extend_below_crop`, `patches`
+- **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `extend_below_crop`, `patches`, `cuts`
 - **assemble.extend_below_crop[i]** — required: `part`, `run`, `tag`
 - **assemble.patches[i]** — required: `name`, `box`, `alpha`, `draw`
 - **assemble.patches[i].draw**, when an object — required: `before`
+- **assemble.cuts[i]** — required: `from`, `into`, `polygon`, `draw`, `overlap`
+- **assemble.cuts[i].draw**, when an object — required: `before`
 - **bones[i]**, a single bone — required: `name`, `parent`, `at`; optional: `tip`
 - **bones[i]**, a chain — required: `chain`, `parent`, `points`, `tip`
-- **meshes.<part>** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`; optional in every mode: `exponent`, `rule`
+- **meshes.<part>** — exactly one of `grid`, `contour`, `auto`; required in every mode: `r`, `segments`; optional in every mode: `exponent`, `rule`; optional with `contour` or `auto`: `ribs`
+- **meshes.<part>.ribs.<chain>** — required: `stations`
 - **meshes.<part>.contour** — required: `tolerance`, `margin`, `spacing`; optional: `budget`, `stray`, `regions`
 - **meshes.<part>.contour.regions[i]** — required: `name`, `shape`, `bone`, `spacing`, `band`, and `cx`, `cy`, `r` for a circle or `points` for a polygon
 - **meshes.<part>.auto** — required: `source`, `sourceBounds`, `targets`, `influences`, `budget`, `minArtSamples`, `motion`; optional: `protect`, `regions`, and the three Stage B opt-ins `boundaryRuns`, `retriangulate`, `removalOrder`
@@ -152,7 +155,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | --- | --- | --- |
 | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from`, 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` |
 | `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 |
-| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions`; 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`) |
+| `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones`, `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions`; 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`); `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`, `loop_max_diff`, the seam figures), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `RECOMPOSITE_HOLES`, `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "1.2.0",
+  "version": "1.3.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/skills/rig-parts/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rig-parts
-description: Turn one anime character painting and its See-through layer decomposition into a verified 2D character rig (Spine 4.3 skeleton data) — measured parts, weighted meshes, bone chains and a looping idle — with rig-parts, which gates everything through rig-c before it is written. Use for a request to rig or animate a single character painting, to run or read rig-parts layers, sheet, assemble, propose, rig, check, loop or build, or to write or fix a rig-parts config.json. Not for cutting art into parts by hand, for authoring a rig from loose PNGs (that is the rigc skill), for expressions or lip-sync, or for running See-through itself.
+description: Turn one anime character painting and its See-through layer decomposition into a verified 2D character rig (Spine 4.3 skeleton data) — measured parts, weighted meshes, bone chains and a looping idle — with rig-parts, which gates everything through rig-c before it is written. Use for a request to rig or animate a single character painting, to run or read rig-parts layers, sheet, assemble, propose, rig, check, loop or build, or to write or fix a rig-parts config.json. Not for cutting art into parts by hand, for authoring a rig from loose PNGs (that is the rigc skill), for lip-sync or swapping a part's image, or for running See-through itself.
 license: MIT
 compatibility: Requires Bun 1.2 or later. The tool is the npm package rig-parts (bunx rig-parts, or bun add -d rig-parts); rig-c is installed with it. See-through is run separately.
 ---
@@ -75,6 +75,13 @@ stage writes are the whole interface.
    `assemble.patches` entry (a rig-pixel box, `alpha: "silhouette"`, drawn
    `"back"` and reaching under its neighbours, its bone in `regions`) and assemble
    again; never add a part to `rig/` or `parts/` by hand (AUTHORING §5).
+   One layer holding two things that must move apart (a scarf end inside
+   `topwear`, both arms in one `handwear`): add an `assemble.cuts` entry — a
+   polygon in rig pixels read off `work/rig/parts/<part>.png` plus its
+   `parts.json` `x`, `y`, a new name, a `draw`, an `overlap` (the band the part
+   keeps under the piece's edge; 1 px closed the seam on scarf) — and give the piece its own
+   `meshes` entry; the `cut:` line gives the split. At overlap 0 a cut through
+   opaque art leaves a seam `check` reads (AUTHORING §5).
    A seated or reclining figure: add `--keypoints <file>` (body-18 joints in
    painting px, each observed, occluded or missing; AUTHORING §3, *A posed
    figure*) so the neck, hip, chest and sleeves follow the pose and LINT reads
@@ -132,11 +139,13 @@ share is synthesis where the painting was there to be taken.
   a GPU or the network.
 - Give a layer two depths: a layer in front of another in one place and behind it in
   another is right in the still and wrong in motion.
-- Expressions, lip-sync, or any animation but one looping `idle`.
+- Propose, key or judge any animation but the looping `idle`, or lip-sync: every slot
+  holds one attachment, so nothing swaps a part's image. Expressions and a jiggle are
+  yours to build on top (below).
 - Write animated WebP: `loop` writes GIF and APNG.
 - Know what the art does not tag: a swinging element painted inside another layer,
   hair of an unfamiliar shape, whether an accessory swings. Those are yours to add.
-- Promise a success rate. Two public characters and eight private ones check green;
+- Promise a success rate. Three public characters and eight private ones check green;
   that is all that has been measured.
 
 ## Where to read next
@@ -144,6 +153,15 @@ share is synthesis where the painting was there to be taken.
 [docs/AUTHORING.md](https://github.com/firejune/rig-parts/blob/main/docs/AUTHORING.md)
 first — every config field, the command order, what to read after each stage, every
 refusal. It is in the installed package at `node_modules/rig-parts/docs/AUTHORING.md`,
-the copy that matches the version you run. A `RIG_RIGC_GREEN` or `CHECK_RIGC_GREEN`
+the copy that matches the version you run. Two recipes there cover what this package
+leaves to you:
+
+- An expression or any other named animation: AUTHORING §3, *Recipe: expressions and other
+  named animations* (`motion.animations_from`; built and gated with the rig, not measured).
+- A jiggle (a bust, the hips): AUTHORING §3, *Recipe: a soft region driven by physics* (a
+  config-only bone, a `contour` region on it, a `physics` constraint; `examples/sample`
+  carries one, and its slow idle barely moves it).
+
+A `RIG_RIGC_GREEN` or `CHECK_RIGC_GREEN`
 line quotes rig-c's own assertion; rig-c's guide for those is
 `node_modules/rig-c/docs/AUTHORING.md`, and its `rigc` skill covers the compiler.