spine-parts 0.5.0 → 0.6.0

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,7 +87,7 @@ 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 and their `geometry.json` (skinned vertices per frame), `contact.png`, `motion_heat.png`, `check.json` |
@@ -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.
 

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, RIGC_GEOMETRY_VERSION, type RigcRunner, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } 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';
@@ -98,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
@@ -110,8 +111,8 @@ usage:
       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:
@@ -121,14 +122,14 @@ 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
+      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),
@@ -163,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
@@ -247,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
@@ -263,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
@@ -398,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;
@@ -414,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>');
@@ -421,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);
@@ -456,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);
@@ -767,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') {
@@ -787,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 {
@@ -797,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

@@ -279,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.
@@ -294,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`
@@ -569,6 +601,8 @@ See-through with another seed.
 | `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
@@ -676,7 +710,8 @@ What each figure is, and is not:
 - **The face is measured in the head's frame, and its bar is the model's (issue #33).**
   Until #33 the face half read the screen-space heat map, where the head's intended
   roll lights the outline on both examples (16.988 and 11.475, the figures now
-  reported as `screen_heat_mean`), so its ceiling was twice the worse example,
+  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

package/package.json

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

package/src/build.ts

@@ -44,7 +44,7 @@ import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:
 import { dirname, join } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
 import { assemble, type AssembleResult, figuresLine, holeLines, type ProjectRule, type SeamRule, stageFields } from './assemble.ts';
-import { type CheckReport, JUDGEMENT_LINES, type JudgementLine, readFrameSet, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK } from './check.ts';
+import { type CheckReport, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PageEdges, readFrameSet, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK } from './check.ts';
 import { loadConfig, loadEarlyConfig } from './config.ts';
 import { PartsError, type Problem, problemLine } from './errors.ts';
 import { encodeGif } from './gif.ts';
@@ -183,21 +183,19 @@ function gateRun(label: string, rigc: RigcRunner, args: string[]): GateRun {
 
 /**
  * spine-rigc's round trip over the rig in a scratch directory: `build` under
- * the spine-html profile with `--pack`, then `validate` of that build under
- * the spine profile. The files are staged exactly as `--out` will receive
+ * the spine-html profile with `--pack --page-edges <edges>`, then `validate`
+ * of that build under the spine profile. The files are staged exactly as `--out` will receive
  * them, so what passed is what is written. The scratch directory is the
  * caller's, and is emptied here before and after.
  */
-function gateThroughRigc(out: RigOutput, texts: Array<[string, string]>, rigc: RigcRunner, scratch: string): GateRun[] {
+function gateThroughRigc(out: RigOutput, texts: Array<[string, string]>, rigc: RigcRunner, scratch: string, edges: PageEdges): GateRun[] {
   rmSync(scratch, { recursive: true, force: true });
   try {
     mkdirSync(join(scratch, 'images'), { recursive: true });
     for (const [file, img] of out.images) writeFileSync(join(scratch, 'images', file), encodePngBytes(img));
     for (const [file, text] of texts) writeFileSync(join(scratch, file), text);
     const build = join(scratch, 'build');
-    const html = gateRun('build --profile spine-html --pack', rigc, [
-      'build', '--rig', join(scratch, 'rig.json'), '--motion', join(scratch, 'motion.json'), '--out', build, '--profile', 'spine-html', '--pack',
-    ]);
+    const html = gateRun(packedBuildLabel(edges), rigc, ['build', '--rig', join(scratch, 'rig.json'), '--motion', join(scratch, 'motion.json'), '--out', build, ...packedBuildArgs(edges)]);
     if (html.status !== 0) return [html];
     return [html, gateRun('validate --profile spine', rigc, ['validate', build, '--profile', 'spine'])];
   } finally {
@@ -212,6 +210,8 @@ export interface RigStageInput {
   out: string;
   /** Where the idle's keys on mesh-driving bones go; `ctl` when absent. See `IDLE_KEYS` in `src/rig.ts`. */
   idleKeys?: IdleKeys;
+  /** The gate build's `--page-edges`; {@link DEFAULT_PAGE_EDGES} when absent. The pack is scratch here; the gate is what it is for. */
+  pageEdges?: PageEdges;
 }
 
 /** Author the rig, gate it through rigc in `scratch`, and write `out` only when both gates are green. */
@@ -249,7 +249,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
       ? `  idle keys ctl: ${rig.meshKeyed.length} mesh-driving bone(s) keyed by the idle, each keyed through a same-origin <bone>_ctl parent`
       : `  idle keys direct: ${rig.meshKeyed.length} mesh-driving bone(s) keyed in place, ${rig.rig.invariants === undefined ? 'so no invariants.idleDrivesMeshes is declared (it would switch nothing off)' : 'invariants.idleDrivesMeshes declared'}`,
   );
-  const gate = gateThroughRigc(rig, texts, rigc, scratch);
+  const gate = gateThroughRigc(rig, texts, rigc, scratch, input.pageEdges ?? DEFAULT_PAGE_EDGES);
   for (const g of gate) {
     log(`  rigc ${g.label}: exit ${g.status}`);
     for (const l of g.lines) log(`    ${l.trim()}`);
@@ -280,6 +280,8 @@ export interface CheckStageInput {
   /** The directory holding parts.json and parts/; the rig directory when they sit there. */
   parts: string;
   out: string;
+  /** The packed build's `--page-edges`; {@link DEFAULT_PAGE_EDGES} when absent. */
+  pageEdges?: PageEdges;
 }
 
 /** The pack line as it is printed: rigc's own, then the page's opaque share beside the spineboy yardstick. */
@@ -315,8 +317,9 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   const v = rigc(['--version']);
   log(`spine-parts check: ${input.rig} -> ${input.out}`);
   log(`  rigc ${v.out.trim().split('\n')[0]} at ${bin}`);
-  const r = runCheck(input.rig, input.out, rigc, input.parts);
-  log('  gate spine-html (rigc build --profile spine-html --pack), verbatim:');
+  const edges = input.pageEdges ?? DEFAULT_PAGE_EDGES;
+  const r = runCheck(input.rig, input.out, rigc, input.parts, edges);
+  log(`  gate spine-html (rigc ${packedBuildLabel(edges)}), verbatim:`);
   for (const l of r.gateHtml) log(l);
   log('  gate spine (rigc validate build --profile spine), verbatim:');
   for (const l of r.gateSpine) log(l);
@@ -427,6 +430,8 @@ export interface BuildInput {
   seam: SeamRule;
   project: ProjectRule;
   loop: boolean;
+  /** `--page-edges` for both packed builds, the rig stage's gate and the check's artifact. */
+  pageEdges: PageEdges;
 }
 
 /** The two rigc processes, as each command runs its own: `rig` gates through one, `check` measures through the other. */
@@ -487,7 +492,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   const out = input.out;
   mkdirSync(out, { recursive: true });
   for (const p of BUILD_OWNS) rmSync(join(out, p), { recursive: true, force: true });
-  log(`spine-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}${input.loop ? ', with the idle loop' : ''}`);
+  log(`spine-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}${input.loop ? ', with the idle loop' : ''}`);
 
   try {
     // build runs rig next, which needs the whole config, so the full loader is
@@ -505,14 +510,14 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   }
 
   try {
-    rigStage({ config: input.config, parts: out, out: join(out, 'rig') }, run.rig, run.scratch, prefixed('rig'));
+    rigStage({ config: input.config, parts: out, out: join(out, 'rig'), pageEdges: input.pageEdges }, run.rig, run.scratch, prefixed('rig'));
   } catch (err) {
     return refused('rig', err);
   }
 
   let report: CheckReport;
   try {
-    report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check') }, run.check, run.checkBin, prefixed('check'));
+    report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges }, run.check, run.checkBin, prefixed('check'));
   } catch (err) {
     return refused('check', err);
   }

package/src/check.ts

@@ -23,7 +23,7 @@
  *
  * | output | what |
  * | --- | --- |
- * | `build/` | `rigc build --profile spine-html --pack` — the packed atlas is the final artifact |
+ * | `build/` | `rigc build --profile spine-html --pack --page-edges free` (or `pot`, when the caller names it; {@link PAGE_EDGES}) — the packed atlas is the final artifact |
  * | `gate_spine-html.txt` | that build's gate lines, verbatim |
  * | `gate_spine.txt` | `rigc validate build/ --profile spine`'s gate lines, verbatim |
  * | `idle_frames/` | `rigc render --animation idle --fps 12 --max 640 --geometry`: `frames.json` + `idle/f*.png` + `idle/geometry.json` (each mesh's skinned vertices, which `TEXTURE_STRETCH` reads, and every bone's world transform, which the face half of `STILL_REGIONS_DARK` reads) |
@@ -184,6 +184,40 @@ export const GEOMETRY_SPEC = 'rigc-geometry/1';
 /** Issue #2's yardstick, measured on the Spine example export `spineboy.png` (alpha > 0). */
 export const SPINEBOY_YARDSTICK = '1024x256, 40 region(s), 45.8% opaque (alpha > 0)';
 
+/**
+ * What a packed page's edges may be: spine-rigc's `build --pack --page-edges`,
+ * handed to it verbatim (the flag is in spine-rigc's CLI since 1.4.0, the
+ * floor `check` already requires; 1.5.0 made `free` search every width).
+ * `pot` is a power of two on both edges; `free` is the least-area page the
+ * placement needs, at the cost rigc's help states: region attachments sample
+ * within 1 LSB of the loose build rather than exactly.
+ *
+ * `free` is the default here although rigc's own default is `pot`: the packed
+ * page is this package's final artifact, and on the two public examples `free`
+ * takes the page from 1024x2048 to 967x1338 (covered 56.3 % -> 91.2 %) and
+ * from 512x2048 to 479x1166 (49.7 % -> 93.4 %), rigc 1.5.1. The cost was
+ * measured on the same two builds. Each of the 49 idle frames differs from the
+ * `pot` build's, by at most 1 level in any channel (demo 2,373 px, sample 651
+ * px over all 49). On sample that moves STILL_REGIONS_DARK's reported
+ * screen-space face mean from 11.475 to 11.472; no bar or status moves. The
+ * atlas rigc writes says `filter: Linear, Linear` and has no `repeat` line, so
+ * a consumer that mipmaps or repeats the page itself is the one that wants
+ * `pot`. AUTHORING §5, *Page edges*, holds the tables.
+ */
+export const PAGE_EDGES = ['pot', 'free'] as const;
+export type PageEdges = (typeof PAGE_EDGES)[number];
+export const DEFAULT_PAGE_EDGES: PageEdges = 'free';
+
+/** The packed build's rigc arguments after `--out <dir>`, as every stage that packs passes them. */
+export function packedBuildArgs(edges: PageEdges): string[] {
+  return ['--profile', 'spine-html', '--pack', '--page-edges', edges];
+}
+
+/** The packed build as a label: the rigc command line that was run, after `rigc`. */
+export function packedBuildLabel(edges: PageEdges): string {
+  return `build ${packedBuildArgs(edges).join(' ')}`;
+}
+
 // ---------------------------------------------------------------------------
 // the rigc process, injected
 // ---------------------------------------------------------------------------
@@ -423,19 +457,68 @@ export interface PackLine {
   regions: number;
   coveredPct: number;
   padding: number;
+  /** `free` when the line ends `, page edges free`, `pot` when it carries no suffix — spine-rigc prints the suffix exactly when it packed under `--page-edges free` (its `cli.ts`, the pack line). */
+  pageEdges: PageEdges;
 }
 
-const PACK = /pack: (\S+) (\d+)x(\d+), (\d+) region\(s\), ([\d.]+)% covered, padding (\d+)/;
+/** rigc's pack line, whole: the line is this and nothing else, or it is refused. */
+const PACK = /^pack: (\S+) (\d+)x(\d+), (\d+) region\(s\), (\d+(?:\.\d+)?)% covered, padding (\d+)(, page edges free)?$/;
 
+/**
+ * Every pack line among the gate lines — a line that reads `pack:` once its
+ * `..` gutter is taken off. A pack line spine-rigc 1.5.1 would not print (an
+ * unknown suffix, a missing field) is refused, `CHECK_PACK_LINE_READS`, naming
+ * the line and the form required: a line half-read would lose the one field
+ * that changed.
+ */
 export function parsePackLines(lines: readonly string[]): PackLine[] {
   const out: PackLine[] = [];
+  const problems: Problem[] = [];
   for (const l of lines) {
-    const m = PACK.exec(l);
-    if (m !== null) out.push({ line: l.trim().replace(/^\.\.\s+/, ''), page: m[1], width: Number(m[2]), height: Number(m[3]), regions: Number(m[4]), coveredPct: Number(m[5]), padding: Number(m[6]) });
+    const text = l.trim().replace(/^\.\.\s+/, '');
+    if (!text.startsWith('pack:')) continue;
+    const m = PACK.exec(text);
+    if (m === null) {
+      problems.push({
+        code: 'CHECK_PACK_LINE_READS',
+        object: `rigc's pack line ${JSON.stringify(text)}`,
+        detail: 'does not read as "pack: <page> <W>x<H>, <N> region(s), <P>% covered, padding <D>", with ", page edges free" after it or nothing; that form is required',
+      });
+      continue;
+    }
+    out.push({ line: text, page: m[1], width: Number(m[2]), height: Number(m[3]), regions: Number(m[4]), coveredPct: Number(m[5]), padding: Number(m[6]), pageEdges: m[7] === undefined ? 'pot' : 'free' });
   }
+  refuseIfAny(problems);
   return out;
 }
 
+function powerOfTwo(n: number): boolean {
+  return Number.isInteger(n) && n > 0 && (n & (n - 1)) === 0;
+}
+
+/**
+ * Where a pack line disagrees with the `--page-edges` the build was given:
+ * the line's own suffix must say the same, and a `pot` page must be a power of
+ * two on both edges, as rigc's help defines it. One problem per disagreement,
+ * `CHECK_PACK_PAGE_EDGES`; empty is agreement.
+ */
+export function packEdgeProblems(pack: readonly PackLine[], edges: PageEdges): Problem[] {
+  const problems: Problem[] = [];
+  for (const p of pack) {
+    const object = `packed page ${p.page}`;
+    if (p.pageEdges !== edges) {
+      problems.push({
+        code: 'CHECK_PACK_PAGE_EDGES',
+        object,
+        detail: `rigc's pack line says page edges ${p.pageEdges} (${p.pageEdges === 'free' ? 'it ends ", page edges free"' : 'no ", page edges free" suffix'}); the build was run with --page-edges ${edges}, so page edges ${edges} is required`,
+      });
+    } else if (edges === 'pot' && !(powerOfTwo(p.width) && powerOfTwo(p.height))) {
+      problems.push({ code: 'CHECK_PACK_PAGE_EDGES', object, detail: `is ${p.width}x${p.height}; the build was run with --page-edges pot, so a power of two on both edges is required` });
+    }
+  }
+  return problems;
+}
+
 /** Share of a page's pixels with alpha above 0 — the measure issue #2's spineboy figure is in. rigc's "covered" is region rectangles, not pixels. */
 export function opaqueShare(r: Raster): number {
   let n = 0;
@@ -745,9 +828,11 @@ function rigcFailed(what: string, call: RigcCall, lines: readonly string[]): Pro
  * gate file is written first, so the refusal's evidence is on disk. Otherwise
  * it measures everything, writes every output including `check.json`, and
  * returns the report; `report.problems` names each bar that was not met, and
- * `figures.PASS` is true exactly when it is empty.
+ * `figures.PASS` is true exactly when it is empty. `pageEdges` reaches rigc's
+ * `--page-edges` verbatim, and a pack line that disagrees with it is refused
+ * (`CHECK_PACK_PAGE_EDGES`).
  */
-export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome: string = rigDir): CheckReport {
+export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome: string = rigDir, pageEdges: PageEdges = DEFAULT_PAGE_EDGES): CheckReport {
   const inp = readCheckInputs(rigDir, partsHome);
   requireRigcVersion(rigc);
   const out = resolve(outDir);
@@ -764,11 +849,12 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   };
 
   // 1. build, packed, under the policy profile
-  const build = rigc(['build', '--rig', inp.rigPath, '--motion', inp.motionPath, '--out', buildDir, '--profile', 'spine-html', '--pack']);
+  const build = rigc(['build', '--rig', inp.rigPath, '--motion', inp.motionPath, '--out', buildDir, ...packedBuildArgs(pageEdges)]);
   const gateHtml = buildGateLines(build.out);
   write('gate_spine-html.txt', `${gateHtml.join('\n')}\n`);
-  if (build.status !== 0) refuseIfAny(rigcFailed('build --profile spine-html --pack', build, gateHtml));
+  if (build.status !== 0) refuseIfAny(rigcFailed(packedBuildLabel(pageEdges), build, gateHtml));
   const pack = parsePackLines(gateHtml);
+  refuseIfAny(packEdgeProblems(pack, pageEdges));
   const packOpaque = pack.filter((p) => existsSync(join(buildDir, p.page))).map((p) => ({ page: p.page, share: opaqueShare(readPng(join(buildDir, p.page))) }));
 
   // 2. validate under the validity profile
@@ -907,7 +993,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     PASS: false,
   };
   const barProblems: Problem[] = [];
-  if (!htmlGreen) barProblems.push(...rigcFailed('build --profile spine-html --pack', build, gateHtml));
+  if (!htmlGreen) barProblems.push(...rigcFailed(packedBuildLabel(pageEdges), build, gateHtml));
   if (!spineGreen) barProblems.push(...rigcFailed('validate --profile spine', validate, gateSpine));
   if (figures.loop_max_diff !== LOOP_MAX_BAR) {
     barProblems.push({