spine-parts 0.7.0 → 0.8.0

package/README.md

@@ -34,17 +34,17 @@ was shifted down into the canvas (its proposal ran 118 px above the top edge;
 <code>propose --head-box</code> now makes that shift itself), and <code>hair_back</code>
 is taken from the full run, because the twin tails leave the head crop sideways
 (a plan edit). <code>check</code> printed, verbatim:<br/>
-<code>49 assertions: 23 measured (23 passed, 0 failed), 26 skipped, 0 not in profile "spine-html"</code><br/>
+<code>50 assertions: 24 measured (24 passed, 0 failed), 26 skipped, 0 not in profile "spine-html"</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 967x1338, 22 region(s), 91.2% covered, padding 2, page edges free</code><br/>
+<code>pack: skeleton.png 922x1348, 22 region(s), 95.0% covered, padding 2, page edges free, shape polygon</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,520 bytes, one 256-entry palette at a measured error of max 57, mean 1.601
+12 fps, 1,706,719 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,350 bytes; the GIF, at the same error, 1,812,238). Frame 29 (2.417 s) is the
+13,645,503 bytes; the GIF, at the same error, 1,812,288). 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
@@ -86,10 +86,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 --page-edges free` and gated under `spine-html`, which holds every rule `spine` measures (on the demo, rigc 1.5.1 and 2.0.3: the 14 rules `validate --profile spine` measures are among the build's 23; 15 are not in `spine`) |
+| `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 --pack-shape polygon` and gated under `spine-html`, which holds every rule `spine` measures (on the demo, rigc 2.1.3: the 14 rules `validate --profile spine` measures are among the build's 24; 16 are not in `spine`) |
 | `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` |
+| `check/` | both gate files verbatim, the idle's frames and their `geometry.json` (skinned vertices per frame), `contact.png`, `motion_heat.png`, `check.json` (with `pack_mode`, the `--page-edges` and `--pack-shape` the page was packed under) |
 | `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
