spine-parts 0.1.0 → 0.2.0

package/README.md

@@ -15,7 +15,7 @@ input is silent.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/firejune/spine-parts/main/assets/demo-source.png" alt="The demo painting: a generated full-body character in a white and pink frilled dress with long pink twin tails, standing with her hands clasped" height="420" />
-  <img src="https://raw.githubusercontent.com/firejune/spine-parts/main/assets/demo-idle.gif" alt="The same character as a Spine rig, breathing, blinking once and swaying her hair, sleeves and skirt in a four-second loop" height="420" />
+  <img src="https://raw.githubusercontent.com/firejune/spine-parts/main/assets/demo-idle.png" alt="The same character as a Spine rig, breathing, blinking once and swaying her hair, sleeves and skirt in a four-second loop" height="420" />
 </p>
 
 <p align="center">
@@ -42,8 +42,10 @@ is taken from the full run, because the twin tails leave the head crop sideways
 <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</code>'s GIF, 48 frames at
-12 fps, 1,812,041 bytes; the painting is shown at half size, resampled and written
+comparable with it. The loop is <code>spine-parts loop --palette</code>'s indexed APNG, 48 frames at
+12 fps, 1,706,468 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,611 bytes; the GIF, at the same error, 1,812,041); the painting is shown at half size, resampled and written
 by this package's PNG codec (nothing here encodes JPEG). <code>spine-parts sheet</code>
 made the contact sheet.
 </em></p>
@@ -86,7 +88,7 @@ page** (issue #2):
 | `parts/*.png`, `parts.json`, `recomposite_rig.png` | the loose parts, each cropped to its alpha box; the record of where every part came from and how many of its pixels were re-taken from the painting; the flat stack of parts |
 | `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` |
-| `idle.gif`, `idle.png` | with `--loop`: the idle as a GIF and a lossless APNG |
+| `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
 export's `spineboy.png` as a yardstick (a reference, not a bar), and the three
@@ -203,14 +205,14 @@ agent skill.
 | `layers <dir \| layers.json \| file.psd>` | print every layer of a decomposition: draw order, name, tag group, box, size, opaque pixels, depth |
 | `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
 | `assemble --propose-plan …` | propose `assemble.plan` and `extend_below_crop` from the two runs |
-| `assemble --source --full --head --config --out [--seam]` | merge the two runs into rig-space parts, `parts.json` and the recomposite |
+| `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json` and the recomposite |
 | `propose --head-box --full <run> --canvas WxH` | propose `seethrough.head_box` from the full run, held inside the painting |
 | `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` | author `rig.json` + `motion.json`, written only after spine-rigc's round trip is green |
-| `check --rig --out [--parts]` | build packed, gate under both profiles, render the idle, measure seam and loop |
-| `loop --frames <dir> --out <file.gif \| file.png>` | encode a rendered idle as a looping GIF or APNG |
-| `build --config --source --full --head --out [--seam] [--loop]` | assemble, rig and check in one process, stopping at the first refusal |
+| `check --rig --out [--parts]` | build packed, gate under both profiles, render the idle, measure seam, loop and the five judgement lines |
+| `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 |
 
 `spine-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
 reason is a FAIL line), 2 a usage error or a command this version does not implement.
@@ -229,9 +231,11 @@ These are limits of the approach, stated so nobody reads more into a green run:
   that is, is below.
 - **No success rate is claimed.** Ten characters have been measured stage by stage
   against the reference implementation this package ports — the two public examples
