spine-rigc 2.1.0 → 2.1.2

package/README.md

@@ -698,7 +698,8 @@ what it found — the executable, the bundle, the `CFBundleName` that bundle
 declares, or the banner the binary prints about itself — rather than starting it
 and failing downstream. Both refusals point at `--exported <file>`, which
 measures an export the editor already made and is the half of this tool that
-needs no editor at all.
+needs no editor at all. A build whose `skeleton.json` is missing, is not JSON, or
+holds JSON that is not one object is refused by name before the editor starts.
 
 ⛔ **Run the round trip by hand, on a machine that has the editor.** CI has no
 editor, so no automated check runs it.

package/docs/AUTHORING.md

@@ -145,6 +145,10 @@ thing: with `@esotericsoftware/spine-core` installed beside the package, `rigc`
 `bun cli.ts` and runs every command; without it, `rigc` runs `cli_core.ts` — the
 entry that links none of spine-core, `bun cli_core.ts` in a clone — which refuses by
 name the commands that need the runtime (its `--help` lists the ones it runs).
+`validate` is one of them, and pointed at a rigc build — a directory with
+`skeleton.model.json` beside the pair — its refusal says that build already ran the
+gate before it wrote, and which rules that gate is on this entry, before the install
+route; on a Spine export it says what it always said (`RC36`).
 `rigc --version` names the entry that ran.
 
 That entry's `build` takes the same flags and writes the same files, byte for byte:
@@ -517,17 +521,39 @@ what changes is that two rectangles may overlap where neither footprint is.
   touch.
 - **The placement** is the same MaxRects search, ordering and tie-breaks, with
   the free list split by what each region owns instead of by its cell, and a
-  candidate is the free rectangle that holds what the cell owns. Every pass is
-  also run as the `rect` pass on the same page and the better kept — more parts
-  placed, then the higher bottom edge, then `rect` on a tie — so a `polygon`
-  page is never larger than the `rect` page. `--page-edges` and the spill rule
-  are unchanged, except that the `free` search's area bound sums the texels
-  the cells own rather than the cells, since overlapping cells can cover more
-  than the page (a spilled `polygon` page was refused as fitting no page until
-  it did — `PK86`). What it costs in time is measured on a set shaped like a
-  production rig (30 regions of 200 to 900 px, hulls near their rectangles,
-  one `free` page about 2023x2046): 1.1–1.4 s against `rect`'s 0.2 s for the
-  pack alone, the same page.
+  candidate is a free rectangle that holds the box of what the cell owns. Every
+  pass is also run as the `rect` pass on the same page and the better kept —
+  more parts placed, then the higher bottom edge, then `rect` on a tie.
+  `--page-edges` and the spill rule are unchanged, except that the `free`
+  search's area bound sums the texels the cells own rather than the cells,
+  since overlapping cells can cover more than the page (a spilled `polygon`
+  page was refused as fitting no page until it did — `PK86`).
+- **Where a cell may go in a free rectangle** (issue #1104). A candidate puts
+  the box of what the cell owns at the free rectangle's top-left corner, the
+  cell reaching up and left of it — so a cell whose drawn part is inset from
+  its corner (a large region whose mesh draws a small part of it) could never
+  go on an empty page, and every pass lost to the `rect` pass. A second
+  candidate puts the cell's own corner there instead, wherever the first would
+  leave the page. Both keep the cell on the page; the atlas format does not
+  change.
+- **The pack written is the least total page area of three whole packs** —
+  the `rect` pack, the footprint pack with the first anchor alone, and with
+  both — summed over every page, a spill's included, the earlier on a tie. So a
+  `polygon` pack is never larger in page area than the `rect` pack on any set,
+  by construction (before #1104 a spill could make it so: a generated set under
+  `pot` wrote 8,388,608 texels against `rect`'s 6,291,456). No single placement
+  rule gives that: the second anchor alone packs one test set 7.2 % larger than
+  the first. On a production rig's region set (31 meshes, a two-page `free`
+  spill under `rect`) it takes 4,367,445 texels to 2,585,264 (−40.8 %); on a
+  generated set of that shape (`fixtures/polypack_shapes.ts`, seed 1107)
+  4,433,292 over two pages to 2,037,204 on one; under `pot` both go to one
+  2048x2048 page. **What it costs**, for the pack alone (`--page-edges free`,
+  padding 2, page size 2048): the three packs' searches, none shared — on seed
+  1107 1.09 s against `rect`'s 0.06 s, on seed 1105 1.29 s against 0.07 s,
+  under `pot` 0.17–0.21 s; counted, 13.6 times `rect`'s free-list splits on seed
+  1107, which `PK93` holds within 25 times. The cost is the placing the
+  second anchor makes possible: before #1102 the same search threw its passes
+  away and took 260–304 s on the production set.
 - **The pixels.** Every cell is drawn whole in packing order, then every
   region's owned texels are drawn again with its own values, so every texel a
   region can sample is its own (`PK79`). A texel nobody owns carries the last

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/atlas.ts

@@ -713,6 +713,44 @@ export const PACK_SHAPES = ['rect', 'polygon'] as const;
 export type PackShape = (typeof PACK_SHAPES)[number];
 export const DEFAULT_PACK_SHAPE: PackShape = 'rect';
 
+/**
+ * Where a `polygon` candidate may put a cell against the free rectangle it is
+ * placed in (issue #1104) — `packOnePageByFootprint`, *Candidates*.
+ *
+ * `box` puts the cell's owned box on the free rectangle's corner — the only
+ * rule before #1104. The other three may also put the cell's own corner there
+ * (`packOnePageByFootprint`, *Candidates*):
+ *
+ *   * `box-or-cell` — on every free rectangle;
+ *   * `box-else-cell` — only on a free rectangle where the owned box's anchor
+ *     would put the cell off the page;
+ *   * `best-of` — the footprint pass run with `box` and with `box-or-cell` on
+ *     the same page and the better kept (more cells, then the higher bottom
+ *     edge, then `box`), as `placePass` keeps the better of `rect` and a
+ *     footprint pass.
+ *
+ * No single rule is never-larger than `box` — `box-or-cell` packs `PK78`'s
+ * wedge set 7.2 % larger — so `polygon` does not pick one: it packs the whole
+ * set as `rect`, under `box` and under `box-else-cell` and keeps the least Σ
+ * page area (`POLYGON_CANDIDATE_RULES`, `packAtlas`). `box-else-cell` is the
+ * third candidate on measurement: over 96 packs (seeds 1100–1124, the tree's
+ * 21 sets, the wedge and spill sets, `pot` and `free`) the choice with it sums
+ * to 212,607,001 texels, with `best-of` 214,407,755 and with `box-or-cell` the
+ * same. `best-of` is never worse than `box` on one page, but against
+ * `box-else-cell` it gives the smaller pack on 12 of the 27 sets where the two
+ * differ and the larger on 15 — neither dominates, and the sum decides.
+ *
+ * The CLI never sets one rule; `PackOptions.footprintAnchors` is the instrument's and the plant's.
+ */
+export const FOOTPRINT_ANCHORS = ['box', 'box-or-cell', 'box-else-cell', 'best-of'] as const;
+export type FootprintAnchors = (typeof FOOTPRINT_ANCHORS)[number];
+/** The rule a footprint search uses when it is given none — `freePageSearch`'s and `footprintPass`'s callers outside `packAtlas`. */
+export const DEFAULT_FOOTPRINT_ANCHORS: FootprintAnchors = 'box';
+/** The footprint rules `polygon` packs under besides `rect`, in the order a tie goes to (`packAtlas`). */
+export const POLYGON_CANDIDATE_RULES: readonly FootprintAnchors[] = ['box', 'box-else-cell'];
+/** Which whole pack a `polygon` pack kept: `rect`'s, or one footprint rule's. */
+export type PackCandidate = 'rect' | FootprintAnchors;
+
 /**
  * The part of a region its attachments draw, in the region's own texels — x
  * right and y down from the drawing's top-left corner, so `(u · width, v ·
@@ -750,6 +788,21 @@ export interface PackOptions {
   pageEdges?: PageEdges;
   /** What two rectangles may share (default `rect`). See `PACK_SHAPES`. */
   shape?: PackShape;
+  /**
+   * One footprint rule alone instead of `polygon`'s choice between whole packs
+   * (`FOOTPRINT_ANCHORS`) — for `tools/pack_anchor.ts` and the selftest's plant
+   * (`PK97`); the CLI never sets it. Absent, `polygon` keeps the least Σ page
+   * area of `rect` and `POLYGON_CANDIDATE_RULES`.
+   */
+  footprintAnchors?: FootprintAnchors;
+  /** Where to count what every search the pack runs placed (`PassTally`) — the controls' and the instrument's cost reading. */
+  tally?: PassTally;
+  /**
+   * `false` runs every footprint pass of every search to its end — issue
+   * #1102's early stop off, for the selftest's plant (`PK95`) only. The pages are
+   * the same either way (`PK94`); only the cost differs.
+   */
+  stopAtMiss?: boolean;
 }
 
 /** Where one region landed. `x`/`y` are the REGION's own corner, not its cell's. */
