rig-c 2.37.0 → 2.38.0

package/README.md

@@ -575,6 +575,7 @@ commands take it and what its default is.
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
 | `repack <dir> --out <dir>` | a packed build **repacked from its own output** — `skeleton.json`, `skeleton.atlas` and the pages, with no parts kept — under the packing flags `build --pack` takes, so a packer improvement reaches a build whose parts are gone. Every region is lifted off its page, the skeleton read back with `ingest`, and `build --pack` run over the lifted parts with the same gate; it writes only after every region is shown pixel-identical to the input's, the skeleton byte-identical and the gate green, and refuses by name an atlas it cannot lift exactly. A skeleton the rebuild does not reproduce byte for byte — a build written before 2.2.0, whose header box was its stage — is refused naming every differing path, and written, every path printed, only under `--accept-skeleton-differences`. `--stage-box <slot>` reads the stage from the box a build carries for it (`skeleton.stageBox`), the one way the three files alone carry the stage exactly ([AUTHORING §0.4](docs/AUTHORING.md)) |
+| `repack <dir> --out <dir> --keep-pages` | **`skeleton.model.json` alone, for the pages already in place** — for a player that reads the document beside an atlas and pages that already shipped. The same read and stage rules, then `build --atlas-in` over the input atlas in place of the lift and the pack; it writes the document, and nothing else, only after its `pages` are shown to state the atlas as it stands, the rebuilt skeleton byte-identical to the one on disk (so `spine.sha256` names it — no acceptance flag here) and the gate green. `--out` is usually the build's own directory and must not already hold a `skeleton.model.json`; a page or region line the document has no field for is refused by name ([AUTHORING §0.4](docs/AUTHORING.md)) |
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid |

package/docs/AUTHORING.md

@@ -1317,6 +1317,7 @@ that lifts them.
 | `--stage x,y,w,h` | handed to `ingest` as its own `--stage` (§0.3) — a box for a skeleton that states none, refused beside one that does |
 | `--stage-box <slot>` | handed to `ingest` as its own `--stage-box` (§0.3): the stage read from the bounding box a build writes for a rig that states `skeleton.stageBox` — the exact way to carry the stage through a repack of the three files alone (*The stage*, below). `ingest`'s refusals reach the caller in its own words |
 | `--accept-skeleton-differences` | write the rebuild even where its `skeleton.json` differs from the input's, with **every** differing path printed and both values (default: refused naming them, check (b) below). Nothing else relaxes: check (a) and the gate hold exactly as without it. Beside a skeleton that comes back byte-identical, check (b)'s line says the flag accepted nothing |