-  here and eight private ones, one See-through seed each — and all ten check green.
-  That is an existence proof, not a rate.
-- **`loop` writes GIF and APNG, not WebP**: an animated WebP needs a VP8/VP8L
+  here and eight private ones, one See-through seed each — and all ten check green
+  on the gates, the seam and the loop. The judgement lines `check` added since
+  (issue #11) have been measured on the two public examples only. That is an
+  existence proof, not a rate.
+- **`loop` writes GIF and APNG (lossless and indexed), not WebP**: an animated WebP needs a VP8/VP8L
   encoder, which this package does not carry.
 - **The proposer reads tags, not pictures.** A swinging element painted inside another
   layer (a sash tail in the skirt), hair that is none of the shapes it knows, and
@@ -239,14 +243,31 @@ These are limits of the approach, stated so nobody reads more into a green run:
 
 ### How much of a rig the model painted
 
-`parts.json` records, per part, how many opaque pixels were re-taken from the painting
-(`source_px_taken`) against the part's opaque pixels (`opaque_px`); the rest is
-See-through's synthesis. Across the ten reference rigs, **41.8 %** of all rig pixels
-are not source pixels (issue #9); on the two public examples it is 38.6 % (`sample`)
-and 36.4 % (`demo`), from their `expected/parts.json`. Most of it is art that really
-is hidden — a back-hair layer, a neck — but the figure **over-counts**: a thin part
-that is fully visible (a brow, a lash, an iris) has no eroded opaque core, so none of
-its pixels qualify for projection and they count as synthesized (issue #9).
+`parts.json` splits each part's opaque pixels (`opaque_px`) into `visible_px` — no
+later layer of its See-through run is opaque in front of them — and `occluded_px`,
+and counts the visible ones whose colour was not taken from the painting
+(`visible_not_projected_px`). On the two public examples, from the totals of their
+`expected/parts.json` (the default `--project core`):
+
+| | opaque px | occluded | visible, not projected | taken from the painting |
+| --- | --- | --- | --- | --- |
+| `sample` | 298,632 | 79,143 (26.5 %) | 36,227 (12.1 %) | 183,262 (61.4 %) |
+| `demo` | 767,102 | 202,346 (26.4 %) | 76,801 (10.0 %) | 487,955 (63.6 %) |
+
+The occluded share is art the painting does not show — a back-hair layer, a neck, the
+parts of an ear under the hair — and is See-through's synthesis by necessity; it is
+what the decomposition is for. The visible-but-not-projected share is synthesis where
+the painting was there to be taken: a part too thin for the reference rule's 5x5
+eroded core, an anti-aliased fringe below alpha 250, a rim beside a layer in front, a
+pixel refused for drift. `--project visible` keeps the erosion only along a rim with a
+layer in front, which takes that share to 22,476 (7.5 %) on `sample` and 49,672 (6.5 %)
+on `demo` (from the `parts.json` of a `--project visible` build). On the eleven thin
+head parts — brows, lashes, irises, eye whites, ears, mouth — it takes 296 of
+`sample`'s 1,289 visible pixels where `core` takes 110, and 824 of `demo`'s 2,162
+where `core` takes 343. What neither rule takes is the fringe: a per-pixel
+classification of those parts under `visible`, recorded with the change that added
+the flag, puts 813 of `sample`'s 993 still-unprojected pixels and 879 of `demo`'s
+1,338 below alpha 250.
 
 ## Requirements
 

package/cli.ts

@@ -16,7 +16,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, wri
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { DEFAULT_SEAM_RULE, proposeFields, proposePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
+import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
 import { assembleStage, build, checkStage, loopStage, readRuns, readSource, rigStage } from './src/build.ts';
 import { findRigc, type RigcRunner, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK } from './src/check.ts';
 import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
@@ -103,31 +103,53 @@ usage:
       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. Prints the pack line 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.
-
-  spine-parts loop --frames <dir> --out <file.png | file.gif>
+      frame at t = duration) at max |d| 0. Then five 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).
+      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. Prints the pack line
+      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.
+
+  spine-parts loop --frames <dir> --out <file.png | file.gif> [--palette]
       Encode a frame set rigc render wrote (its --out directory, or the set
       directory inside it) as a looping animation: .png writes an APNG
-      (acTL/fcTL/fdAT, lossless), .gif a GIF89a (one 255-colour median-cut
-      palette, no dithering, LZW, delays rounded so the loop's length is exact).
-      The fps is read from frames.json. When the last frame equals frame 0 it is
-      dropped, and the output says so: the loop wraps onto frame 0 itself.
-      Animated WebP is not written — it needs a VP8/VP8L encoder, out of scope.
+      (acTL/fcTL/fdAT, lossless — the exactness record), .png with --palette an
+      indexed APNG (colour type 3, one palette for every frame: 255 median-cut
+      colours plus one transparent entry, alpha graded per entry, no dithering,
+      filter None — the README-sized file), .gif a GIF89a (the same 255-colour
+      median cut, no dithering, LZW, delays rounded so the loop's length is
+      exact). The indexed APNG and the GIF print their palette error, per
+      channel over every frame. The fps is read from frames.json. When the last
+      frame equals frame 0 it is dropped, and the output says so: the loop wraps
+      onto frame 0 itself. Animated WebP is not written — it needs a VP8/VP8L
+      encoder, out of scope.
 
   spine-parts assemble --source <painting.png> --full <dir|psd> --head <dir|psd>
                        --config <config.json> --out <dir> [--seam near-white|silhouette]
+                       [--project core|visible]
       Merge the full-body and head-crop See-through runs into rig-space parts:
       <out>/rig/parts/<name>.png (each cropped to its alpha box), <out>/rig/parts.json
       and <out>/render/recomposite_rig.png. Reads config.seethrough.head_box and
       .resolution and config.assemble.rig_scale, .plan and .extend_below_crop.
-      Prints one line per part, the seam override counts, and
-      \`recomposite vs source\` (mean |d| and % within 8 over the mean channel;
-      error px: max channel > 40; uncovered: of those, where no part has alpha
-      above 128). Writes nothing unless every check passed. --seam defaults to
-      ${DEFAULT_SEAM_RULE}.
+      Prints one line per part, the seam override counts, the \`pixels:\` totals
+      (opaque = visible + occluded; taken from the painting; visible but not
+      projected), and \`recomposite vs source\` (mean |d| and % within 8 over the
+      mean channel; error px: max channel > 40; uncovered: of those, where no
+      part has alpha above 128). Writes nothing unless every check passed.
+      --seam defaults to ${DEFAULT_SEAM_RULE}. --project says where a layer takes
+      the painting's pixel: core (the reference's) erodes every layer's top-most
+      opaque area by 5x5 first, so a part a few pixels wide takes none; visible
+      erodes only along a rim where a later layer is in front. It defaults to
+      ${DEFAULT_PROJECT_RULE}.
 
   spine-parts assemble --propose-plan --source <painting.png> --full <dir|psd>
                        --head <dir|psd> --config <config.json>
@@ -162,9 +184,11 @@ usage:
       verbatim, checkpoint, LoRAs, sampler, control, elapsed) for --seeds
       seeds from --seed0, and control_<skeleton>.png when generation.control
       is set. The pose words are generation.pose, or the control skeleton's own.
+      The config needs only key and generation here; the rest comes later.
 
   spine-parts build --config <config.json> --source <painting.png> --full <dir|psd>
-                    --head <dir|psd> --out <dir> [--seam near-white|silhouette] [--loop]
+                    --head <dir|psd> --out <dir> [--seam near-white|silhouette]
+                    [--project core|visible] [--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
@@ -172,11 +196,14 @@ usage:
       correct the proposal against its overlay, and write the result into the
       config. Into --out: parts/ + parts.json + recomposite_rig.png (assemble),
       rig/ (rig), check/ (check, with the packed build in check/build/), and with
-      --loop idle.gif and idle.png (APNG) from check/idle_frames/. The paths it
-      writes are cleared first. A green build ends with the pack line beside the
-      spineboy yardstick and the 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}.
+      --loop idle.png (lossless APNG), idle-indexed.png (indexed APNG) and
+      idle.gif from check/idle_frames/, then one loop: line with the three sizes
+      and the two palette errors. The paths it writes are cleared first. A
+      green build ends with the pack line beside the spineboy yardstick and the
+      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).
 
   spine-parts --version
   spine-parts --help
@@ -456,14 +483,21 @@ function cmdPropose(args: string[]): number {
 }
 
 function cmdLoop(args: string[]): number {
-  const f = flags(args, ['--frames', '--out'], 'loop');
+  const palettes = args.filter((a) => a === '--palette').length;
+  if (palettes > 1) return usage('--palette is given twice');
+  const f = flags(
+    args.filter((a) => a !== '--palette'),
+    ['--frames', '--out'],
+    'loop',
+  );
   if (typeof f === 'string') return usage(f);
   const out = f.get('--out') as string;
   const ext = extname(out).toLowerCase();
   if (ext === '.webp') return usage(`--out ${out}: animated WebP needs a VP8/VP8L encoder, which is out of scope; write .png (APNG) or .gif`);
   if (ext !== '.png' && ext !== '.gif') return usage(`--out ${out} is neither .png (APNG) nor .gif`);
+  if (palettes === 1 && ext !== '.png') return usage(`--palette selects the indexed APNG, so --out must be a .png; ${out} is a GIF, which is always one palette`);
   try {
-    loopStage(f.get('--frames') as string, out, ext === '.png' ? 'apng' : 'gif', console.log);
+    loopStage(f.get('--frames') as string, out, ext === '.gif' ? 'gif' : palettes === 1 ? 'indexed' : 'apng', console.log);
     return EXIT_OK;
   } catch (err) {
     return printRefusal(err);
@@ -473,7 +507,7 @@ function cmdLoop(args: string[]): number {
 function cmdAssemble(args: string[]): number {
   const flags = new Map<string, string>();
   let propose = false;
-  const valued = ['--source', '--full', '--head', '--config', '--out', '--seam'];
+  const valued = ['--source', '--full', '--head', '--config', '--out', '--seam', '--project'];
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === '--propose-plan') {
@@ -488,23 +522,25 @@ function cmdAssemble(args: string[]): number {
     i++;
   }
   for (const f of ['--source', '--full', '--head', '--config']) if (!flags.has(f)) return usage(`assemble needs ${f}`);
-  if (propose && (flags.has('--out') || flags.has('--seam'))) return usage('--propose-plan prints to the console; it takes neither --out nor --seam');
+  if (propose && (flags.has('--out') || flags.has('--seam') || flags.has('--project'))) return usage('--propose-plan prints to the console; it takes none of --out, --seam, --project');
   if (!propose && !flags.has('--out')) return usage('assemble needs --out <dir>');
   const seam = flags.get('--seam') ?? DEFAULT_SEAM_RULE;
   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 [source, full, head, config] = ['--source', '--full', '--head', '--config'].map((f) => flags.get(f) as string);
   try {
     if (propose) {
       const src = readSource(source);
       const runs = readRuns(full, head);
-      const g = proposeFields(loadEarlyConfig(config));
+      const g = proposeFields(loadEarlyConfig(config, 'layers'));
       const proposal = proposePlan(runs.full, runs.head, { sourceW: src.width, sourceH: src.height, ...g });
       console.log(JSON.stringify(proposal, null, 2));
       return EXIT_OK;
     }
     const out = flags.get('--out') as string;
     assembleStage(
-      { source, full, head, config, seam: seam as SeamRule },
+      { source, full, head, config, seam: seam as SeamRule, project: project as ProjectRule },
       { partsJson: join(out, 'rig', 'parts.json'), partsDir: join(out, 'rig', 'parts'), recomposite: join(out, 'render', 'recomposite_rig.png') },
       console.log,
     );
@@ -567,7 +603,12 @@ async function cmdComfy(args: string[]): Promise<number> {
   for (const x of [wait, timeout, poll]) if (typeof x === 'string') return usage(x);
   const out = v.get('--out');
   if (out === undefined) return usage(`comfy ${sub} needs --out <dir>`);
+  const configPath = v.get('--config');
+  if (sub === 'paint' && configPath === undefined) return usage('comfy paint needs --config <config.json>');
   try {
+    // The config is a local file, so it is answered before any host is: a
+    // config comfy paint cannot paint from is refused with no box named.
+    const cfg = sub === 'paint' ? loadEarlyConfig(configPath as string, 'paint') : null;
     const host = resolveHost(v.get('--host'), process.env.COMFY_HOST);
     const client = new ComfyClient(host, { poll: poll as number, request: 30 });
     if (sub === 'seethrough') {
@@ -599,12 +640,10 @@ async function cmdComfy(args: string[]): Promise<number> {
       console.log(`  wrote ${join(out, 'layers.json')}, meta.json, parts/ (${r.layers.length} PNG) and previews/ (${r.previews.length} PNG); GPU job ended`);
       return EXIT_OK;
     }
-    const configPath = v.get('--config');
-    if (configPath === undefined) return usage('comfy paint needs --config <config.json>');
-    const cfg = loadConfig(configPath);
+    if (cfg === null) return usage('comfy paint needs --config <config.json>');
     const seeds = intFlag(v, '--seeds', 1, 1);
     if (typeof seeds === 'string') return usage(seeds);
-    const seed0 = intFlag(v, '--seed0', cfg.generation?.seed ?? 0, 0);
+    const seed0 = intFlag(v, '--seed0', cfg.generation.seed, 0);
     if (typeof seed0 === 'string') return usage(seed0);
     console.log(`spine-parts comfy paint: ${cfg.key} -> ${out}`);
     console.log(`  ${seeds} seed(s) from ${seed0}${v.has('--seed0') ? '' : ' (generation.seed)'}; wait <= ${wait} s per seed, timeout ${timeout} s`);
@@ -623,7 +662,7 @@ function cmdInputs(args: string[]): number {
   const out = f.get('--out') as string;
   try {
     if (!existsSync(source)) throw new PartsError([{ code: 'INPUTS_SOURCE_PRESENT', object: source, detail: 'no such file; the painting is required' }]);
-    const cfg = loadEarlyConfig(f.get('--config') as string);
+    const cfg = loadEarlyConfig(f.get('--config') as string, 'layers');
     const painting = readPng(source);
     const r = makeInputs(painting, cfg, source);
     mkdirSync(out, { recursive: true });
@@ -645,7 +684,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'];
+  const valued = ['--config', '--source', '--full', '--head', '--out', '--seam', '--project'];
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === '--loop') {
@@ -663,6 +702,8 @@ function cmdBuild(args: string[]): number {
   for (const f of ['--config', '--source', '--full', '--head', '--out']) if (!flags.has(f)) return usage(`build needs ${f}`);
   const seam = flags.get('--seam') ?? DEFAULT_SEAM_RULE;
   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 [config, source, full, head, out] = ['--config', '--source', '--full', '--head', '--out'].map((f) => flags.get(f) as string);
   let bin: string;
   try {
@@ -673,7 +714,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, loop },
+      { config, source, full, head, out, seam: seam as SeamRule, project: project as ProjectRule, loop },
       { rig: rigGateRunner(), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'rig-gate') },
       console.log,
     );

package/docs/AUTHORING.md

@@ -9,7 +9,8 @@ has to change.
 The worked example throughout is [`examples/sample`](../examples/sample): its
 `config.json` is a complete, loading config, `proposal.json` is what the proposer
 wrote for it, and `expected/` is what the reference implementation produced from
-the same inputs. `bun run fetch-examples` puts its painting and See-through layers
+the same inputs — except `check.json`, which this port's `build` regenerates since
+the reference has no judgement lines (§7). `bun run fetch-examples` puts its painting and See-through layers
 into `examples/sample/inputs/`.
 
 ## 1. Prerequisites
@@ -90,11 +91,22 @@ swing, hair of another shape, whether an accessory swings — is yours to add, a
 
 Two steps are external: the See-through runs (by any route; the optional `comfy seethrough` adapter is only a client for a ComfyUI box). Everything else is this tool.
 
+0. **The painting (optional).** `spine-parts comfy paint --config config.json --out inputs --host <url>`
+   generates `painting_<seed>.png` on a ComfyUI box; any other route to a painting
+   skips this step and leaves `generation` out. At this point the config needs only
+   `key` and `generation`: `comfy paint` reads it through the partial loader's `paint`
+   door (`parseEarlyConfig(raw, 'paint')`), which requires those two, reads nothing
+   else, and refuses unknown and retired keys like the full loader. A config without
+   `generation` is refused as `CONFIG_FIELD_PRESENT: config.generation`, naming the
+   fields the block holds. Everything else arrives later: `seethrough` and
+   `assemble.rig_scale` before step 1, `head_box` from step 4, the plan from step 6,
+   and `bones`, `meshes`, `regions` and `motion` from `propose` in step 7.
 1. **The full image.** `spine-parts inputs --source inputs/painting.png --config config.json --out inputs`
    writes `st_input_full.png`, the painting centred on a white square as tall as it is.
    At this point the config needs only `key`, `seethrough` (without `head_box`) and
    `assemble.rig_scale`: `inputs` and `assemble --propose-plan` read it through the
-   partial loader (`parseEarlyConfig`), which refuses unknown and retired keys like the
+   partial loader's `layers` door (`parseEarlyConfig(raw, 'layers')`), which checks
+   `generation` too when it is present, and which refuses unknown and retired keys like the
    full one and leaves the later sections for later. A landscape or translucent
    painting is refused (`INPUTS_PAINTING_PORTRAIT`, `INPUTS_PAINTING_OPAQUE`).
 2. **See-through, full run** (external).
@@ -123,10 +135,24 @@ Two steps are external: the See-through runs (by any route; the optional `comfy
 | --- | --- | --- | --- |
 | `layers` | the table | every tag the plan will need has opaque pixels; one `face` in the head run | a run whose layer PNG is not its box's size (`LAYERS_PNG_MATCHES_BBOX`) |
 | `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, then `recomposite vs source: mean \|d\|, within 8, error px > 40, uncovered error px` | on the examples: `sample` 0.84 / 98.0 % / 4,512 / 1,185; `demo` 2.39 / 95.8 % / 11,050 / 1,564 (default rule) | `uncovered error px` high: part of the figure is in no layer — a plan entry is missing, or hair left the head crop sideways (the demo's `hair_back` is taken from the full run for that reason) |
+| `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` | on the examples: `sample` 0.84 / 98.0 % / 4,512 / 1,185; `demo` 2.39 / 95.8 % / 11,050 / 1,564 (default rule) | `uncovered error px` high: part of the figure is in no layer — a plan entry is missing, or hair left the head crop sideways (the demo's `hair_back` is taken from the full run for that reason) |
 | `propose` | `note:` lines, `LINT` lines, `landmarks.png` | no LINT line: every chain link lies on its mesh's art | a link off the art (a bone on the background) — move it onto the layer |
 | `rig` (inside `build`) | one line per mesh: vertices, triangles, bones, influences, `cover`; then rigc's gate lines | `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:`, `check.json` | `check: PASS` | `CHECK_SEAM_WITHIN_BAR` or `CHECK_LOOP_CLOSES` (§6) |
+| `check` (inside `build`) | the gate lines verbatim, the pack line, `loop:`, `seam:`, the five judgement lines (§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.
+`idle.png` (`loop --out x.png`) is the lossless APNG: every frame decodes to the
+rendered frame byte for byte, so it is the exactness record. `idle-indexed.png`
+(`loop --out x.png --palette`) is an indexed APNG — colour type 3, one palette for
+every frame (255 median-cut colours and one transparent entry, alpha graded per
+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,611 B lossless, 1,706,468 B indexed and 1,812,041 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.
 
 `--seam near-white` (the default) is the reference implementation's rule: where the
 flat stack of parts differs from the painting by more than 60, the top part takes the
@@ -136,6 +162,38 @@ 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.
 
+`--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`
+keeps the erosion only along a rim where a later layer of the run is in front, and
+takes every other top-most `alpha >= 250` pixel; neither rule takes a fringe pixel
+(alpha below 250). On the examples it lowered the pixels that are visible but not
+projected from 36,227 to 22,476 (`sample`) and 76,801 to 49,672 (`demo`), recomposite
+error pixels from 4,512 to 4,116 and 11,050 to 9,820, and the check seam from 0.207 to
+0.206 and 0.326 to 0.325, with no other check figure changed. The default stays the
+reference's so the examples stay comparable with it. `build` takes both flags.
+
+`parts.json` holds one record per part, in plan order. Its counts:
+
+| field | counts |
+| --- | --- |
+| `opaque_px` | the part PNG's pixels with alpha above 8 |
+| `visible_px` | of those, the ones no later layer of their See-through run is opaque (alpha >= 250) in front of — a pixel copied in below the head crop is judged in its extend layer's run |
+| `occluded_px` | the rest of `opaque_px`: art the painting does not show, See-through's synthesis by necessity |
+| `projected_core_px` | the projection rule's candidates: top-most `alpha >= 250`, eroded (`core`) or kept off a front rim (`visible`) |
+| `source_px_taken` | of those, the ones that took the painting's pixel (the reference's count, before any merge) |
+| `visible_not_projected_px` | visible pixels whose colour did not come from projection — too thin for the core, a fringe, a rim, refused for drift, or a merge ring |
+| `refused_drift_px` | candidates refused because See-through's pixel and the painting's differ by more than 90 |
+| `merged_px` | pixels brought in below the head crop, and the ring that closes their seam |
+| `seam_override_px` | pixels the seam pass recoloured to the painting |
+
+`visible_px + occluded_px = opaque_px`, and every projected pixel is visible; the stage
+refuses (`ASSEMBLE_COUNTS_ADD_UP`) rather than write counts that break either, and the
+reader refuses a record that breaks them (`PARTS_COUNTS_ADD_UP`). The three visibility
+counts are this port's: a `parts.json` the reference wrote has none of them and still
+reads, but a record with only some of them is refused. The `pixels:` line after the
+per-part lines prints their totals.
+
 ## 6. Refusals: the rule, and what has to change
 
 Every refusal is `FAIL  RULE: object — detail`. Inside `build` it is printed under the
@@ -184,7 +242,7 @@ stage's prefix (`[assemble]   FAIL  …`), and the build stops there.
 | `COMFY_QUEUE_EMPTY`, `COMFY_PROMPT_ACCEPTED`, `COMFY_HISTORY_WITHIN`, `COMFY_RUN_OK` | someone else's job kept the queue busy past `--wait`, the box rejected the graph, the job did not finish within `--timeout`, or it ended in error (quoted) | `--wait`/`--timeout`, or what the quoted error names |
 | `COMFY_HISTORY_OUTPUTS`, `COMFY_VIEW_PRESENT`, `COMFY_MANIFEST_NAMED`, `COMFY_MANIFEST_IS_THIS_RUN`, `COMFY_LAYER_NAME` | the job's outputs are missing, unreadable, belong to another run, or name a layer that is not a plain file name | the wrapper's version on the box; report it |
 | `COMFY_IMAGE_PRESENT`, `COMFY_OUT_EMPTY`, `COMFY_OUT_FREE` | no `--image`, an `--out` that already holds files, or a seed whose painting is already on disk | `--image`, `--out`, `--seed0` |
-| `COMFY_CONFIG_GENERATION`, `COMFY_PAINTING_SIZE` | the config has no `generation` block, or the painting that came back is not twice the latent | `config.generation` |
+| `CONFIG_FIELD_PRESENT` on `config.generation`, `COMFY_PAINTING_SIZE` | `comfy paint` was given a config with no `generation` block (the line names the fields it holds), or the painting that came back is not twice the latent | `config.generation` |
 
 ### assemble
 
@@ -197,6 +255,7 @@ stage's prefix (`[assemble]   FAIL  …`), and the build stops there.
 | `ASSEMBLE_RUN_CANVAS` | a run's canvas is not `resolution` square | `seethrough.resolution`, or the run |
 | `ASSEMBLE_PLAN_TAG_IN_RUN`, `ASSEMBLE_EXTEND_TAG_IN_RUN` | an entry takes a tag its run does not hold (the detail lists what it does hold) | that entry's run or tag |
 | `ASSEMBLE_PART_OPAQUE` | a part ended with no opaque pixel | drop the entry, or take the tag from the other run |
+| `ASSEMBLE_COUNTS_ADD_UP` | a part's visible and occluded counts do not add up to its opaque pixels, or a projected pixel is not visible — an assembler bug, not an input problem | report it with the part named; nothing was written |
 
 ### propose
 
@@ -206,7 +265,7 @@ stage's prefix (`[assemble]   FAIL  …`), and the build stops there.
 | `PROPOSE_SOURCE_PRESENT`, `PROPOSE_PNG_PRESENT`, `PROPOSE_PNG_MATCHES_BOX` | the painting or a part PNG is missing, or a PNG is not its box | `--source`, `--parts` (re-run assemble) |
 | `PROPOSE_FACE_PRESENT` | no part comes from a `face` layer; every other rule scales by it | `assemble.plan` |
 | `PROPOSE_ACCESSORY_BODY` | an accessory has nothing above its pendant rows to hang its bone on | that part's plan entry, or author its bones by hand |
-| `PARTS_*` (`PARTS_FILE_PRESENT`, `PARTS_IS_JSON`, `PARTS_KEY_KNOWN`, `PARTS_FIELD_PRESENT`, `PARTS_FIELD_TYPE`, `PARTS_NAME_UNIQUE`, `PARTS_FROM_KNOWN`, `PARTS_BOX_INSIDE_RIG`) | the `parts.json` read is not assemble's contract | re-run assemble; do not edit `parts.json` |
+| `PARTS_*` (`PARTS_FILE_PRESENT`, `PARTS_IS_JSON`, `PARTS_KEY_KNOWN`, `PARTS_FIELD_PRESENT`, `PARTS_FIELD_TYPE`, `PARTS_NAME_UNIQUE`, `PARTS_FROM_KNOWN`, `PARTS_BOX_INSIDE_RIG`, `PARTS_COUNTS_ADD_UP`) | the `parts.json` read is not assemble's contract (`PARTS_COUNTS_ADD_UP`: `visible_px + occluded_px` is not `opaque_px`, or `visible_not_projected_px` is above `visible_px`) | re-run assemble; do not edit `parts.json` |
 
 ### rig
 
@@ -225,13 +284,18 @@ stage's prefix (`[assemble]   FAIL  …`), and the build stops there.
 | rule | means | change |
 | --- | --- | --- |
 | `CHECK_RIGC_PRESENT` | no `rigc` binary found (every place looked is listed) | `bun install` |
-| `CHECK_INPUT_PRESENT`, `CHECK_INPUT_IS_JSON`, `CHECK_PART_PNG_PRESENT`, `CHECK_PART_PNG_MATCHES_BOX`, `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` | re-run rig (`build` does both) |
+| `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_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 |
 | `CHECK_SEAM_WITHIN_BAR` | the setup pose does not reproduce the flat stack of parts | usually a region or mesh placed off its part; compare with `recomposite_rig.png` |
+| `CHECK_BREATH_VISIBLE` | the torso (`topwear`), rendered alone, barely moves over the idle — or the feet (`footwear`), rendered alone, move at all | the chest's breath tracks (`motion.tracks` on `chest`), or the torso mesh's `segments`; for the feet, the bone their region rides (`regions.<part>`, `root` in both examples) |
+| `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 |
-| `LOOP_ENCODE` | the loop encoder refused a frame (translucent pixel in a GIF, a size change) | the frames |
+| `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 |
 
 ## 7. The bars `check` enforces, and what only an eye answers today
@@ -249,16 +313,76 @@ 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 check cannot see a wrong animation. Seven judgements still need an eye, and
-each is a missing instrument (issue #11), not a question to ask a person:
-
-- breathing is visible (chest to waist) while the feet stay put;
-- one blink, and no hole or colour patch behind the closed eye;
-- hair and accessories lag the head (phase delay down each chain);
-- sleeve ends, hems and skirt edges swing while their roots barely move;
-- at rest, no gap, white rim or doubled line between layers;
-- no visible texture stretch (it appears when amplitudes grow);
-- `motion_heat.png` is dark where nothing should move (face outline, shoes).
+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
+`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 —
+report it as not verified. Every region is chosen by the See-through tag in
+`parts.json`'s `from`, never by a part's name. Heat is a pixel's largest per-channel
+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
+the two examples [observed]:
+
+| line | measures | bar | `demo` | `sample` | SKIP when |
+| --- | --- | --- | --- | --- | --- |
+| `BREATH_VISIBLE` | `topwear` parts rendered alone (`rigc render --slot`): heat mean over their box; `footwear` parts alone: heat max over theirs | torso mean ≥ 3.809; feet max ≤ 0 | 15.252; 0 | 7.618; 0 | no `topwear` or no `footwear` part |
+| `BLINK_NO_HOLE` | the setup pose with every `scaley` track on the eyewhite slots' bones held at its closed value, against the setup pose, at full size: pixels in the eyewhite box that show the page where the open eye had art | 0 px | 0 | 0 | no `eyewhite` part, or no `scaley` track on its bones goes below its first key |
+| ″ (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) |
+
+What each figure is, and is not:
+
+- **The seam is the answer to "at rest, no gap, white rim or doubled line between
+  layers".** A gap shows the page, a rim a colour no part has there, a doubled line a
+  part drawn off its place; each changes the setup-pose render against the flat stack,
+  which is what the seam bar measures. No separate line is written for it.
+- **The blink is measured at the setup pose, not in an idle frame.** On both examples
+  the eyes are fully shut from 2.37 s to 2.41 s, and no 12 fps idle frame falls inside
+  that window (`idle_frames_closed` is empty: frames 28 and 29 are 2.333 s and
+  2.417 s), so the idle render and the loop encoded from it never show the closed eye.
+  rigc's `render` takes no time, so the closed pose is a throwaway animation holding
+  the blink tracks' closed value, built and rendered beside the seam's still on the
+  same grid — the comparison is then of what the blink alone changed.
+- **The colour-patch figure is not reliable enough for a bar.** "Nearest colour in the
+  open eye's box" counts a legitimate colour the open eye never showed (skin under the
+  lid) as a patch, and a patch the open eye happened to contain as none. It is
+  reported, and 15 and 11 on the examples are what a clean lid looks like.
+- **A lag is read modulo half a cycle.** A sine's sign is half a cycle of phase, and
+  the keys cannot tell `amp −0.6, phase 0.2` from `amp 0.6, phase 0.7` — the mirrored
+  chains of both examples are written the first way — so the reading folds a step into
+  (−¼, ¼] of a cycle and reports amplitudes unsigned. A lag of a quarter cycle or more
+  cannot be told from a lead. Tracks whose keys are not a sampled sine are listed as
+  `unread`, and a keyed bone under a keyed ancestor of another period (the demo's
+  tassel under the head) is listed in `other_period` and not compared.
+- **Tip over root is a centroid, not a displacement.** Art entering or leaving a half
+  moves its centroid too. The halves' mean heat was the brief's first choice and was
+  rejected: heat is texture times motion, and on the demo's sleeves the lower half's
+  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.
 
 ## 8. What one character costs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-parts",
-  "version": "0.1.0",
+  "version": "0.2.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": {