@@ -782,6 +835,8 @@ export interface PackResult {
   padding: number;
   /** The shape the pack was made under — what the `pack:` line's last field states. */
   shape: PackShape;
+  /** The whole pack that was kept: `rect` under `shape: 'rect'`, and under `polygon` the candidate of least Σ page area (`packAtlas`). */
+  candidate: PackCandidate;
 }
 
 /** A free rectangle in the MaxRects free list. */
@@ -826,15 +881,18 @@ function smallestPageFor(
   maxEdge: number,
   pageEdges: PageEdges,
   shapes?: readonly CellShape[],
+  anchors: FootprintAnchors = DEFAULT_FOOTPRINT_ANCHORS,
+  tally?: PassTally,
+  stopAtMiss = true,
 ): { width: number; height: number; rects: Rect[] } | null {
-  if (pageEdges === 'free') return smallestFreePageFor(cells, maxEdge, shapes);
+  if (pageEdges === 'free') return smallestFreePageFor(cells, maxEdge, shapes, anchors, tally, stopAtMiss);
   const edges: number[] = [];
   for (let e = 1; e <= maxEdge; e *= 2) edges.push(e);
   const candidates: Array<{ w: number; h: number }> = [];
   for (const w of edges) for (const h of edges) candidates.push({ w, h });
   candidates.sort((a, b) => a.w * a.h - b.w * b.h || a.w - b.w);
   for (const candidate of candidates) {
-    const attempt = placePass(cells, shapes, candidate.w, candidate.h);
+    const attempt = placePass(cells, shapes, candidate.w, candidate.h, Infinity, { wholeOrNothing: stopAtMiss, anchors, tally });
     if (attempt.some((r) => r === null)) continue;
     return { width: candidate.w, height: candidate.h, rects: attempt as Rect[] };
   }
@@ -886,8 +944,13 @@ function smallestFreePageFor(
   cells: Array<{ w: number; h: number }>,
   maxEdge: number,
   shapes?: readonly CellShape[],
+  anchors: FootprintAnchors = DEFAULT_FOOTPRINT_ANCHORS,
+  tally?: PassTally,
+  stopAtMiss = true,
 ): { width: number; height: number; rects: Rect[] } | null {
-  return freePageSearch(cells, maxEdge, shapes).page;
+  const search = freePageSearch(cells, maxEdge, shapes, { anchors, stopAtMiss });
+  if (tally !== undefined) for (const key of Object.keys(tally) as Array<keyof PassTally>) tally[key] += search.tally[key];
+  return search.page;
 }
 
 /** What one `free` page search did: the page it chose, and what each width cost. */
@@ -901,6 +964,23 @@ export interface FreePageSearch {
   abandoned: number;
   /** Widths never placed: too narrow for the cells' area, or wide enough that the tallest cell alone loses. */
   skipped: number;
+  /** What the passes placed, by kind (`PassTally`). */
+  tally: PassTally;
+}
+
+/**
+ * How `freePageSearch` runs its passes — for the selftest's plants only
+ * (`PK94`, `PK95`). Each turns one of issue #1102's savings off: `stopAtMiss:
+ * false` runs every footprint pass to its end, `edgeIndex: false` prunes the
+ * free list by scanning all of it. The page is the same either way; only what
+ * it costs differs, and the plants hold that.
+ */
+export interface FreePageSearchOptions {
+  stopAtMiss?: boolean;
+  /** `false` scans the whole free list for a piece's containers (`splitFree`), as the prune did before issue #1102. */
+  edgeIndex?: boolean;
+  /** Where a candidate may anchor a cell (`FOOTPRINT_ANCHORS`) — `tools/pack_anchor.ts`'s candidate rules; default `box`. */
+  anchors?: FootprintAnchors;
 }
 
 /**
@@ -910,7 +990,13 @@ export interface FreePageSearch {
  * packer uses; the counts are for the control. `shapes`, one per cell, is
  * `shape: 'polygon'`'s placement (`placePass`); absent, the rectangle pass.
  */
-export function freePageSearch(cells: Array<{ w: number; h: number }>, maxEdge: number, shapes?: readonly CellShape[]): FreePageSearch {
+export function freePageSearch(
+  cells: Array<{ w: number; h: number }>,
+  maxEdge: number,
+  shapes?: readonly CellShape[],
+  options: FreePageSearchOptions = {},
+): FreePageSearch {
+  const wholeOrNothing = options.stopAtMiss ?? true;
   let widest = 0;
   let tallest = 0;
   let cellArea = 0;
@@ -927,7 +1013,7 @@ export function freePageSearch(cells: Array<{ w: number; h: number }>, maxEdge:
     cellArea = 0;
     for (const shape of shapes) cellArea += shape.owned;
   }
-  const out: FreePageSearch = { page: null, widths: 0, completed: 0, abandoned: 0, skipped: 0 };
+  const out: FreePageSearch = { page: null, widths: 0, completed: 0, abandoned: 0, skipped: 0, tally: emptyTally() };
   let best: { width: number; height: number; rects: Rect[] } | null = null;
   for (let width = Math.ceil(widest / FREE_EDGE_STEP) * FREE_EDGE_STEP; width <= maxEdge; width += FREE_EDGE_STEP) {
     out.widths++;
@@ -937,7 +1023,7 @@ export function freePageSearch(cells: Array<{ w: number; h: number }>, maxEdge:
       continue;
     }
     const maxBottom = best === null ? Infinity : Math.floor(bestArea / width);
-    const attempt = placePass(cells, shapes, width, maxEdge, maxBottom);
+    const attempt = placePass(cells, shapes, width, maxEdge, maxBottom, { wholeOrNothing, tally: out.tally, edgeIndex: options.edgeIndex ?? true, anchors: options.anchors });
     let height = 0;
     for (const r of attempt) if (r !== null) height = Math.max(height, r.y + r.h);
     if (height > maxBottom) {
@@ -1094,9 +1180,46 @@ function placePass(
   pageW: number,
   pageH: number,
   maxBottom = Infinity,
+  pass: PassOptions = {},
 ): Array<Rect | null> {
-  const byRect = packOnePage(cells, pageW, pageH, maxBottom);
-  if (shapes === undefined || shapes.every((s) => s.whole)) return byRect;
+  const wholeOrNothing = pass.wholeOrNothing ?? false;
+  const tally = pass.tally;
+  if (shapes === undefined || shapes.every((s) => s.whole)) {
+    const byRect = packOnePage(cells, pageW, pageH, maxBottom);
+    if (tally !== undefined) tally.rectPlaced += placedCount(byRect);
+    return byRect;
+  }
+  // ⭐ `wholeOrNothing` is the page searches' question (issue #1102): they keep
+  // a pass only when it placed every cell, so a pass that has missed one is
+  // already discarded, whatever it does next. Two savings follow, and neither
+  // can change a page the search keeps:
+  //
+  //   * the rectangle pass is not run when the cells' own area exceeds the
+  //     page — disjoint rectangles cannot all fit, so it could not place every
+  //     cell, and the pass it would have lost or won against is discarded either
+  //     way (a footprint pass that placed every cell beats a rectangle pass that
+  //     did not, on the first key);
+  //   * the footprint pass stops at its first miss (`packOnePageByFootprint`'s
+  //     `stopAtMiss`), returning the cells after it as not placed.
+  //
+  // What is returned can then differ from the full answer only in which of two
+  // failed passes it is, or in how many cells a failed pass placed — and the
+  // searches read neither. The spill's assignment pass, which keeps the cells
+  // a pass did place, never asks this (`packAtlas`).
+  //
+  // Measured on a replica of a production rig (31 meshes, a two-page `free`
+  // spill at 2048, padding 2), where the pack took 260–304 s against `rect`'s
+  // 0.14–0.24 s: the single-page search ran a full footprint pass at every one of its
+  // 854 widths (54 % of the time), because nothing fits and so no best page
+  // ever bounds a width, and the first page's own search ran one at every width
+  // it did not abandon (46 %). The largest cell's owned box does not start at
+  // its cell's corner, so on an empty page that cell is every footprint pass's
+  // first miss — all 1,709 of them — and every one of those passes was thrown
+  // away (issue #1104 measures the anchor that causes it). With the early stop the pack takes 0.15–0.7 s by the load, the
+  // same pages.
+  const rectCanFit = !wholeOrNothing || cellAreaOf(cells) <= pageW * pageH;
+  const byRect = rectCanFit ? packOnePage(cells, pageW, pageH, maxBottom) : null;
+  if (tally !== undefined && byRect !== null) tally.rectPlaced += placedCount(byRect);
   // ⭐ `polygon` never costs a page anything `rect` would have saved. Both passes
   // are run on the same page and the better one is kept: more cells placed,
   // then the higher bottom edge, then — on a tie — the rectangle pass. Two
@@ -1107,15 +1230,86 @@ function placePass(
   // than `rect` on two of the five gallery rigs that carry a mesh, because a
   // greedy pass that places one cell differently places every later one
   // differently too.
-  const byFootprint = packOnePageByFootprint(shapes, pageW, pageH, maxBottom);
-  const placedOf = (pass: Array<Rect | null>): number => pass.reduce((n, r) => (r === null ? n : n + 1), 0);
-  const bottomOf = (pass: Array<Rect | null>): number => pass.reduce((n, r) => (r === null ? n : Math.max(n, r.y + r.h)), 0);
-  const placedRect = placedOf(byRect);
-  const placedFoot = placedOf(byFootprint);
+  const anchors = pass.anchors ?? DEFAULT_FOOTPRINT_ANCHORS;
+  let byFootprint = packOnePageByFootprint(shapes, pageW, pageH, maxBottom, wholeOrNothing, pass.edgeIndex ?? true, tally, anchors === 'best-of' ? 'box' : anchors);
+  if (anchors === 'best-of') {
+    // Issue #1104's fourth candidate: both searches on the same page, the
+    // better kept and the first anchor's on a tie — so a pass is never worse
+    // than the first anchor's on that page.
+    if (tally !== undefined) tally.footprintPlaced += placedCount(byFootprint);
+    const byTwo = packOnePageByFootprint(shapes, pageW, pageH, maxBottom, wholeOrNothing, pass.edgeIndex ?? true, tally, 'box-or-cell');
+    const bottom = (placed: Array<Rect | null>): number => placed.reduce((n, r) => (r === null ? n : Math.max(n, r.y + r.h)), 0);
+    const placedBox = placedCount(byFootprint);
+    const placedTwo = placedCount(byTwo);
+    if (placedTwo > placedBox || (placedTwo === placedBox && bottom(byTwo) < bottom(byFootprint))) byFootprint = byTwo;
+    if (tally !== undefined) tally.footprintPlaced += placedTwo;
+  } else if (tally !== undefined) tally.footprintPlaced += placedCount(byFootprint);
+  if (byRect === null) return byFootprint;
+  const bottomOf = (placed: Array<Rect | null>): number => placed.reduce((n, r) => (r === null ? n : Math.max(n, r.y + r.h)), 0);
+  const placedRect = placedCount(byRect);
+  const placedFoot = placedCount(byFootprint);
   if (placedFoot !== placedRect) return placedFoot > placedRect ? byFootprint : byRect;
   return bottomOf(byFootprint) < bottomOf(byRect) ? byFootprint : byRect;
 }
 
+/** How `placePass` runs — what the page searches ask of it (issue #1102). */
+interface PassOptions {
+  /** Only a pass that places every cell is kept by the caller. See `placePass`. */
+  wholeOrNothing?: boolean;
+  /** Where to count what the passes placed. */
+  tally?: PassTally;
+  /** `splitFree`'s edge index (default on); off only for the selftest's plant. */
+  edgeIndex?: boolean;
+  /** Where a candidate may anchor a cell (`FOOTPRINT_ANCHORS`). */
+  anchors?: FootprintAnchors;
+}
+
+/** How many cells a pass placed. */
+function placedCount(pass: ReadonlyArray<Rect | null>): number {
+  let n = 0;
+  for (const r of pass) if (r !== null) n++;
+  return n;
+}
+
+/** The cells' own area — what disjoint rectangles need of a page at least. */
+function cellAreaOf(cells: ReadonlyArray<{ w: number; h: number }>): number {
+  let area = 0;
+  for (const cell of cells) area += cell.w * cell.h;
+  return area;
+}
+
+/**
+ * What a page search's passes placed, by kind — the operation count a search's
+ * cost is held by (`PK93`), since a footprint placement splits the free list
+ * once per band of what the cell owns and a rectangle placement once.
+ */
+export interface PassTally {
+  /** Cells placed by rectangle passes (`packOnePage`). */
+  rectPlaced: number;
+  /** Cells placed by footprint passes (`packOnePageByFootprint`). */
+  footprintPlaced: number;
+  /** Free-list splits the footprint passes made — one per band of every cell they placed (`splitFree`). */
+  bandSplits: number;
+  /** Containment tests the footprint passes' prune made (`splitFree`). */
+  containmentTests: number;
+  /**
+   * Free rectangles that held a cell's owned box and were refused as its
+   * first-anchor candidate only because the cell, anchored there, would leave
+   * the page — at negative x or y, or past the right or bottom edge (issue
+   * #1104, `tools/pack_anchor.ts`).
+   */
+  boxAnchorRefused: number;
+  /** Cells a footprint pass missed although some free rectangle held their owned box. */
+  missedByAnchor: number;
+  /** Cells a footprint pass placed at the second anchor — the cell's own corner on the free rectangle's — under a candidate rule that has one (`FOOTPRINT_ANCHORS`). */
+  secondAnchorPlaced: number;
+}
+
+/** A tally with nothing counted. */
+export function emptyTally(): PassTally {
+  return { rectPlaced: 0, footprintPlaced: 0, bandSplits: 0, containmentTests: 0, boxAnchorRefused: 0, missedByAnchor: 0, secondAnchorPlaced: 0 };
+}
+
 // ---------------------------------------------------------------------------
 // footprints — `shape: 'polygon'` (issue #1099)
 // ---------------------------------------------------------------------------
@@ -1377,44 +1571,100 @@ function shapesMeet(a: CellShape, ax: number, ay: number, b: CellShape, bx: numb
  * px, hulls near their rectangles, a `free` page about 2023x2046) the pack
  * took 18.5 s with the slivers kept and spent 95 % of it in this prune.
  */
-function splitFree(free: Rect[], put: Rect, minW = 1, minH = 1): void {
+function splitFree(free: Rect[], put: Rect, minW = 1, minH = 1, edgeIndex = true, tally?: PassTally): void {
   const next: Rect[] = [];
-  const untouched: boolean[] = [];
+  /** Per entry of `next`: `UNTOUCHED`, or which side of `put` the piece was cut from. */
+  const side: number[] = [];
   for (const fr of free) {
     const overlaps = put.x < fr.x + fr.w && put.x + put.w > fr.x && put.y < fr.y + fr.h && put.y + put.h > fr.y;
     if (!overlaps) {
       next.push(fr);
-      untouched.push(true);
+      side.push(UNTOUCHED);
       continue;
     }
-    if (put.x > fr.x) next.push({ x: fr.x, y: fr.y, w: put.x - fr.x, h: fr.h });
+    if (put.x > fr.x) {
+      next.push({ x: fr.x, y: fr.y, w: put.x - fr.x, h: fr.h });
+      side.push(LEFT_OF_PUT);
+    }
     if (put.x + put.w < fr.x + fr.w) {
       next.push({ x: put.x + put.w, y: fr.y, w: fr.x + fr.w - (put.x + put.w), h: fr.h });
+      side.push(RIGHT_OF_PUT);
+    }
+    if (put.y > fr.y) {
+      next.push({ x: fr.x, y: fr.y, w: fr.w, h: put.y - fr.y });
+      side.push(ABOVE_PUT);
     }
-    if (put.y > fr.y) next.push({ x: fr.x, y: fr.y, w: fr.w, h: put.y - fr.y });
     if (put.y + put.h < fr.y + fr.h) {
       next.push({ x: fr.x, y: put.y + put.h, w: fr.w, h: fr.y + fr.h - (put.y + put.h) });
+      side.push(BELOW_PUT);
     }
-    while (untouched.length < next.length) untouched.push(false);
   }
   const contains = (a: Rect, b: Rect): boolean => b.x >= a.x && b.y >= a.y && b.x + b.w <= a.x + a.w && b.y + b.h <= a.y + a.h;
   const usable = (r: Rect): boolean => r.w >= minW && r.h >= minH;
+  // ⭐ The third saving (issue #1102): a piece's containers are looked for only
+  // among the entries that share the edge it was cut along. A piece cut from
+  // the left of `put` ends at `put.x` and keeps its parent's rows, which meet
+  // `put`'s rows (the parent overlapped `put`). A rectangle containing it covers
+  // those rows from the piece's left edge to at least `put.x`; if it reached
+  // past `put.x` it would overlap `put` — and no entry of `next` does (an
+  // untouched rectangle by definition, a piece by construction). So every
+  // container of a left piece ENDS at `put.x`; likewise a right piece's starts
+  // at `put.x + put.w`, an upper piece's ends at `put.y` and a lower piece's
+  // starts at `put.y + put.h`. The test is the full prune's test, asked of the
+  // only entries that can answer it yes, so `contained` is the same boolean and
+  // the list the same list in the same order. Measured where the footprint
+  // pass does work (`fixtures/polypack_shapes.ts`, seed 1105, the searches a
+  // `polygon` pack of it runs): 415,916,651 containment tests by the full scan,
+  // 15,407,179 by the index, 3.2 s → 2.3 s; with the early stop off as well,
+  // 11,928,721,590 → 537,215,014 and 101 s → 14.5 s. `edgeIndex: false` is
+  // that scan, kept so the selftest can hold that the index finds what the
+  // scan finds (`PK94`) and for nothing else.
+  const scan: number[][] = [[], [], [], []];
+  const all: number[] = [];
+  for (let j = 0; j < next.length; j++) {
+    const r = next[j];
+    if (!usable(r)) continue;
+    if (!edgeIndex) {
+      all.push(j);
+      continue;
+    }
+    if (r.x + r.w === put.x) scan[LEFT_OF_PUT].push(j);
+    if (r.x === put.x + put.w) scan[RIGHT_OF_PUT].push(j);
+    if (r.y + r.h === put.y) scan[ABOVE_PUT].push(j);
+    if (r.y === put.y + put.h) scan[BELOW_PUT].push(j);
+  }
   free.length = 0;
+  let tests = 0;
   for (let i = 0; i < next.length; i++) {
     if (!usable(next[i])) continue;
-    if (untouched[i]) {
+    if (side[i] === UNTOUCHED) {
       free.push(next[i]);
       continue;
     }
     let contained = false;
-    for (let j = 0; j < next.length && !contained; j++) {
-      if (i === j || !usable(next[j])) continue;
-      if (contains(next[j], next[i]) && (j < i || !contains(next[i], next[j]))) contained = true;
+    for (const j of edgeIndex ? scan[side[i]] : all) {
+      if (i === j) continue;
+      tests++;
+      if (contains(next[j], next[i]) && (j < i || !contains(next[i], next[j]))) {
+        contained = true;
+        break;
+      }
     }
     if (!contained) free.push(next[i]);
   }
+  if (tally !== undefined) {
+    tally.bandSplits++;
+    tally.containmentTests += tests;
+  }
 }
 
+/** Which side of the placed rectangle a free-list piece was cut from (`splitFree`) — an index into its edge lists. */
+const LEFT_OF_PUT = 0;
+const RIGHT_OF_PUT = 1;
+const ABOVE_PUT = 2;
+const BELOW_PUT = 3;
+const UNTOUCHED = -1;
+
 /**
  * `packOnePage` with the free-space test replaced by the footprint test
  * (issue #1099) — the placement `shape: 'polygon'` makes.
@@ -1434,9 +1684,12 @@ function splitFree(free: Rect[], put: Rect, minW = 1, minH = 1): void {
  *   * a candidate is a free rectangle that holds the cell's protected set's
  *     bounding box, anchored at its top-left corner — the cell placed so that
  *     box's corner lands there, which may put the cell's own unclaimed
- *     texels over a neighbour's — and whose cell stays on the page;
- *   * the score is Best Short Side Fit over that box, with the same total
- *     tie-break (smallest long-side leftover, then topmost, then leftmost);
+ *     texels over a neighbour's — and whose cell stays on the page
+ *     (*Candidates*, below, for the rules measured beside it);
+ *   * the score is Best Short Side Fit over the part of the free rectangle the
+ *     box uses from its corner (the box itself, under the default anchor),
+ *     with the same total tie-break (smallest long-side leftover, then
+ *     topmost, then leftmost, then the first anchor);
  *   * the free list is split and pruned by the same code (`splitFree`), once
  *     per rectangle of the protected set.
  *
@@ -1445,6 +1698,27 @@ function splitFree(free: Rect[], put: Rect, minW = 1, minH = 1): void {
  * a pack with no mesh region makes `packOnePage`'s decisions one for one
  * (`PK82`).
  *
+ * ## Candidates — the second anchor (issue #1104)
+ *
+ * The first anchor puts the owned box's corner on the free rectangle's corner,
+ * the cell then reaching up and left of it by the box's offset. So a cell whose
+ * box is inset by `(dx, dy)` can only go where a free rectangle starts at least
+ * `dx` from the page's left and `dy` from its top — on an empty page, nowhere.
+ * A large region whose mesh draws a small part of it is then every footprint
+ * pass's first miss: on `fixtures/polypack_shapes.ts`'s seed 1107, and on the
+ * production rig it stands for, every footprint pass lost to the rectangle pass
+ * and the polygon pack was the `rect` pack to the texel.
+ *
+ * The second anchor puts the cell's own corner there instead, the box inset by
+ * its offset, and is a candidate when the free rectangle holds the box where it
+ * then lies. The two coincide when the box starts at the cell's corner, so it
+ * is only tried for an inset box — never for a whole cell, which is why a pack
+ * with no mesh region is unchanged by it. Both keep the box inside a free
+ * rectangle and the cell on the page, so no texel test, gutter or atlas field
+ * changes: `bounds` stays inside `size`, as the runtime's UVs assume. Which
+ * free rectangles get it is the rule (`FOOTPRINT_ANCHORS`); which rule's pack
+ * is written is `packAtlas`'s choice by Σ page area.
+ *
  * 🔒 **The footprint test is then stated outright rather than trusted to the
  * bookkeeping.** A candidate inside a free rectangle cannot meet a placed set,
  * because no free rectangle overlaps one; every placement is nevertheless
@@ -1455,7 +1729,16 @@ function splitFree(free: Rect[], put: Rect, minW = 1, minH = 1): void {
  * over the cells in the caller's order, each over a finite free list, every
  * choice made by a total order, and no input but the cells and the page.
  */
-function packOnePageByFootprint(shapes: readonly CellShape[], pageW: number, pageH: number, maxBottom = Infinity): Array<Rect | null> {
+function packOnePageByFootprint(
+  shapes: readonly CellShape[],
+  pageW: number,
+  pageH: number,
+  maxBottom = Infinity,
+  stopAtMiss = false,
+  edgeIndex = true,
+  tally?: PassTally,
+  anchors: FootprintAnchors = DEFAULT_FOOTPRINT_ANCHORS,
+): Array<Rect | null> {
   const free: Rect[] = [{ x: 0, y: 0, w: pageW, h: pageH }];
   const placed: Array<Rect | null> = [];
   const owned: Array<{ shape: CellShape; x: number; y: number }> = [];
@@ -1470,37 +1753,67 @@ function packOnePageByFootprint(shapes: readonly CellShape[], pageW: number, pag
 
   for (const shape of shapes) {
     const box = shape.bbox;
-    let best: Rect | null = null;
+    let best: { x: number; y: number; frX: number; frY: number; anchor: number } | null = null;
     let bestShort = Infinity;
     let bestLong = Infinity;
+    let held = false;
+    // The second anchor differs from the first only when the box is inset.
+    const anchorCount = anchors !== 'box' && (box.x !== 0 || box.y !== 0) ? 2 : 1;
     for (const fr of free) {
       if (fr.w < box.w || fr.h < box.h) continue;
-      const x = fr.x - box.x;
-      const y = fr.y - box.y;
-      if (x < 0 || y < 0 || x + shape.width > pageW || y + shape.height > pageH) continue;
-      const leftoverW = fr.w - box.w;
-      const leftoverH = fr.h - box.h;
-      const short = Math.min(leftoverW, leftoverH);
-      const long = Math.max(leftoverW, leftoverH);
-      if (best !== null) {
-        if (short > bestShort) continue;
-        if (short === bestShort) {
-          if (long > bestLong) continue;
-          if (long === bestLong) {
-            if (fr.y > best.y) continue;
-            if (fr.y === best.y && fr.x >= best.x) continue;
+      held = true;
+      let firstOffPage = false;
+      for (let anchor = 0; anchor < anchorCount; anchor++) {
+        // Anchor 0: the owned box's corner on the free corner. Anchor 1: the
+        // cell's own corner there, the box then inset by its own offset.
+        const x = anchor === 0 ? fr.x - box.x : fr.x;
+        const y = anchor === 0 ? fr.y - box.y : fr.y;
+        const usedW = anchor === 0 ? box.w : box.x + box.w;
+        const usedH = anchor === 0 ? box.h : box.y + box.h;
+        if (usedW > fr.w || usedH > fr.h) continue;
+        const offPage = x < 0 || y < 0 || x + shape.width > pageW || y + shape.height > pageH;
+        if (anchor === 0) firstOffPage = offPage;
+        // `box-else-cell`: the second anchor only where the first left the page.
+        if (anchor === 1 && anchors === 'box-else-cell' && !firstOffPage) continue;
+        if (offPage) {
+          if (anchor === 0 && tally !== undefined) tally.boxAnchorRefused++;
+          continue;
+        }
+        const leftoverW = fr.w - usedW;
+        const leftoverH = fr.h - usedH;
+        const short = Math.min(leftoverW, leftoverH);
+        const long = Math.max(leftoverW, leftoverH);
+        if (best !== null) {
+          if (short > bestShort) continue;
+          if (short === bestShort) {
+            if (long > bestLong) continue;
+            if (long === bestLong) {
+              if (fr.y > best.frY) continue;
+              if (fr.y === best.frY) {
+                if (fr.x > best.frX) continue;
+                if (fr.x === best.frX && anchor >= best.anchor) continue;
+              }
+            }
           }
         }
+        best = { x, y, frX: fr.x, frY: fr.y, anchor };
+        bestShort = short;
+        bestLong = long;
       }
-      best = fr;
-      bestShort = short;
-      bestLong = long;
     }
     if (best === null) {
+      if (held && tally !== undefined) tally.missedByAnchor++;
       placed.push(null);
+      // A caller that keeps only a pass placing every cell has its answer
+      // (`placePass`, `wholeOrNothing`): the rest are not placed.
+      if (stopAtMiss) {
+        while (placed.length < shapes.length) placed.push(null);
+        return placed;
+      }
       continue;
     }
-    const put: Rect = { x: best.x - box.x, y: best.y - box.y, w: shape.width, h: shape.height };
+    if (best.anchor === 1 && tally !== undefined) tally.secondAnchorPlaced++;
+    const put: Rect = { x: best.x, y: best.y, w: shape.width, h: shape.height };
     for (const other of owned) {
       // Two cells that do not overlap cannot share a texel, and that answer
       // takes no texel to read; only an overlap is scanned, and only over the
@@ -1521,11 +1834,26 @@ function packOnePageByFootprint(shapes: readonly CellShape[], pageW: number, pag
       while (placed.length < shapes.length) placed.push(null);
       return placed;
     }
-    for (const r of shape.rects) splitFree(free, { x: put.x + r.x, y: put.y + r.y, w: r.w, h: r.h }, minW, minH);
+    for (const r of shape.rects) splitFree(free, { x: put.x + r.x, y: put.y + r.y, w: r.w, h: r.h }, minW, minH, edgeIndex, tally);
   }
   return placed;
 }
 
+/**
+ * One footprint pass on an empty `pageW x pageH` page, run to its end, with
+ * what it counted — exported for `tools/pack_anchor.ts` (issue #1104).
+ */
+export function footprintPass(
+  shapes: readonly CellShape[],
+  pageW: number,
+  pageH: number,
+  anchors: FootprintAnchors = DEFAULT_FOOTPRINT_ANCHORS,
+): { rects: Array<{ x: number; y: number; w: number; h: number } | null>; tally: PassTally } {
+  const tally = emptyTally();
+  const rects = packOnePageByFootprint(shapes, pageW, pageH, Infinity, false, true, tally, anchors);
+  return { rects, tally };
+}
+
 const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 const isNumberList = (v: unknown): v is number[] => Array.isArray(v) && v.every((n) => typeof n === 'number' && Number.isFinite(n));
 
@@ -1733,6 +2061,130 @@ function extrudeCell(page: Plate, source: Plate, cellX: number, cellY: number, p
   }
 }
 
+/** Where every part lands and the size each page is written at — one candidate's whole pack, before anything is drawn. */
+interface PackLayout {
+  /** page index -> the placements on it, in packing order. */
+  perPage: Placement[][];
+  /** page index -> the size that page is written at. */
+  pageSizes: Array<{ width: number; height: number }>;
+  placements: Placement[];
+}
+
+/**
+ * One whole pack's layout under one placement rule: the single-page search,
+ * or — when the set does not fit one page — the spill, each page then shrunk
+ * to the smallest that holds it. `shapes` absent is the rectangle pass
+ * throughout (`rect`, and the first of `polygon`'s candidates); given, the
+ * footprint pass under `anchors`.
+ */
+function layoutPack(
+  sorted: readonly PackInput[],
+  cells: Array<{ w: number; h: number }>,
+  shapes: readonly CellShape[] | undefined,
+  maxEdge: number,
+  pageEdges: PageEdges,
+  padding: number,
+  anchors: FootprintAnchors,
+  tally?: PassTally,
+  stopAtMiss = true,
+): PackLayout {
+  const single = smallestPageFor(cells, maxEdge, pageEdges, shapes, anchors, tally, stopAtMiss);
+
+  /** page index -> the placements on it, in packing order. */
+  const perPage: Placement[][] = [];
+  /** page index -> the size that page is written at. */
+  const pageSizes: Array<{ width: number; height: number }> = [];
+  const placements: Placement[] = [];
+  if (single !== null) {
+    perPage.push([]);
+    pageSizes.push({ width: single.width, height: single.height });
+    single.rects.forEach((rect, i) => {
+      const place: Placement = {
+        region: sorted[i].region,
+        page: 0,
+        x: rect.x + padding,
+        y: rect.y + padding,
+        width: sorted[i].width,
+        height: sorted[i].height,
+      };
+      perPage[0].push(place);
+      placements.push(place);
+    });
+  } else {
+    // Spill. Which parts share a page is decided at the MAXIMUM size — that is
+    // what makes the boundary deterministic and independent of the shrink below
+    // — and parts are taken in packing order, whatever will not fit the current
+    // page opening the next one.
+    let remaining = sorted.map((input, i) => ({ input, cell: cells[i], shape: shapes?.[i] }));
+    const shapesOf = (list: typeof remaining): CellShape[] | undefined =>
+      shapes === undefined ? undefined : list.map((r) => r.shape ?? footprintCell(r.input.width, r.input.height, padding));
+    while (remaining.length > 0) {
+      const pageIndex = perPage.length;
+      const attempt = placePass(
+        remaining.map((r) => r.cell),
+        shapesOf(remaining),
+        maxEdge,
+        maxEdge,
+        Infinity,
+        { anchors, tally },
+      );
+      const onPage: typeof remaining = [];
+      const leftOver: typeof remaining = [];
+      attempt.forEach((rect, i) => {
+        if (rect === null) leftOver.push(remaining[i]);
+        else onPage.push(remaining[i]);
+      });
+      if (onPage.length === 0) {
+        // Unreachable: every cell was proven to fit an empty page above. Kept as
+        // a named stop rather than an infinite loop if that ever stops holding.
+        throw new CompileError(
+          `packing stalled with ${remaining.length} region(s) left and an empty ${maxEdge}x${maxEdge} page`,
+        );
+      }
+      // ⭐ Then the page is written at the smallest power-of-two pair that holds
+      // the cells assigned to it, not at the maximum (issue #266, follow-up 3).
+      // A spill used to write `pageSize x pageSize` for every page, so a set that
+      // overflowed by one small part paid for a second full page of transparency
+      // — 4 MiB of decoded RAM at the 2048 default for a part that might be
+      // 64x64. Re-packing through the same search the single-page case uses is
+      // what keeps "the page written is the smallest that holds what is on it"
+      // one rule; a page whose own cells need the maximum simply gets it back.
+      const shrunk = smallestPageFor(
+        onPage.map((r) => r.cell),
+        maxEdge,
+        pageEdges,
+        shapesOf(onPage),
+        anchors,
+        tally,
+        stopAtMiss,
+      );
+      if (shrunk === null) {
+        // Unreachable for the same reason as the stall above: these cells were
+        // just placed on a maxEdge page.
+        throw new CompileError(`page ${pageIndex + 1} of the spill holds ${onPage.length} region(s) that no page fits`);
+      }
+      const onThisPage: Placement[] = [];
+      shrunk.rects.forEach((rect, i) => {
+        const place: Placement = {
+          region: onPage[i].input.region,
+          page: pageIndex,
+          x: rect.x + padding,
+          y: rect.y + padding,
+          width: onPage[i].input.width,
+          height: onPage[i].input.height,
+        };
+        onThisPage.push(place);
+        placements.push(place);
+      });
+      perPage.push(onThisPage);
+      pageSizes.push({ width: shrunk.width, height: shrunk.height });
+      remaining = leftOver;
+    }
+  }
+
+  return { perPage, pageSizes, placements };
+}
+
 /**
  * Pack these parts onto shared pages.
  *
@@ -1796,9 +2248,17 @@ function extrudeCell(page: Plate, source: Plate, cellX: number, cellY: number, p
  *     two footprints keeps them `2 · padding` apart (`CellShape`);
  *   * **the placement** is `packOnePageByFootprint`, MaxRects with the free list
  *     split by what each cell owns, run beside the rectangle pass on every page
- *     tried and kept only when it is better (`placePass`) — so a `polygon` page
- *     is never larger than the `rect` page, and a set with no mesh footprint is
- *     placed exactly as under `rect` (`PK82`);
+ *     tried and kept only when it is better (`placePass`);
+ *   * **the pack written** is the least Σ page area — over every page, a spill's
+ *     included — of three whole packs: `rect`'s, the footprint pack under the
+ *     owned box's anchor, and under `box-else-cell` (issue #1104), the earlier
+ *     on a tie. So a `polygon` pack is never larger in page area than `rect`'s
+ *     on any set, by construction, and a set with no mesh footprint is `rect`'s
+ *     pack to the byte (`PK82`). The per-page rule alone never promised that
+ *     across a spill: seed 1105 under `pot` packed 8,388,608 texels against
+ *     `rect`'s 6,291,456 before it (`PK96`). It costs the three packs' searches
+ *     — no search is shared, since a free search's bounds depend on the best
+ *     page its own passes found;
  *   * **the pixels** are drawn in two passes: every cell whole in packing order,
  *     as under `rect`, then every region's owned texels again with its own
  *     values. The owned sets are disjoint, so the second pass's order decides
@@ -1858,94 +2318,31 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
   const shapes =
     shape === 'polygon' ? sorted.map((input) => footprintCell(input.width, input.height, padding, input.footprint)) : undefined;
 
-  const single = smallestPageFor(cells, maxEdge, pageEdges, shapes);
-
-  /** page index -> the placements on it, in packing order. */
-  const perPage: Placement[][] = [];
-  /** page index -> the size that page is written at. */
-  const pageSizes: Array<{ width: number; height: number }> = [];
-  const placements: Placement[] = [];
-  if (single !== null) {
-    perPage.push([]);
-    pageSizes.push({ width: single.width, height: single.height });
-    single.rects.forEach((rect, i) => {
-      const place: Placement = {
-        region: sorted[i].region,
-        page: 0,
-        x: rect.x + padding,
-        y: rect.y + padding,
-        width: sorted[i].width,
-        height: sorted[i].height,
-      };
-      perPage[0].push(place);
-      placements.push(place);
-    });
-  } else {
-    // Spill. Which parts share a page is decided at the MAXIMUM size — that is
-    // what makes the boundary deterministic and independent of the shrink below
-    // — and parts are taken in packing order, whatever will not fit the current
-    // page opening the next one.
-    let remaining = sorted.map((input, i) => ({ input, cell: cells[i], shape: shapes?.[i] }));
-    const shapesOf = (list: typeof remaining): CellShape[] | undefined =>
-      shapes === undefined ? undefined : list.map((r) => r.shape ?? footprintCell(r.input.width, r.input.height, padding));
-    while (remaining.length > 0) {
-      const pageIndex = perPage.length;
-      const attempt = placePass(
-        remaining.map((r) => r.cell),
-        shapesOf(remaining),
-        maxEdge,
-        maxEdge,
-      );
-      const onPage: typeof remaining = [];
-      const leftOver: typeof remaining = [];
-      attempt.forEach((rect, i) => {
-        if (rect === null) leftOver.push(remaining[i]);
-        else onPage.push(remaining[i]);
-      });
-      if (onPage.length === 0) {
-        // Unreachable: every cell was proven to fit an empty page above. Kept as
-        // a named stop rather than an infinite loop if that ever stops holding.
-        throw new CompileError(
-          `packing stalled with ${remaining.length} region(s) left and an empty ${maxEdge}x${maxEdge} page`,
-        );
-      }
-      // ⭐ Then the page is written at the smallest power-of-two pair that holds
-      // the cells assigned to it, not at the maximum (issue #266, follow-up 3).
-      // A spill used to write `pageSize x pageSize` for every page, so a set that
-      // overflowed by one small part paid for a second full page of transparency
-      // — 4 MiB of decoded RAM at the 2048 default for a part that might be
-      // 64x64. Re-packing through the same search the single-page case uses is
-      // what keeps "the page written is the smallest that holds what is on it"
-      // one rule; a page whose own cells need the maximum simply gets it back.
-      const shrunk = smallestPageFor(
-        onPage.map((r) => r.cell),
-        maxEdge,
-        pageEdges,
-        shapesOf(onPage),
-      );
-      if (shrunk === null) {
-        // Unreachable for the same reason as the stall above: these cells were
-        // just placed on a maxEdge page.
-        throw new CompileError(`page ${pageIndex + 1} of the spill holds ${onPage.length} region(s) that no page fits`);
-      }
-      const onThisPage: Placement[] = [];
-      shrunk.rects.forEach((rect, i) => {
-        const place: Placement = {
-          region: onPage[i].input.region,
-          page: pageIndex,
-          x: rect.x + padding,
-          y: rect.y + padding,
-          width: onPage[i].input.width,
-          height: onPage[i].input.height,
-        };
-        onThisPage.push(place);
-        placements.push(place);
-      });
-      perPage.push(onThisPage);
-      pageSizes.push({ width: shrunk.width, height: shrunk.height });
-      remaining = leftOver;
-    }
+  // ⭐ `polygon` is a choice between whole packs (issue #1104), made on the
+  // one figure the mode exists to lower — the sum of the pages' areas — and
+  // made over every page, a spill's included. The candidates, in order: the
+  // rectangle pack (`rect`'s own, to the byte); the footprint pack with the
+  // owned box's anchor (`box`); and the footprint pack that may also put a
+  // cell's own corner where the first anchor would leave the page
+  // (`box-else-cell`). The least Σ area wins, the earlier candidate on a tie.
+  // So a `polygon` pack is never larger than `rect`'s, nor than the one-anchor
+  // pack, on any set — by construction, across a spill as well as on one page,
+  // which no single greedy rule gives: one more candidate position placed
+  // PK78's gem differently and every tile after it (one page 7.2 % larger),
+  // and the first page of a spill choosing differently left seed 1105 under
+  // `pot` on two 2048x2048 pages against `rect`'s 2048x2048 + 1024x2048.
+  // `footprintAnchors` names one rule alone instead (the instrument, the plant).
+  const candidates: Array<{ name: PackCandidate; layout: PackLayout }> = [];
+  if (shapes === undefined) candidates.push({ name: 'rect', layout: layoutPack(sorted, cells, undefined, maxEdge, pageEdges, padding, 'box', opts.tally, opts.stopAtMiss ?? true) });
+  else if (opts.footprintAnchors !== undefined) candidates.push({ name: opts.footprintAnchors, layout: layoutPack(sorted, cells, shapes, maxEdge, pageEdges, padding, opts.footprintAnchors, opts.tally, opts.stopAtMiss ?? true) });
+  else {
+    candidates.push({ name: 'rect', layout: layoutPack(sorted, cells, undefined, maxEdge, pageEdges, padding, 'box', opts.tally, opts.stopAtMiss ?? true) });
+    for (const rule of POLYGON_CANDIDATE_RULES) candidates.push({ name: rule, layout: layoutPack(sorted, cells, shapes, maxEdge, pageEdges, padding, rule, opts.tally, opts.stopAtMiss ?? true) });
   }
+  const areaOf = (layout: PackLayout): number => layout.pageSizes.reduce((n, p) => n + p.width * p.height, 0);
+  let chosen = candidates[0];
+  for (const c of candidates) if (areaOf(c.layout) < areaOf(chosen.layout)) chosen = c;
+  const { perPage, pageSizes, placements } = chosen.layout;
 
   // Draw. Reading each source once, in packing order, keeps the decode count at
   // one per part whatever the page layout turned out to be.
@@ -2019,7 +2416,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
     });
   });
 
-  return { pages, placements, atlasText: writeAtlasText(emitPages), padding, shape };
+  return { pages, placements, atlasText: writeAtlasText(emitPages), padding, shape, candidate: chosen.name };
 }
 
 // ---------------------------------------------------------------------------

package/src/cli/shared.ts

@@ -1225,8 +1225,13 @@ interface CommandDoc {
    * claim anybody keeps by hand: `RC26` in `selftest.ts` derives it from the
    * import graph of the module whose bodies register the command, and a
    * mark that disagrees with the graph is red by name.
+   *
+   * `rerunsTheGate` marks a command whose body re-runs the gate `build` ran
+   * before it wrote (`validate`): refused by the entry that links none of the
+   * runtime and pointed at a rigc build, its refusal says that gate already
+   * ran (`gatedOnWrite`, issue #1097).
    */
-  runtime: false | { for: string; core?: CoreBody };
+  runtime: false | { for: string; core?: CoreBody; rerunsTheGate?: true };
   /**
    * Whether the command exists for the Spine format — reads, writes, compares
    * or embeds Spine skeleton data as the whole of what it does with it — so
@@ -1311,7 +1316,7 @@ export const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'validate',
-    runtime: { for: 'the gate it re-runs is the round trip through it' },
+    runtime: { for: 'the gate it re-runs is the round trip through it', rerunsTheGate: true },
     spineFormat: true,
     usage: [
       'rigc validate <dir | skeleton.json> [--atlas <path>] [--profile spine|spine-html]',
@@ -2279,6 +2284,51 @@ export function entryCommands(linksRuntime: boolean): CommandDoc[] {
   });
 }
 
+/**
+ * What the refusal of a command that re-runs the gate says when its target is
+ * a rigc build (issue #1097): that build already ran the gate, before it wrote
+ * anything. A consumer met the refusal and read it as a gate the install could
+ * not run, because the refusal said only what `validate` needs (#1095).
+ *
+ * ⚠️ Every clause is a fact about what the directory carries, never a reading
+ * of the document: `skeleton.model.json` beside the pair is what makes it a
+ * rigc build (`resolveBuild`'s `modelPath`), and emit-only-after-green is
+ * what makes a rigc build gated on write. It does not say which entry wrote
+ * it, which spec version the document is, or that the skeleton is still the
+ * one the gate passed — nothing here reads the document, so those are said as
+ * where to look (`spine.sha256`), not as findings.
+ */
+export function gatedOnWriteSentence(skeletonPath: string): string {
+  return (
+    `The target is a rigc build — ${skeletonPath} has ${MODEL_DOCUMENT_FILE} beside it — and a rigc build writes nothing until its gate is green: ` +
+    `that gate ran when the pair was written, and the document is the record of what it passed, its spine.sha256 naming the skeleton bytes the gate read ` +
+    "— on this entry the gate is the model side's rules over the document and the round trip's own restated over the emitted text, " +
+    'with A00_ROUNDTRIP_PARSE alone reported as a SKIP.'
+  );
+}
+
+/**
+ * `gatedOnWriteSentence` for a refused command marked `rerunsTheGate`, or
+ * `null` — the refusal then says what it always said. The target is
+ * `cmdValidate`'s: the positional (`.` without one) through `resolveBuild`;
+ * a `--cut` or `--rig` run derives its directory from a spec, which the
+ * refusal does not compile, so it keeps the sentence it had. Arguments
+ * `parseArgs` or `resolveBuild` refuses are the command's to refuse, not the
+ * runtime refusal's, and leave it as it was.
+ */
+function gatedOnWrite(doc: CommandDoc, args: readonly string[]): string | null {
+  if (doc.runtime === false || doc.runtime.rerunsTheGate !== true) return null;
+  try {
+    const { flags, positional } = parseArgs([...args], REPEATABLE_FLAGS[doc.name]);
+    if (flags.cut !== undefined || flags.rig !== undefined) return null;
+    const build = resolveBuild(positional[0] ?? '.', flags.atlas);
+    return build.modelPath === null ? null : gatedOnWriteSentence(build.skeletonPath);
+  } catch (err) {
+    if (err instanceof UsageError) return null;
+    throw err;
+  }
+}
+
 /**
  * A command `COMMANDS` documents and this entry does not run, because its body
  * reaches spine-core and the entry links none of it — refused naming what the
@@ -2286,10 +2336,12 @@ export function entryCommands(linksRuntime: boolean): CommandDoc[] {
  * A `SpineRuntimeError`, so it is printed and exits as the export an entry
  * cannot pose is.
  */
-function commandNeedsRuntime(doc: CommandDoc, runs: readonly string[]): SpineRuntimeError {
+function commandNeedsRuntime(doc: CommandDoc, runs: readonly string[], args: readonly string[]): SpineRuntimeError {
   const needs = doc.runtime === false ? 'nothing' : doc.runtime.for;
+  const gated = gatedOnWrite(doc, args);
   return new SpineRuntimeError(
     `\`${doc.name}\` runs through spine-core (${needs}), and the runtime could not be used: ${SPINE_SIDE_ABSENT}. ` +
+      (gated === null ? '' : `${gated} `) +
       `The commands this entry runs are ${runs.join(', ')}; the entry that links spine-core runs \`${doc.name}\` — ` +
       `installed, \`rigc ${doc.name}\` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, \`bun cli.ts ${doc.name}\``,
   );
@@ -2325,7 +2377,7 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
     }
     if (!known.includes(command)) {
       const elsewhere = COMMANDS.find((doc) => doc.name === command);
-      if (elsewhere !== undefined) throw commandNeedsRuntime(elsewhere, known);
+      if (elsewhere !== undefined) throw commandNeedsRuntime(elsewhere, known, rest);
       throw new UsageError(`unknown command: ${command}`);
     }
 

package/tools/editor_roundtrip.ts

@@ -936,6 +936,103 @@ export function shapeDiff(before: Shape, after: Shape): string[] {
   return rows;
 }
 
+/** What a JSON value is, in the words a refusal names it by: `null`, `an array`, `a number`, … */
+function jsonKind(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return typeof value === 'object' ? 'an object' : `a ${typeof value}`;
+}
+
+/** True for the one JSON kind a skeleton file and each of its records is: a plain object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The build's `skeleton.json`, read and parsed once, or the sentence the tool
+ * refuses it with (issue #1090).
+ *
+ * 🚨 The `skeleton.images` probe in `main` used to be the first thing that read
+ * this file, and it read it with a bare `JSON.parse`. A file that was not JSON,
+ * or was JSON holding `null`, therefore left the tool as an uncaught
+ * `SyntaxError` / `TypeError` and its stack — before the editor, so with nothing
+ * of the editor's to quote, and in a shape no other refusal in this file has.
+ * And a file holding `[]` or `7` did not stop at all: the probe found no
+ * `skeleton.images` on it and the run went on to hand the editor a file that is
+ * not a skeleton, minutes of import for a refusal this could state for free.
+ *
+ * ⭐ So this is the one reader of the build's skeleton text before step 1, and
+ * it refuses by the file's path and what it found there: a directory, the
+ * parser's own message, or the JSON kind that is not an object. What it hands
+ * back is the value the probe reads, so a readable build is parsed exactly as
+ * it was and every line after this prints as it did.
+ */
+function readBuildSkeleton(source: string): { skeleton: Record<string, unknown> } | { refusal: string } {
+  const required =
+    'The round trip imports that file into the editor, so it has to be one skeleton JSON object — `skeleton`, ' +
+    '`bones`, `slots`, … — which is what `rigc build` writes there.';
+  let text: string;
+  try {
+    text = readFileSync(source, 'utf8');
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'EISDIR') return { refusal: `the build's skeleton.json at ${source} is a directory, not a file. ${required}` };
+    return { refusal: `the build's skeleton.json at ${source} could not be read (${code ?? String(err)}). ${required}` };
+  }
+  if (text.trim() === '') {
+    return { refusal: `the build's skeleton.json at ${source} is empty (${text.length} byte(s), no JSON value in them). ${required}` };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    const said = err instanceof Error ? err.message : String(err);
+    return { refusal: `the build's skeleton.json at ${source} is not JSON — the parser stopped with "${said}". ${required}` };
+  }
+  if (!isRecord(parsed)) {
+    return { refusal: `the build's skeleton.json at ${source} is JSON, but it holds ${jsonKind(parsed)} rather than an object. ${required}` };
+  }
+  return { skeleton: parsed };
+}
+
+/**
+ * The field of the build's skeleton the images probe would have thrown on, as a
+ * sentence naming it and what it holds — or null when every field the probe
+ * dereferences is the kind it reads (issue #1090).
+ *
+ * ⚠️ Only those fields, and only on the path that reads them: the walk below
+ * runs when `skeleton.images` is declared, and a field this does not read is the
+ * gate's to judge after the import, not a precondition of the editor's. Asking
+ * more here would be a second validator in front of the first.
+ */
+function imagesProbeFault(skeleton: Record<string, unknown>): string | null {
+  const head = skeleton.skeleton;
+  if (!isRecord(head)) return null;
+  const images = head.images;
+  if (images === undefined) return null;
+  if (typeof images !== 'string') return `\`skeleton.images\` holds ${jsonKind(images)}, not a path string`;
+  if (images === '') return null;
+  const skins = skeleton.skins;
+  if (skins === undefined) return null;
+  if (!Array.isArray(skins)) return `\`skins\` holds ${jsonKind(skins)}, not an array`;
+  for (let i = 0; i < skins.length; i++) {
+    const skin: unknown = skins[i];
+    if (!isRecord(skin)) return `\`skins[${i}]\` holds ${jsonKind(skin)}, not an object`;
+    const attachments = skin.attachments;
+    if (attachments === undefined) continue;
+    if (!isRecord(attachments)) return `\`skins[${i}].attachments\` holds ${jsonKind(attachments)}, not an object`;
+    for (const [slot, entries] of Object.entries(attachments)) {
+      if (!isRecord(entries)) return `\`skins[${i}].attachments.${slot}\` holds ${jsonKind(entries)}, not an object`;
+      for (const [placeholder, att] of Object.entries(entries)) {
+        if (!isRecord(att)) {
+          return `\`skins[${i}].attachments.${slot}.${placeholder}\` holds ${jsonKind(att)}, not an object`;
+        }
+      }
+    }
+  }
+  return null;
+}
+
 function main(): void {
   const opts = parseArgs(process.argv.slice(2));
   const rigc = rigcCommand();
@@ -975,6 +1072,19 @@ function main(): void {
   };
 
   if (!existsSync(source)) fail(`no skeleton.json in the build directory ${opts.build}`);
+  // 🔒 Read and parsed HERE, once, before anything else reads it (issue #1090):
+  // a build whose skeleton is not one JSON object is refused by name rather than
+  // thrown as a stack by the probe below, or handed to the editor.
+  const read = readBuildSkeleton(source);
+  if ('refusal' in read) return fail(read.refusal);
+  const probeFault = imagesProbeFault(read.skeleton);
+  if (probeFault !== null) {
+    fail(
+      `the build's skeleton.json at ${source} is an object, but ${probeFault} — one of the fields read before ` +
+        "step 1 to check that every image the editor's import will look for is there. A skeleton `rigc build` " +
+        'wrote never carries that; rebuild the directory with `rigc build … --copy-images`.',
+    );
+  }
 
   // 🚨 The art the EDITOR will look for, checked before the editor is started —
   // issue #562. The editor's JSON import reads `skeleton.images` and finds each
@@ -1010,7 +1120,9 @@ function main(): void {
       skeleton?: { images?: string };
       skins?: Array<{ attachments?: Record<string, Record<string, { type?: string; name?: string; path?: string }>> }>;
     }
-    const probe = JSON.parse(readFileSync(source, 'utf8')) as ImagesProbe;
+    // The value `readBuildSkeleton` parsed, and the fields this walk reads are
+    // the ones `imagesProbeFault` has already held to their kinds.
+    const probe = read.skeleton as ImagesProbe;
     const declared = probe.skeleton?.images;
     if (declared !== undefined && declared !== '') {
       const imagesDir = resolve(opts.build, declared);