spine-rigc 2.1.1 → 2.1.3

package/README.md

@@ -698,7 +698,10 @@ 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,
+and so is a build with no atlas or an atlas that is a directory, or an
+`--exported` file that is not one JSON object.
 
 ⛔ **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,26 +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**, measured for the pack alone
-  (`--page-edges free`, padding 2, page size 2048, both shapes in one
-  process, a shared machine, so read the ratios): on a production rig's region
-  set (31 meshes, a few of them large, a two-page spill, the `rect` pages to
-  the texel) 0.15–0.18 s against `rect`'s 0.06 s — it was 260–304 s before
-  issue #1102, because a page search ran a full footprint pass at every width
-  and threw each one away; on a generated set of that shape
-  (`fixtures/polypack_shapes.ts`, seed 1107) 0.17 s against 0.06 s, from
-  4.5 s. Where the footprint pass does move a page the cost is real work and
-  stays: on a generated set it packs smaller (seed 1105, 4,882,012 →
-  4,467,942 texels over two pages) 0.96–0.99 s against 0.07–0.10 s, about ten
-  to fourteen times `rect`, from 127 s. `PK93` holds the first generated set
-  as a count of free-list splits, within ten times `rect`'s.
+  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.1",
+  "version": "2.1.3",
   "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, Infinity, { wholeOrNothing: true });
+    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. */
@@ -916,6 +979,8 @@ 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;
 }
 
 /**
@@ -948,7 +1013,7 @@ export function freePageSearch(
     cellArea = 0;
     for (const shape of shapes) cellArea += shape.owned;
   }
-  const out: FreePageSearch = { page: null, widths: 0, completed: 0, abandoned: 0, skipped: 0, tally: { rectPlaced: 0, footprintPlaced: 0, bandSplits: 0, containmentTests: 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++;
@@ -958,7 +1023,7 @@ export function freePageSearch(
       continue;
     }
     const maxBottom = best === null ? Infinity : Math.floor(bestArea / width);
-    const attempt = placePass(cells, shapes, width, maxEdge, maxBottom, { wholeOrNothing, tally: out.tally, edgeIndex: options.edgeIndex ?? true });
+    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) {
@@ -1150,7 +1215,7 @@ function placePass(
   // 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. With the early stop the pack takes 0.15–0.7 s by the load, the
+  // 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;
@@ -1165,8 +1230,20 @@ 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, wholeOrNothing, pass.edgeIndex ?? true, tally);
-  if (tally !== undefined) tally.footprintPlaced += placedCount(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);
@@ -1183,6 +1260,8 @@ interface PassOptions {
   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. */
