rig-c 2.37.0 → 2.39.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.39.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/core/tracks.ts

@@ -88,14 +88,65 @@
  * compounds without it. The state carries nothing from one step to the next
  * but its entries, so a write lasts one pose, as on the single track.
  *
+ * ## Alpha and additive entries (issue #1344)
+ *
+ * An entry carries spine-core's `TrackEntry.alpha` (`MixOptions.alpha`, 1 when
+ * absent, changed while it plays by `setAlpha`) and `TrackEntry.additive`
+ * (`MixOptions.additive`). 4.3.13 has no `MixBlend` on an entry — `additive` is
+ * a boolean fixed before the next apply — so the option carries that name and
+ * that type. What the runtime does with them, ported and measured (`CO52`):
+ *
+ * - **Alpha is a weight, multiplied in**: the current entry applies at
+ *   `alpha · mix`; one mixing out at `from.alpha · fromMix · (1 − mix)`, its
+ *   held timelines at that over `1 − mix · to.alpha`. Track 0 below alpha 1
+ *   leaves the setup-pose shortcut and mixes as a higher track does.
+ * - **Events ignore alpha**: the current entry fires its events at any alpha,
+ *   0 included; an entry mixing out fires none (`eventThreshold` 0, above).
+ * - **Attachments ignore alpha**: `alphaAttachmentThreshold` is 0, so the
+ *   current entry keeps its attachments at any alpha, 0 included;
+ *   `mixAttachmentThreshold` is 0, so an entry mixing out keeps none. The draw
+ *   order stays refused, so `mixDrawOrderThreshold` has nothing to act on.
+ * - **Additive adds what the runtime marks additive** (`Timeline.additive`):
+ *   every bone timeline keying numbers and the deform. On a property a lower
+ *   track or an older entry keyed, the keyed value (a rotation's, a
+ *   translation's, a shear's) is added times alpha — `current + value · alpha`
+ *   — a scale's offset from the setup scale is added, and a deform's offset
+ *   from the setup vertices (weighted: the offsets themselves). From the setup
+ *   pose it is the same as replacing. A rotation is added as it stands, with
+ *   no shortest-angle wrap and no remembered direction (`shortestRotation` is
+ *   `additive || …`). Colour, attachment, inherit and event timelines do not
+ *   read `add`: under an additive entry they apply as under a replacing one.
+ *   Track 0 at alpha 1 with no mix adds nothing — the runtime passes `add`
+ *   false on that shortcut.
+ * - **An additive entry is never held**, and does not hold what it mixes in
+ *   over: its additive timelines take their mode with no `HOLD` bit, and a
+ *   timeline of an entry it replaces is not held for it. Mixing out, an
+ *   additive entry adds at its faded alpha, so its offset fades to nothing.
+ *
+ * `CO52`'s oracle resets bones and slots (`setupPose()`) before every apply,
+ * not the bones alone as `CO51`'s does: on its blend probe a two-colour key at
+ * a partial alpha over track 0's `rgba` mixes the dark colour from what the
+ * previous frame left, which carries in a runtime whose slots are not reset —
+ * measured off with the bones-only reset, equal with the full one. The state
+ * poses every frame from the setup pose, slots included, as it always has.
+ *
+ * Each rejected reading is planted (`TracksPlant`) and read red by `CO52`:
+ * alpha inverted, alpha ignored, additive as replace, an additive rotation
+ * through the remembered direction, an additive entry's attachments as a
+ * plain timeline, the hold blind to the entry mixing in, the holds as if no
+ * entry were additive, and an alpha threshold of one half on attachments.
+ *
  * ## What is left out, by name
  *
  * An animation is refused when it is set or queued if it keys what the state
  * does not mix: a constraint timeline (ik, transform, path, physics, slider),
  * a sequence timeline, the draw order, or a deform of a path attachment (a
  * path's deformed curve reaches the constraints, which this state poses from
- * their records as they stand). Additive entries, `timeScale`, an entry's own
- * `alpha` and the listeners are not offered.
+ * their records as they stand). `timeScale`, `holdPrevious`, `reverse`,
+ * `shortestRotation` on a replacing entry, the thresholds as options, per-pair
+ * mix tables and the listeners are not offered. An additive entry is refused
+ * nothing more: every timeline the state accepts is defined under it (*Alpha
+ * and additive entries* below).
  *
  * ⛔ **A state refused part-way stays refused**, as a live track does: a step
  * is checked before anything moves, and a refusal past that — a construct the
