spine-parts 0.4.0 → 0.5.0

package/NOTICE.md

@@ -39,12 +39,14 @@ wrapper code.
 | Weights | Licence as stated on the model card | Observed |
 | --- | --- | --- |
 | [`layerdifforg/seethroughv0.0.2_layerdiff3d`](https://huggingface.co/layerdifforg/seethroughv0.0.2_layerdiff3d) | `license:apache-2.0` tag | 2026-09-27, Hugging Face model API |
+| (same card, after its 2026-09-28 commit *"Add licence terms, NOTICE and base model metadata"*) | `license:openrail++` tag; the card's *Licence* section says the maintainers' own contributions are Apache-2.0 and the weights also inherit the licences of the models they are derived from — Animagine XL 4.0 / Stable Diffusion XL 1.0 (CreativeML Open RAIL++-M) and LayerDiffuse (CreativeML Open RAIL-M) | 2026-09-28, Hugging Face model API and card |
 | [`layerdifforg/seethroughv0.0.1_marigold`](https://huggingface.co/layerdifforg/seethroughv0.0.1_marigold) | no licence tag on the card | 2026-09-27, Hugging Face model API |
+| (same card, after its 2026-09-28 revision) | `license:openrail++` tag | 2026-09-28, Hugging Face model API |
 
 Maintainer statement, on the Hugging Face discussion
 [`layerdifforg/seethroughv0.0.2_layerdiff3d/discussions/1`](https://huggingface.co/layerdifforg/seethroughv0.0.2_layerdiff3d/discussions/1)
 (user `24yearsold`, 2026-04-07): *"Yes all our models are aligned with our main
-repo to use Apache 2.0."*
+repo to use Apache 2.0."* The 2026-09-28 card revision above narrows that: Apache-2.0 for the maintainers' contributions, with the base models' Open RAIL terms inherited. spine-parts does not distribute these weights; a user who fetches them accepts the terms the card states on the day they fetch.
 
 ### Training data
 

package/README.md

@@ -90,7 +90,7 @@ page** (issue #2):
 | `check/build/skeleton.json`, `skeleton.atlas`, `skeleton.png` | **the artifact** — Spine 4.3 skeleton data and one packed page, written by `rigc build --pack` and gated under both profiles |
 | `parts/*.png`, `parts.json`, `recomposite_rig.png`, `recomposite_error_rig.png` | the loose parts, each cropped to its alpha box; the record of where every part came from, how many of its pixels were re-taken from the painting, and the recomposite's uncovered holes with their boxes; the flat stack of parts; its error map — red where no part covers a pixel the painting has, blue where a part covers it in the wrong colour |
 | `rig/` | `rig.json` and `motion.json` in spine-rigc's spec, `mesh_report.json`, the padded `images/` |
-| `check/` | both gate files verbatim, the idle's frames, `contact.png`, `motion_heat.png`, `check.json` |
+| `check/` | both gate files verbatim, the idle's frames and their `geometry.json` (skinned vertices per frame), `contact.png`, `motion_heat.png`, `check.json` |
 | `idle.png`, `idle-indexed.png`, `idle.gif` | with `--loop`: the idle as a lossless APNG (the exactness record), an indexed APNG with one shared palette (the small one) and a GIF; the last two print their palette error |
 
 The last lines of a green build are the pack line, printed beside the Spine example
@@ -132,6 +132,27 @@ spine-parts at what it wrote:
 | Upstream CLI | `python inference/scripts/inference_psd.py --srcp <image> --save_to_psd` in a checkout of [shitagaki-lab/see-through](https://github.com/shitagaki-lab/see-through) | the `.psd` in `workspace/layerdiff_output/` |
 | ComfyUI wrapper | [jtydhr88/ComfyUI-See-through](https://github.com/jtydhr88/ComfyUI-See-through) on your own ComfyUI box; the optional `comfy` adapter (`spine-parts comfy seethrough`) drives it | the `layers.json` + PNGs it writes |
 
+**The head run is needed on every route that was read.** See-through's model
+already separates the head in a second stage of its own: it crops the head the
+first stage found, runs the face tags on that crop at the same `resolution`, and
+pastes the result back **resized to the full image's scale**. So the face comes
+back at the full run's pixel density whichever route ran it, and the separate
+head run on `st_input_head.png` is what gives the eyes more pixels
+(read on 2026-09-28 at see-through `a25a549` and wrapper 0.5.0 `98d754b`):
+
+- *Hugging Face Space* — the same two-stage code, with `resolution` capped at
+  1280 (768 by default): the head run is still needed.
+- *ModelScope demo* — its code was not read, so what the head run adds on that
+  route has not been measured.
+- *Upstream CLI* — the `.psd` frame is the `resolution`-sided square the first
+  stage ran on (1280 by default), and the head stage is pasted into it at that
+  scale: the head run is still needed.
+- *ComfyUI wrapper* — `SeeThrough_GenerateLayers` runs both stages with no input
+  to change the second, at most `resolution` 2048, which on the examples' 2432 px
+  square is 1.19 source px per layer px against 0.77 and 0.47 for their head
+  crops; at the 1024 the examples ran, the full run's right eye white is 22×13 px
+  and the head run's 60×38: the head run is still needed.
+
 **See-through is required; ComfyUI is not.** The wrapper is one route among
 four, and `spine-parts comfy` is only a convenience for that route: every
 stage after See-through reads files, whichever route wrote them. On the two
@@ -222,7 +243,7 @@ agent skill.
 | `propose --parts --source --out [--compare <config>]` | propose bones, meshes, regions and an idle; draw the overlay |
 | `propose … --from-config <config>` | draw and LINT the config's current bones |
 | `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json`, written only after spine-rigc's round trip is green; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared |
-| `check --rig --out [--parts]` | build packed, gate under both profiles, render the idle, measure seam, loop and the five judgement lines, and report the recomposite's holes from `parts.json` |
+| `check --rig --out [--parts]` | build packed, gate under both profiles, render the idle, measure seam, loop and the six judgement lines (mesh texture stretch among them, from the idle's `render --geometry`), and report the recomposite's holes from `parts.json` |
 | `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
 | `build --config --source --full --head --out [--seam] [--project] [--loop]` | assemble, rig and check in one process, stopping at the first refusal |
 

package/cli.ts

@@ -18,7 +18,7 @@ import { basename, dirname, extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, HOLES_LISTED, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
 import { assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns, readSource, rigStage } from './src/build.ts';
-import { findRigc, PARTS_HOME_SENTENCE, type RigcRunner, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK } from './src/check.ts';
+import { findRigc, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, type RigcRunner, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
 import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
 import { type CharacterConfig, loadConfig, loadEarlyConfig } from './src/config.ts';
 import { PartsError, problemLine } from './src/errors.ts';
@@ -77,7 +77,8 @@ usage:
       regions, motion with its blink — and a blink.still cut for a lash that
       reaches far above its eyewhite, when a clear row allows one; no blink
       when no part is an eyewhite, and no brows in it when no part is an
-      eyebrow, each said in a note — and notes)
+      eyebrow, each said in a note; an iris or lash on a side with no
+      eyewhite rides head, said in a note — and notes)
       and the overlay to correct against, <out>/render/landmarks.png and
       landmarks_head.png. Prints every
       note and a LINT line for each chain link that lies off its mesh's art, for a
@@ -105,8 +106,9 @@ usage:
       and one idle of sines and a blink whose closed hold is at least one
       12 fps frame, so the idle frames and the loop show the eyes shut
       (RIG_BLINK_HOLD_SPANS_A_FRAME otherwise); no blink when the config
-      states no motion.blink, and a blink group that names no bone is refused
-      by the loader, CONFIG_BLINK_GROUP_MEMBERS, before rigc starts. --parts is the
+      states no motion.blink, and a blink group that names no bone, or one
+      bone twice, is refused by the loader, CONFIG_BLINK_GROUP_MEMBERS or
+      CONFIG_BLINK_GROUP_UNIQUE, before rigc starts. --parts is the
       directory holding parts.json and parts/<name>.png. The result is built
       through spine-rigc (profile spine-html, packed, then validated under
       profile spine) in a scratch directory first, and --out receives
@@ -127,19 +129,30 @@ usage:
       Both are only read. Into --out:
       build/ (rigc build --profile spine-html --pack: the packed atlas is the
       artifact), gate_spine-html.txt and gate_spine.txt (the gate lines
-      verbatim), idle_frames/ (rigc render --animation idle --fps 12 --max 640),
+      verbatim), idle_frames/ (rigc render --animation idle --fps 12 --max 640
+      --geometry: the frames and geometry.json, the skinned vertices and
+      every bone's world transform per frame),
       contact.png, motion_heat.png and check.json. PASS needs both gates
       "0 failed", the seam (setup pose vs the flat composite of parts/) at mean
       |d| <= ${SEAM_MEAN_BAR.toFixed(1)} with <= ${SEAM_PX_BAR} px over ${SEAM_PX_LEVEL}, and the loop (idle frame 0 vs the
-      frame at t = duration) at max |d| 0. Then five judgement lines, each in
+      frame at t = duration) at max |d| 0. Then six judgement lines, each in
       check.json and on the console as NAME: PASS|FAIL|SKIP with its figures and
       bars (AUTHORING §7): BREATH_VISIBLE (the topwear moves, the footwear does
       not, each rendered alone), BLINK_NO_HOLE (the setup pose with the blink
       held shut shows no background inside the eyewhite box), CHAIN_LAG (every
       rotate track lags its keyed ancestor and amplitude grows down each
       chain, read off motion.json), TIP_OVER_ROOT (each handwear/bottomwear
-      part's lower half travels further than its upper half) and
-      STILL_REGIONS_DARK (the heat map over the face outline and the feet).
+      part's lower half travels further than its upper half),
+      STILL_REGIONS_DARK (the face outline in the frame of the bone the face's
+      slot rides, at most twice the resampler's own error on this rig — read
+      off the whole rig moved rigidly as the idle moves that bone — with the
+      screen-space figure reported beside it; the feet in screen space) and
+      TEXTURE_STRETCH (every mesh triangle's edges over the idle against their
+      rest length, max(ratio, 1/ratio) <= ${TEXTURE_STRETCH_CEILING}; the worst
+      triangle is named by slot, triangle, vertices, edge and frame).
+      Needs spine-rigc ${RIGC_GEOMETRY_VERSION} or later, whose render writes
+      geometry.json; an older rigc is refused, CHECK_RIGC_VERSION, before
+      anything is built.
       Regions come from parts.json's See-through tags; a line with nothing to
       read says SKIP and why — neither a pass nor a failure — and PASS needs
       every line that measured to be PASS. Then RECOMPOSITE_HOLES: REPORTED,

package/docs/AUTHORING.md

@@ -76,7 +76,7 @@ read by no CPU stage).
 | `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`) |
-| `motion.blink` | rig | **proposed**: `{t, eyes, brows, squash, brow_drop}`; the whole blink, `t` to `t + 0.364` s (`t + 0.314` s without brows: the brows' keys are the ones that end last), must fit inside the idle (`RIG_BLINK_INSIDE_IDLE`). The `eyes` group's `scaley` squashes every part on the eye bones about the bone's origin, the eyewhite's centre. Optional: a figure with no `eyewhite-r`/`-l` part has no eye bone, so `propose` writes no `blink` and notes `no blink: no eyewhite part (looked for: eyewhite-r, eyewhite-l), …`; with eyes and no `eyebrow-r`/`-l` part it writes the blink without `brows` and `brow_drop` and notes `blink without brows: …`. `brows` and `brow_drop` are stated together or not at all (`CONFIG_BLINK_BROWS_PAIRED`), and a group that names no bone is refused (`CONFIG_BLINK_GROUP_MEMBERS`) — rigc would refuse it one stage later, `group "eyes" declares no members`. The timing is fixed, not a field (table below) |
+| `motion.blink` | rig | **proposed**: `{t, eyes, brows, squash, brow_drop}`; the whole blink, `t` to `t + 0.364` s (`t + 0.314` s without brows: the brows' keys are the ones that end last), must fit inside the idle (`RIG_BLINK_INSIDE_IDLE`). The `eyes` group's `scaley` squashes every part on the eye bones about the bone's origin, the eyewhite's centre. Optional: a figure with no `eyewhite-r`/`-l` part has no eye bone, so `propose` writes no `blink` and notes `no blink: no eyewhite part (looked for: eyewhite-r, eyewhite-l), …`; with eyes and no `eyebrow-r`/`-l` part it writes the blink without `brows` and `brow_drop` and notes `blink without brows: …`. `brows` and `brow_drop` are stated together or not at all (`CONFIG_BLINK_BROWS_PAIRED`), and a group that names no bone is refused (`CONFIG_BLINK_GROUP_MEMBERS`) — rigc would refuse it one stage later, `group "eyes" declares no members` — as is a group that names one bone twice (`CONFIG_BLINK_GROUP_UNIQUE`; rigc: `group "eyes" names member "eye" twice`). An `irides-*` or `eyelash-*` part on a side with no eyewhite has no eye bone to ride: `propose` places it on `head` as a region, which the blink does not move, and notes `no eyewhite part for eye_r (looked for: eyewhite-r): iris (head:irides-r) is placed on head as a region, …`. The timing is fixed, not a field (table below) |
 | `motion.blink.still` | rig | **proposed** only for a lash `propose` notes (below), then checked: `{<part>: {row, bone}}` — the rows of that region part above `row` (rig px, y down) are drawn by a second slot `<part>_still` on `bone` and do not blink; rows from `row` down keep the part's slot and blink. The part must be a region on a bone `eyes` names, `bone` one it does not (`CONFIG_STILL_OFF_THE_BLINK`), and `row` a row of the part with no art across its whole width (`RIG_STILL_ROW_CLEAR`) |
 
 The blink's timing is the tree's (`BLINK` in `src/motion.ts`), in seconds after
@@ -101,7 +101,8 @@ leave it 0.01 s after the lids open. The rig stage refuses a hold under one fram
 name (`RIG_BLINK_HOLD_SPANS_A_FRAME`, §6), counted over the same 250,000 phases.
 
 The proposer's reach (from `src/propose.ts`): roles come from each part's tag —
-`face` makes `hip`/`chest`/`neck`/`head`, the eyewhites make the eye bones, brows are
+`face` makes `hip`/`chest`/`neck`/`head`, the eyewhites make the eye bones (irides and
+lashes ride them, or `head` on a side with no eyewhite), brows are
 told apart by position, `bottomwear` makes the hip and three skirt chains,
 `handwear` makes sleeve chains (one blob or two), `front hair` makes fringe chains
 and a lock chain for each strand that hangs below the chin, `back hair` makes a bun
@@ -226,7 +227,11 @@ full loader before its assemble stage writes anything.
 4. `spine-parts propose --head-box --full inputs/layers/full --canvas <W>x<H>` →
    `seethrough.head_box`. Run `spine-parts inputs` again: it now also writes
    `st_input_head.png`, the painting cropped to that box at its exact size.
-5. **See-through, head run** (external), on that crop.
+5. **See-through, head run** (external), on that crop. See-through's own second,
+   head stage does not replace it: that stage's layers are pasted back at the full
+   run's scale on every route that was read (README *Getting See-through layers*),
+   so the full run's eyes stay at its density — 22×13 px for the demo's right eye
+   white at `resolution` 1024, against 60×38 px in the head run.
 6. `spine-parts assemble --propose-plan --source … --full … --head … --config config.json`
    → paste `plan` and `extend_below_crop` into `config.assemble`. Config: the
    `layers` row, with `head_box`.
@@ -260,9 +265,9 @@ 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` | on the examples: `sample` 0.84 / 98.0 % / 4,512 / 1,185, 259 holes, the largest 94 px; `demo` 2.39 / 95.8 % / 11,050 / 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, `landmarks.png` | 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 | 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 |
+| `propose` | `note:` lines, `LINT` lines, `landmarks.png` | 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 | 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` |
 | `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`) | `cover 1.00000` on every mesh, both gates `0 failed` | `RIG_LATTICE_ONE_LOOP`: change that mesh's `grid` |
-| `check` (inside `build`) | the gate lines verbatim, the pack line, `loop:`, `seam:`, the five judgement lines and `RECOMPOSITE_HOLES` (§7), `check.json` | `check: PASS`, and a judgement line SKIP only where the character lacks what it reads | `CHECK_SEAM_WITHIN_BAR` or `CHECK_LOOP_CLOSES` (§6) |
+| `check` (inside `build`) | the gate lines verbatim, the pack line, `loop:`, `seam:`, the six judgement lines and `RECOMPOSITE_HOLES` (§7), `check.json` | `check: PASS`, and a judgement line SKIP only where the character lacks what it reads | `CHECK_SEAM_WITHIN_BAR` or `CHECK_LOOP_CLOSES` (§6) |
 | `loop` (inside `build --loop`, or `loop --frames … --out …`) | the dropped-duplicate line, each file's line, then `loop: idle.png N B (lossless); idle-indexed.png N B (max …, mean …); idle.gif N B (max …, mean …)` | `f0048.png equals f0000.png byte for byte, so it is dropped` | `LOOP_ENCODE` (§6) |
 
 `loop` writes three files from one frame set, and they are not interchangeable.
@@ -482,6 +487,7 @@ See-through with another seed.
 | `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` |
 | `CONFIG_BLINK_GROUP_MEMBERS` | `motion.blink.eyes` or `motion.blink.brows` is `[]`: a group with no members, which rigc refuses at the gate | a figure with no eyewhite part has nothing to blink: leave `motion.blink` out; one with no eyebrow part: leave `brows` and `brow_drop` out |
+| `CONFIG_BLINK_GROUP_UNIQUE` | `motion.blink.eyes` or `motion.blink.brows` names one bone more than once; the detail gives the bone and every index it sits at. rigc refuses it at the gate (`group "eyes" names member "eye" twice`) | name each bone once: the group keys every member it names |
 | `CONFIG_BLINK_BROWS_PAIRED` | `motion.blink.brows` without `brow_drop`, or `brow_drop` without `brows` | state both or neither |
 | `CONFIG_STILL_OFF_THE_BLINK` | a `motion.blink.still` entry names a region on a bone the blink's `eyes` does not name (nothing to hold still), or its `bone` is one the blink's `eyes` names (the still piece would blink) | that entry's part, or its `bone` — the eye bone's parent, `head` as proposed |
 
@@ -550,6 +556,7 @@ See-through with another seed.
 | `CHECK_RIGC_PRESENT` | no `rigc` binary found (every place looked is listed) | `bun install` |
 | `CHECK_INPUT_PRESENT` on `…/parts.json` | `--parts` named a directory without `parts.json` — most often `parts/` itself. The detail says it: "--parts names the directory holding parts.json and parts/, not parts/ itself (after build, that is build's --out, whose rig is <out>/rig); without --parts it is --rig", and names the parent when the parent holds `parts.json` | `--parts` — the directory above `parts/` |
 | `CHECK_INPUT_PRESENT`, `CHECK_INPUT_IS_JSON`, `CHECK_PART_PNG_PRESENT`, `CHECK_PART_PNG_MATCHES_BOX`, `CHECK_PART_SLOT_PRESENT`, `CHECK_RIG_STAGE_PRESENT`, `CHECK_RIG_STAGE_IS_THE_CANVAS`, `CHECK_RIG_ROOT_BONE`, `CHECK_IDLE_PRESENT` | the rig directory is incomplete or disagrees with `parts.json` (`CHECK_PART_SLOT_PRESENT`: a part with no slot of its own name, which the judgement lines render it by) | re-run rig (`build` does both) |
+| `CHECK_RIGC_VERSION` | `rigc --version` is below 1.4.0, or prints no version: its `render` has no `--geometry`, which `TEXTURE_STRETCH` reads. Refused before anything is built | `bun install` (this package depends on spine-rigc ^1.5.1), or put a newer `rigc` first on `PATH` |
 | `CHECK_RIGC_GREEN` | a rigc step failed; its line is quoted | as `RIG_RIGC_GREEN` |
 | `CHECK_LOOP_LAST_FRAME_AT_DURATION` | the idle's last frame does not sit at `duration` | `motion.duration` — a whole number of 1/12 s |
 | `CHECK_LOOP_CLOSES` | frame 0 and the frame at `duration` differ (max and first pixel quoted) | a track whose last key is not its first |
@@ -558,8 +565,9 @@ See-through with another seed.
 | `CHECK_BLINK_NO_HOLE` | with the blink held shut, the eyewhite box shows the page where the open eye had art | the layer under the eye: the `face` part has no art there. Take the face from the other run, or add a part under the eye; `motion.blink.squash` only hides the hole less |
 | `CHECK_CHAIN_LAG` | a rotate track leads (or does not lag) the keyed bone above it, or a chain link swings less than the link above | that chain track's `phase`/`lag` (a positive `lag`, a child `phase` above its parent's) or its `amps` (non-decreasing toward the tip) |
 | `CHECK_TIP_OVER_ROOT` | a `handwear`/`bottomwear` part's lower half travels less than 1.4725 times as far as its upper half | the chain track's `amps` (grow toward the tip), or the mesh's `segments` (the chain must be among them) |
-| `CHECK_STILL_REGIONS_DARK` | the heat map is brighter than the ceiling over the face outline or over the feet | the part that moves there: a mesh weighted to a swinging bone (`segments`), or a region on the wrong bone |
-| `CHECK_SEAM_FRAME_SIZE`, `FRAMES_SIDECAR` | rigc's render is not what its `frames.json` says | a rigc problem; report it |
+| `CHECK_STILL_REGIONS_DARK` | over the face outline, carried into the frame of the bone the face's slot rides: something moves there that the head does not carry, above twice the resampler's own error on this rig (both figures quoted, with the screen-space one beside them); over the feet, the heat map is brighter than the ceiling | on the face: a mesh over it weighted to a bone the head does not carry (`segments`), or a swinging part (a bang, a chain) whose art crosses the face outline; on the feet: a mesh weighted to a swinging bone, or a region on the wrong bone |
+| `CHECK_TEXTURE_STRETCH` | a mesh triangle's edge, in some idle frame, is more than 1.926544 times its rest length or less than 1/1.926544 of it (the mesh, triangle, its three vertices, the edge and the frame are named); or a rest edge has length 0 | the chain tracks' `amps` on the bones that mesh is weighted to (the stretch grows with them), or the mesh's `segments` — a vertex blending two bones that swing against each other |
+| `CHECK_SEAM_FRAME_SIZE`, `FRAMES_SIDECAR`, `CHECK_GEOMETRY_FILE` | rigc's render is not what its `frames.json` says, or its `geometry.json` is not a whole `rigc-geometry/1` export of the frames beside it (a frame count, a mesh whose vertex count differs from its rest entry; for the face half, another viewport than `frames.json`'s, other frame indices, the head bone or a feature's bone missing from a frame, a non-finite transform or time) | a rigc problem; report it |
 | `LOOP_ENCODE` | the loop encoder refused a frame (translucent pixel in a GIF, a size change) | the frames; for a translucent frame write the lossless or the indexed APNG, which keep alpha |
 | `BUILD_ARTIFACT_PRESENT` | the packed build lacks its `.json`, `.atlas` or page | a rigc problem; report it |
 
@@ -578,8 +586,8 @@ implementation's bars):
 On the examples: `sample` 23/23 and 14/14, seam 0.207 with 0 pixels over 40, loop 0;
 `demo` (default rule) 23/23 and 14/14, seam 0.326 with 2 pixels over 40, loop 0.
 
-A green gate cannot see a wrong animation, so `check` also writes five **judgement
-lines** (issue #11), each a key of `check.json` and a console line
+A green gate cannot see a wrong animation, so `check` also writes six **judgement
+lines** (issue #11; `TEXTURE_STRETCH`, issue #31), each a key of `check.json` and a console line
 `NAME: PASS|FAIL|SKIP — <figures and bars>`, read the same way as the lines above: a
 FAIL makes `PASS` false and prints its own `FAIL  CHECK_<NAME>` line (§6); a SKIP
 says why the rig gave the line nothing to read, and is neither a pass nor a failure —
@@ -590,7 +598,9 @@ change from idle frame 0, in levels of 255, on the idle's 640-pixel grid.
 Each bar follows one rule: a floor is half the weaker example's figure and a ceiling
 twice the worse one's, so the weaker example clears it by a factor of two; a bar the
 model itself fixes (a part on an unkeyed bone does not move, a lag is above 0, a hole
-is 0 pixels) is that value, not a margin. The figures are this port's, measured on
+is 0 pixels) is that value, not a margin — and where the model's value is an error
+the rig itself measures (a face the head carries is still in the head's frame up to
+the resampler's error), the bar is that measurement times the same two. The figures are this port's, measured on
 the two examples [observed]:
 
 | line | measures | bar | `demo` | `sample` | SKIP when |
@@ -600,7 +610,8 @@ the two examples [observed]:
 | ″ (reported) | the same box: each closed-eye pixel's max-channel distance to the nearest colour the open eye's box holds — max, and pixels over 40 | none | 15; 0 | 11; 0 | as above |
 | `CHAIN_LAG` | `motion.json`'s rotate tracks read as sines (DFT of the keys: period, amplitude, phase) and arranged by the bone tree — a keyed bone's parent is its nearest keyed ancestor | every lag ≥ 0.001 cycle; amplitude non-decreasing down each unbranched chain | lags 0.040 (neck to head) to 0.120; 12 chains | lags 0.040 to 0.100; 9 chains | no rotate track under another of the same period |
 | `TIP_OVER_ROOT` | each `handwear`/`bottomwear` part alone: how far the centroid of its art travels in the lower half of its box against the upper half | ratio ≥ 1.4725 | `bottomwear` 2.945, `sleeves` 3.716 | `bottomwear` 4.396, `sleeves` 12.475 | no such part |
-| `STILL_REGIONS_DARK` | the idle's heat over the face outline (where `face` is the top part of the flat stack, less the boxes of `eyewhite`, `irides`, `eyelash`, `eyebrow` and `mouth`) and over the feet (where `footwear` is on top); max reported | face mean ≤ 33.976; feet mean ≤ 3.244 | 16.988; 1.622 | 11.475; 0 | no `face` and no `footwear` part (one of the two absent leaves that half unmeasured) |
+| `STILL_REGIONS_DARK` | the face outline **in the head's own frame**: each idle frame sampled (bilinear) where the head bone has carried each setup-pose pixel of the region, the heat taken over those samples. The head bone is the bone the `face` parts' slot rides in `rig.json`, and its per-frame world transform is `rigc render --geometry`'s. The region is the frame pixels whose whole footprint — 1 + 1/scale rig px each way, what the rasteriser's and this sampler's bilinear taps can reach — is `face` on top of the flat stack, clear by that reach of where `eyewhite`, `irides`, `eyelash`, `eyebrow` and `mouth` go in the head's frame over the idle. `resampler_heat_mean` is the same figure off the whole rig moved rigidly as the idle moves the head (the root keyed to the head's motion, every other key dropped), where every pixel is still in the head's frame by construction. `screen_heat_mean`/`max` over `screen_px` are the screen-space figures this line held until issue #33 (where `face` is on top, less the features' setup boxes), reported. The feet (where `footwear` is on top): the idle's heat in screen space — they ride the root, which the idle does not move, so the screen is their own frame | face `head_frame_heat_mean` ≤ 2 × `resampler_heat_mean` (`mean_ceiling`); feet mean ≤ 3.244 | face 1.321 ≤ 2.292 (resampler 1.146; screen 16.988); feet 1.622 | face 0.884 ≤ 1.765 (resampler 0.883; screen 11.475); feet 0 | no `face` and no `footwear` part (one of the two absent leaves that half unmeasured; so do face parts on two slot bones, or idle frames with no `geometry.json`) |
+| `TEXTURE_STRETCH` | every mesh triangle's three edges in every idle frame, read from the `geometry.json` the idle render writes (`rigc render --geometry`, spine-rigc 1.4.0 or later): skinned length over rest length, the rest being the setup pose's bones with no deform. The figure is the rig's worst max(ratio, 1/ratio); each mesh's largest and smallest ratio, with triangle, vertices, edge and frame, is the detail | max(ratio, 1/ratio) ≤ 1.926544 | 1.388: `hair_back` triangle 449, edge 42-43 at 0.720 in frame 26 (largest stretch 1.291, frame 2) | 1.227: `sleeves` triangle 169, edge 126-51 at 0.815 in frame 28 (largest stretch 1.196, frame 5) | the rig draws no mesh, or the render wrote no `geometry.json` |
 
 After them, one **reported line** with no bar:
 
@@ -651,22 +662,70 @@ What each figure is, and is not:
   mean heat is 1.1 times the upper half's while its centroid travels 3.7 times as far.
   The halves split the box across its rows, which assumes the part hangs — true of a
   front-facing standing figure, the only input this tool takes.
-- **The face ceiling is weak, and the reason is in the examples.** The head rolls, so
-  the face outline is lit in both (16.988 and 11.475); twice the worse is a ceiling a
-  smooth face sliding two rig pixels stays under (the selftest's fixture measures 24.8
-  at that slide and 85.5 at eight). A face-outline instrument that removes the head's
-  own motion needs the head bone's world transform per frame, which rigc's `render`
-  does not export. The feet half has the same shape on the demo: its long skirt swings
-  over the shoes, which lights 1.622.
-
-Still only an eye answers, each a missing instrument rather than a question to ask:
-
-- **no visible texture stretch** (it appears when amplitudes grow): the measure is a
-  mesh triangle's deformed edge length over its rest length, frame by frame, and
-  nothing this package runs gives deformed vertices — spine-parts does not link
-  `spine-core`, and rigc's `render` exports pixels, not vertices;
-- **the face outline held still in the head's own frame** (above): the heat map
-  without the head's roll.
+- **Stretch is read on edges, both ways, and the ceiling doubles |ln r|.** Compression
+  distorts a texture as much as stretch — an edge at half its rest length squeezes
+  the texels on it by the factor an edge at twice its length spreads them — so the
+  figure is max(ratio, 1/ratio), and on both examples the worst triangle is a
+  compression (demo 0.720, sample 0.815). The ceiling rule is applied to the quantity
+  whose zero means "nothing happened", as it is for heat: for a ratio that is |ln r|,
+  so twice demo's |ln 1.388| is ln(1.388²) = ln 1.926544 and sample clears it by 3.2
+  times. Doubling the ratio itself (2.776) was rejected: its zero is not at 1, and it
+  passes an edge drawn at 2.7 times its rest length. The rest is the art's own
+  proportions — on both examples every rest edge equals its `uvs` edge times the
+  attachment's size to within 2.4e-5, the uvs' six-decimal rounding.
+- **The face is measured in the head's frame, and its bar is the model's (issue #33).**
+  Until #33 the face half read the screen-space heat map, where the head's intended
+  roll lights the outline on both examples (16.988 and 11.475, the figures now
+  reported as `screen_heat_mean`), so its ceiling was twice the worse example,
+  33.976 — a ceiling a smooth fixture face sliding two rig pixels stayed under (24.8;
+  eight pixels measured 85.5). The judgement means *nothing moves on the face that
+  the head does not move*, so the heat is now taken after each frame's face region is
+  carried back through the head bone's transform. A region the head carries is then
+  still up to the resampler's error, and nothing more. That error depends on the art
+  and the scale — 1.146 on the demo, 0.883 on the sample, 0.47 on the selftest's
+  smooth fixture face — so no one constant can be the bar: it is measured on the same
+  rig, off a throwaway animation that moves the whole rig rigidly as the idle moves
+  the head, and the ceiling is twice that (the tree's one margin). The calibration is
+  its own `rigc build`: sharing the setup still's build widened the still's viewport
+  (rigc fits it to every animation a skeleton holds) and moved the seam.
+- **The region is the pixels that read the face and nothing else.** A pixel at the
+  outline's rim, or next to a feature, reads a neighbour's art through the two
+  bilinear taps, and that neighbour moving lights it with nothing on the face moving:
+  measured over the rim, a fixture face that does not move at all over a breathing
+  torso read 1.533 against a bar of 0 (its head never moves, so its resampler error is
+  exactly 0), and the proposer's own strand fixture went red on the brows the blink
+  drops below their setup boxes. So the region keeps only pixels whose whole
+  footprint is the face (228 of the demo's 515 screen-space pixels, 271 of the
+  sample's 453), clear of where each feature goes in the head's frame over the idle
+  (its setup box carried by its own bone and back through the head's). Measured over
+  the rim instead, both examples sat at 1.31 and 1.34 times their calibration, and
+  that excess was the bangs' art sliding over the rim.
+- **What the examples show in the head's frame.** The sample is still to its
+  calibration (0.884 against 0.883). The demo reads 1.15 times it (1.321 against
+  1.146), and most of that is the calibration's own noise, not motion: the face
+  rendered alone (`--slot face`), rigid on the head by construction, reads 1.296 on
+  the idle's grid against 1.146 on the calibration's — rigc fits each render's
+  viewport to its own animation, so the two grids sit at a different sub-pixel phase
+  on the art (13 %). The rest, 0.025, is `hair_front`: rendered without it the figure
+  is the face-alone one. Both clear the bar, the demo by a factor of 1.74 and the sample by 2.00.
+- **What the line now catches, and where it stops.** The selftest's fixture face,
+  a mesh weighted wholly to a bone that slides two rig pixels under its head, reads
+  27.886 against a ceiling of 0 on a still head (screen space 26.901, which the
+  retired 33.976 passed) and 27.936 against 0.94 on a rolling one. The same plant on
+  the real examples, at their render scale of about 0.5 (one rig pixel is half a frame
+  pixel): two pixels read 3.216 on the sample (ceiling 1.765, red) and 2.181 on the
+  demo (2.292, green); one pixel reads 1.614 and 1.526 (both green). A smooth skin
+  interior sliding half a frame pixel changes little, and the rim that shows it most is
+  the rim the region leaves out. The line also does not judge a face that moves with
+  the bone its own slot rides: that is the head moving, whatever the bone, so a face
+  region on the wrong bone is the feet half's and the eye's to catch, not this line's.
+- **The feet stay in screen space.** They ride the root, which the idle does not key,
+  so the screen is their own frame. On the demo the long skirt swings over the shoes,
+  which lights 1.622.
+
+Nothing is left that only an eye answers. "No visible texture stretch" left this list
+with issue #31 (`TEXTURE_STRETCH`), and "the face outline held still in the head's own
+frame" with issue #33 (the face half of `STILL_REGIONS_DARK`, above).
 
 ## 8. What one character costs
 
@@ -680,3 +739,10 @@ Still only an eye answers, each a missing instrument rather than a question to a
 About 6.5 minutes of GPU and under a minute of CPU per character, before any hand
 correction. The GPU figures are one run each on one machine; the painting's figure
 excludes choosing among seeds (the demo was chosen from eighteen candidates).
+Since issue #33 `check` runs one more `rigc build` and one more idle render (the face
+calibration, §7); the idle's `geometry.json` is the one issue #31 already writes. The `build` row
+was not re-measured: A/B against the tree before that change, alternating on one
+machine under a load average of 5 to 11, the difference in user + sys was +5.6 and
++0.8 s on the demo and +6.5 and −1.6 s on the sample over two rounds — inside what
+the load moves the same build by (the pre-change demo build alone took 43.6 to
+45.8 s there).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-parts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI-authored Spine 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through spine-rigc before anything is written. A CLI for agents that cannot see the image.",
   "type": "module",
   "bin": {
@@ -57,7 +57,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "spine-rigc": "^1.3.0"
+    "spine-rigc": "^1.5.1"
   },
   "devDependencies": {
     "@types/bun": "^1.4.2",

package/skills/spine-parts/SKILL.md

@@ -26,9 +26,9 @@ stage writes are the whole interface.
   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
-  five judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`,
-  `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`); texture stretch and the face outline in
-  the head's own frame still need an eye (AUTHORING §7). A judgement line that says
+  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.
 - **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
@@ -68,8 +68,10 @@ stage writes are the whole interface.
 7. `spine-parts build --config … --source … --full … --head … --out out --loop`.
    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 five judgement lines the same way as the seam
-   and the loop: a FAIL names the field to change (AUTHORING §6). Quote
+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