+| `--keep-pages` | write **`skeleton.model.json` alone**, for the atlas and pages as they stand — nothing lifted, nothing packed, no page and no atlas written (*Keeping the pages*, below). Takes none of the packing flags and not `--accept-skeleton-differences`, each refused by name (exit 2) |
 
 Every other flag `build` takes is refused by name, with the reason `repack` does not
 take it (`--rig`, `--motion`, `--images`, `--manifest`, `--copy-images`, `--pack`,
@@ -1449,6 +1450,71 @@ either way; the stage line is where it shows. Pass `--stage-box <slot>` for such
 build. (`--stage` adds a box only to a skeleton that states none, which is `ingest`'s
 rule.)
 
+**Keeping the pages — `--keep-pages`** (issue #1339). A player that reads
+`skeleton.model.json` needs the document for the pages it already ships, not for new
+ones: a repack's document states the repacked placement, and beside the old pages it
+describes texels that are not there. `--keep-pages` writes that document and nothing
+else:
+
+```bash
+bun cli.ts repack spine/ --out spine/ --keep-pages
+#   ..    keep   --keep-pages: the atlas and its pages are kept as they are and skeleton.model.json is the one file written; profile spine
+#   ..    stage  640 x 725 at -0.000016,-25 — read from the skeleton's header box: …
+#   ..    check  (a) pages: the document states the atlas's 1 page(s) and 10 region(s) as they stand, field for field (pagesOfAtlas of the input atlas) — no page and no atlas is written
+#   ..    check  (b) skeleton.json: byte-identical to the input's — the document's spine.sha256 names the file on disk
+#   ..    check  (c) gate: green — the report above, on the build against the atlas as it stands
+# rigc: wrote /abs/path/spine/skeleton.model.json
+```
+
+The read and the stage are the repack's — the same `ingest`, the same `--stage` and
+`--stage-box`, the same stage line. In place of the lift and `build --pack` it runs
+**`build --atlas-in`** over the input atlas (§0.1's *a pack somebody already made*),
+which resolves every part to a region of that atlas and writes no page; the atlas and
+its pages are staged as copies in the work directory, so the document's page names
+are the atlas's own. Before the one write, three things are shown: **(a)** the
+document's `pages` are the input atlas's pages and regions field for field;
+**(b)** the rebuilt `skeleton.json` is byte-identical to the input's, so
+`spine.sha256` names the file on disk — **with no acceptance**: a document whose digest
+names a skeleton other than the one beside it is exactly what this must not write, so
+`--accept-skeleton-differences` is refused here, and a build written before 2.2.0
+needs the full repack, which writes the rebuilt skeleton with its own pages; **(c)**
+the gate is green.
+
+- `--out` is usually the build's own directory. It may hold anything **except** a
+  `skeleton.model.json`, which is never written over (exit 2, naming the file): remove
+  it to have it rewritten. The atlas has to sit beside the skeleton, because the
+  document's page names are paths from the directory it sits in.
+- What the document states is accepted as it stands: a turned region, a trimmed
+  region, a page `scale:`, `pma: true`, `index:` and a name spelled twice — the
+  document has fields for each and the core reads them. Whether the skeleton still
+  rebuilds byte for byte against such an atlas is check (b)'s to say, not a
+  refusal's — and measured, it differs for a trim: `gallery/nod` laid with every
+  region turned 90 is written, its poses equal to the document over its own pack, but
+  laid turned **and trimmed** it is refused by (b) on `skeleton.y` and
+  `skeleton.height` alone, because a trimmed region's quad is its kept rectangle and
+  the setup-pose box in the header shrinks with it (`RPK23`). A line the document has **no field for** — `filter` other than
+  `Linear, Linear` (the core samples every page bilinearly), `format`, `repeat`,
+  `split`/`pad`, any other — is refused naming the page or region, because a player
+  reading only the document would draw without it.
+- ⚠️ **A texel is not seen.** Nothing in the three files records one — the atlas
+  states rectangles, not contents — so a page edited after its pack is a page the
+  atlas still describes, and the document written beside it is the same bytes
+  (`RPK24`). The document states placement only.
+
+Measured on `gallery/nod` and `gallery/flex` built `--pack` and reduced to the three
+kinds of file (`RPK20`, `RPK21`): every input file the same bytes after (sha256), the
+document the one file added, its pages `pagesOfAtlas` of the atlas on disk,
+`cli_core.ts` writing the same document byte for byte; posed through the core
+(`poseRawSetup`, `poseRawAnimation`), every pose text-equal to the one the document
+`build` wrote gives, and `render --poser core` drawing the same decoded pixels from the
+kept pages as from the build. Without `--stage-box` the stage is the header's box by
+the rules above — the document differs from `build`'s there, by design, and in the
+order `ingest` writes the animations — and neither the poses nor the frames read it;
+with the stage carried as a box and `--stage-box` given, the stage is the declared one
+too. The document's `images` section names the atlas's page and region for each part,
+where the full repack's names the lifted part in a work directory that no longer
+exists; nothing that poses or draws reads it.
+
 **What each refusal says, and what to change:**
 
 | `rigc repack: …` | exit | change |
@@ -1460,6 +1526,11 @@ rule.)
 | `ingest found N blocker(s) …` / `ingest refused the skeleton: …` | 1 / 2 | the skeleton cannot be read back exactly (§0.3's findings); `--stage` beside a stated box is `ingest`'s refusal |
 | `--out <dir> is not empty …` / `is a file …` | 2 | name a new directory |
 | `repack takes no --<flag>: …` | 2 | drop the flag |
+| `<atlas> cannot be stated by skeleton.model.json as it stands — N reason(s), and nothing was written:` then one line per reason (`page … states filter: …`, `… a line skeleton.model.json has no field for`, `page … is not on disk`, `page … declares size …`, `region … occupies … which leaves the … page`) | 1 | `--keep-pages`: the atlas states something the document cannot carry; repack without `--keep-pages`, or rebuild from the parts |
+| `the build against <atlas> as it stands refused: image "…" resolves to region "…", which the atlas at <atlas> does not have …` | 1 | `--keep-pages`: the skeleton draws a region the atlas does not name — the atlas was edited, or is another build's |
+| `no skeleton.model.json describes these files as they stand, …` then `(b) skeleton.json: …` and the paths | 1 | `--keep-pages`: the skeleton is not what this rigc writes from what it states, so no digest can name it; repack without `--keep-pages` (which writes the rebuild and its pages) |
+| `--out <dir> already holds skeleton.model.json …` | 2 | `--keep-pages`: remove the document to have it rewritten, or name another `--out` |
+| `repack --keep-pages takes no --<flag>: …` / `the atlas … is not in the skeleton's directory …` | 2 | drop the flag; keep the atlas beside the skeleton |
 
 A red gate is `build`'s own report and its `rigc: N assertion(s) failed — nothing
 written`, followed by `rigc repack: nothing was written to <out>; the work directory

package/package.json

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

package/src/cli/repack.ts

@@ -34,6 +34,14 @@
  * `runBuild` that no `finally` sees, from an `exit` listener. A process killed
  * by a signal runs neither and leaves its one directory.
  *
+ * `--keep-pages` (issue #1339) is the same read, refusals-first and stage
+ * rules included, ending in a different build: `build --atlas-in` over the
+ * input atlas, which resolves every part to a region of the pack already on
+ * disk and writes no page, and then the document alone (`keptPagesDocument`).
+ * A flag rather than a verb, because its flow is this one minus the lift and
+ * the pages — a second verb would be a second copy of every refusal above
+ * the build, free to drift from this one.
+ *
  * ⚠️ The lifted parts are not kept: the output is the input's shape, and the
  * parts are recoverable from it at any time by the same lift — keeping a
  * second copy of every texel beside the pages would be two records of one
@@ -41,9 +49,10 @@
  */
 import { parseAtlasText } from '../atlas.ts';
 import { relativeImagesPath } from '../compile.ts';
+import { CompileError } from '../errors.ts';
 import { ingest, INGEST_GUTTERS, IngestError, type IngestFinding, type IngestOptions, IngestSpecRefused, type IngestStage } from '../ingest.ts';
-import { MODEL_DOCUMENT_FILE } from '../model.ts';
-import { atlasRefusals, documentDisagreements, firstLineApart, type InputPage, liftAtlas, polygonOwnedTexels, regionDifferences, REPACK_WORK_PREFIX, RepackError, skeletonDifferences } from '../repack.ts';
+import { MODEL_DOCUMENT_FILE, pagesOfAtlas, spineFileSha256 } from '../model.ts';
+import { atlasRefusals, documentDisagreements, firstLineApart, type InputPage, keptPageRefusals, liftAtlas, polygonOwnedTexels, regionDifferences, REPACK_WORK_PREFIX, RepackError, skeletonDifferences } from '../repack.ts';
 import {
   type BuildGate,
   type BuildReport,
@@ -64,7 +73,7 @@ import {
   writeBuildReport,
 } from './shared.ts';
 import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE } from '../atlas.ts';
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { constants, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 
@@ -78,7 +87,14 @@ import { basename, dirname, join, resolve } from 'node:path';
  */
 export const ACCEPT_FLAG = 'accept-skeleton-differences';
 
-export const REPACK_FLAGS = ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', ACCEPT_FLAG, 'report'] as const;
+/**
+ * The switch that writes `skeleton.model.json` alone, for the atlas and pages
+ * as they stand (issue #1339): `build --atlas-in` over the input atlas in place
+ * of the lift and `build --pack`, nothing written but the document.
+ */
+export const KEEP_PAGES_FLAG = 'keep-pages';
+
+export const REPACK_FLAGS = ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', ACCEPT_FLAG, KEEP_PAGES_FLAG, 'report'] as const;
 
 /** `build`'s flags that `repack` does not take, and why — each refused by name rather than ignored. */
 const BUILD_FLAGS_REFUSED: Readonly<Record<string, string>> = {
@@ -88,7 +104,7 @@ const BUILD_FLAGS_REFUSED: Readonly<Record<string, string>> = {
   images: 'repack lifts the parts off the pages the atlas names; it takes no parts directory',
   'copy-images': 'repack always writes self-contained pages into --out, which is what packing is',
   pack: 'repack always packs; the flag would say nothing',
-  'atlas-in': 'repack MAKES a new pack out of the regions of the old one; --atlas-in would keep the old pack — pass the build itself',
+  'atlas-in': `repack MAKES a new pack out of the regions of the old one; --atlas-in would keep the old pack — pass the build itself, and --${KEEP_PAGES_FLAG} to keep its pack`,
   cut: 'repack takes a build directory, not a cut',
   cuts: 'repack takes a build directory, not a cuts table',
 };
@@ -244,27 +260,87 @@ function pagesLine(inputAtlas: string, inputPages: readonly InputPage[], outAtla
   );
 }
 
+/**
+ * `--keep-pages`'s flags beside the ones it makes meaningless — each refused
+ * by name rather than ignored (issue #1339).
+ */
+const KEEP_PAGES_REFUSED: Readonly<Record<string, string>> = {
+  'page-size': 'nothing is packed, so a page size says nothing',
+  padding: 'nothing is packed, so a padding says nothing',
+  'page-edges': 'nothing is packed, so the page edges say nothing',
+  'pack-shape': 'nothing is packed, so the pack shape says nothing',
+  [ACCEPT_FLAG]:
+    `a document whose spine.sha256 names a skeleton other than the skeleton.json on disk is exactly what --${KEEP_PAGES_FLAG} must not write, and --${KEEP_PAGES_FLAG} writes no skeleton — ` +
+    'repack without it writes the rebuild, its atlas and its pages together',
+};
+
+/** Every flag given that `--keep-pages` makes meaningless, refused by name. */
+function refuseKeepPagesConflicts(flags: Record<string, string>): void {
+  for (const name of Object.keys(KEEP_PAGES_REFUSED).sort()) {
+    if (flags[name] !== undefined) throw new UsageError(`repack --${KEEP_PAGES_FLAG} takes no --${name}: ${KEEP_PAGES_REFUSED[name]}`);
+  }
+}
+
+/**
+ * `--out` under `--keep-pages`: required, a directory or absent, and holding
+ * no `skeleton.model.json` — the one file the command writes is never written
+ * over (issue #1339). Any other file may be there: the input's own directory
+ * is the usual `--out`, since the document belongs beside the pair and pages
+ * it states.
+ */
+function readKeptOut(flags: Record<string, string>): string {
+  if (flags.out === undefined) throw new UsageError(`repack --${KEEP_PAGES_FLAG} needs --out <dir> — the directory ${MODEL_DOCUMENT_FILE} is written into (the build's own directory, to sit beside the pages it states)`);
+  const out = resolve(flags.out);
+  if (existsSync(out)) {
+    if (!statSync(out).isDirectory()) throw new RepackError(`--out ${out} is a file; it takes a directory — nothing was written`, 2);
+    const held = join(out, MODEL_DOCUMENT_FILE);
+    if (existsSync(held)) {
+      throw new RepackError(
+        `--out ${out} already holds ${MODEL_DOCUMENT_FILE} — --${KEEP_PAGES_FLAG} writes that file and nothing else, and never over one: ` +
+          'a document already there is a record somebody kept, and which of the two describes the pages is not this command\'s to decide. ' +
+          `Remove ${held} first to have it rewritten, or name another --out; nothing was written`,
+        2,
+      );
+    }
+  }
+  return out;
+}
+
+/** The name the input atlas is staged under in the work directory: not `skeleton.atlas`, which the build writes beside it. */
+const KEPT_ATLAS = 'kept.atlas';
+
 /**
  * repack — the command body both entries register, with the entry's own gate
  * (`build`'s). `plant` is the selftest's (`RepackPlant`).
  */
 export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, plant?: RepackPlant): void {
   refuseForeignFlags(flags);
+  const keeping = flags[KEEP_PAGES_FLAG] !== undefined;
+  if (keeping) refuseKeepPagesConflicts(flags);
   if (positional.length !== 1) throw new UsageError(`repack takes one path — the build directory, or its skeleton.json — and was given ${positional.length}`);
   // Every flag read before anything is: a typo is a usage error, never a default.
-  const packing: Record<string, string> = {
-    'page-size': String(readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE)),
-    padding: String(readIntFlag(flags, 'padding', DEFAULT_PADDING)),
-    'page-edges': readPageEdges(flags),
-    'pack-shape': readPackShape(flags),
-    profile: readProfile(flags),
-  };
+  const packing: Record<string, string> = keeping
+    ? { profile: readProfile(flags) }
+    : {
+        'page-size': String(readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE)),
+        padding: String(readIntFlag(flags, 'padding', DEFAULT_PADDING)),
+        'page-edges': readPageEdges(flags),
+        'pack-shape': readPackShape(flags),
+        profile: readProfile(flags),
+      };
   const stage = readStageFlag(flags.stage);
-  const out = readOut(flags);
+  const out = keeping ? readKeptOut(flags) : readOut(flags);
   // `--report` (issue #1213): refused inside --out, written on a red gate by the build body and here once --out is written.
   const record = readReportFlag(flags, 'repack', out, gate.supplier);
   const input = resolveBuild(positional[0], flags.atlas);
   if (input.atlas !== 'there') throw new UsageError(input.atlasRefusal);
+  const atlasDir = dirname(input.atlasPath);
+  if (keeping && resolve(atlasDir) !== resolve(dirname(input.skeletonPath))) {
+    throw new UsageError(
+      `repack --${KEEP_PAGES_FLAG}: the atlas ${input.atlasPath} is not in the skeleton's directory ${dirname(input.skeletonPath)} — ` +
+        `${MODEL_DOCUMENT_FILE} sits beside skeleton.json and states the atlas's page names as paths from there, so beside this skeleton they would name pages that are not there`,
+    );
+  }
   const skeletonText = readSkeletonText(input.skeletonPath);
   const atlasText = readFileSync(input.atlasPath, 'utf8');
   const parsed = parseAtlasText(atlasText);
@@ -272,10 +348,15 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
   console.log(`rigc repack ${input.skeletonPath}`);
   console.log(`  ..    atlas  ${input.atlasPath}`);
   console.log(`  ..    out    ${out}`);
-  console.log(`  ..    pack   page-size ${packing['page-size']}, padding ${packing.padding}, page-edges ${packing['page-edges']}, pack-shape ${packing['pack-shape']}, profile ${packing.profile}`);
+  console.log(
+    keeping
+      ? `  ..    keep   --${KEEP_PAGES_FLAG}: the atlas and its pages are kept as they are and ${MODEL_DOCUMENT_FILE} is the one file written; profile ${packing.profile}`
+      : `  ..    pack   page-size ${packing['page-size']}, padding ${packing.padding}, page-edges ${packing['page-edges']}, pack-shape ${packing['pack-shape']}, profile ${packing.profile}`,
+  );
 
-  // What the atlas cannot carry through a repack, all of it, before anything is made.
-  const { refusals, pages } = atlasRefusals(parsed, dirname(input.atlasPath));
+  // What the atlas cannot carry — through a repack, or into the document as it stands — all of it, before anything is made.
+  const lifting = keeping ? null : atlasRefusals(parsed, atlasDir);
+  const refusals = lifting === null ? keptPageRefusals(parsed, atlasDir) : lifting.refusals;
   const modelText = modelTextBeside(input.skeletonPath, skeletonText);
   const disagreement = modelText === undefined ? null : documentDisagreements((parseJsonNamed(modelText, join(dirname(input.skeletonPath), MODEL_DOCUMENT_FILE)) as { pages?: unknown }).pages, parsed);
   if (disagreement !== null) {
@@ -287,7 +368,7 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
   }
   if (refusals.length > 0) {
     throw new RepackError(
-      `${input.atlasPath} cannot be lifted exactly — ${refusals.length} reason(s), and nothing was written:\n${refusals.map((r) => `  ${r}`).join('\n')}`,
+      `${input.atlasPath} ${keeping ? `cannot be stated by ${MODEL_DOCUMENT_FILE} as it stands` : 'cannot be lifted exactly'} — ${refusals.length} reason(s), and nothing was written:\n${refusals.map((r) => `  ${r}`).join('\n')}`,
     );
   }
   console.log(
@@ -312,12 +393,15 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
     const liftDir = join(work, 'lift');
     const specsDir = join(work, 'specs');
     const buildDir = join(work, 'build');
-    const lifted = liftAtlas(pages, liftDir);
-    console.log(
-      `  ..    lift   ${lifted.parts.size} region(s) off ${pages.length} page(s), each named once: ${lifted.turned} turned on its page, ${lifted.trimmed} trimmed of whitespace — ` +
-        'each lifted as the drawing it is (extractRegion)',
-    );
-    if (plant !== undefined) plant(liftDir);
+    // Under --keep-pages nothing is lifted: the build resolves every part against the input atlas (`--atlas-in`), which reads no loose file.
+    const lifted = lifting === null ? null : liftAtlas(lifting.pages, liftDir);
+    if (lifted !== null && lifting !== null) {
+      console.log(
+        `  ..    lift   ${lifted.parts.size} region(s) off ${lifting.pages.length} page(s), each named once: ${lifted.turned} turned on its page, ${lifted.trimmed} trimmed of whitespace — ` +
+          'each lifted as the drawing it is (extractRegion)',
+      );
+      if (plant !== undefined) plant(liftDir);
+    }
 
     let result: { rig: unknown; motion: unknown; findings: IngestFinding[] };
     try {
@@ -342,6 +426,11 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
     writeFileSync(rigPath, `${JSON.stringify(result.rig, null, 2)}\n`);
     writeFileSync(motionPath, `${JSON.stringify(result.motion, null, 2)}\n`);
 
+    if (lifted === null || lifting === null) {
+      keptPagesDocument({ flags, gate, record, input, skeletonText, atlasText, parsed, out, rigPath, motionPath, buildDir, profile: packing.profile });
+      return;
+    }
+
     // (c) `build --pack` through the entry's own gate. It returns only green; a red gate exits from inside it.
     stagedBuild({ rig: rigPath, motion: motionPath, out: buildDir, pack: 'true', ...packing }, gate, record);
 
@@ -373,10 +462,7 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
     } else {
       // Accepted, every path is printed: an accepted difference nobody is shown is the silence the check exists to remove.
       const diff = skeletonDifferences(parseJsonNamed(skeletonText, input.skeletonPath), parseJsonNamed(outSkeleton, join(buildDir, 'skeleton.json')), accepting ? Infinity : SKELETON_DIFFERENCES_SHOWN);
-      const head =
-        diff.total === 0
-          ? `skeleton.json: the rebuild states the same values in other bytes — ${firstLineApart(skeletonText, outSkeleton)}`
-          : `skeleton.json: ${diff.total} place(s) differ from the input`;
+      const head = skeletonHead(diff.total, skeletonText, outSkeleton);
       if (accepting) {
         console.log(`  ..    check  (b) ${head}, accepted by --${ACCEPT_FLAG} — the output's skeleton is this rigc's rebuild, not the input's bytes:`);
         for (const line of diff.lines) console.log(`  ..             ${line}`);
@@ -398,7 +484,7 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
     const staged = readdirSync(buildDir).sort();
     const expected = [...BUILD_TEXTS, ...outPages].sort();
     if (staged.join('\n') !== expected.join('\n')) throw new Error(`internal: the staged build holds [${staged.join(', ')}], not [${expected.join(', ')}]`);
-    console.log(pagesLine(atlasText, pages, outAtlas, buildDir, outPages));
+    console.log(pagesLine(atlasText, lifting.pages, outAtlas, buildDir, outPages));
 
     mkdirSync(out, { recursive: true });
     for (const name of [...outPages, ...BUILD_TEXTS]) {
@@ -412,3 +498,109 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
     process.off('exit', onExit);
   }
 }
+
+/** Check (b)'s head: how many places differ, or — values equal, bytes not — the first line apart. */
+function skeletonHead(total: number, skeletonText: string, outSkeleton: string): string {
+  return total === 0
+    ? `skeleton.json: the rebuild states the same values in other bytes — ${firstLineApart(skeletonText, outSkeleton)}`
+    : `skeleton.json: ${total} place(s) differ from the input`;
+}
+
+/**
+ * `--keep-pages`' tail (issue #1339): `build --atlas-in` over the input atlas
+ * — the build that resolves every part against a pack somebody already made
+ * and writes no page — then the two checks that say the document it spelled
+ * describes the files on disk, then the one write.
+ *
+ * The input atlas and its pages are staged as copies in the build's own
+ * directory, so `--atlas-in`'s re-anchored page names (`relative(outDir, …)`)
+ * are the atlas's own spellings and the document's `pages` names what sits
+ * beside the input skeleton. Nothing under the input is opened for writing.
+ *
+ *   (a) the document's `pages` are `pagesOfAtlas` of the input atlas text,
+ *       field for field — what `build` would have stated had it written this
+ *       atlas itself;
+ *   (b) the rebuilt `skeleton.json` is byte-identical to the input's, so the
+ *       document's `spine.sha256` names the file it will sit beside. There is
+ *       no acceptance here: a digest of a skeleton that is not on disk is the
+ *       document the command exists not to write;
+ *   (c) the gate is green — `runBuild` returns only then.
+ */
+function keptPagesDocument(c: {
+  flags: Record<string, string>;
+  gate: BuildGate;
+  record: BuildReport | null;
+  input: { skeletonPath: string; atlasPath: string };
+  skeletonText: string;
+  atlasText: string;
+  parsed: ReturnType<typeof parseAtlasText>;
+  out: string;
+  rigPath: string;
+  motionPath: string;
+  buildDir: string;
+  profile: string;
+}): void {
+  const atlasDir = dirname(c.input.atlasPath);
+  mkdirSync(c.buildDir, { recursive: true });
+  const keptAtlas = join(c.buildDir, KEPT_ATLAS);
+  writeFileSync(keptAtlas, c.atlasText);
+  for (const page of c.parsed.pages) {
+    const to = join(c.buildDir, page.name);
+    mkdirSync(dirname(to), { recursive: true });
+    copyFileSync(resolve(atlasDir, page.name), to);
+  }
+
+  // (c) `build --atlas-in` through the entry's own gate. It returns only green; a red gate exits from inside it.
+  // A compile refusal names the staged copy of the atlas, so it is restated naming the input's own.
+  try {
+    stagedBuild({ rig: c.rigPath, motion: c.motionPath, out: c.buildDir, 'atlas-in': keptAtlas, profile: c.profile }, c.gate, c.record);
+  } catch (err) {
+    if (!(err instanceof CompileError)) throw err;
+    throw new RepackError(`the build against ${c.input.atlasPath} as it stands refused: ${err.message.split(keptAtlas).join(c.input.atlasPath)} — nothing was written`);
+  }
+
+  const lost: string[] = [];
+  const documentText = readFileSync(join(c.buildDir, MODEL_DOCUMENT_FILE), 'utf8');
+  const doc = parseJsonNamed(documentText, join(c.buildDir, MODEL_DOCUMENT_FILE)) as { pages?: unknown; spine?: { sha256?: unknown } };
+  const stated = skeletonDifferences(pagesOfAtlas(c.atlasText), doc.pages, SKELETON_DIFFERENCES_SHOWN);
+  const regionCount = c.parsed.pages.reduce((n, p) => n + p.regions.length, 0);
+  if (stated.total > 0) {
+    lost.push(
+      `(a) pages: ${stated.total} place(s) where the document would not state the atlas as it stands${stated.total > stated.lines.length ? ` (the first ${stated.lines.length})` : ''} — "the input" is the atlas read, "the rebuild" the document:`,
+      ...stated.lines.map((d) => `  pages${d.startsWith('[') ? '' : '.'}${d}`),
+    );
+  } else {
+    console.log(
+      `  ..    check  (a) pages: the document states the atlas's ${c.parsed.pages.length} page(s) and ${regionCount} region(s) as they stand, field for field (pagesOfAtlas of the input atlas) — ` +
+        'no page and no atlas is written',
+    );
+  }
+  const outSkeleton = readFileSync(join(c.buildDir, 'skeleton.json'), 'utf8');
+  if (outSkeleton === c.skeletonText) {
+    console.log("  ..    check  (b) skeleton.json: byte-identical to the input's — the document's spine.sha256 names the file on disk");
+  } else {
+    const diff = skeletonDifferences(parseJsonNamed(c.skeletonText, c.input.skeletonPath), parseJsonNamed(outSkeleton, join(c.buildDir, 'skeleton.json')), SKELETON_DIFFERENCES_SHOWN);
+    lost.push(
+      `(b) ${skeletonHead(diff.total, c.skeletonText, outSkeleton)}${diff.total > diff.lines.length ? ` (the first ${diff.lines.length})` : ''}:`,
+      ...diff.lines.map((d) => `  ${d}`),
+      `  the document's spine.sha256 would name this rebuild, not the skeleton.json beside it — the one thing --${KEEP_PAGES_FLAG} must not write, so it takes no --${ACCEPT_FLAG}. ` +
+        'repack without it writes the rebuild together with its own atlas and pages, every difference listed under that flag; a build written before 2.2.0, whose header was the stage, differs here in its header box and nowhere else',
+    );
+  }
+  if (lost.length > 0) throw new RepackError(`no ${MODEL_DOCUMENT_FILE} describes these files as they stand, so nothing was written to ${c.out}:\n${lost.map((l) => `  ${l}`).join('\n')}`);
+  if (doc.spine?.sha256 !== spineFileSha256(c.skeletonText)) throw new Error(`internal: the staged ${MODEL_DOCUMENT_FILE}'s spine.sha256 is not the digest of the skeleton.json it was built from`);
+  console.log('  ..    check  (c) gate: green — the report above, on the build against the atlas as it stands');
+
+  mkdirSync(c.out, { recursive: true });
+  // `readKeptOut` refused an existing document; one appearing since is refused here rather than written over.
+  copyFileSync(join(c.buildDir, MODEL_DOCUMENT_FILE), join(c.out, MODEL_DOCUMENT_FILE), constants.COPYFILE_EXCL);
+  console.log(`rigc: wrote ${join(c.out, MODEL_DOCUMENT_FILE)}`);
+  if (c.record !== null) writeBuildReport(c.record);
+  if (resolve(c.out) === resolve(dirname(c.input.skeletonPath))) console.log(c.gate.look(c.out));
+  else {
+    console.log(
+      `rigc: ${MODEL_DOCUMENT_FILE} names the atlas's pages as paths from ${dirname(c.input.skeletonPath)} and the digest of the skeleton.json there; ` +
+        'it is read beside those files',
+    );
+  }
+}

package/src/cli/shared.ts

@@ -125,7 +125,7 @@ export { PACKAGE_ROOT, readPackageMeta, readVersion };
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'accept-skeleton-differences']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry', 'accept-skeleton-differences', 'keep-pages']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -1092,6 +1092,13 @@ const FLAG_MEANINGS: Record<string, string> = {
     'with both values (default: refused naming them). It says only where the two differ, never why — a build written ' +
     'before 2.2.0, whose header box was the stage, differs in those four fields and nowhere else. Region identity and ' +
     'the gate hold exactly as without it; beside an input that needs none, the check line says it accepted nothing',
+  'keep-pages':
+    'write skeleton.model.json alone, for the atlas and pages as they stand: nothing is lifted or packed, the build ' +
+    'resolves every part against the input atlas (build --atlas-in) and the document states that atlas\'s pages and ' +
+    'regions field for field, its spine.sha256 the skeleton.json beside them. Written only when the rebuilt skeleton is ' +
+    'byte-identical to the input\'s and the gate is green; --out may be the build\'s own directory and must not already ' +
+    'hold skeleton.model.json (refused by name, never written over). A page or region line the document has no field ' +
+    'for is refused naming it. Takes none of the packing flags, nor --accept-skeleton-differences',
   'stage-box':
     'the slot whose bounding box carries the stage — what `build` writes for a rig that asks for one ' +
     '(`skeleton.stageBox`). Its four corners are read as the rebuild\'s stage in place of the header\'s box, which ' +
@@ -1308,6 +1315,7 @@ export const COMMANDS: CommandDoc[] = [
       core: {
         usage: [
           `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences] [--report <file>]   (gated without spine-core — see repack --help)`,
+          `rigc repack <dir | skeleton.json> --out <dir> --keep-pages [--atlas <path>] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--report <file>]   (skeleton.model.json alone, pages kept)`,
         ],
         notes: [
           'a packed build repacked from its own output — skeleton.json, skeleton.atlas and the',
@@ -1322,15 +1330,17 @@ export const COMMANDS: CommandDoc[] = [
           'here: the model side over the document and the round trip\'s own rules restated over',
           'the emitted text, A00_ROUNDTRIP_PARSE a SKIP naming spine-core. An atlas the lift',
           'cannot read exactly is refused by name before anything is made: docs/AUTHORING.md',
-          '§0.4 lists what is accepted and what is refused, and why.',
+          '§0.4 lists what is accepted and what is refused, and why. --keep-pages writes',
+          'skeleton.model.json alone, for the atlas and pages as they stand (see repack --help).',
         ],
       },
     },
     spineFormat: true,
     usage: [
       `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences] [--report <file>]`,
+          `rigc repack <dir | skeleton.json> --out <dir> --keep-pages [--atlas <path>] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--report <file>]   (skeleton.model.json alone, pages kept)`,
     ],
-    flags: ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', 'accept-skeleton-differences', 'report'],
+    flags: ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', 'accept-skeleton-differences', 'keep-pages', 'report'],
     overrides: {
       out: {
         value: '<dir>',
@@ -1360,6 +1370,15 @@ export const COMMANDS: CommandDoc[] = [
       'lists what is accepted and what is refused, and why. The stage line says which stage the',
       'rebuild declared and where it was read (--stage, the skeleton.model.json beside the',
       'pair, or the header\'s box).',
+      '--keep-pages writes skeleton.model.json alone, for the atlas and pages as they stand (a',
+      'player that reads the document beside pages already shipped): the same read, the same',
+      'ingest and stage rules, then build --atlas-in over the input atlas, which writes no page.',
+      '(a) the document states the atlas\'s pages and regions field for field; (b) the rebuilt',
+      'skeleton.json is byte-identical to the input\'s, so spine.sha256 names the file on disk',
+      '(no acceptance: a digest of another skeleton is the document it must not write); (c) the',
+      'gate is green. A turned, trimmed, scaled or premultiplied page is stated as it is; a line',
+      'the document has no field for is refused by name. Nothing in the three files records a',
+      'texel, so a page edited after its pack is not seen: the document states placement only.',
     ],
   },
   {

package/src/repack.ts

@@ -40,6 +40,10 @@
  * PNG is missing or not the size the atlas declares, would be lifted from
  * texels the atlas does not describe.
  *
+ * `repack --keep-pages` (issue #1339) asks another question of the same
+ * atlas — not "can it be repacked?" but "can the model document state it as
+ * it stands?" — and `keptPageRefusals` is its list.
+ *
  * 🔒 Every refusal is collected before the first file is written, and the
  * command writes nothing when there is one. Nothing here guesses: there is no
  * "close enough" cut.
@@ -49,8 +53,10 @@
  */
 import { type AtlasPage, type AtlasRegion, extractRegion, footprintCell, packFootprints, pageFootprint, type ParsedAtlas, readEntry } from './atlas.ts';
 import { Plate, readPlate } from '../tools/plate.ts';
+import { MODEL_DOCUMENT_FILE } from './model.ts';
+import { readPngHeader } from './png.ts';
 import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 
 /**
  * A repack refused: an input it cannot lift exactly, a repack that lost
@@ -260,6 +266,99 @@ export function atlasRefusals(parsed: ParsedAtlas, atlasDir: string): { refusals
   return { refusals, pages };
 }
 
+/**
+ * The page lines `skeleton.model.json` states (issue #1339): `size` as the
+ * page's `width`/`height`, `pma`, and `scale` as the number written
+ * (`pagesOfAtlas`). `filter: Linear, Linear` is the one sampling the document
+ * implies by leaving filters out — the core's draw is bilinear on every path
+ * (`src/render.ts`'s header) — so a page stating it states nothing the document
+ * drops.
+ */
+const PAGE_FIELDS_STATED = new Set(['size', 'pma', 'scale']);
+
+/** The region lines the document states: placement, the drawing's own size and turn, and `index`. */
+const REGION_FIELDS_STATED = new Set([...REGION_PLACEMENT_KEYS, 'index']);
+
+/**
+ * Every reason a model document cannot be written for this atlas AS IT STANDS
+ * — `repack --keep-pages`, issue #1339 — in file order, empty when it can be.
+ *
+ * The question is not `atlasRefusals`' (can it be lifted and repacked?) but
+ * whether the document's `pages` section can say everything the atlas says.
+ * So a turned region, a trimmed region, a page `scale:`, `pma: true`, an
+ * `index:` and a name the atlas spells twice are not refused here — the
+ * document states each of them (`ModelPage`, `ModelPageRegion`) and the core
+ * reads them (`./core/uvs.ts`); whether the skeleton still rebuilds byte for
+ * byte against them is the command's check (b), not a guess made here. Every
+ * line the document has no field for is refused naming its page or region: a
+ * player reading only the document would draw without it. The page PNGs are
+ * checked as `atlasRefusals` checks them — on disk, the size the atlas
+ * declares, every rectangle on its page — because the document is written to
+ * sit beside them; and a page name that is not a relative path below the
+ * atlas's directory is refused, because the document's page names are paths
+ * from the directory it sits in.
+ *
+ * ⚠️ What no refusal here can see is a texel. Nothing in the three files
+ * records one — the atlas states rectangles, not contents — so a page edited
+ * after it was packed is a page the atlas still describes, and the document
+ * written beside it is the same bytes. That is a limit of the inputs, stated
+ * rather than papered over.
+ */
+export function keptPageRefusals(parsed: ParsedAtlas, atlasDir: string): string[] {
+  const refusals: string[] = [];
+  if (parsed.regions.length === 0) refusals.push('the atlas names no region, so the document would state no placement');
+  for (const { page, fields, regions } of atlasFields(parsed)) {
+    const segments = page.name.split('/');
+    if (page.name.includes('\\') || isAbsolute(page.name) || segments.some((s) => s === '' || s === '.' || s === '..')) {
+      refusals.push(
+        `page "${page.name}" is not a relative path below the atlas's directory (an empty, "." or ".." segment, a leading "/" or a "\\"), ` +
+          `and ${MODEL_DOCUMENT_FILE}'s page names are paths from the directory it sits in`,
+      );
+    } else {
+      const path = resolve(atlasDir, page.name);
+      if (!existsSync(path)) refusals.push(`page "${page.name}" is not on disk: nothing at ${path}`);
+      else {
+        const header = readPngHeader(path);
+        if (header.info === null) refusals.push(`page "${page.name}" cannot be read as PNG: ${header.problem}`);
+        else if (header.info.width !== page.width || header.info.height !== page.height) {
+          refusals.push(
+            `page "${page.name}" declares size ${page.width}x${page.height} and ${path} is ${header.info.width}x${header.info.height} — ` +
+              'the document would state the declared grid beside a page that is not on it',
+          );
+        }
+      }
+    }
+    for (const entry of fields) {
+      const value = entry.values.join(', ');
+      if (PAGE_FIELDS_STATED.has(entry.key) || (entry.key === 'filter' && value === PAGE_FIELDS_WRITTEN.filter)) continue;
+      refusals.push(
+        entry.key === 'filter'
+          ? `page "${page.name}" states filter: ${value} — ${MODEL_DOCUMENT_FILE} states no filter and the core samples every page bilinearly (filter: ${PAGE_FIELDS_WRITTEN.filter}), so a player reading the document would draw this page otherwise than the atlas asks`
+          : `page "${page.name}" states ${entry.key}: ${value}, a line ${MODEL_DOCUMENT_FILE} has no field for — a player reading only the document would draw without it`,
+      );
+    }
+    regions.forEach(({ raw, fields: regionFields }, k) => {
+      const name = raw.trim();
+      for (const entry of regionFields) {
+        if (entry.key === 'rotate') {
+          if (!ROTATE_VALUES.has(entry.values[0] ?? '')) {
+            refusals.push(`region "${name}" on page "${page.name}" states rotate: ${entry.values.join(', ')}, which is not one of true, false, 0, 90, 180, 270 — the turns the document's degrees can state`);
+          }
+          continue;
+        }
+        if (REGION_FIELDS_STATED.has(entry.key)) continue;
+        refusals.push(
+          `region "${name}" on page "${page.name}" states ${entry.key}: ${entry.values.join(', ')}, a line ${MODEL_DOCUMENT_FILE} has no field for` +
+            `${entry.key === 'split' || entry.key === 'pad' ? ' (a nine-patch region)' : ''} — a player reading only the document would draw without it`,
+        );
+      }
+      const geometry = geometryRefusal(page, page.regions[k]);
+      if (geometry !== null) refusals.push(geometry);
+    });
+  }
+  return refusals;
+}
+
 /** Every region the atlas names, lifted, in file order, by its (trimmed) name. */
 export interface Lift {
   parts: Map<string, Plate>;