@@ -117,10 +168,18 @@ export interface TracksOptions {
   adjust?: LocalAdjust;
 }
 
-/** How `setAnimation` starts an entry: whether it loops, and over how many seconds the entry it replaces mixes out (0 cuts). */
+/**
+ * How `setAnimation` starts an entry: whether it loops, over how many seconds
+ * the entry it replaces mixes out (0 cuts), and — issue #1344 — how strongly
+ * it applies and whether it adds (the header's *Alpha and additive entries*).
+ */
 export interface MixOptions {
   loop: boolean;
   mixDuration: number;
+  /** `TrackEntry.alpha`: from 0 to 1, multiplied into every timeline's weight; 1 when absent. Changed while the entry plays with `LiveTracks.setAlpha`. */
+  alpha?: number;
+  /** `TrackEntry.additive`: the entry's bone and deform timelines add their keyed values to what the tracks below posed rather than replacing it; `false` when absent. Fixed when the entry is set or queued, as the runtime fixes it before the next apply. */
+  additive?: boolean;
 }
 
 /** How `addAnimation` queues an entry: `MixOptions`, and its delay — at or below 0 relative to when the entry before it completes, above 0 seconds after the entry before starts. */
@@ -136,6 +195,10 @@ export interface TrackEntryView {
   /** The animation time the entry applies at now (`getAnimationTime`): the track time wrapped or held at the duration. */
   animationTime: number;
   duration: number;
+  /** The entry's alpha as it stands (`MixOptions.alpha`, `LiveTracks.setAlpha`). */
+  alpha: number;
+  /** Whether the entry adds (`MixOptions.additive`). */
+  additive: boolean;
 }
 
 /** The live tracks (`openTracks`). */