@@ -1213,6 +1292,22 @@ export interface PassTally {
   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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -1589,9 +1684,12 @@ const UNTOUCHED = -1;
  *   * 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.
  *
@@ -1600,6 +1698,27 @@ const UNTOUCHED = -1;
  * 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
@@ -1618,6 +1737,7 @@ function packOnePageByFootprint(
   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> = [];
@@ -1633,33 +1753,56 @@ function packOnePageByFootprint(
 
   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.
@@ -1669,7 +1812,8 @@ function packOnePageByFootprint(
       }
       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
@@ -1695,6 +1839,21 @@ function packOnePageByFootprint(
   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));
 
@@ -1902,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.
  *
@@ -1965,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
@@ -2027,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.
@@ -2188,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,167 @@ 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 } {
+  return readSkeletonObject(
+    source,
+    "the build's skeleton.json",
+    '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.',
+  );
+}
+
+/**
+ * One skeleton file read and parsed, with its bytes — or the sentence the tool
+ * refuses it with, naming `what` it is, its path, what was found there and the
+ * `required` sentence. The one body behind `readBuildSkeleton` and the
+ * `--exported` read (issue #1107), so the two files are refused in one shape.
+ *
+ * The bytes are handed back because the `--exported` file is written into the
+ * candidate from them: the file step 3 measures is then the file this parsed,
+ * byte for byte, rather than whatever is at the path by the time step 3 runs.
+ */
+function readSkeletonObject(
+  path: string,
+  what: string,
+  required: string,
+): { skeleton: Record<string, unknown>; bytes: Buffer } | { refusal: string } {
+  let bytes: Buffer;
+  try {
+    bytes = readFileSync(path);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'EISDIR') return { refusal: `${what} at ${path} is a directory, not a file. ${required}` };
+    return { refusal: `${what} at ${path} could not be read (${code ?? String(err)}). ${required}` };
+  }
+  const text = bytes.toString('utf8');
+  if (text.trim() === '') {
+    return { refusal: `${what} at ${path} 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: `${what} at ${path} is not JSON — the parser stopped with "${said}". ${required}` };
+  }
+  if (!isRecord(parsed)) {
+    return { refusal: `${what} at ${path} is JSON, but it holds ${jsonKind(parsed)} rather than an object. ${required}` };
+  }
+  return { skeleton: parsed, bytes };
+}
+
+/**
+ * The build's atlas, read once before step 1, or the sentence the tool refuses
+ * it with (issue #1107): its name and the page names it lists.
+ *
+ * 🚨 This read used to sit at step 3, after the editor had imported and
+ * exported. So a build with no atlas was refused by name only after a licensed
+ * editor had spent an import and an export on it, and a directory named
+ * `*.atlas` beside the build threw `EISDIR` there as a stack. Neither needs the
+ * editor to answer: the atlas is rigc's input to step 3, not the editor's.
+ *
+ * ⭐ Every `*.atlas` entry is read, not only the one whose pages are listed,
+ * because step 3 copies every one of them beside the export, and a directory
+ * among them throws at that copy. The first entry is the atlas, as it always was.
+ *
+ * ⚠️ "Read" is all this can mean. The tool's own reader of an atlas is the line
+ * filter below, which accepts any text, so there is no malformed atlas for it to
+ * refuse; what the atlas SAYS is the gate's to judge at step 3 (`A08`, `A17`).
+ */
+function readBuildAtlas(build: string): { pageNames: string[] } | { refusal: string } {
+  const atlases = readdirSync(build).filter((f) => f.endsWith('.atlas'));
+  if (atlases.length === 0) return { refusal: `no .atlas in the build directory ${build}` };
+  const required =
+    'Step 3 copies the build\'s atlas and pages beside the export so the export can be loaded and measured, so ' +
+    'every `.atlas` there has to be a file — the one `rigc build` writes.';
+  let first: string | null = null;
+  for (const name of atlases) {
+    const path = join(build, name);
+    try {
+      const text = readFileSync(path, 'utf8');
+      if (first === null) first = text;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'EISDIR') return { refusal: `the build's atlas at ${path} is a directory, not a file. ${required}` };
+      return { refusal: `the build's atlas at ${path} could not be read (${code ?? String(err)}). ${required}` };
+    }
+  }
+  const pageNames = (first ?? '')
+    .split('\n')
+    .filter((line) => /\.(png|jpg|jpeg)\s*$/i.test(line.trim()) && !line.startsWith(' ') && !line.startsWith('\t'))
+    .map((line) => line.trim());
+  return { pageNames };
+}
+
+/**
+ * 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 +1136,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
@@ -1001,16 +1175,22 @@ function main(): void {
   // makes — and `--pack --copy-images` is refused by `cli.ts`, correctly,
   // because a packed atlas does not reference loose parts.
   //
-  // ⛔ It is checked HERE, before step 1, rather than beside the atlas check
-  // further down, because each precondition sits before the step it protects:
-  // the atlas's page names matter to the harness's own copy in step 3, and this
-  // matters to the editor's import in step 1.
+  // ⛔ It is checked HERE, before step 1, because it matters to the editor's
+  // import in step 1. The atlas and an `--exported` file are read before step 1
+  // as well, just below, although nothing before step 3 uses them (issue #1107):
+  // they are rigc's inputs and not the editor's, so reading them first costs the
+  // editor nothing and refuses before a licensed editor is started on a trip
+  // that cannot finish — the reason `readBuildSkeleton` reads the build's
+  // skeleton first (#1090). So the order is: every input rigc reads is read
+  // before the editor starts, and only what the editor writes is read after it.
   {
     interface ImagesProbe {
       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);
@@ -1055,6 +1235,48 @@ function main(): void {
     }
   }
 
+  // The export is a skeleton only; it needs the build's atlas and pages beside
+  // it to be a candidate anything can load — so the atlas is step 3's, and it is
+  // read here, before step 1, for the reason the sentence above gives.
+  //
+  // 🚨 Which is why the build has to be SELF-CONTAINED, and this refuses when it
+  // is not. An ordinary build's atlas names its pages by a relative path back to
+  // the art directory; copy that atlas to a directory at another depth and every
+  // page name resolves to nothing. Found by running this tool — it reported four
+  // `A17_ATLAS_PAGE_FILES_EXIST` failures that were the harness's fault and not
+  // the editor's, which is the worst kind of red: a real assertion, correctly
+  // fired, pointing at the wrong culprit.
+  const atlas = readBuildAtlas(opts.build);
+  if ('refusal' in atlas) return fail(atlas.refusal);
+  const wandering = atlas.pageNames.filter((n) => n.includes('/'));
+  if (wandering.length > 0) {
+    fail(
+      `the build's atlas names its pages by path, not by filename — the first is "${wandering[0]}". ` +
+        'The round trip copies the atlas beside the export, at a different depth, so every one of those ' +
+        `${wandering.length} page name(s) would resolve to nothing and A17 would blame the editor for it. ` +
+        'Rebuild with `--copy-images`, which puts the pages beside the skeleton and names them plainly.',
+    );
+  }
+
+  // 🔒 The `--exported` file, read and parsed here for the same reason (issue
+  // #1107): one skeleton JSON object, in `readBuildSkeleton`'s shape, or refused
+  // by name. It used to be read first by step 4's `skinsDeclaredBy`, bare, so a
+  // file that was not JSON was gated and diffed by steps 3–4 and then left the
+  // tool as a `SyntaxError` stack. Step 3's candidate is written from these
+  // bytes, so what is measured is what was parsed.
+  let exportedBytes: Buffer | null = null;
+  if (opts.exported !== null) {
+    if (!existsSync(opts.exported)) fail(`no such export: ${opts.exported}`);
+    const got = readSkeletonObject(
+      opts.exported,
+      'the --exported file',
+      'Steps 3-6 measure that file as the editor\'s JSON export of this build, so it has to be one skeleton JSON ' +
+        'object — `skeleton`, `bones`, `slots`, … — which is what the editor\'s `-e json` export writes.',
+    );
+    if ('refusal' in got) return fail(got.refusal);
+    exportedBytes = got.bytes;
+  }
+
   rmSync(opts.out, { recursive: true, force: true });
   mkdirSync(join(opts.out, 'export'), { recursive: true });
   mkdirSync(join(opts.out, 'export-cand'), { recursive: true });
@@ -1065,7 +1287,6 @@ function main(): void {
 
   let exportedJson: string;
   if (opts.exported !== null) {
-    if (!existsSync(opts.exported)) fail(`no such export: ${opts.exported}`);
     exportedJson = opts.exported;
     emit(`  editor   NOT RUN — measuring an export the editor already made: ${opts.exported}`);
     emit('');
@@ -1134,33 +1355,12 @@ function main(): void {
     exportedJson = join(opts.out, 'export', written[0]);
   }
 
-  // The export is a skeleton only; it needs the build's atlas and pages beside
-  // it to be a candidate anything can load.
-  //
-  // 🚨 Which is why the build has to be SELF-CONTAINED, and this refuses when it
-  // is not. An ordinary build's atlas names its pages by a relative path back to
-  // the art directory; copy that atlas to a directory at another depth and every
-  // page name resolves to nothing. Found by running this tool — it reported four
-  // `A17_ATLAS_PAGE_FILES_EXIST` failures that were the harness's fault and not
-  // the editor's, which is the worst kind of red: a real assertion, correctly
-  // fired, pointing at the wrong culprit.
+  // The candidate: the export beside the build's atlas and pages, which were
+  // read before step 1 (see `readBuildAtlas`). An `--exported` file is written
+  // from the bytes parsed there; the editor's own export is copied from disk.
   const cand = join(opts.out, 'export-cand');
-  const atlasName = readdirSync(opts.build).find((f) => f.endsWith('.atlas'));
-  if (atlasName === undefined) fail(`no .atlas in the build directory ${opts.build}`);
-  const pageNames = readFileSync(join(opts.build, atlasName!), 'utf8')
-    .split('\n')
-    .filter((line) => /\.(png|jpg|jpeg)\s*$/i.test(line.trim()) && !line.startsWith(' ') && !line.startsWith('\t'))
-    .map((line) => line.trim());
-  const wandering = pageNames.filter((n) => n.includes('/'));
-  if (wandering.length > 0) {
-    fail(
-      `the build's atlas names its pages by path, not by filename — the first is "${wandering[0]}". ` +
-        'The round trip copies the atlas beside the export, at a different depth, so every one of those ' +
-        `${wandering.length} page name(s) would resolve to nothing and A17 would blame the editor for it. ` +
-        'Rebuild with `--copy-images`, which puts the pages beside the skeleton and names them plainly.',
-    );
-  }
-  copyFileSync(exportedJson, join(cand, 'skeleton.json'));
+  if (exportedBytes !== null) writeFileSync(join(cand, 'skeleton.json'), exportedBytes);
+  else copyFileSync(exportedJson, join(cand, 'skeleton.json'));
   for (const f of readdirSync(opts.build)) {
     if (f.endsWith('.atlas') || f.endsWith('.png')) copyFileSync(join(opts.build, f), join(cand, f));
   }