spine-parts 0.4.0 → 0.6.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

@@ -38,14 +38,14 @@ is taken from the full run, because the twin tails leave the head crop sideways
 <code>49 assertions: 14 measured (14 passed, 0 failed), 20 skipped, 15 not in profile "spine"</code><br/>
 <code>loop: idle 49 frame(s) at 12 fps, f0000 vs f0048 (t = 4s): max |d| 0 (0 required)</code><br/>
 <code>seam: setup pose at 714x1216, scale 0.9422: mean |d| 0.324 (&lt;= 1.0), 2 px over 40 (&lt;= 50), 0 px over 80 (reported)</code><br/>
-<code>pack: skeleton.png 1024x2048, 22 region(s), 56.3% covered, padding 2</code><br/>
+<code>pack: skeleton.png 967x1338, 22 region(s), 91.2% covered, padding 2, page edges free</code><br/>
 <code>--seam silhouette</code> repaired the navy blobs the default rule leaves on the white
 blouse (recomposite error pixels 11,050 → 9,540); the default stays
 <code>near-white</code>, the reference implementation's rule, so the examples stay
 comparable with it. The loop is <code>spine-parts loop --palette</code>'s indexed APNG, 48 frames at
-12 fps, 1,706,785 bytes, one 256-entry palette at a measured error of max 57, mean 1.601
+12 fps, 1,706,520 bytes, one 256-entry palette at a measured error of max 57, mean 1.601
 per channel over every frame (the lossless APNG beside it, the exactness record, is
-13,645,519 bytes; the GIF, at the same error, 1,812,625). Frame 29 (2.417 s) is the
+13,645,350 bytes; the GIF, at the same error, 1,812,238). Frame 29 (2.417 s) is the
 closed eye: the blink holds for 0.084 s, one 12 fps frame rounded up, where the
 reference implementation held 0.04 s and no frame of its loop showed the eyes shut
 (issue #32); the painting is shown at half size, resampled and written
@@ -87,10 +87,10 @@ page** (issue #2):
 
 | path under `--out` | what |
 | --- | --- |
-| `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 |
+| `check/build/skeleton.json`, `skeleton.atlas`, `skeleton.png` | **the artifact** — Spine 4.3 skeleton data and one packed page, written by `rigc build --pack --page-edges free` 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
@@ -99,12 +99,23 @@ artifact paths — here for `examples/sample`:
 
 ```
 build: PASS — the packed atlas is the artifact; parts/ and rig/ are the intermediates it was made from
-  pack: skeleton.png 512x2048, 20 region(s), 49.7% covered, padding 2; page opaque 28.7% (alpha > 0) — spineboy yardstick 1024x256, 40 region(s), 45.8% opaque (alpha > 0), a reference and not a bar
+  pack: skeleton.png 479x1166, 20 region(s), 93.4% covered, padding 2, page edges free; page opaque 53.9% (alpha > 0) — spineboy yardstick 1024x256, 40 region(s), 45.8% opaque (alpha > 0), a reference and not a bar
   out/check/build/skeleton.json
   out/check/build/skeleton.atlas
   out/check/build/skeleton.png
 ```
 
+The page's edges are free by default: rigc picks the least-area page the parts need,
+not the next power of two. On the two examples that is 967x1338 and 479x1166, where a
+power-of-two page is 1024x2048 and 512x2048, and covered goes from 56.3 % to 91.2 % and
+from 49.7 % to 93.4 %. The cost is the one rigc's help states: *"region attachments
+sampling within 1 LSB of the loose build rather than exactly"*. Measured on both
+examples, every idle frame stays within 1 level of the power-of-two build's. The atlas says
+`filter: Linear, Linear` and has no `repeat` line, so `--page-edges pot` is for a
+consumer that mipmaps or repeats the page; it writes exactly the page builds wrote
+before the flag existed. The measurements are in
+[AUTHORING §5, *Page edges*](docs/AUTHORING.md#5-after-each-stage-what-to-read).
+
 The packer is spine-rigc's, and no other: a packed region is a lossless copy, and an
 atlas written by anything else would have no oracle behind it.
 
@@ -132,6 +143,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 +254,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 { DEFAULT_PAGE_EDGES, findRigc, PAGE_EDGES, type PageEdges, 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
@@ -97,6 +98,7 @@ usage:
       printed when one was needed.
 
   spine-parts rig --config <config.json> --parts <dir> --out <dir> [--idle-keys ctl|direct]
+                  [--page-edges pot|free]
       Author the rig: unrotated bones at the config's landmarks (a chain makes
       <chain>0..n), a square lattice mesh over every part in config.meshes
       weighted by distance to its candidate bone segments, a region for every
@@ -105,11 +107,12 @@ 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
+      through spine-rigc (profile spine-html, packed with --page-edges as for
+      check, then validated under profile spine) in a scratch directory first, and --out receives
       images/*.png, rig.json, motion.json and mesh_report.json only when both
       are green. Prints one line per mesh and the rigc gate lines.
       --idle-keys says where the idle's keys on a bone a mesh is weighted to go:
@@ -119,27 +122,38 @@ usage:
       spine-rigc 1.3.0 or later and makes A15 a SKIP that prints its cost (the
       stage prints that SKIP line). The pose is the same to one level of float
       rounding, and so is the per-frame mesh work (AUTHORING §5).
-  spine-parts check --rig <dir> --out <dir> [--parts <dir>]
+  spine-parts check --rig <dir> --out <dir> [--parts <dir>] [--page-edges pot|free]
       Build, gate, render and measure a rig through spine-rigc's CLI (the rigc at
       node_modules/.bin/rigc, or on PATH). --rig holds rig.json and motion.json
       (with an "idle").
       ${PARTS_HOME_SENTENCE}.
       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),
+      build/ (rigc build --profile spine-html --pack --page-edges <value>: 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
+      --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,
@@ -150,6 +164,16 @@ usage:
       beside the spineboy yardstick (${SPINEBOY_YARDSTICK}), a reference and not
       a bar. Exit 0 on PASS, 1 on FAIL — every FAIL line names the bar, the value
       and the value required.
+      --page-edges is handed to rigc verbatim and defaults to ${DEFAULT_PAGE_EDGES}: the
+      least-area page the parts need (on the two public examples 967x1338 and
+      479x1166, where pot writes 1024x2048 and 512x2048), at the cost rigc
+      states — region attachments sample within 1 LSB of the loose build
+      rather than exactly (measured on both examples: every idle frame within
+      1 level of the pot build's; AUTHORING §5, Page edges). pot is a power of two on both edges, for a consumer
+      that mipmaps or repeats the page (the atlas declares filter Linear,
+      Linear and no repeat). rigc's pack line ends ", page edges free" under
+      free; a line that disagrees with the value passed, or a pot page that is
+      not a power of two, is refused, CHECK_PACK_PAGE_EDGES.
 
   spine-parts loop --frames <dir> --out <file.png | file.gif> [--palette]
       Encode a frame set rigc render wrote (its --out directory, or the set
@@ -234,7 +258,7 @@ usage:
 
   spine-parts build --config <config.json> --source <painting.png> --full <dir|psd>
                     --head <dir|psd> --out <dir> [--seam near-white|silhouette]
-                    [--project core|visible] [--loop]
+                    [--project core|visible] [--page-edges pot|free] [--loop]
       assemble, then rig, then check, in one process, each stage's own lines
       printed under [assemble], [rig] and [check]; the first stage that refuses
       stops the build with its own FAIL lines. The config must already carry
@@ -250,7 +274,8 @@ usage:
       three artifact paths — skeleton .json, .atlas and the packed page: the
       packed atlas is the result, the loose parts are the intermediate it was
       made from. --seam defaults to ${DEFAULT_SEAM_RULE}, --project to
-      ${DEFAULT_PROJECT_RULE} (both as for assemble).
+      ${DEFAULT_PROJECT_RULE} (both as for assemble), --page-edges to ${DEFAULT_PAGE_EDGES}
+      (as for check; both packed builds, rig's gate and check's artifact, take it).
 
   spine-parts --version
   spine-parts --help
@@ -385,15 +410,26 @@ function rigGateRunner(): RigcRunner {
   };
 }
 
+/** `--page-edges`, or its default; a value spine-rigc does not take is a usage error naming the two it does. */
+function pageEdgesOf(value: string | undefined): PageEdges | string {
+  const edges = value ?? DEFAULT_PAGE_EDGES;
+  return (PAGE_EDGES as readonly string[]).includes(edges) ? (edges as PageEdges) : `--page-edges ${edges}; one of ${PAGE_EDGES.join(', ')} is required`;
+}
+
+function isPageEdges(v: PageEdges | string): v is PageEdges {
+  return (PAGE_EDGES as readonly string[]).includes(v);
+}
+
 function cmdRig(args: string[]): number {
   let config: string | null = null;
   let partsDir: string | null = null;
   let out: string | null = null;
   let idleKeys: string | null = null;
+  let pageEdges: string | null = null;
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     const value = args[i + 1];
-    if (!['--config', '--parts', '--out', '--idle-keys'].includes(flag)) return usage(`rig does not take "${flag}"`);
+    if (!['--config', '--parts', '--out', '--idle-keys', '--page-edges'].includes(flag)) return usage(`rig does not take "${flag}"`);
     if (value === undefined) return usage(`${flag} needs a value`);
     i++;
     if (flag === '--config') config = value;
@@ -401,6 +437,9 @@ function cmdRig(args: string[]): number {
     else if (flag === '--idle-keys') {
       if (idleKeys !== null) return usage('--idle-keys is given twice');
       idleKeys = value;
+    } else if (flag === '--page-edges') {
+      if (pageEdges !== null) return usage('--page-edges is given twice');
+      pageEdges = value;
     } else out = value;
   }
   if (config === null) return usage('rig needs --config <config.json>');
@@ -408,9 +447,11 @@ function cmdRig(args: string[]): number {
   if (out === null) return usage('rig needs --out <dir>');
   const keys = idleKeys ?? DEFAULT_IDLE_KEYS;
   if (!(IDLE_KEYS as readonly string[]).includes(keys)) return usage(`--idle-keys ${keys}; one of ${IDLE_KEYS.join(', ')} is required`);
+  const edges = pageEdgesOf(pageEdges ?? undefined);
+  if (!isPageEdges(edges)) return usage(edges);
   const scratch = mkdtempSync(join(tmpdir(), 'spine-parts-rig-'));
   try {
-    rigStage({ config, parts: partsDir, out, idleKeys: keys as IdleKeys }, rigGateRunner(), scratch, console.log);
+    rigStage({ config, parts: partsDir, out, idleKeys: keys as IdleKeys, pageEdges: edges }, rigGateRunner(), scratch, console.log);
     return EXIT_OK;
   } catch (err) {
     return printRefusal(err);
@@ -443,13 +484,15 @@ function flags(args: string[], known: readonly string[], command: string, option
 }
 
 function cmdCheck(args: string[]): number {
-  const f = flags(args, ['--rig', '--out'], 'check', ['--parts']);
+  const f = flags(args, ['--rig', '--out'], 'check', ['--parts', '--page-edges']);
   if (typeof f === 'string') return usage(f);
   const rig = f.get('--rig') as string;
   const out = f.get('--out') as string;
+  const edges = pageEdgesOf(f.get('--page-edges'));
+  if (!isPageEdges(edges)) return usage(edges);
   try {
     const bin = findRigc(import.meta.dir, process.env.PATH ?? '');
-    const r = checkStage({ rig, parts: f.get('--parts') ?? rig, out }, rigcRunner(bin), bin, console.log);
+    const r = checkStage({ rig, parts: f.get('--parts') ?? rig, out, pageEdges: edges }, rigcRunner(bin), bin, console.log);
     return r.figures.PASS ? EXIT_OK : EXIT_REFUSED;
   } catch (err) {
     return printRefusal(err);
@@ -754,7 +797,7 @@ function cmdInputs(args: string[]): number {
 function cmdBuild(args: string[]): number {
   const flags = new Map<string, string>();
   let loop = false;
-  const valued = ['--config', '--source', '--full', '--head', '--out', '--seam', '--project'];
+  const valued = ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges'];
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === '--loop') {
@@ -774,6 +817,8 @@ function cmdBuild(args: string[]): number {
   if (!(SEAM_RULES as readonly string[]).includes(seam)) return usage(`--seam ${seam}; one of ${SEAM_RULES.join(', ')} is required`);
   const project = flags.get('--project') ?? DEFAULT_PROJECT_RULE;
   if (!(PROJECT_RULES as readonly string[]).includes(project)) return usage(`--project ${project}; one of ${PROJECT_RULES.join(', ')} is required`);
+  const edges = pageEdgesOf(flags.get('--page-edges'));
+  if (!isPageEdges(edges)) return usage(edges);
   const [config, source, full, head, out] = ['--config', '--source', '--full', '--head', '--out'].map((f) => flags.get(f) as string);
   let bin: string;
   try {
@@ -784,7 +829,7 @@ function cmdBuild(args: string[]): number {
   const scratch = mkdtempSync(join(tmpdir(), 'spine-parts-build-'));
   try {
     const r = build(
-      { config, source, full, head, out, seam: seam as SeamRule, project: project as ProjectRule, loop },
+      { config, source, full, head, out, seam: seam as SeamRule, project: project as ProjectRule, loop, pageEdges: edges },
       { rig: rigGateRunner(), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'rig-gate') },
       console.log,
     );

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.
@@ -274,9 +279,11 @@ entry, no dithering, filter None) — and is the small file to show. `idle.gif`
 (`loop --out x.gif`) is the same median cut in a GIF. The indexed APNG and the GIF
 print their palette error, per channel over R, G and B of every frame (and alpha's
 max for the APNG); a figure is a measurement of the file, not a bar. On the demo:
-13,645,519 B lossless, 1,706,785 B indexed and 1,812,625 B GIF, both palette files at
+13,645,350 B lossless, 1,706,520 B indexed and 1,812,238 B GIF, both palette files at
 max 57, mean 1.601 — the two share one quantiser, so their error is the same by
-construction and the size is the difference. The loop shows the blink closed: the
+construction and the size is the difference. That is `--seam silhouette` (the README's
+animation); with `--page-edges pot` the same build writes 13,645,519, 1,706,785 and
+1,812,625 B at the same error. The loop shows the blink closed: the
 eyes' hold is at least one 12 fps frame (below), so whatever `motion.blink.t` is, one
 idle frame lands inside it, and `check.json`'s `BLINK_NO_HOLE.idle_frames_closed`
 names it — `[29]` on both examples.
@@ -289,6 +296,36 @@ outside the figure. On the demo it lowered recomposite error pixels from 11,050
 9,540 and changed no check bar; on the sample it changed nothing. The default stays
 the reference's so the examples stay comparable with it.
 
+**Page edges.** `rig`, `check` and `build` pack through `rigc build --pack
+--page-edges <v>`, and hand the value to rigc verbatim. The default is `free`,
+the least-area page the parts need. `--page-edges pot` is the opt-out: a power of
+two on both edges, which is the page every build wrote before this flag. The pack
+line says which one ran, because rigc ends it with `, page edges free` under `free`.
+Measured with rigc 1.5.1 on the two examples, by `tools/atlas_population.ts`:
+
+| build | page | covered | page opaque | page / figure |
+| --- | --- | --- | --- | --- |
+| demo, `pot` | 1024x2048 | 56.3 % | 36.8 % | 2.651 |
+| demo, `free` | 967x1338 | 91.2 % | 59.7 % | 1.636 |
+| sample, `pot` | 512x2048 | 49.7 % | 28.7 % | 3.294 |
+| sample, `free` | 479x1166 | 93.4 % | 53.9 % | 1.755 |
+
+rigc's help states the cost: *"a smaller page, at the cost of region attachments
+sampling within 1 LSB of the loose build rather than exactly"*. On these builds
+every one of the 49 idle frames differs from the `pot` build, by at most 1 level
+in any channel:
+
+| example | idle frames that differ | pixels that differ (all 49 frames) | max \|d\| |
+| --- | --- | --- | --- |
+| demo | 49 of 49 | 2,373 | 1 |
+| sample | 49 of 49 | 651 | 1 |
+
+Only one check figure moved. It has no bar: sample's reported screen-space face
+mean in `STILL_REGIONS_DARK`, 11.475 under `pot` and 11.472 under `free`. Every
+barred figure and every status is the same under both. The atlas rigc writes says
+`filter: Linear, Linear` and has no `repeat` line, so choose `pot` for a consumer
+that mipmaps or repeats the page.
+
 `--project core` (the default) is the reference's projection rule: a layer takes the
 painting's pixel only inside its top-most `alpha >= 250` area eroded by a 5x5 square,
 so a part a few pixels wide (a lash, a brow, an iris) takes none. `--project visible`
@@ -482,6 +519,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 +588,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,9 +597,12 @@ 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 |
+| `CHECK_PACK_LINE_READS` | rigc printed a `pack:` line that is not `pack: <page> <W>x<H>, <N> region(s), <P>% covered, padding <D>` with `, page edges free` after it or nothing; the line is quoted | a rigc this package does not know the output of; report it, with `rigc --version` |
+| `CHECK_PACK_PAGE_EDGES` | the pack line disagrees with the `--page-edges` the build was run with — its `, page edges free` suffix is there under `pot` or missing under `free`, or a `pot` page is not a power of two on both edges | a rigc problem; report it, with `rigc --version` |
 | `BUILD_ARTIFACT_PRESENT` | the packed build lacks its `.json`, `.atlas` or page | a rigc problem; report it |
 
 ## 7. The bars `check` enforces, and what only an eye answers today
@@ -578,8 +620,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 +632,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 +644,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 +696,71 @@ 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`; sample's reads 11.472 since the page edges
+  default to `free`, *Page edges* in §5), 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 +774,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).