@@ -148,6 +211,8 @@ export interface LiveTracks {
   addAnimation(track: number, animation: string, options: QueueOptions): void;
   /** Queues a mix out to nothing after the last entry on `track`; `delay` 0 ends the mix when that entry completes. */
   addEmptyAnimation(track: number, mixDuration: number, delay: number): void;
+  /** Sets the alpha of `track`'s current entry (`TrackEntry.alpha`), from the next pose on; an entry it mixes from keeps its own. A track playing nothing is refused. */
+  setAlpha(track: number, alpha: number): void;
   /** Pose 0, the reset (the header's *What a step is*): once, before the first `step`. */
   start(): RawPose;
   /** The next pose: every entry moved by `dt`, a finite time at or above 0. */
@@ -174,6 +239,22 @@ export interface TracksPlant extends TimelinePlant {
   queueDelayNow?: boolean;
   /** An entry mixing out fires its events while the mix is below one half — the reading the issue's brief stated, which the runtime's `eventThreshold` of 0 contradicts. */
   eventsUntilHalfMix?: boolean;
+  /** `CO52`'s, issue #1344: every entry's alpha read as `1 − alpha`. */
+  alphaInverted?: boolean;
+  /** Every entry's alpha read as 1 — the option ignored. */
+  alphaIgnored?: boolean;
+  /** An additive entry applied, and its modes computed, as a replacing one. */
+  additiveAsReplace?: boolean;
+  /** An additive entry's rotations mixed through the remembered direction (`applyRotateTimeline`) as a replacing entry's are, rather than added through the timeline itself. */
+  additiveRotateRemembered?: boolean;
+  /** An additive entry's attachment timelines applied as a plain timeline (`AttachmentTimeline.apply`, no attachment state) rather than under the threshold rule (`applyAttachmentTimeline`). */
+  additiveAttachmentsDirect?: boolean;
+  /** The hold alpha computed as if the entry mixing in were at alpha 1 (`keep = 1 − mix`, not `1 − mix·to.alpha`). */
+  holdIgnoresEntryAlpha?: boolean;
+  /** The holds computed as if no entry were additive: an additive entry's own timelines held, and a timeline held under an additive entry mixing in. */
+  additiveHeld?: boolean;
+  /** An entry applied below alpha one half keeps none of its attachments — a threshold the runtime's `alphaAttachmentThreshold` of 0 does not have. */
+  attachmentsBelowHalfAlpha?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -206,6 +287,11 @@ interface MixAnimation {
 /** The empty animation (`AnimationState.emptyAnimation`): no timeline, duration 0 — one object, so setting it on an entry never applied replaces that entry. */
 const EMPTY: MixAnimation = { name: null, duration: 0, timelines: [], ids: new Set() };
 
+/** `Timeline.additive`: the timelines the runtime adds under an additive entry — every bone timeline that keys numbers, and the deform. Colour, attachment, inherit and event timelines do not read `add`. */
+function addable(tl: MixTimeline): boolean {
+  return tl.type === 'deform' || (tl.type === 'bone' && tl.kind !== 'inherit');
+}
+
 /** The properties a bone timeline keys, spine-core's `propertyIds` by bone name. */
 const BONE_PROPERTIES: Record<BoneTimelineKind, readonly string[]> = {
   rotate: ['rotate'], translate: ['x', 'y'], translatex: ['x'], translatey: ['y'], scale: ['scaleX', 'scaleY'], scalex: ['scaleX'], scaley: ['scaleY'], shear: ['shearX', 'shearY'], shearx: ['shearX'], sheary: ['shearY'], inherit: ['inherit'],
@@ -289,6 +375,10 @@ interface Entry {
   mixTime: number;
   mixDuration: number;
   totalAlpha: number;
+  /** `TrackEntry.alpha`. */
+  alpha: number;
+  /** `TrackEntry.additive`. */
+  additive: boolean;
   keepHold: boolean;
   timelineMode: number[];
   timelineHoldMix: Array<Entry | null | undefined>;
@@ -296,12 +386,12 @@ interface Entry {
   timelinesRotation: number[];
 }
 
-/** A new entry (`AnimationState.trackEntry`): every field the runtime's default; the mix duration 0, `AnimationStateData`'s default mix. */
+/** A new entry (`AnimationState.trackEntry`): every field the runtime's default; the mix duration 0, `AnimationStateData`'s default mix, alpha 1, not additive. */
 function newEntry(anim: MixAnimation, loop: boolean): Entry {
   return {
     anim, loop, previous: null, next: null, mixingFrom: null, mixingTo: null,
     delay: 0, trackTime: 0, trackLast: -1, nextTrackLast: -1, trackEnd: Number.MAX_VALUE,
-    animationLast: -1, nextAnimationLast: -1, mixTime: 0, mixDuration: 0, totalAlpha: 0, keepHold: false,
+    animationLast: -1, nextAnimationLast: -1, mixTime: 0, mixDuration: 0, totalAlpha: 0, alpha: 1, additive: false, keepHold: false,
     timelineMode: [], timelineHoldMix: [], timelinesRotation: [],
   };
 }
@@ -535,6 +625,22 @@ class Mixer {
     return this.plant.mixReversed === true ? 1 - m : m;
   }
 
+  /** `TrackEntry.alpha` — inverted or ignored under the plants. */
+  alphaOf(e: Entry): number {
+    if (this.plant.alphaIgnored === true) return 1;
+    return this.plant.alphaInverted === true ? 1 - e.alpha : e.alpha;
+  }
+
+  /** `TrackEntry.additive` — never under the plant that applies an additive entry as a replacing one. */
+  additiveOf(e: Entry): boolean {
+    return e.additive && this.plant.additiveAsReplace !== true;
+  }
+
+  /** Whether `computeHold` reads an entry as additive — never under the plant that holds as if none were. */
+  private holdsAdditive(e: Entry | null): boolean {
+    return e !== null && this.additiveOf(e) && this.plant.additiveHeld !== true;
+  }
+
   update(delta: number): void {
     const tracks = this.tracks;
     for (let i = 0, n = tracks.length; i < n; i++) {
@@ -612,7 +718,7 @@ class Mixer {
       const current = tracks[i];
       if (current === null || current.delay > 0) continue;
       // Apply mixing from entries first.
-      let alpha = 1;
+      let alpha = this.alphaOf(current);
       if (current.mixingFrom !== null) alpha *= this.applyMixingFrom(current, pose, i);
       else if (current.trackTime >= current.trackEnd && current.next === null) alpha = 0;
       // Apply the current entry.
@@ -621,20 +727,27 @@ class Mixer {
       const timelines = current.anim.timelines;
       const count = timelines.length;
       if (i === 0 && alpha === 1) {
+        // Track 0 at full weight poses from the setup pose and adds nothing, additive or not — the runtime passes `add` false here.
         for (const tl of timelines) {
           if (tl.type === 'attachment') this.applyAttachment(pose, tl, animationTime, SETUP, true);
-          else this.applyTimeline(pose, tl, animationLast, animationTime, true, 1, SETUP, false);
+          else this.applyTimeline(pose, tl, animationLast, animationTime, true, 1, SETUP, false, false);
         }
       } else {
         const modes = current.timelineMode;
-        const retain = alpha >= 0;
-        const firstFrame = current.timelinesRotation.length !== count << 1;
+        // `alphaAttachmentThreshold` is 0: an entry keeps its attachments at any alpha, 0 included.
+        const retain = this.plant.attachmentsBelowHalfAlpha === true ? alpha >= 0.5 : alpha >= 0;
+        const add = this.additiveOf(current);
+        // `shortestRotation = add || …`: an additive entry's rotations go through the timeline itself, never the remembered direction.
+        const shortest = add && this.plant.additiveRotateRemembered !== true;
+        const firstFrame = !shortest && current.timelinesRotation.length !== count << 1;
         if (firstFrame) current.timelinesRotation.length = count << 1;
         timelines.forEach((tl, ii) => {
           const from = this.fromOf(modes[ii] & MODE, i);
-          if (tl.type === 'bone' && tl.kind === 'rotate') this.applyRotate(pose, tl, animationTime, alpha, from, current.timelinesRotation, ii << 1, firstFrame);
-          else if (tl.type === 'attachment') this.applyAttachment(pose, tl, animationTime, from, retain);
-          else this.applyTimeline(pose, tl, animationLast, animationTime, true, alpha, from, false);
+          if (!shortest && tl.type === 'bone' && tl.kind === 'rotate') this.applyRotate(pose, tl, animationTime, alpha, from, current.timelinesRotation, ii << 1, firstFrame);
+          else if (tl.type === 'attachment') {
+            if (add && this.plant.additiveAttachmentsDirect === true) this.applyAttachmentDirect(pose, tl, animationTime, from, false);
+            else this.applyAttachment(pose, tl, animationTime, from, retain);
+          } else this.applyTimeline(pose, tl, animationLast, animationTime, true, alpha, from, false, add);
         });
       }
       if (i === 0) base = animationTime;
@@ -657,15 +770,17 @@ class Mixer {
     const from = to.mixingFrom as Entry;
     const fromMix = from.mixingFrom !== null ? this.applyMixingFrom(from, pose, track) : 1;
     const mix = this.mixOf(to);
-    const a = 1 * fromMix;
-    const keep = 1 - mix * 1;
+    const a = this.alphaOf(from) * fromMix;
+    const keep = 1 - mix * (this.plant.holdIgnoresEntryAlpha === true ? 1 : this.alphaOf(to));
     const alphaMix = a * (1 - mix);
     const alphaHold = keep > 0 ? alphaMix / keep : a;
     const timelines = from.anim.timelines;
     const count = timelines.length;
     const modes = from.timelineMode;
     const holdMix = from.timelineHoldMix;
-    const firstFrame = from.timelinesRotation.length !== count << 1;
+    const add = this.additiveOf(from);
+    const shortest = add && this.plant.additiveRotateRemembered !== true;
+    const firstFrame = !shortest && from.timelinesRotation.length !== count << 1;
     if (firstFrame) from.timelinesRotation.length = count << 1;
     const animationLast = from.animationLast;
     const animationTime = animationTimeOf(from);
@@ -680,10 +795,15 @@ class Mixer {
         alpha = h === null || h === undefined ? alphaHold : alphaHold * (1 - this.mixOf(h));
       } else alpha = alphaMix;
       from.totalAlpha += alpha;
-      if (tl.type === 'bone' && tl.kind === 'rotate') this.applyRotate(pose, tl, animationTime, alpha, mixFrom, from.timelinesRotation, i << 1, firstFrame);
-      else if (tl.type === 'attachment') this.applyAttachment(pose, tl, animationTime, mixFrom, false);
+      if (!shortest && tl.type === 'bone' && tl.kind === 'rotate') this.applyRotate(pose, tl, animationTime, alpha, mixFrom, from.timelinesRotation, i << 1, firstFrame);
+      else if (tl.type === 'attachment') {
+        // `mixAttachmentThreshold` is 0: an entry mixing out never keeps an attachment, whatever its alpha.
+        if (add && this.plant.additiveAttachmentsDirect === true) this.applyAttachmentDirect(pose, tl, animationTime, mixFrom, true);
+        else this.applyAttachment(pose, tl, animationTime, mixFrom, false);
+      }
       // An entry mixing out fires no event: `eventThreshold` is 0 and its events are applied only while the mix is below it.
-      else this.applyTimeline(pose, tl, animationLast, animationTime, fire, alpha, mixFrom, true);
+      // An additive one mixing out adds at the faded alpha — its additive timelines are never held (`computeHold`).
+      else this.applyTimeline(pose, tl, animationLast, animationTime, fire, alpha, mixFrom, true, add);
     });
     from.nextAnimationLast = animationTime;
     from.nextTrackLast = from.trackTime;
@@ -712,16 +832,23 @@ class Mixer {
     const holdMix = entry.timelineHoldMix;
     holdMix.length = 0;
     const to = entry.mixingTo;
+    const add = this.holdsAdditive(entry);
+    const toAdds = this.holdsAdditive(to);
     timelines.forEach((tl, i) => {
       const from = this.propertyFrom(track, tl.ids);
+      // An additive entry's additive timelines are never held, and the entry's keepHold does not reach them.
+      if (add && addable(tl)) {
+        modes[i] = from;
+        return;
+      }
       let mode: number;
-      // Hold if the next entry will overwrite this property.
-      if (to === null || tl.instant || !hasAny(to.anim, tl.ids)) mode = from;
+      // Hold if the next entry will overwrite this property — an additive one adding to it does not.
+      if (to === null || tl.instant || (toAdds && addable(tl)) || !hasAny(to.anim, tl.ids)) mode = from;
       else {
         mode = from | HOLD;
         // Find the next entry that doesn't overwrite this property. Its mix fades out the hold, instead of it ending abruptly.
         for (let next = to.mixingTo; next !== null; next = next.mixingTo) {
-          if (!hasAny(next.anim, tl.ids)) {
+          if ((this.holdsAdditive(next) && addable(tl)) || !hasAny(next.anim, tl.ids)) {
             if (next.mixDuration > 0) holdMix[i] = next;
             break;
           }
@@ -761,12 +888,12 @@ class Mixer {
     return keys[index].values.map((_v, c) => channel(keys, index, c, t));
   }
 
-  /** `Timeline.apply` for every timeline but an attachment's and a rotation mixed below full weight. */
-  private applyTimeline(pose: Pose, tl: MixTimeline, lastTime: number, time: number, fire: boolean, alpha: number, from: number, out: boolean): void {
+  /** `Timeline.apply` for every timeline but an attachment's and a rotation mixed below full weight; `add` is the entry's, read only by the timelines the runtime adds (`addable`). */
+  private applyTimeline(pose: Pose, tl: MixTimeline, lastTime: number, time: number, fire: boolean, alpha: number, from: number, out: boolean, add: boolean): void {
     switch (tl.type) {
-      case 'bone': return this.applyBone(pose, tl, time, alpha, from, out);
+      case 'bone': return this.applyBone(pose, tl, time, alpha, from, out, add);
       case 'colour': return this.applyColour(pose, tl, time, alpha, from);
-      case 'deform': return this.applyDeform(pose, tl, time, alpha, from);
+      case 'deform': return this.applyDeform(pose, tl, time, alpha, from, add);
       case 'events':
         if (fire) pose.events.push(...eventsFired(tl.keys, lastTime, time, rawNumber, time < lastTime));
         return;
@@ -774,7 +901,7 @@ class Mixer {
     }
   }
 
-  private applyBone(pose: Pose, tl: Extract<MixTimeline, { type: 'bone' }>, time: number, alpha: number, from: number, out: boolean): void {
+  private applyBone(pose: Pose, tl: Extract<MixTimeline, { type: 'bone' }>, time: number, alpha: number, from: number, out: boolean, add: boolean): void {
     const bone = pose.bone(tl.bone);
     if (bone === null) return;
     const setup = this.doc.bones[tl.bone];
@@ -797,7 +924,8 @@ class Mixer {
     const relative = (field: 'x' | 'y' | 'rotation' | 'shearX' | 'shearY', i: number): void => {
       const s = setup[field] ?? 0;
       const c = bone[field] ?? 0;
-      bone[field] = v === null ? beforeFirstKey(from, alpha, c, s) : from === SETUP ? s + v[i] * alpha : c + (v[i] + s - c) * alpha;
+      // `getRelativeValue`: from the setup pose the same either way; else the keyed value added, or the value over the setup mixed in.
+      bone[field] = v === null ? beforeFirstKey(from, alpha, c, s) : from === SETUP ? s + v[i] * alpha : c + (add ? v[i] : v[i] + s - c) * alpha;
     };
     const pair = (fx: 'x' | 'shearX', fy: 'y' | 'shearY'): void => {
       const sx = setup[fx] ?? 0;
@@ -815,6 +943,9 @@ class Mixer {
       if (from === SETUP) {
         bone[fx] = sx + v[0] * alpha;
         bone[fy] = sy + v[1] * alpha;
+      } else if (add) {
+        bone[fx] = (bone[fx] ?? 0) + v[0] * alpha;
+        bone[fy] = (bone[fy] ?? 0) + v[1] * alpha;
       } else {
         bone[fx] = (bone[fx] ?? 0) + (sx + v[0] - (bone[fx] ?? 0)) * alpha;
         bone[fy] = (bone[fy] ?? 0) + (sy + v[1] - (bone[fy] ?? 0)) * alpha;
@@ -823,7 +954,7 @@ class Mixer {
     const scale = (field: 'scaleX' | 'scaleY', i: number): void => {
       const s = setup[field] ?? 1;
       const c = bone[field] ?? 1;
-      bone[field] = v === null ? beforeFirstKey(from, alpha, c, s) : scaleValue(v[i] * s, alpha, from, out, c, s);
+      bone[field] = v === null ? beforeFirstKey(from, alpha, c, s) : scaleValue(v[i] * s, alpha, from, out, add, c, s);
     };
     switch (tl.kind) {
       case 'rotate': relative('rotation', 0); break;
@@ -845,8 +976,8 @@ class Mixer {
             bone.scaleY = (bone.scaleY ?? 1) + (sy - (bone.scaleY ?? 1)) * alpha;
           }
         } else {
-          bone.scaleX = scaleValue(v[0] * (setup.scaleX ?? 1), alpha, from, out, bone.scaleX ?? 1, setup.scaleX ?? 1);
-          bone.scaleY = scaleValue(v[1] * (setup.scaleY ?? 1), alpha, from, out, bone.scaleY ?? 1, setup.scaleY ?? 1);
+          bone.scaleX = scaleValue(v[0] * (setup.scaleX ?? 1), alpha, from, out, add, bone.scaleX ?? 1, setup.scaleX ?? 1);
+          bone.scaleY = scaleValue(v[1] * (setup.scaleY ?? 1), alpha, from, out, add, bone.scaleY ?? 1, setup.scaleY ?? 1);
         }
         break;
       case 'scalex': scale('scaleX', 0); break;
@@ -858,7 +989,7 @@ class Mixer {
   private applyRotate(pose: Pose, tl: Extract<MixTimeline, { type: 'bone' }>, time: number, alpha: number, from: number, rotations: number[], i: number, firstFrame: boolean): void {
     if (firstFrame) rotations[i] = 0;
     if (alpha === 1) {
-      this.applyBone(pose, tl, time, 1, from, false);
+      this.applyBone(pose, tl, time, 1, from, false, false);
       return;
     }
     const bone = pose.bone(tl.bone);
@@ -934,6 +1065,15 @@ class Mixer {
     else if (!setup) s.attachmentState = ATTACH_SETUP;
   }
 
+  /** `AttachmentTimeline.apply` — the plain timeline, writing no attachment state: only `additiveAttachmentsDirect` reaches it, the reading `CO52` rejects. */
+  private applyAttachmentDirect(pose: Pose, tl: Extract<MixTimeline, { type: 'attachment' }>, time: number, from: number, out: boolean): void {
+    if (!pose.slotLive(tl.slot)) return;
+    const index = (this.plant.search ?? keyIndexAt)(tl.keys, time);
+    if (out || index < 0) {
+      if (from !== CURRENT) pose.setAttachment(tl.slot, this.doc.slots[tl.slot].setup);
+    } else pose.setAttachment(tl.slot, tl.keys[index].name ?? null);
+  }
+
   private applyColour(pose: Pose, tl: Extract<MixTimeline, { type: 'colour' }>, time: number, alpha: number, from: number): void {
     if (!pose.slotLive(tl.slot)) return;
     const slot = this.doc.slots[tl.slot];
@@ -1030,7 +1170,7 @@ class Mixer {
   }
 
   /** `DeformTimeline.apply`: every live slot showing the record the timeline keys, its deform array mixed. */
-  private applyDeform(pose: Pose, tl: Extract<MixTimeline, { type: 'deform' }>, time: number, alpha: number, from: number): void {
+  private applyDeform(pose: Pose, tl: Extract<MixTimeline, { type: 'deform' }>, time: number, alpha: number, from: number, add: boolean): void {
     const keys = tl.timeline.deform;
     if (keys === null) return;
     pose.slots.forEach((s, k) => {
@@ -1061,13 +1201,27 @@ class Mixer {
         }
         return;
       }
-      // `applyToSlot`, never additive.
-      if (alpha === 1) s.deform = [...target];
-      else if (mixFrom === SETUP) {
+      // `applyToSlot`: added only over a deform already there — over none it is the setup pose's branch, additive or not.
+      const fromSetup = mixFrom === SETUP;
+      if (alpha === 1) {
+        if (add && !fromSetup) {
+          const current = s.deform as number[];
+          if (!vertices.weighted) {
+            const setup = setupArray(vertices);
+            s.deform = current.map((c, i) => c + (target[i] - setup[i]));
+          } else s.deform = current.map((c, i) => c + target[i]);
+        } else s.deform = [...target];
+      } else if (fromSetup) {
         if (!vertices.weighted) {
           const setup = setupArray(vertices);
           s.deform = target.map((v, i) => setup[i] + (v - setup[i]) * alpha);
         } else s.deform = target.map((v) => v * alpha);
+      } else if (add) {
+        const current = s.deform as number[];
+        if (!vertices.weighted) {
+          const setup = setupArray(vertices);
+          s.deform = current.map((c, i) => c + (target[i] - setup[i]) * alpha);
+        } else s.deform = current.map((c, i) => c + target[i] * alpha);
       } else {
         const current = s.deform as number[];
         s.deform = current.map((c, i) => c + (target[i] - c) * alpha);
@@ -1083,10 +1237,11 @@ function beforeFirstKey(from: number, alpha: number, current: number, setup: num
   return current;
 }
 
-/** `CurveTimeline1.getScaleValue` past the first key, `value` the curve times the setup scale, never additive. */
-function scaleValue(value: number, alpha: number, from: number, out: boolean, current: number, setup: number): number {
-  if (alpha === 1) return value;
+/** `CurveTimeline1.getScaleValue` past the first key, `value` the curve times the setup scale; added, its offset from the setup scale is added to the base. */
+function scaleValue(value: number, alpha: number, from: number, out: boolean, add: boolean, current: number, setup: number): number {
+  if (alpha === 1 && !add) return value;
   let base = from === SETUP ? setup : current;
+  if (add) return base + (value - setup) * alpha;
   if (out) return base + (Math.abs(value) * Math.sign(base) - base) * alpha;
   base = Math.abs(base) * Math.sign(value);
   return base + (value - base) * alpha;
@@ -1117,6 +1272,20 @@ function loopOf(options: MixOptions | undefined, call: string): boolean {
   return options.loop;
 }
 
+/** An alpha: a finite number from 0 to 1, or the call refused naming it — the runtime clamps nothing and defines no weight outside it. */
+function alphaValue(v: unknown, what: string, call: string): number {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 1) throw new CoreInputError(`the live tracks' ${call} ${what} is ${typeof v === 'number' ? String(v) : JSON.stringify(v)}, not a number from 0 to 1`);
+  return v;
+}
+
+/** `options.alpha` and `options.additive`: 1 and `false` when absent, else refused by name where they are not a weight and a boolean. */
+function blendOf(options: MixOptions, call: string): { alpha: number; additive: boolean } {
+  const alpha = options.alpha === undefined ? 1 : alphaValue(options.alpha, 'options.alpha', call);
+  const additive: unknown = options.additive;
+  if (additive !== undefined && typeof additive !== 'boolean') throw new CoreInputError(`the live tracks' ${call} options.additive is ${JSON.stringify(additive)}, not true or false — an entry adds or it does not`);
+  return { alpha, additive: additive === true };
+}
+
 function delayOf(v: number, call: string): number {
   if (typeof v !== 'number' || !Number.isFinite(v)) throw new CoreInputError(`the live tracks' ${call} delay is ${String(v)}, not a finite number`);
   return v;
@@ -1163,8 +1332,11 @@ class Tracks implements LiveTracks {
     const i = trackIndex(track, 'setAnimation');
     const loop = loopOf(options, 'setAnimation');
     const mix = finiteAtOrAbove0(options.mixDuration, 'mixDuration', 'setAnimation');
+    const blend = blendOf(options, 'setAnimation');
     const entry = this.mixer.setAnimation(i, this.mixer.animation(animation), loop);
     entry.mixDuration = mix;
+    entry.alpha = blend.alpha;
+    entry.additive = blend.additive;
   }
 
   setEmptyAnimation(track: number, mixDuration: number): void {
@@ -1182,8 +1354,11 @@ class Tracks implements LiveTracks {
     const loop = loopOf(options, 'addAnimation');
     const mix = finiteAtOrAbove0(options.mixDuration, 'mixDuration', 'addAnimation');
     const delay = delayOf(options.delay, 'addAnimation');
+    const blend = blendOf(options, 'addAnimation');
     const entry = this.mixer.addAnimation(i, this.mixer.animation(animation), loop, delay);
     this.mixer.setMixDuration(entry, mix, delay);
+    entry.alpha = blend.alpha;
+    entry.additive = blend.additive;
   }
 
   addEmptyAnimation(track: number, mixDuration: number, delay: number): void {
@@ -1197,10 +1372,19 @@ class Tracks implements LiveTracks {
     entry.trackEnd = mix;
   }
 
+  setAlpha(track: number, alpha: number): void {
+    this.live('setAlpha');
+    const i = trackIndex(track, 'setAlpha');
+    const a = alphaValue(alpha, 'alpha', 'setAlpha');
+    const e = this.mixer.tracks[i] ?? null;
+    if (e === null) throw new CoreInputError(`the live tracks' setAlpha names track ${i}, which plays nothing — there is no entry to weigh`);
+    e.alpha = a;
+  }
+
   current(track: number): TrackEntryView | null {
     const e = this.mixer.tracks[trackIndex(track, 'current')] ?? null;
     if (e === null) return null;
-    return { animation: e.anim.name, loop: e.loop, trackTime: e.trackTime, animationTime: animationTimeOf(e), duration: e.anim.duration };
+    return { animation: e.anim.name, loop: e.loop, trackTime: e.trackTime, animationTime: animationTimeOf(e), duration: e.anim.duration, alpha: e.alpha, additive: e.additive };
   }
 
   start(): RawPose {

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>;