@@ -98,15 +98,15 @@ 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 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
+  pack: skeleton.png 477x1151, 20 region(s), 95.0% covered, padding 2, page edges free, shape polygon; page opaque 54.8% (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
+not the next power of two. On the two examples, packed by rectangles, 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
@@ -115,6 +115,16 @@ consumer that mipmaps or repeats the page; it writes exactly the page builds wro
 before the flag existed. The measurements are in
 [AUTHORING §5, *Page edges*](docs/AUTHORING.md#5-after-each-stage-what-to-read).
 
+The pack shape is `polygon` by default (spine-rigc 2.1): a region only meshes draw is
+packed by its emitted hull, so a neighbour may sit inside its rectangle where the hull
+is not; a region attachment stays its rectangle. On the two examples that takes the
+free page from 967x1338 to 922x1348 (covered 91.2 % to 95.0 %, 3.9 % less area) and
+from 479x1166 to 477x1151 (93.4 % to 95.0 %, 1.7 % less), at the cost class `free`
+already has: every idle frame within 1 level of the `rect` build's, and no figure in
+`check.json` but `pack_mode` moves. `--pack-shape rect` writes the page and atlas
+0.7.0 wrote. The measurements are in
+[AUTHORING §5, *Pack shape*](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

@@ -17,7 +17,7 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
 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 { 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 { DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, type PackShape, 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';
@@ -97,7 +97,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]
+                  [--page-edges pot|free] [--pack-shape rect|polygon]
       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 +110,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 with --page-edges as for
-      check; rigc's build gates the compile and the packed pages on disk) in a
+      through spine-rigc (profile spine-html, packed with --page-edges and
+      --pack-shape as for check; rigc's build gates the compile and the packed pages on disk) in a
       scratch directory first, and --out receives images/*.png, rig.json,
       motion.json and mesh_report.json only when it is green. Prints one line
       per mesh and the rigc gate lines.
@@ -123,18 +123,19 @@ usage:
       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>] [--page-edges pot|free]
+                    [--pack-shape rect|polygon]
       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 --page-edges <value>: the
-      packed atlas is the artifact), gate_spine-html.txt (the gate lines
+      build/ (rigc build --profile spine-html --pack --page-edges <value>
+      --pack-shape <value>: the packed atlas is the artifact), gate_spine-html.txt (the gate lines
       verbatim), idle_frames/ (rigc render --animation idle --fps 12 --max 640
       --geometry: the frames and geometry.json, the skinned vertices and
       every bone's world transform per frame),
       contact.png, motion_heat.png and check.json (with rigc_entry, the rigc
-      entry that gated the build). PASS needs every gate summary
+      entry that gated the build, and pack_mode, the two pack flags). PASS needs every gate summary
       "0 failed", the seam (setup pose vs the flat composite of parts/) at mean
       |d| <= ${SEAM_MEAN_BAR.toFixed(1)} with <= ${SEAM_PX_BAR} px over ${SEAM_PX_LEVEL}, and the loop (idle frame 0 vs the
       frame at t = duration) at max |d| 0. Then six judgement lines, each in
@@ -166,15 +167,25 @@ usage:
       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
+      least-area page the parts need (on the two public examples, rect, 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
+      Linear and no repeat). rigc's pack line carries ", 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.
+      --pack-shape is handed to rigc verbatim and defaults to ${DEFAULT_PACK_SHAPE}:
+      a region only meshes draw is packed by its emitted hull, so a neighbour
+      may sit inside its rectangle where the hull is not (on the two public
+      examples, under free, 922x1348 and 477x1151 where rect writes 967x1338
+      and 479x1166), at the cost of the same 1-level class as free (measured
+      on both examples: every idle frame within 1 level of the rect build's;
+      AUTHORING §5, Pack shape). rect keeps every region's cell apart and
+      writes the page earlier releases wrote. rigc's pack line ends
+      ", shape rect" or ", shape polygon"; a line that disagrees with the
+      value passed is refused, CHECK_PACK_SHAPE.
 
   spine-parts loop --frames <dir> --out <file.png | file.gif> [--palette]
       Encode a frame set rigc render wrote (its --out directory, or the set
@@ -259,7 +270,8 @@ 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] [--page-edges pot|free] [--loop]
+                    [--project core|visible] [--page-edges pot|free]
+                    [--pack-shape rect|polygon] [--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
@@ -275,8 +287,9 @@ 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), --page-edges to ${DEFAULT_PAGE_EDGES}
-      (as for check; both packed builds, rig's gate and check's artifact, take it).
+      ${DEFAULT_PROJECT_RULE} (both as for assemble), --page-edges to ${DEFAULT_PAGE_EDGES} and
+      --pack-shape to ${DEFAULT_PACK_SHAPE} (as for check; both packed builds, rig's gate
+      and check's artifact, take them).
 
   spine-parts --version
   spine-parts --help
@@ -407,16 +420,27 @@ function isPageEdges(v: PageEdges | string): v is PageEdges {
   return (PAGE_EDGES as readonly string[]).includes(v);
 }
 
+/** `--pack-shape`, or its default; a value spine-rigc does not take is a usage error naming the two it does. */
+function packShapeOf(value: string | undefined): PackShape | string {
+  const shape = value ?? DEFAULT_PACK_SHAPE;
+  return (PACK_SHAPES as readonly string[]).includes(shape) ? (shape as PackShape) : `--pack-shape ${shape}; one of ${PACK_SHAPES.join(', ')} is required`;
+}
+
+function isPackShape(v: PackShape | string): v is PackShape {
+  return (PACK_SHAPES 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;
+  let packShape: 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', '--page-edges'].includes(flag)) return usage(`rig does not take "${flag}"`);
+    if (!['--config', '--parts', '--out', '--idle-keys', '--page-edges', '--pack-shape'].includes(flag)) return usage(`rig does not take "${flag}"`);
     if (value === undefined) return usage(`${flag} needs a value`);
     i++;
     if (flag === '--config') config = value;
@@ -427,6 +451,9 @@ function cmdRig(args: string[]): number {
     } else if (flag === '--page-edges') {
       if (pageEdges !== null) return usage('--page-edges is given twice');
       pageEdges = value;
+    } else if (flag === '--pack-shape') {
+      if (packShape !== null) return usage('--pack-shape is given twice');
+      packShape = value;
     } else out = value;
   }
   if (config === null) return usage('rig needs --config <config.json>');
@@ -436,6 +463,8 @@ function cmdRig(args: string[]): number {
   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 shape = packShapeOf(packShape ?? undefined);
+  if (!isPackShape(shape)) return usage(shape);
   let bin: string;
   try {
     bin = findRigc(import.meta.dir, process.env.PATH ?? '');
@@ -444,7 +473,7 @@ function cmdRig(args: string[]): number {
   }
   const scratch = mkdtempSync(join(tmpdir(), 'spine-parts-rig-'));
   try {
-    rigStage({ config, parts: partsDir, out, idleKeys: keys as IdleKeys, pageEdges: edges }, rigcRunner(bin), scratch, console.log);
+    rigStage({ config, parts: partsDir, out, idleKeys: keys as IdleKeys, pageEdges: edges, packShape: shape }, rigcRunner(bin), scratch, console.log);
     return EXIT_OK;
   } catch (err) {
     return printRefusal(err);
@@ -486,15 +515,17 @@ function flags(args: string[], known: readonly string[], command: string, option
 }
 
 function cmdCheck(args: string[]): number {
-  const f = flags(args, ['--rig', '--out'], 'check', ['--parts', '--page-edges']);
+  const f = flags(args, ['--rig', '--out'], 'check', ['--parts', '--page-edges', '--pack-shape']);
   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);
+  const shape = packShapeOf(f.get('--pack-shape'));
+  if (!isPackShape(shape)) return usage(shape);
   try {
     const bin = findRigc(import.meta.dir, process.env.PATH ?? '');
-    const r = checkStage({ rig, parts: f.get('--parts') ?? rig, out, pageEdges: edges }, rigcRunner(bin), bin, console.log);
+    const r = checkStage({ rig, parts: f.get('--parts') ?? rig, out, pageEdges: edges, packShape: shape }, rigcRunner(bin), bin, console.log);
     return r.figures.PASS ? EXIT_OK : EXIT_REFUSED;
   } catch (err) {
     return printRefusal(err);
@@ -799,7 +830,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', '--page-edges'];
+  const valued = ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape'];
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === '--loop') {
@@ -821,6 +852,8 @@ function cmdBuild(args: string[]): number {
   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 shape = packShapeOf(flags.get('--pack-shape'));
+  if (!isPackShape(shape)) return usage(shape);
   const [config, source, full, head, out] = ['--config', '--source', '--full', '--head', '--out'].map((f) => flags.get(f) as string);
   let bin: string;
   try {
@@ -831,7 +864,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, pageEdges: edges },
+      { config, source, full, head, out, seam: seam as SeamRule, project: project as ProjectRule, loop, pageEdges: edges, packShape: shape },
       { rig: rigcRunner(bin), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'rig-gate') },
       console.log,
     );

package/docs/AUTHORING.md

@@ -279,11 +279,12 @@ 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,350 B lossless, 1,706,520 B indexed and 1,812,238 B GIF, both palette files at
+13,645,503 B lossless, 1,706,719 B indexed and 1,812,288 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. 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
+animation, spine-rigc 2.1.3); with `--pack-shape rect` the same build writes 13,645,350,
+1,706,520 and 1,812,238 B, and with `--page-edges pot --pack-shape rect` 13,645,519,
+1,706,785 and 1,812,625 B, all 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.
@@ -300,10 +301,11 @@ the reference's so the examples stay comparable with it.
 --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 on the two examples by `tools/atlas_population.ts` with rigc 1.5.1, and again
-with rigc 2.0.3, which reproduced every figure in both tables and the one check figure
-below:
+line says which one ran, because rigc writes `, page edges free` after the padding under
+`free`. Measured on the two examples by `tools/atlas_population.ts` with rigc 1.5.1, and
+again with rigc 2.0.3 and with rigc 2.1.3 under `--pack-shape rect` (the frames table
+by the same idle render), which reproduced every figure in both tables and the one
+check figure below:
 
 | build | page | covered | page opaque | page / figure |
 | --- | --- | --- | --- | --- |
@@ -328,6 +330,56 @@ barred figure and every status is the same under both. The atlas rigc writes say
 `filter: Linear, Linear` and has no `repeat` line, so choose `pot` for a consumer
 that mipmaps or repeats the page.
 
+**Pack shape.** `rig`, `check` and `build` also hand rigc `--pack-shape <v>`
+verbatim (spine-rigc 2.1.0 and later). `rect` keeps every region's cell apart, the
+only packing before 2.1. `polygon`, the default here (rigc's own is `rect`), packs a
+region that only meshes draw by its emitted hull, so a neighbour may sit inside its
+rectangle where the hull is not, with the padding kept between footprints; a region
+attachment stays its rectangle. rigc gates the result on the packed pages with
+`A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP` (SKIP on the compile pass, where every part has
+its own page; PASS on the packed pass, both shapes, both examples). The pack line ends
+`, shape rect` or `, shape polygon` under either, and `check.json`'s `pack_mode` records
+both flags. Measured on the two examples with spine-rigc 2.1.3 (the full entry,
+spine-core 4.3.13 beside it), `spine-parts build` with `--page-edges free` and each
+shape, the table columns by `tools/atlas_population.ts`:
+
+| build | page | page area | covered | page opaque | page / figure |
+| --- | --- | --- | --- | --- | --- |
+| demo, `rect` | 967x1338 | 1,293,846 | 91.2 % | 59.7 % | 1.636 |
+| demo, `polygon` | 922x1348 | 1,242,856 (−3.9 %) | 95.0 % | 62.1 % | 1.571 |
+| sample, `rect` | 479x1166 | 558,514 | 93.4 % | 53.9 % | 1.755 |
+| sample, `polygon` | 477x1151 | 549,027 (−1.7 %) | 95.0 % | 54.8 % | 1.725 |
+
+Covered is Σ region rectangles over page area, as rigc prints it; under `polygon` the
+rectangles may overlap where a hull leaves room, so it is not a union and can exceed
+100 %. Page opaque is the measure of what the page holds. Under `--page-edges pot` the
+shape changes nothing on these two examples: both shapes write 1024x2048 and 512x2048,
+and the idle frames are identical.
+
+The cost, from `rect` to `polygon` (the idle `check` renders, `rigc render --animation
+idle --fps 12 --max 640`, compared frame by frame, max over R, G, B and A):
+
+| example | idle frames that differ | pixels that differ (all 49 frames) | max \|d\| |
+| --- | --- | --- | --- |
+| demo | 49 of 49 | 2,594 | 1 |
+| sample | 49 of 49 | 740 | 1 |
+
+That is the class `free` already costs (the table above, measured by the same
+comparison), a little larger. No figure in `check.json` moved but `pack_mode`: every
+bar, every status and every reported figure is the same under both shapes.
+`--pack-shape rect` gives back the page and atlas 0.7.0 wrote: on both examples
+they are byte-identical to rigc 2.0.3's `--page-edges free` build of the same rig (the
+skeleton JSON differs only in its relative `images` path), and selftest `CK53` holds
+`rect` to rigc's own rectangle page.
+
+The hull ceiling (spine-parts #58: hull area over rectangle area, 0.812 on demo and
+0.814 on sample) is not what the packer realises here: the hollows inside the meshes'
+rectangles are worth only what fits into them. On the polygon pages, read off the
+atlas, demo's packed rectangles overlap in 21 pairs (17 a region attachment inside a
+mesh's rectangle, 4 a mesh inside another's) and sample's in 12 (10 and 2); no two
+region attachments overlap. More would take tighter hulls, meshes in place of
+regions, or a stronger nesting search in rigc, each its own card.
+
 `--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`
@@ -590,7 +642,7 @@ See-through with another seed.
 | `CHECK_RIGC_PRESENT` | no `rigc` binary found (every place looked is listed) | `bun install` |
 | `CHECK_INPUT_PRESENT` on `…/parts.json` | `--parts` named a directory without `parts.json` — most often `parts/` itself. The detail says it: "--parts names the directory holding parts.json and parts/, not parts/ itself (after build, that is build's --out, whose rig is <out>/rig); without --parts it is --rig", and names the parent when the parent holds `parts.json` | `--parts` — the directory above `parts/` |
 | `CHECK_INPUT_PRESENT`, `CHECK_INPUT_IS_JSON`, `CHECK_PART_PNG_PRESENT`, `CHECK_PART_PNG_MATCHES_BOX`, `CHECK_PART_SLOT_PRESENT`, `CHECK_RIG_STAGE_PRESENT`, `CHECK_RIG_STAGE_IS_THE_CANVAS`, `CHECK_RIG_ROOT_BONE`, `CHECK_IDLE_PRESENT` | the rig directory is incomplete or disagrees with `parts.json` (`CHECK_PART_SLOT_PRESENT`: a part with no slot of its own name, which the judgement lines render it by) | re-run rig (`build` does both) |
-| `CHECK_RIGC_VERSION` | `rigc --version` is below 1.4.0, or prints no version: its `render` has no `--geometry`, which `TEXTURE_STRETCH` reads. Refused before anything is built | `bun install` (this package depends on spine-rigc ^2.0.3), or put a newer `rigc` first on `PATH` |
+| `CHECK_RIGC_VERSION` | `rigc --version` is below 1.4.0, or prints no version: its `render` has no `--geometry`, which `TEXTURE_STRETCH` reads. Refused before anything is built | `bun install` (this package depends on spine-rigc ^2.1.3), or put a newer `rigc` first on `PATH` |
 | `CHECK_RIGC_ENTRY`, `CHECK_RIGC_ENTRY_READS` | `rigc --version` names no entry (a rigc below 2.0.0), or names one in neither launcher form (`entry: cli.ts — @esotericsoftware/spine-core <v> present`, `entry: cli_core.ts — @esotericsoftware/spine-core absent — …`); `check.json`'s `rigc_entry` records the one that gated the build | `bun install` |
 | `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 |
@@ -604,8 +656,9 @@ 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` |
+| `CHECK_PACK_LINE_READS` | rigc printed a `pack:` line that is not `pack: <page> <W>x<H>, <N> region(s), <P>% covered, padding <D>`, then `, page edges free` or nothing, then `, shape rect`, `, shape polygon` or nothing (spine-rigc 2.1 prints the shape; 1.5–2.0 printed none, read as `rect`); an unknown shape is this refusal; 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` clause 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` |
+| `CHECK_PACK_SHAPE` | the pack line disagrees with the `--pack-shape` the build was run with — it ends `, shape rect` under `polygon` or `, shape polygon` under `rect`, or it has no shape clause (the 1.5–2.0 form, read as `rect`) under `polygon` | a rigc older than 2.1.0 on `PATH`: rigc 2.0.3 takes `--pack-shape` without a word, packs by rectangles and prints the form with no shape clause, so this refusal is what catches it — `bun install` (this package depends on spine-rigc ^2.1.3); otherwise 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
@@ -617,7 +670,9 @@ implementation's bars):
   under the `spine-html` profile, gated once over the compile and once over the packed
   pages on disk. There is no `spine` gate of its own: `spine-html` holds every rule
   `spine` measures (on the demo, rigc 1.5.1 and 2.0.3: `validate --profile spine`'s 14
-  measured rules are all among the build's 23, the 15 others not in `spine`; `CH09`
+  measured rules are all among the build's 23, the 15 others not in `spine`; rigc
+  2.1.3: the same 14 among the build's 24, which adds
+  `A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP` on the packed pass, 16 not in `spine`; `CH09`
   holds it on every fetched example);
 - **seam**: the setup-pose render against the flat composite of `parts/`: mean
   max-channel |d| ≤ 1.0 of 255, and at most 50 pixels over 40;

package/package.json

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

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 { causeLines, type CheckReport, type PackLine, 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 { causeLines, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, 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';
@@ -192,21 +192,21 @@ function gateRun(label: string, rigc: RigcRunner, args: string[]): GateRun {
 
 /**
  * spine-rigc's gate over the rig in a scratch directory: `build` under the
- * spine-html profile with `--pack --page-edges <edges>`, which runs the gate
+ * spine-html profile with `--pack --page-edges <edges> --pack-shape <shape>`, which runs the gate
  * once over the compile and once over the packed pages on disk. There is no
  * second `validate --profile spine` run: spine-html holds every rule spine
  * measures (selftest `CH09`). 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, edges: PageEdges): GateRun[] {
+function gateThroughRigc(out: RigOutput, texts: Array<[string, string]>, rigc: RigcRunner, scratch: string, mode: PackMode): 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');
-    return [gateRun(packedBuildLabel(edges), rigc, ['build', '--rig', join(scratch, 'rig.json'), '--motion', join(scratch, 'motion.json'), '--out', build, ...packedBuildArgs(edges)])];
+    return [gateRun(packedBuildLabel(mode), rigc, ['build', '--rig', join(scratch, 'rig.json'), '--motion', join(scratch, 'motion.json'), '--out', build, ...packedBuildArgs(mode)])];
   } finally {
     rmSync(scratch, { recursive: true, force: true });
   }
@@ -221,6 +221,8 @@ export interface RigStageInput {
   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;
+  /** The gate build's `--pack-shape`; {@link DEFAULT_PACK_SHAPE} when absent. */
+  packShape?: PackShape;
 }
 
 /** Author the rig, gate it through rigc in `scratch`, and write `out` only when the gate is green. */
@@ -258,7 +260,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, input.pageEdges ?? DEFAULT_PAGE_EDGES);
+  const gate = gateThroughRigc(rig, texts, rigc, scratch, { pageEdges: input.pageEdges ?? DEFAULT_PAGE_EDGES, packShape: input.packShape ?? DEFAULT_PACK_SHAPE });
   for (const g of gate) {
     log(`  rigc ${g.label}: exit ${g.status}`);
     for (const l of g.lines) log(`    ${l.trim()}`);
@@ -291,6 +293,8 @@ export interface CheckStageInput {
   out: string;
   /** The packed build's `--page-edges`; {@link DEFAULT_PAGE_EDGES} when absent. */
   pageEdges?: PageEdges;
+  /** The packed build's `--pack-shape`; {@link DEFAULT_PACK_SHAPE} when absent. */
+  packShape?: PackShape;
 }
 
 /** The pack line as it is printed: rigc's own, then the page's opaque share beside the spineboy yardstick. */
@@ -328,9 +332,9 @@ export function checkStage(input: CheckStageInput, rigc: RigcRunner, bin: string
   const versionLines = v.out.trim().split('\n');
   const entryLine = versionLines.find((l) => l.startsWith('entry:'));
   log(`  rigc ${versionLines[0]} at ${bin}${entryLine === undefined ? '' : `; ${entryLine}`}`);
-  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:`);
+  const mode: PackMode = { pageEdges: input.pageEdges ?? DEFAULT_PAGE_EDGES, packShape: input.packShape ?? DEFAULT_PACK_SHAPE };
+  const r = runCheck(input.rig, input.out, rigc, input.parts, mode);
+  log(`  gate spine-html (rigc ${packedBuildLabel(mode)}), verbatim:`);
   for (const l of r.gateHtml) log(l);
   for (const l of packLines(r)) log(`  ${l}`);
   const fig = r.figures;
@@ -441,6 +445,8 @@ export interface BuildInput {
   loop: boolean;
   /** `--page-edges` for both packed builds, the rig stage's gate and the check's artifact. */
   pageEdges: PageEdges;
+  /** `--pack-shape` for both packed builds, as `pageEdges`; {@link DEFAULT_PACK_SHAPE} when absent. */
+  packShape?: PackShape;
 }
 
 /**
@@ -514,7 +520,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}, page edges ${input.pageEdges}${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}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${input.loop ? ', with the idle loop' : ''}`);
 
   try {
     // build runs rig next, which needs the whole config, so the full loader is
@@ -532,14 +538,14 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   }
 
   try {
-    rigStage({ config: input.config, parts: out, out: join(out, 'rig'), pageEdges: input.pageEdges }, run.rig, run.scratch, prefixed('rig'));
+    rigStage({ config: input.config, parts: out, out: join(out, 'rig'), pageEdges: input.pageEdges, packShape: input.packShape }, 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'), pageEdges: input.pageEdges }, run.check, run.checkBin, prefixed('check'));
+    report = checkStage({ rig: join(out, 'rig'), parts: out, out: join(out, 'check'), pageEdges: input.pageEdges, packShape: input.packShape }, run.check, run.checkBin, prefixed('check'));
   } catch (err) {
     return refused('check', err);
   }

package/src/check.ts

@@ -25,7 +25,7 @@
  *
  * | output | what |
  * | --- | --- |
- * | `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 |
+ * | `build/` | `rigc build --profile spine-html --pack --page-edges free --pack-shape polygon` (or `pot`, `rect`, when the caller names them; {@link PAGE_EDGES}, {@link PACK_SHAPES}) — the packed atlas is the final artifact |
  * | `gate_spine-html.txt` | that build's gate lines, verbatim — the one gate: rigc's `build` runs it once over the compile and once over the packed pages on disk, and `spine-html` holds every rule `spine` measures (selftest `CH09`) |
  * | `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) |
  * | `contact.png` | rigc's own contact sheet of that render, copied out |
@@ -196,7 +196,7 @@ export const SPINEBOY_YARDSTICK = '1024x256, 40 region(s), 45.8% opaque (alpha >
  * `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 and 2.0.3 alike. The cost was
+ * from 512x2048 to 479x1166 (49.7 % -> 93.4 %), rigc 1.5.1, 2.0.3 and 2.1.3 (`rect`) alike. 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
@@ -209,14 +209,53 @@ export const PAGE_EDGES = ['pot', 'free'] as const;
 export type PageEdges = (typeof PAGE_EDGES)[number];
 export const DEFAULT_PAGE_EDGES: PageEdges = 'free';
 
+/**
+ * What two packed rectangles may share: spine-rigc's `build --pack
+ * --pack-shape`, handed to it verbatim (in spine-rigc's CLI since 2.1.0; this
+ * package's range starts at 2.1.3). `rect` keeps every region's cell apart;
+ * `polygon` packs a region that only meshes draw by its emitted hull, so a
+ * neighbour may sit inside its rectangle where the hull is not, with the
+ * padding kept between footprints — a region attachment stays its rectangle
+ * (rigc's help).
+ *
+ * `polygon` is the default here although rigc's own default is `rect`, for the
+ * reason {@link DEFAULT_PAGE_EDGES} is `free`: the packed page is this
+ * package's final artifact, rigc gates the footprints on the pages on disk
+ * (`A49_PACKED_FOOTPRINTS_DO_NOT_OVERLAP`), and the cost is the class already
+ * accepted for `free`. Measured with spine-rigc 2.1.3 (the full entry,
+ * spine-core 4.3.13 beside it), `spine-parts build` on the two public examples
+ * under `--page-edges free`: `polygon` takes demo's page from 967x1338 (91.2 %
+ * covered) to 922x1348 (95.0 %), 3.9 % less area, and sample's from 479x1166
+ * (93.4 %) to 477x1151 (95.0 %), 1.7 % less. Each of the 49 idle frames at 12
+ * fps differs from the `rect` build's by at most 1 level in any channel (demo
+ * 2,594 px, sample 740 px over all 49), and no figure in `check.json` but
+ * `pack_mode` moves. Under `--page-edges pot` both shapes give the same page
+ * size and the same frames. AUTHORING §5, *Pack shape*, holds the tables.
+ * `--pack-shape rect` writes the page and atlas rigc 2.0.3 wrote for 0.7.0
+ * (measured byte for byte on both examples; selftest `CK53` holds rect to
+ * rigc's own rect page).
+ */
+export const PACK_SHAPES = ['rect', 'polygon'] as const;
+export type PackShape = (typeof PACK_SHAPES)[number];
+export const DEFAULT_PACK_SHAPE: PackShape = 'polygon';
+
+/** How a packed build packs: its `--page-edges` and its `--pack-shape`, each handed to rigc verbatim. */
+export interface PackMode {
+  pageEdges: PageEdges;
+  packShape: PackShape;
+}
+
+/** Both defaults, {@link DEFAULT_PAGE_EDGES} and {@link DEFAULT_PACK_SHAPE}. */
+export const DEFAULT_PACK_MODE: PackMode = { pageEdges: DEFAULT_PAGE_EDGES, packShape: DEFAULT_PACK_SHAPE };
+
 /** 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];
+export function packedBuildArgs(mode: PackMode): string[] {
+  return ['--profile', 'spine-html', '--pack', '--page-edges', mode.pageEdges, '--pack-shape', mode.packShape];
 }
 
 /** 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(' ')}`;
+export function packedBuildLabel(mode: PackMode): string {
+  return `build ${packedBuildArgs(mode).join(' ')}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -553,19 +592,32 @@ 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). */
+  /** `free` when the line carries `, page edges free` after the padding, `pot` when it does not — spine-rigc prints the clause exactly when it packed under `--page-edges free` (its `src/cli/shared.ts`, the pack line). */
   pageEdges: PageEdges;
+  /**
+   * The line's last clause, `, shape rect` or `, shape polygon`: spine-rigc
+   * 2.1 names the `--pack-shape` it packed under on every pack line, its
+   * default included. A line with no shape clause is the 1.5.1–2.0.3 form,
+   * from a rigc that had no other shape, and reads as `rect`.
+   */
+  packShape: PackShape;
 }
 
 /** 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)?$/;
+const PACK = /^pack: (\S+) (\d+)x(\d+), (\d+) region\(s\), (\d+(?:\.\d+)?)% covered, padding (\d+)(, page edges free)?(?:, shape (rect|polygon))?$/;
+
+/** A pack line that names its shape: the spine-rigc 2.1 form. */
+const PACK_SHAPE_CLAUSE = /, shape (?:rect|polygon)$/;
 
 /**
  * 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 to 2.0.3 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.
+ * `..` gutter is taken off. Two forms are read, each by name: spine-rigc
+ * 2.1's, which ends `, shape rect` or `, shape polygon`, and the 1.5.1–2.0.3
+ * form, which has no shape clause and reads as `rect`; in both,
+ * `, page edges free` sits between the padding and the shape or is absent. Any
+ * other line (an unknown shape, an unknown suffix, a missing field, the clauses
+ * out of order) is refused, `CHECK_PACK_LINE_READS`, naming the line and the
+ * form required: a line half-read would lose the field that changed.
  */
 export function parsePackLines(lines: readonly string[]): PackLine[] {
   const out: PackLine[] = [];
@@ -578,11 +630,21 @@ export function parsePackLines(lines: readonly string[]): PackLine[] {
       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',
+        detail: 'does not read as "pack: <page> <W>x<H>, <N> region(s), <P>% covered, padding <D>", then ", page edges free" or nothing, then ", shape rect", ", shape polygon" 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' });
+    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',
+      packShape: m[8] === 'polygon' ? 'polygon' : 'rect',
+    });
   }
   refuseIfAny(problems);
   return out;
@@ -593,12 +655,20 @@ function powerOfTwo(n: number): boolean {
 }
 
 /**
- * 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.
+ * Where a pack line disagrees with the pack mode the build was given. The
+ * line's own page-edges clause must say the `--page-edges` passed, and a `pot`
+ * page must be a power of two on both edges, as rigc's help defines it,
+ * `CHECK_PACK_PAGE_EDGES`. By the same rule the line's shape must be the
+ * `--pack-shape` passed, `CHECK_PACK_SHAPE` — a line with no shape clause
+ * reads as `rect`, so under `polygon` it disagrees. That is the case that
+ * matters: rigc 2.0.3 takes `--pack-shape` without a word, packs by
+ * rectangles and prints the form with no shape clause (measured), so a rigc
+ * older than 2.1.0 first on `PATH` is refused here rather than shipping a
+ * rect page as a polygon one. One problem per disagreement; empty is
+ * agreement.
  */
-export function packEdgeProblems(pack: readonly PackLine[], edges: PageEdges): Problem[] {
+export function packEdgeProblems(pack: readonly PackLine[], mode: PackMode): Problem[] {
+  const edges = mode.pageEdges;
   const problems: Problem[] = [];
   for (const p of pack) {
     const object = `packed page ${p.page}`;
@@ -606,11 +676,18 @@ export function packEdgeProblems(pack: readonly PackLine[], edges: PageEdges): P
       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`,
+        detail: `rigc's pack line says page edges ${p.pageEdges} (${p.pageEdges === 'free' ? 'it carries ", page edges free"' : 'no ", page edges free" clause'}); 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` });
     }
+    if (p.packShape !== mode.packShape) {
+      problems.push({
+        code: 'CHECK_PACK_SHAPE',
+        object,
+        detail: `rigc's pack line says shape ${p.packShape} (${PACK_SHAPE_CLAUSE.test(p.line) ? `it ends ", shape ${p.packShape}"` : 'no ", shape" clause: the 1.5.1-2.0.3 form, read as rect'}); the build was run with --pack-shape ${mode.packShape}, so shape ${mode.packShape} is required`,
+      });
+    }
   }
   return problems;
 }
@@ -885,6 +962,8 @@ export interface CheckFigures {
   gate_spine_html_green: boolean;
   /** Which rigc entry gated the build ({@link readRigcEntry}): provenance, not a bar. */
   rigc_entry: RigcEntryRecord;
+  /** How the artifact's page was packed: the `--page-edges` and `--pack-shape` rigc was handed, which its pack line was read to agree with ({@link packEdgeProblems}). Provenance, not a bar. */
+  pack_mode: { page_edges: PageEdges; pack_shape: PackShape };
   loop_max_diff: number;
   seam_mean: number;
   seam_px_over_40: number;
@@ -931,11 +1010,12 @@ export function rigcFailed(what: string, call: RigcCall, lines: readonly string[
  * 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. `pageEdges` reaches rigc's
- * `--page-edges` verbatim, and a pack line that disagrees with it is refused
- * (`CHECK_PACK_PAGE_EDGES`).
+ * `figures.PASS` is true exactly when it is empty. `mode` reaches rigc's
+ * `--page-edges` and `--pack-shape` verbatim, a pack line that disagrees with
+ * either is refused (`CHECK_PACK_PAGE_EDGES`, `CHECK_PACK_SHAPE`), and
+ * `check.json` records it as `pack_mode`.
  */
-export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome: string = rigDir, pageEdges: PageEdges = DEFAULT_PAGE_EDGES): CheckReport {
+export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, partsHome: string = rigDir, mode: PackMode = DEFAULT_PACK_MODE): CheckReport {
   const inp = readCheckInputs(rigDir, partsHome);
   const rigcEntry = readRigcEntry(requireRigcVersion(rigc));
   const out = resolve(outDir);
@@ -952,12 +1032,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, ...packedBuildArgs(pageEdges)]);
+  const build = rigc(['build', '--rig', inp.rigPath, '--motion', inp.motionPath, '--out', buildDir, ...packedBuildArgs(mode)]);
   const gateHtml = buildGateLines(build.out);
   write('gate_spine-html.txt', `${gateHtml.join('\n')}\n`);
-  if (build.status !== 0) refuseIfAny(rigcFailed(packedBuildLabel(pageEdges), build, gateHtml));
+  if (build.status !== 0) refuseIfAny(rigcFailed(packedBuildLabel(mode), build, gateHtml));
   const pack = parsePackLines(gateHtml);
-  refuseIfAny(packEdgeProblems(pack, pageEdges));
+  refuseIfAny(packEdgeProblems(pack, mode));
   const packOpaque = pack.filter((p) => existsSync(join(buildDir, p.page))).map((p) => ({ page: p.page, share: opaqueShare(readPng(join(buildDir, p.page))) }));
 
   // 2. no second gate: `rigc validate --profile spine` of this build measured no rule the build's own two passes
@@ -1080,6 +1160,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
   const figures: CheckFigures = {
     gate_spine_html_green: htmlGreen,
     rigc_entry: rigcEntry,
+    pack_mode: { page_edges: mode.pageEdges, pack_shape: mode.packShape },
     loop_max_diff: loop.max,
     seam_mean: round3(seam.mean),
     seam_px_over_40: seam.over40,
@@ -1094,7 +1175,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     PASS: false,
   };
   const barProblems: Problem[] = [];
-  if (!htmlGreen) barProblems.push(...rigcFailed(packedBuildLabel(pageEdges), build, gateHtml));
+  if (!htmlGreen) barProblems.push(...rigcFailed(packedBuildLabel(mode), build, gateHtml));
   if (figures.loop_max_diff !== LOOP_MAX_BAR) {
     barProblems.push({
       code: 'CHECK_LOOP_CLOSES',