@rig-c/parts 0.0.0-stage → 1.5.3

package/docs/MIGRATION.md

@@ -0,0 +1,137 @@
+# Migrating from 0.16.0
+
+0.16.0 was the last version published under the package's former name. This page is
+what changed between it and 1.0.0 for a user of the command, an author of a config
+and a reader of the files a build writes; what 1.0.0 holds stable is
+[STABILITY.md](STABILITY.md). It comes in two parts: 0.16.0 to the release candidate
+1.0.0-rc.1, then what landed between the candidate and 1.0.0. Every figure is quoted
+from the pull request that measured it.
+
+## In one paragraph
+
+Install `rig-parts`. A config that built on 0.16.0 loads and builds unchanged: every
+config change since is a new, opt-in field inside a new mesh mode. The bytes a
+config without that mode builds moved once, by a declared exception (every mesh
+triangle's vertex order, #133); apart from it, each change since 0.16.0 that touched
+the code was measured against the tree before it on the three public examples'
+builds, and moved no byte of them. Inside the automatic mode, one change after the
+candidate moves declared bytes, named in *Since 1.0.0-rc.1*: the skinning envelope's
+reference (#169).
+
+## From 0.16.0 to 1.0.0-rc.1
+
+### The package name
+
+| | 0.16.0 | 1.0.0-rc.1 and 1.0.0 |
+| --- | --- | --- |
+| npm package | the former name | `rig-parts`; the alias `spine-parts` is published beside it at every version, the same files with only the `name` in `package.json` changed |
+| command | the former name | `rig-parts`; the install also keeps the alias `spine-parts` as a second command on the same launcher, for the transition |
+| repository | the former repository name (GitHub redirects it) | `firejune/rig-parts` |
+| selftest variables | the `SPINE_PARTS_` names | `RIG_PARTS_CORPUS`, `RIG_PARTS_SELFTEST_JOBS`, each read first, with the former `SPINE_PARTS_` name read when it is not set |
+| spec ids of the files authors write and this package writes | `spine-parts-requirements/1`, `spine-parts-scene/1`, `spine-parts-keypoints/1`, `spine-parts-bonemap/1`, `spine-parts-basis/1`, `spine-parts-scene-report/1` | unchanged: they name a file format, not the tool, so a file written before the rename still reads |
+| public examples repository | `spine-parts-examples` | unchanged (it keeps the name it was published under) |
+
+What to do: install with `npm install -g rig-parts` and write `rig-parts` in scripts.
+A script or a dependant that names the alias `spine-parts` keeps working and keeps
+receiving every release; how long the alias stays is RELEASING.md's *The alias stays
+until its retirement questions have written answers*. No build output carries the
+package name: a grep of all 330 files the three example builds write found neither
+spelling (#142). The console does: the lines that name the tool (5 per build: the
+`build`, `assemble`, `rig` twice and `check` lines) now say `rig-parts`. Where a
+config uses a constraint or `--idle-keys direct`, the `why` prose this package writes
+into `rig.json`'s invariants names `rig-parts` too; that prefix is the one known
+output change of the rename (#142).
+
+### rig-c, as this package sees it
+
+The dependency is `rig-c` `^2.33.0` at 1.0.0 (`^2.31.0` at 1.0.0-rc.1; the moves
+between the two are in *Since 1.0.0-rc.1*), where 0.16.0 took the same upstream
+package under its former npm name at `^2.15.0`; that name is spelled only in `CHANGELOG.md`.
+The upstream package was renamed on npm at 2.20.4 with the same `exports` map
+(#138), and every import, probe and sentence here names `rig-c`. A project that
+installed the former upstream name beside this package installs nothing more:
+`rig-c` comes as a dependency. No Spine runtime is a dependency, as in 0.16.0.
+
+### The config
+
+**A config that built on 0.16.0 loads unchanged.** The loader's only change between
+the two is one more optional key, `auto`, on `meshes.<part>`, and the objects under it;
+no key was removed, renamed or made required outside it, and no CLI flag was added or
+removed (`git diff v0.16.0` of `src/config.ts` and `cli.ts`). `grid` and `contour`
+meshes read exactly as before, and `propose` still writes `grid`.
+
+What an author who adopts the new mode meets (AUTHORING §3, *An automatic mesh*):
+
+- **`meshes.<part>.auto`**, the third mesh mode (#131): the contour mesh at alpha 1
+  and above, reduced and locally refined by rig-c's `reduceMesh` under declared
+  bounds. Exactly one of `grid`, `contour` and `auto` per mesh.
+- **`motion` is required in it** (#134): at least `maxLocalDeformation`, the bound
+  the reduced mesh's motion against its unreduced source on the idle must meet
+  before the part is written. A part the idle cannot deform is refused, never
+  passed.
+- **`maxOvershoot` and `maxUndercut` take `null`** (#139), in `sourceBounds` and in
+  `targets.artFit`: measured and reported, not bounded. Leaving the field out is
+  still refused by name.
+- **The acceptance loop** (#141) replays a less-reduced step when the motion gate
+  refuses the full reduction; it needs no field. **`motion.selection`** (#151,
+  opt-in) replaces its bisection with a budgeted multi-interval search.
+- **The Stage B opt-ins** (#147): `boundaryRuns`, `retriangulate`, `removalOrder`.
+- **`motion.gradation`** (#150, opt-in): the author's G for rig-c's allocation
+  contrast row.
+- **`motion.residual`** (#152, opt-in): the skinning residual as a per-step veto.
+
+Without any of these the mode's output is what it was before each was added: every
+pull request that added one compared the opt-out run against the tree before it,
+byte for byte.
+
+### The bytes a build writes
+
+| change | what moved | measured |
+| --- | --- | --- |
+| #131, the automatic mode | nothing for a config without `auto` | 330 of 330 files of the three example builds identical, main at rig-c 2.15.0 against the change at 2.19.0 |
+| #133, the winding | **the declared exception**: every mesh `triangles` triple `[a, b, c]` is written `[a, c, b]` (counter-clockwise in Spine world), in `rig.json`, the compiled `skeleton.json`, `skeleton.model.json` and the render's `geometry.json`; the `TEXTURE_STRETCH` entries in `check.json` that print a triangle's vertices and edge print them in that order; `spine.sha256` follows the skeleton bytes | every rendered PNG byte-identical before and after; the triangle index, the unordered edge, the frame, the ratio and the severity unchanged |
+| #134, #137 to #142, #146, #147, #150, #152 | nothing | 330 of 330 at each, against the tree before it; the console differs in the one `rigc <version>` line per build where rig-c moved |
+| #172 unit 1b, one mask under `stray` | nothing for a part without `auto.source.stray`; a part that declares it now builds where its extra islands at or under the figure refused it (`REDUCE_SOURCE_FAILS_ITS_ART_BOUNDS`): the islands are cleared from the art every reader of the mesh takes, and its row gains `stray_cleared` (islands, pixels, art pixels) and its mesh line a `stray cleared` clause; the written image is the part as assembled | the selftest's `SY01`–`SY06` on a synthetic crumb part; a part without `stray` reads the very mask object it read before (`SY03`) |
+| #151, the multi-interval selection | nothing without `motion.selection` | measured on the selftest's fixture configs, not the example builds: rig.json, motion.json, mesh_report.json and the printed log identical in all six configurations; #152 then measured the example builds against the tree #151 left, 330 of 330 |
+
+What to do: a consumer that compares a build with one 0.16.0 wrote, byte for byte,
+expects the #133 exception and nothing else; one that reads the meshes (a renderer,
+a culling pass, rig-c's own orientation rows) now reads every triangle
+counter-clockwise in Spine world, as rig-c writes its own. Spine does not cull, so
+nothing draws differently.
+
+## Since 1.0.0-rc.1
+
+Every change below is additive to the interface: a field that was refused is now
+accepted, or a build that was refused now builds; nothing a 1.0.0-rc.1 config could
+say is removed or reads differently, outside the declared byte move below. No CLI
+flag was added or removed.
+
+- **Density-only regions** (#156, opt-in): an `auto.regions` entry may leave out both
+  `bone` and `band` to ask rig-c for density without touching any weight. One without
+  the other is refused by name (`CONFIG_REGION_BAND_NEEDS_BONE`,
+  `CONFIG_REGION_BONE_NEEDS_BAND`; at 1.0.0-rc.1 the same input was refused
+  `CONFIG_FIELD_PRESENT`, naming the missing field), and a region with both reads as
+  before. A config without such a region builds as before.
+- **The skinning envelope's reference** (#169), **the declared byte move**: under
+  `motion.residual`, the envelope rig-c's reducer is sent is derived against the
+  lowest common ancestor of the slot's bone and every bone the part's weights bind,
+  where 1.0.0-rc.1 derived it against the slot's bone and, when a bound bone did not
+  hang below it, sent no target, so the residual veto did not apply. Such a part's
+  reduction, written mesh and `mesh_report.json` row move; a part whose bound bones
+  all hang below the slot's bone makes the same call as before. The
+  `skinning_residual` row keeps its shape: its `reference` names the bone the envelope
+  was derived against, and a part whose reference is not the slot's bone carries a
+  second `rule` sentence naming the rule. `ENVELOPE_BONE_NOT_BELOW_REFERENCE` keeps
+  its name and its check.
+- **rig-c `^2.33.0`** (#163, #166, #173, from `^2.31.0`): 2.32.1 refuses, by name, a
+  refinement insertion whose triangle would read as degenerate (`MQ_DEGENERATE`)
+  instead of writing it (rigc#1311); 2.32.2 no longer misrefuses a motion sample on an
+  edge two triangles share (`COMPARE_UV_CARRIER_NOT_UNIQUE`, rigc#1323); 2.33.0 adds
+  named interior lines, which this package does not send. The three example builds
+  are byte-identical across the move (#173).
+
+What to do: nothing for a config without `auto`. A config under `auto` that declares
+`motion.residual` may write a different mesh than 1.0.0-rc.1 did, as above; a
+consumer that compares builds byte for byte with 1.0.0-rc.1 expects that move and
+nothing else.

package/docs/STABILITY.md

@@ -0,0 +1,262 @@
+# Interface stability
+
+This page states what **1.0.0 holds stable**, and what it does not. Every item is
+read off the tree: the command and flag lists below are held to
+`cli.ts`, and the config field list to the loader in `src/config.ts`, by the
+selftest's `TY13` and `TY14` (the `tree` suite), so neither list can drift from the
+code without a red run. What changed for an author coming from 0.16.0 is
+[MIGRATION.md](MIGRATION.md).
+
+## What "stable" means here
+
+From 1.0.0 the package follows semantic versioning over the items on this page. A
+stable item is not removed, renamed, or given another meaning inside a major
+version; a new command, flag, optional config field, report key or refusal may
+arrive in a minor version, because a reader written against the old surface still
+reads it. A refusal may be retired in a minor version when what it refused becomes
+accepted (0.13.0 retired two ik refusals that way, when rig-c's parser took them
+over).
+
+The list was frozen for review at the release candidate 1.0.0-rc.1, and 1.0.0 was
+promoted from it after the owner's acceptance of the production evidence (issue #126,
+item 7; `docs/evidence/production-trial.md` in the repository). Every interface
+change between the two is additive, and [MIGRATION.md](MIGRATION.md)'s *Since
+1.0.0-rc.1* names each one, with the build bytes that moved.
+
+Bytes are a separate promise, and a narrower one: **one version of this package
+with one installed rig-c writes the same bytes for the same inputs** (*Determinism*
+below). A build's bytes are not promised across versions. A later version may move
+them, and when it does, the change that moves them declares which bytes and why (the
+winding change of #133 is the example: [MIGRATION.md](MIGRATION.md)).
+
+## Commands and flags
+
+Exit codes are part of the interface: **0** the command did what it says, **1** it
+refused its input (every reason a `FAIL` line), **2** a usage error or a command
+this version does not implement. No command is unimplemented at 1.0.0 (`LATER`
+in `cli.ts` is empty). A refusal line has the shape
+`  FAIL  <RULE>: <object> — <value found>; <value required>`: the rule name is a
+stable identifier, and the detail after it is prose that may be reworded. A command
+also answers to the alias `spine-parts` as long as the install keeps it
+([MIGRATION.md](MIGRATION.md)). `-h`, `help` and `-v` are the short forms of
+`--help` and `--version`. The flags' meanings are `rig-parts --help`'s; their
+defaults are the help's too, and none is guessed from the art.
+
+<!-- stable:commands -->
+| command | flags |
+| --- | --- |
+| `layers` | one positional path: a wrapper directory, a `layers.json` or a `.psd` |
+| `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols` |
+| `inputs` | `--source`, `--config`, `--out` |
+| `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
+| `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll` |
+| `assemble` | `--propose-plan` with `--source`, `--full`, `--head`, `--config`; or `--source`, `--full`, `--head`, `--config`, `--out`, optional `--seam` (near-white, silhouette), `--project` (core, visible) |
+| `propose` | `--head-box` with `--full`, `--canvas` |
+| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`) |
+| `compare` | `--left`, `--right`; optional `--map` |
+| `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
+| `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills` |
+| `loop` | `--frames`, `--out`; optional `--palette` |
+| `build` | `--config`, `--source`, `--full`, `--head`, `--out`; optional `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--requirements`, `--idle-keys` |
+| `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
+| (none) | `--version`, `--help` |
+<!-- /stable:commands -->
+
+`TY13` holds the first column to the commands `cli.ts` dispatches and the set of
+flags named anywhere in the table to the set of flags `cli.ts` spells. It holds the
+names, not which command takes which flag: that pairing is the CLI's, and the `cli`
+suite's controls read it from the help.
+
+## The config contract
+
+`src/config.ts` is the schema and the loader, and
+[AUTHORING §3](AUTHORING.md#3-configjson-field-by-field) explains every field. The
+rules that make the contract:
+
+- **Every key is known or refused** (`CONFIG_KEY_KNOWN`), a required key that is
+  missing is refused by name (`CONFIG_FIELD_PRESENT`), and nothing is defaulted
+  from the art. A field absent where absence means "none" (a contour's `stray`, an
+  automatic mesh's `minAngle`) is written as that in the report, never filled in.
+- **Two open doors, and nothing reads behind them**: `note` and any key ending in
+  `_note` hold a string anywhere an object is; any key beginning `x-` with a name
+  after it holds any JSON value in the same places. They are not open in `meshes`,
+  `regions` or `motion.blink.still`, whose keys are part names.
+- **Coordinates** in `bones`, `meshes` and `motion` are rig pixels, y down, origin
+  top-left.
+- **A mesh is one of three modes**: `grid` (the lattice, what `propose` writes),
+  `contour` (the traced outline with declared interior points) or `auto` (the
+  automatic mode: the contour mesh at alpha 1 and above reduced by rig-c's
+  `reduceMesh` under declared bounds, written only when its motion against the
+  unreduced source passes the author's bounds). Two, or none, is
+  `CONFIG_MESH_MODE`. The top-level default does not change: `propose` writes
+  `grid`, and a config that names no `auto` builds as it did before the mode
+  existed.
+- **`constraints`** are rig-c's own rig-spec constraints (`RigConstraint` in
+  rig-c's `src/rig.ts`), handed to rigc as written; this loader checks their
+  `type`, their `name` and that every bone they name resolves.
+
+The fields, object by object (a bold path is where the object sits; `<part>` is a
+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`, `constraints`
+- **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`
+- **generation.control** — required: `skeleton`, `strength`, `end_percent`; optional: `model`
+- **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
+- **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`
+- **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`; optional: `under`
+- **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.&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`
+- **meshes.&lt;part&gt;.ribs.&lt;chain&gt;** — required: `stations`
+- **meshes.&lt;part&gt;.contour** — required: `tolerance`, `margin`, `spacing`; optional: `budget`, `stray`, `regions`
+- **meshes.&lt;part&gt;.contour.regions[i]** — required: `name`, `shape`, `bone`, `spacing`, `band`, and `cx`, `cy`, `r` for a circle or `points` for a polygon
+- **meshes.&lt;part&gt;.auto** — required: `source`, `sourceBounds`, `targets`, `influences`, `budget`, `minArtSamples`, `motion`; optional: `protect`, `regions`, the three Stage B opt-ins `boundaryRuns`, `retriangulate`, `removalOrder`, and `stimulus`
+- **meshes.&lt;part&gt;.auto.source** — required: `tolerance`, `margin`, `spacing`; optional: `stray`
+- **meshes.&lt;part&gt;.auto.sourceBounds** and **meshes.&lt;part&gt;.auto.targets.artFit** — required: `minCoverage`, `maxOvershoot`, `maxUndercut` (each of the last two a number or null, the bound declared absent)
+- **meshes.&lt;part&gt;.auto.targets** — required: `artFit`, `maxBoundaryDeviation`; optional: `minAngle`
+- **meshes.&lt;part&gt;.auto.influences** — required: `maxInfluences`, `minWeight`
+- **meshes.&lt;part&gt;.auto.budget** — required: `maxCandidates`
+- **meshes.&lt;part&gt;.auto.motion** — required: `maxLocalDeformation`; optional: `maxStretch`, `minStretch`, `deformMayFold`, `gradation`, `selection`, `residual`
+- **meshes.&lt;part&gt;.auto.motion.selection** — required: `policy`, `maxProbes`
+- **meshes.&lt;part&gt;.auto.motion.residual** — required: `maxResidual`
+- **meshes.&lt;part&gt;.auto.protect** — optional: `hull`, `vertices`, `edges`, `regionBoundaries`, `weightJump`, `influences`
+- **meshes.&lt;part&gt;.auto.regions[i]** — required: `name`, `shape`, `maxEdgeLength`, `transition`, `grade`, `minArtSamples`, and `cx`, `cy`, `r` for a circle or `points` for a polygon; optional: `bone`, `band` (both or neither; with neither the region is density only)
+- **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`
+- **regions.&lt;part&gt;** — a bone name
+- **motion** — required: `duration`, `tracks`; optional: `blink`, `animations_from`
+- **motion.tracks[i]**, a single track — required: `bone`, `prop`, `amp`, `period`, `phase`; optional: `base`
+- **motion.tracks[i]**, a chain track — required: `chain`, `amps`, `period`, `phase`, `lag`
+- **motion.blink** — required: `t`, `eyes`, `squash`; optional: `brows`, `brow_drop`, `still`
+- **motion.blink.still.&lt;part&gt;** — required: `row`, `bone`
+- **motion.animations_from**, the file it names — required: `spec`, `animations`
+- **proposal.json**, the file propose writes — `bones`, `meshes`, `regions`, `motion` under the rules above, and `notes`
+<!-- /stable:config -->
+
+`TY14` holds the set of field names in backticks above to the set of names the
+loader's object checks spell (every `c.object(…)` in `src/config.ts`, with the lists
+they name), in both directions, and refuses an object check whose key list it cannot
+read. It holds the names, not their nesting or which are required: the `config`
+suite's controls hold those, refusal by refusal.
+
+The values a field takes (`retriangulate` is "delaunay", `removalOrder`
+"deformation-load", `selection.policy` "multi-interval"; the units and ranges of
+every number) are AUTHORING §3's tables, and the loader refuses any other by name.
+
+## Files this package writes
+
+| file | written by | what is stable |
+| --- | --- | --- |
+| `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`); `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 — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `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` |
+| the scene report | `compose` | spec `spine-parts-scene-report/1` |
+| `idle.png`, `idle-indexed.png`, `idle.gif` | `loop`, `build --loop` | APNG and GIF encodings of the rendered idle |
+
+Files authors write for this package, each with a spec id the reader holds:
+`spine-parts-requirements/1` (`check --requirements`), `spine-parts-scene/1`
+(`compose --scene`), `spine-parts-keypoints/1` (`propose --keypoints`),
+`spine-parts-bonemap/1` (`compare --map`). The spec ids keep the package's former
+name on purpose: they name a file format, not the tool, and a file written before
+the rename still reads. They do not change at 1.0.
+
+## Environment
+
+The installed package reads two environment variables and no other: `PATH`, where
+the launcher finds Bun and the CLI finds the `rigc` its own `node_modules` holds,
+and `COMFY_HOST`, which `comfy paint` and `comfy seethrough` read when `--host` is
+not given (it has no default). `RIG_PARTS_CORPUS` and `RIG_PARTS_SELFTEST_JOBS`,
+with their former `SPINE_PARTS_` names read when they are not set, are the
+selftest's, a development interface of this repository: the selftest does not ship
+in the package.
+
+## rig-c
+
+`dependencies` takes `rig-c` `^2.33.0`: 2.33.0 or any later 2.x. Bun 1.2 or later
+runs the package (`engines`). What this package relies on in rig-c, every import
+read off `src/` and `cli.ts`:
+
+- the named entries `rig-c/mesh` (the outline functions, `measureAuthoredMeshFit`,
+  `reduceMesh`, `skinningEnvelopeBone`, `writeMeshQualityReport` and their types)
+  and `rig-c/meshcompare` (`compareMeshesInMotion`);
+- the deep paths its `exports` map carries: `rig-c/src/rig.ts` (`parseRigSpec`,
+  `RIG_SPEC_VERSION`, the constraint keys), `rig-c/src/errors.ts`,
+  `rig-c/src/png.ts`, `rig-c/src/transform.ts` (the y flip, through
+  `src/coords.ts` only), `rig-c/tools/plate.ts` (the PNG codec) and
+  `rig-c/tools/font5x7.ts`;
+- the `rigc` command: `build` and `render`, and `--version`, whose `entry:` line
+  says which validator gated a build (`check.json`'s `rigc_entry`).
+
+A rig-c release that moves any of these breaks this package by name, and the
+install smoke is where that shows first. No Spine runtime is a dependency: an
+install is gated by rigc's own validator, and `@esotericsoftware/spine-core` is a
+development dependency of this repository only.
+
+## What is not stable
+
+- **The evidence documents** under `docs/evidence/`: their layout, columns and
+  figures are a measurement record of one tree on one rig-c, regenerated when the
+  tools or rig-c move.
+- **The tools** under `tools/` (the matrix, the surveys, the comparisons) and their
+  command lines, and the scripts under `scripts/`.
+- **The selftest**: its control names, counts and line wording.
+- **Console prose** beyond the shapes above: the detail after a rule name, the
+  wording of a note, the order of informational lines.
+- **The examples' `expected/` outputs**: they are this repository's regression
+  record and move with any change that declares a byte move.
+- **Bytes across versions**, as stated at the top.
+
+## Bounded time, and what the checks cost
+
+The automatic mode's search is bounded by counts the author declares or the call
+derives, never by a clock (`src/` reads none): rig-c's `reduceMesh` tries at most
+`budget.maxCandidates` steps, the acceptance loop replays at most ⌈log₂(N − I)⌉
+removal steps (N the call's accepted operations, I the refinement's), and the
+multi-interval selection at most `motion.selection.maxProbes`, each replay one
+unpacked gated build and one motion comparison. Wall time is therefore a property of
+the input and the machine. Measured: the evidence tools run every cell under a
+600 s cap and a whole matrix under 2,700 s (`docs/evidence/auto-mesh-matrix.md`,
+*re-running*); one `reduceMesh` call on the public parts took 0.7 s to 10.7 s at
+rig-c 2.23.0 (the same document's quiet timing table, a remote WSL runner, pool,
+load under 2); at rig-c 2.31.0 the whole rig stage of one automatic part, motion
+gate and acceptance loop included, took 1.1 s to 61.6 s on the eight parts the
+surveys switch, demo `bottomwear` the slowest at 12 gated builds, with a run-to-run
+spread of ±15 % on that part (pull request #152's paired exclusive timing, remote
+20-core runner; the surveys print wall time to standard error, not into the
+documents). On CI (`ubuntu-latest`), the last two green runs on `main` took 4 min
+54 s and 8 min 28 s for the full selftest (842 controls over 45 suites at
+`22b2c5a`, with the public examples fetched; the job's limit is 20 minutes) and
+42 s and 41 s for the install smoke (6 cases; limit 10 minutes), at `8be4cd1` and
+`22b2c5a` respectively. None of these figures is a promise: they are what the named
+runs measured.
+
+## Determinism
+
+The same inputs, with the same version of this package and the same installed
+rig-c, write the same bytes: fixed key order in every JSON written, stable sorts, no
+clock, no randomness and no locale-sensitive formatting. `src/` is pure outside
+`src/comfy/` (`TY06` refuses a clock, randomness or network call anywhere else under
+`src/`). The selftest holds it by running the same thing twice and comparing the bytes:
+`PN01` (the PNG codec), `PT01` (`parts.json` round trip), `AS07` (`assemble`
+from the CLI), `SK04` (the skeleton), `RG03` (two lattice builds), `CW20` and
+`CT20` (a contour rig and a contour mesh), `AM24` (an automatic mesh), `MO11`,
+`MO27`, `MO44`, `MO50`, `MO63` and `MO74` (the motion gate, the acceptance
+loop's replay, every Stage B opt-in, a gradation, the multi-interval selection's
+policy path and the residual veto), `CK02`, `CK33` and `CK79` (`check`, its
+stretch geometry, and `check --requirements`), `DG13` (`basis.json`), `LP08`
+(the indexed APNG) and `ST26` (the `compare` printout). With the public examples
+fetched, the `chain` suite builds each of them and holds `parts.json`
+(`CH02`), `rig.json`, `motion.json` and `mesh_report.json` (`CH03`),
+`check.json` (`CH04`) and the gate file (`CH05`) to its tracked `expected/`,
+field by field, with the tolerances `CH07` plants against.

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@rig-c/parts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.3",
+  "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": {
+    "rig-parts": "./bin/rig-parts.cjs",
+    "spine-parts": "./bin/rig-parts.cjs"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "license": "MIT",
+  "author": "firejune",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/firejune/rig-parts.git"
+  },
+  "homepage": "https://github.com/firejune/rig-parts#readme",
+  "bugs": "https://github.com/firejune/rig-parts/issues",
+  "keywords": [
+    "spine",
+    "spine2d",
+    "spine-2d",
+    "ai",
+    "ai-agents",
+    "rigging",
+    "character-rigging",
+    "character-parts",
+    "layer-decomposition",
+    "see-through",
+    "anime",
+    "live2d-alternative",
+    "weighted-mesh",
+    "skeletal-animation",
+    "psd",
+    "cli"
+  ],
+  "files": [
+    "bin/rig-parts.cjs",
+    "cli.ts",
+    "src",
+    "workflows",
+    "docs/AUTHORING.md",
+    "docs/MIGRATION.md",
+    "docs/STABILITY.md",
+    "skills",
+    "NOTICE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "fetch-examples": "bash scripts/fetch-examples.sh",
+    "selftest": "bun selftest.ts",
+    "smoke": "bun scripts/install_smoke.ts",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx eslint .",
+    "prepublishOnly": "bun run typecheck && bun run lint && bun run selftest"
+  },
+  "dependencies": {
+    "ag-psd": "^31.0.2",
+    "rig-c": "^2.33.0"
+  },
+  "devDependencies": {
+    "@esotericsoftware/spine-core": "4.3.13",
+    "@types/bun": "^1.4.2",
+    "eslint": "^10.11.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.1"
+  }
+}

package/skills/rig-parts/SKILL.md

@@ -0,0 +1,167 @@
+---
+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 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.
+---
+
+# rig-parts — a painting to a Spine rig, for agents
+
+rig-parts merges See-through's two layer runs over one painting into rig-space
+parts, authors a rig spec and a motion spec over them, and hands those to
+rig-c, which compiles, gates, packs and renders. You cannot see the painting,
+the layers or the rig. The printed lines, `docs/AUTHORING.md` and the files each
+stage writes are the whole interface.
+
+## Non-negotiables
+
+- **rig-c's gate is never bypassed.** rig-parts writes no Spine data
+  itself; `rig` writes only after rigc's `build` gate is green, and `build`'s
+  artifact is what rigc wrote. There is no flag that skips it, and none may be added.
+  `check.json`'s `rigc_entry` names which gate ran: rigc's own validator in an
+  install, the spine-core round trip where the runtime is installed beside rigc.
+- **No value is invented.** A missing config field is a refusal naming it. Take a
+  value from the command that proposes it (`propose --head-box`,
+  `assemble --propose-plan`, `propose`) or decide it yourself — never guess one
+  because the tool refused.
+- **The refusal is the instruction.** `FAIL  RULE: object — detail` names the object,
+  the value found and the value required; AUTHORING §6 maps every rule to the field
+  or input that has to change.
+- **Green is not "looks right".** `check` measures the gates, the seam, the loop and
+  six judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`,
+  `TIP_OVER_ROOT`, `STILL_REGIONS_DARK` — its face half in the head's own frame —
+  and `TEXTURE_STRETCH`) (AUTHORING §7). A judgement line that says
+  SKIP was not verified: report it as such, with its reason, never as passed.
+  No line judges a bang over the face or the eyes: `STILL_REGIONS_DARK`'s
+  `crossing` reports how deep each one swings, and only an eye can say whether
+  that reads right.
+- **What a scene asks is declared, not assumed.** When the request says what the
+  motion must do — a hand on a cup, a sleeve taking half an arm's turn, a joint
+  inside a range, a fringe that must not part from the face — write it into a `spine-parts-requirements/1` file and pass
+  `check --requirements <file>` (or `build --requirements`); every bar in it is the
+  requester's, never yours to invent (AUTHORING §7, *Declared requirements*). Each
+  line is PASS, FAIL or NOT MEASURABLE; a NOT MEASURABLE is not green, and a kind the
+  file does not declare was not measured — say so, never "passed".
+- **A hole in the layers is invisible to every bar.** Painting that no part holds is
+  missing from the setup pose and from the flat stack alike, so the seam passes over
+  it. `assemble` lists it (`uncovered hole N: <px> px at x,y wxh (between …)`) and
+  paints it red in `recomposite_error_rig.png`; `check` copies it into `check.json` as
+  `RECOMPOSITE_HOLES`, a REPORTED line with no bar. Read it; never report it as a
+  pass.
+
+## The loop
+
+1. `rig-parts inputs --source <painting> --config config.json --out <dir>` writes
+   `st_input_full.png`, the painting on a white square. The config needs only `key`,
+   `seethrough` and `assemble.rig_scale` at this point. Run See-through on it — any
+   route; the optional `comfy seethrough` adapter only talks to a ComfyUI box.
+2. `rig-parts layers <full run>` — read the table. A `WARN  PLAN_LAYER_…` line names
+   a layer See-through invented (a translucent haze, or one out of proportion);
+   the plan step leaves it out and says so in its `notes`.
+3. `rig-parts propose --head-box --full <full run> --canvas <W>x<H>` → put
+   `head_box` in the config, run `inputs` again (it now also writes
+   `st_input_head.png`, the crop at that box), and run See-through on the crop.
+4. `rig-parts assemble --propose-plan …` → `config.assemble.plan` and
+   `extend_below_crop`.
+5. `rig-parts assemble … --out work` — read the `uncovered hole` lines and look at
+   `work/render/recomposite_error_rig.png`; a large red hole between two parts is a
+   gap See-through left (a skirt split into two legs), fixed in the plan or the layers,
+   not in the rig. Then `rig-parts propose --parts work/rig
+   --source <painting> --out work` → copy `bones`, `meshes`, `regions`, `motion`
+   from `proposal.json` into the config. `assemble` needs the plan and none of
+   those four; do not stub them to get past it (AUTHORING §4 says what each step
+   requires). If an `uncovered hole` stays large with the plan right — a piece
+   of the figure neither run holds, red in `recomposite_error_rig.png` — add an
+   `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
+   the joints, not screen y. Never write a joint you did not get from an
+   estimator or the painting: say `missing` and let the rule stand in.
+6. Correct against `render/landmarks.png` and `note:` lines; a
+   `coverage … not checked` line is a bone no check read (the line says why),
+   and `basis.json` beside the proposal says what each bone rests on — check
+   the `ratio` bones and any with a `fallback` first. `propose …
+   --from-config config.json` (with the same `--keypoints`) until it prints no
+   `LINT` line. `rig-parts compare
+   --left work/proposal.json --right config.json` lists what the correction changed,
+   bone by bone — origin, parent, tip, length, direction (AUTHORING §4).
+   A constraint the motion needs (an ik reaching a scene target, physics on a
+   link) goes in `config.constraints`, in rig-c's own rig-spec shape: the
+   loader resolves the bones it names and nothing else, and rigc's gate refuses
+   the rest in its words. A scene target is a single bone under `root`. A two-bone
+   ik over links the idle keys needs `--idle-keys direct` on `rig` or `build`
+   (rigc refuses the pair the link's control splits, and the line names the flag
+   on the command that ran; AUTHORING §3).
+7. `rig-parts build --config … --source … --full … --head … --out out --loop`
+   (add `--idle-keys direct` when step 6 said so).
+   It stops at the first stage that refuses, printing that stage's lines under
+   `[assemble]`, `[rig]` or `[check]`. Fix what the FAIL line names and build again.
+8. Read `out/check/check.json` — the six judgement lines the same way as the seam
+   and the loop: a FAIL names the field to change (AUTHORING §6);
+   `TEXTURE_STRETCH` names the worst mesh triangle (slot, triangle, vertices, edge,
+   frame), so quote it even on a PASS. Quote
+   `RECOMPOSITE_HOLES` (uncovered px, hole count, the largest hole's box) in the
+   report whatever `PASS` says. The artifact is the three paths the build prints
+   last: `check/build/skeleton.json`, `skeleton.atlas` and the packed page. Report
+   them with the pack line and the check figures verbatim.
+
+Several characters in one rig: build each one green on its own, then
+`rig-parts compose --scene scene.json --out scene` (spec `spine-parts-scene/1`:
+the canvas, each character's `build` and `offset`, an optional plate with its
+`provenance`, and the `order` of the characters' slots, back to front). You write
+the order and the offsets; nothing infers them, nothing scales a character, and
+nothing detects or separates people. Report the plate's provenance as you declared
+it and the order as `scene.json` records it (AUTHORING §7, *Composing several
+characters*).
+
+`--seam silhouette` repairs more of the seam on white garments than the default
+`near-white` (the demo: 10,340 → 8,644 recomposite error pixels); the default is
+the reference implementation's rule. `--project visible` lets thin visible parts
+(lashes, brows, irises) take the painting's pixels, which the default `core` rule
+erodes away. Name both rules you used in your report, and quote the assemble
+`pixels:` line: its occluded share is hidden art, its "visible but not projected"
+share is synthesis where the painting was there to be taken.
+
+## What this will not do
+
+- Run See-through or generate the painting itself. The optional `comfy seethrough`
+  and `comfy paint` commands drive a ComfyUI box you name; nothing else here reaches
+  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.
+- 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. Three public characters and eight private ones check green;
+  that is all that has been measured.
+
+## Where to read next
+
+[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. 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.