spine-parts 0.1.0 → 0.3.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>
@@ -83,10 +85,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 |
-| `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 |
+| `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` |
-| `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
@@ -166,9 +168,9 @@ than queueing behind someone else's job.
 ## The loop, for an agent
 
 ```sh
-spine-parts inputs --source painting.png --config config.json --out inputs   # st_input_full.png; the config needs only key, seethrough, assemble.rig_scale
+spine-parts inputs --source painting.png --config config.json --out inputs   # st_input_full.png
 #    See-through on st_input_full.png (external, or `spine-parts comfy seethrough`) -> layers/full
-spine-parts layers layers/full                      # every layer: box, opaque px, depth
+spine-parts layers layers/full                      # every layer: box, opaque px, depth, plausibility figures; WARN lines
 spine-parts propose --head-box --full layers/full --canvas 1664x2432
 #    -> seethrough.head_box into config.json
 spine-parts inputs --source painting.png --config config.json --out inputs   # now st_input_head.png too
@@ -177,6 +179,10 @@ spine-parts sheet --source painting.png --layers layers/full --layers layers/hea
 spine-parts assemble --propose-plan --source painting.png --full layers/full --head layers/head --config config.json
 #    -> assemble.plan and extend_below_crop
 spine-parts assemble --source painting.png --full layers/full --head layers/head --config config.json --out work
+#    -> work/rig: parts.json and parts/; the config holds no bones, meshes, regions or motion yet
+#    -> read the `uncovered hole N:` lines and look at work/render/recomposite_error_rig.png:
+#       red is painting that no part holds, and no later gate can see it
+#    -> a large red hole neither run holds? add an assemble.patches entry (cut from the painting) and assemble again
 spine-parts propose --parts work/rig --source painting.png --out work
 #    -> proposal.json and render/landmarks.png; correct it, copy bones/meshes/regions/motion into config.json
 spine-parts propose --parts work/rig --source painting.png --out work --from-config config.json
@@ -185,6 +191,11 @@ spine-parts build --config config.json --source painting.png --full layers/full
 #    -> read out/check/check.json; every FAIL line names what has to change
 ```
 
+At each step the config holds only what that step reads; the one table of what
+that is, step by step, is [docs/AUTHORING.md §4](docs/AUTHORING.md#4-the-command-order).
+The selftest runs this block in order, command by command, on each fetched example,
+from a config holding only what the first step reads (`RL01`).
+
 `propose` is deliberately not a step of `build`: the proposal is a draft to correct
 against its overlay, and a config with bones is `build`'s input. `rig`, `check` and
 `loop` are the same stages one at a time. [docs/AUTHORING.md](docs/AUTHORING.md) is
@@ -200,17 +211,17 @@ agent skill.
 | `inputs --source <png> --config <json> --out <dir>` | the two images See-through is fed: the painting on a white square, and the head box's crop once the config has one |
 | `comfy paint --config --out [--host]` | optional: generate the painting on a ComfyUI box from the config's `generation` block |
 | `comfy seethrough --image --out [--host]` | optional: run the ComfyUI See-through wrapper on one image and write the form `layers` reads |
-| `layers <dir \| layers.json \| file.psd>` | print every layer of a decomposition: draw order, name, tag group, box, size, opaque pixels, depth |
+| `layers <dir \| layers.json \| file.psd>` | print every layer of a decomposition: draw order, name, tag group, box, size, opaque pixels, depth, and its translucent, background and area figures; a `WARN` line for a layer `--propose-plan` will leave out |
 | `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 --propose-plan …` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule |
+| `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json`, the recomposite and its error map, and list the uncovered holes |
 | `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, 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 |
 
 `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,24 +240,45 @@ 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
-  whether an accessory swings are the corrector's to add.
+  whether an accessory swings are the corrector's to add. The one accessory shape it
+  measures is a hanging strand on a headwear or earwear layer: each gets a pendulum
+  chain, and a strand it cannot chain is named in a note rather than left stiff.
 
 ### 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,16 +16,16 @@ 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 { 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 { 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 { 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';
 import { proposeHeadBox } from './src/headbox.ts';
 import { makeInputs } from './src/inputs.ts';
-import { type LayerSet, readLayers } from './src/layers.ts';
-import { checkProposal, compare, compareLines, drawLandmarks, lint, lintLine, type PartSet, propose, readPartSet, serializeProposal } from './src/propose.ts';
+import { figuresPhrase, implausibleRules, layerFigures, type LayerSet, pct, readLayers, ruleSummary, times } from './src/layers.ts';
+import { checkProposal, compare, compareLines, drawLandmarks, HIP_MIN_FRACTION, lint, lintLine, type PartSet, propose, readPartSet, serializeProposal } from './src/propose.ts';
 import { readPng, writePng } from './src/raster/png.ts';
 import { buildSheet, defaultCaption, type Tile, tilesFrom } from './src/sheet.ts';
 
@@ -52,9 +52,14 @@ usage:
   spine-parts layers <dir | layers.json | file.psd>
       Read a See-through decomposition — the ComfyUI wrapper form (a directory
       holding layers.json and one PNG per layer) or an upstream .psd — and print
-      every layer: draw order, name, tag group, box, size, opaque pixels, depth.
-      Refuses, by name, a missing file, an unknown tag, a PNG whose size is not
-      its box, and anything else outside the input contract.
+      every layer: draw order, name, tag group, box, size, opaque pixels, depth,
+      and three plausibility figures over its opaque pixels — translucent share
+      (alpha below 128), background share (min channel above 235) and area as a
+      multiple of the rest of the figure (the other layers' union). A layer that
+      crosses a plausibility rule gets a WARN line naming the rule and the bar;
+      --propose-plan leaves it out. Refuses, by name, a missing file, an
+      unknown tag, a PNG whose size is not its box, and anything else outside
+      the input contract — never a WARN.
 
   spine-parts sheet --source <painting.png> --layers <path> [--layers <path> ...]
                     --out <sheet.png> [--cell <px>] [--cols <n>]
@@ -68,9 +73,15 @@ usage:
       Propose bones, meshes, regions and an idle from the assembled parts (<dir>
       holds parts.json and parts/). Roles come from each part's See-through tag,
       never its name. Writes <out>/proposal.json (config-shaped: bones, meshes,
-      regions, motion with its blink, 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.
+      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 — 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
+      hip that is not below the chest, and for a hip above ${HIP_MIN_FRACTION} of the figure's
+      height (the shoulders); a headwear/earwear layer with hanging strands
+      gets one pendulum chain per strand and a note with each strand's x, rows
+      and width ("-- no chain proposed" is the one to act on; AUTHORING §3).
       --compare prints each shared bone's distance, proposal to config, in px.
 
   spine-parts propose --parts <dir> --source <painting.png> --out <dir> --from-config <config.json>
@@ -86,7 +97,9 @@ usage:
       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
-      part in config.regions, and one idle of sines and a blink. --parts is the
+      part in config.regions (a motion.blink.still part as two: the rows above
+      its row on a second slot <part>_still, which the blink does not move),
+      and one idle of sines and a blink. --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
@@ -95,45 +108,86 @@ usage:
   spine-parts check --rig <dir> --out <dir> [--parts <dir>]
       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 holds parts.json and parts/ and defaults to
-      --rig. Both are only read. Into --out:
+      (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),
       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. Then RECOMPOSITE_HOLES: REPORTED,
+      read from parts.json's recomposite block (uncovered error px, hole count,
+      the largest hole's box and the parts bordering it) — a line with no bar,
+      never a FAIL, because a pixel no part holds is missing from both sides of
+      the seam; SKIP when parts.json has no such block. 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}.
+      <out>/rig/parts/<name>.png (each cropped to its alpha box), <out>/rig/parts.json,
+      <out>/render/recomposite_rig.png and <out>/render/${ERROR_MAP_FILE} (the error
+      map: uncovered error px red, covered error px blue, the rest the painting in
+      light grey). Reads config.seethrough.head_box and
+      .resolution and config.assemble.rig_scale, .plan, .extend_below_crop and
+      .patches — extra parts cut from the painting itself over a rig-pixel box
+      (alpha "silhouette": the painting's figure inside it; "box": all of it),
+      drawn "back", "front" or {"before": <plan part>}, recorded in parts.json
+      as from "painting:<name>" and counted 100 % source — and no rig section:
+      bones, meshes, regions and motion need not exist yet, because propose
+      drafts them from these parts (AUTHORING §4, the table).
+      Prints one line per part, the seam override counts, the \`pixels:\` totals
+      (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), then the uncovered holes (8-connected) and the
+      largest ${HOLES_LISTED}, each \`uncovered hole N: <px> px at x,y wxh (between
+      "<part>" <px> px, …)\` — the list parts.json holds under recomposite.
+      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>
       Print {plan, extend_below_crop, notes} for config.assemble, from the two
-      runs. Reads only config.seethrough.head_box, config.seethrough.resolution
-      and config.assemble.rig_scale — the rest of the config need not exist yet.
+      runs. A layer \`layers\` WARNs about (PLAN_LAYER_TRANSLUCENT,
+      PLAN_LAYER_BACKGROUND, PLAN_LAYER_OVERSIZED) is not proposed, and a note
+      names it, its figures and the rule. Reads only config.seethrough.head_box,
+      config.seethrough.resolution and config.assemble.rig_scale — the rest of
+      the config need not exist yet.
 
   spine-parts inputs --source <painting.png> --config <config.json> --out <dir>
       Cut the two images See-through is fed: <out>/st_input_full.png (the
@@ -162,21 +216,27 @@ 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
       bones, meshes, regions and motion — propose is not a step of build: run it,
       correct the proposal against its overlay, and write the result into the
-      config. Into --out: parts/ + parts.json + recomposite_rig.png (assemble),
+      config. Into --out: parts/ + parts.json + recomposite_rig.png +
+      ${ERROR_MAP_FILE} (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
@@ -206,7 +266,8 @@ function fixed(v: number | null): string {
 function printLayerTable(set: LayerSet): void {
   console.log(`spine-parts layers: ${set.form === 'wrapper' ? 'ComfyUI wrapper form' : 'PSD'}, ${set.source}`);
   console.log(`  canvas ${set.canvas.w}x${set.canvas.h}, ${set.layers.length} layer(s), back to front`);
-  const rows = set.layers.map((l) => [
+  const figures = layerFigures(set);
+  const rows = set.layers.map((l, i) => [
     String(l.drawOrder),
     l.name,
     l.tag.group,
@@ -215,14 +276,26 @@ function printLayerTable(set: LayerSet): void {
     `${l.pixels.width}x${l.pixels.height}`,
     String(l.opaquePx),
     fixed(l.depth),
+    pct(figures[i].translucent),
+    pct(figures[i].background),
+    times(figures[i].areaRatio),
   ]);
-  const head = ['order', 'name', 'group', 'left,top', 'right,bottom', 'size', 'opaque_px', 'depth'];
+  const head = ['order', 'name', 'group', 'left,top', 'right,bottom', 'size', 'opaque_px', 'depth', 'translucent', 'background', 'area'];
   const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
   const line = (cells: string[]): string => `  ${cells.map((c, i) => c.padEnd(widths[i])).join('  ')}`.trimEnd();
   console.log(line(head));
   for (const r of rows) console.log(line(r));
   const painted = set.layers.filter((l) => l.opaquePx > 0).length;
   console.log(`  ${set.layers.length} layer(s): ${painted} with opaque pixels, ${set.layers.length - painted} with none`);
+  // A reader refuses nothing on plausibility: it says what --propose-plan will leave out, and why.
+  let warned = 0;
+  for (const f of figures) {
+    for (const rule of implausibleRules(f)) {
+      console.log(`  WARN  ${rule}: layer "${f.name}" — ${figuresPhrase(f)}; ${ruleSummary(rule)} is required, so --propose-plan leaves it out`);
+      warned++;
+    }
+  }
+  console.log(`  ${warned} WARN line(s)`);
 }
 
 function cmdLayers(args: string[]): number {
@@ -271,6 +344,9 @@ function cmdSheet(args: string[]): number {
     const tiles: Tile[] = [{ name: 'source', image: src, caption: basename(source) }];
     for (const path of layers) tiles.push(...tilesFrom(path));
     const sheet = buildSheet(tiles, cols, cell);
+    // The README's loop writes sheets/layers.png into a folder nothing made yet;
+    // every other command creates its --out, so this one does too.
+    mkdirSync(dirname(out), { recursive: true });
     writePng(out, sheet);
     console.log(`spine-parts sheet: ${out}`);
     console.log(`  ${tiles.length} tile(s) in ${cols} column(s) of ${cell} px, sheet ${sheet.width}x${sheet.height}`);
@@ -369,7 +445,8 @@ function printLint(P: PartSet, spec: { bones: CharacterConfig['bones']; meshes:
   const res = lint(P, spec);
   for (const f of res.findings) console.log(lintLine(f));
   for (const m of res.unknownMeshes) console.log(`note: mesh ${JSON.stringify(m)} names no part in parts.json, so it was not linted`);
-  console.log(`${res.findings.length} LINT line(s) over ${Object.keys(spec.meshes).length - res.unknownMeshes.length} mesh(es)`);
+  for (const b of res.missingTorsoBones) console.log(`note: no single bone named ${JSON.stringify(b)}, so the hip was not linted against the chest${b === 'hip' ? ' or the figure height' : ''}`);
+  console.log(`${res.findings.length} LINT line(s) over ${Object.keys(spec.meshes).length - res.unknownMeshes.length} mesh(es) and the hip`);
   return res.findings.length;
 }
 
@@ -456,14 +533,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 +557,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,24 +572,26 @@ 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 },
-      { partsJson: join(out, 'rig', 'parts.json'), partsDir: join(out, 'rig', 'parts'), recomposite: join(out, 'render', 'recomposite_rig.png') },
+      { 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'), errorMap: join(out, 'render', ERROR_MAP_FILE) },
       console.log,
     );
     return EXIT_OK;
@@ -567,7 +653,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 +690,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 +712,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 +734,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 +752,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 +764,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,
     );