spine-rigc 1.6.2 → 1.7.0

package/src/core/world.ts

@@ -3,9 +3,23 @@
  * the compiled model's bones (issue #925). Written from what a bone's fields
  * mean and from measurement against the runtime's pose dump
  * (`tools/pose_oracle.ts dump`, spine-core 4.3.13), and held to it by the core
- * suite's equivalence controls; it shares no code with `src/transform.ts`,
- * which is the compiler's arithmetic and stays frozen so that no emitted byte
- * moves.
+ * suite's equivalence controls.
+ *
+ * ⭐ **The compiler's setup transforms are this evaluator too** (issue #1015).
+ * `src/transform.ts` held a second evaluator of its own until then, and the
+ * two differed in exactly three places, none of them a different matrix: the
+ * degree factor (`Math.PI / 180` there, the runtime's 3.1415927 here), the
+ * frame of a bone with scale 1 and no shear (`[cos, −sin, sin, cos]` of the
+ * rotation there, the y column at `rotation + 90` here), and how a radian
+ * angle is turned into degrees (divided by the degree factor there,
+ * multiplied by `180 / pi` here). Every byte rigc emits was computed with the
+ * compiler's three, so they are a parameter of this evaluator
+ * (`WorldArithmetic`) rather than a rewrite of the emitter's numbers: the
+ * compiler passes its own and the posing core passes none, which is
+ * `RUNTIME_ARITHMETIC`, the measured choices below. Measured with the
+ * compiler's degree factor and frame taken from here instead: 2 of 19
+ * recipes moved, by at most 4e-5 (issue #1015's report) — whether the
+ * compiler should bind with the runtime's constant is its own question.
  *
  * ## What each measured choice is
  *
@@ -99,6 +113,28 @@ export const RUNTIME_DEG = 180 / RUNTIME_PI;
 /** A parent x axis whose squared length is at most this is collapsed for `noRotationOrReflection` (issue #979): `1e-5` squared, as measured — see the header. */
 export const COLLAPSED_X_AXIS_SQ = 0.00001 * 0.00001;
 
+/**
+ * The three places an evaluator's arithmetic may differ in the last bit while
+ * computing the same matrix (issue #1015) — see the header. The core poses with
+ * `RUNTIME_ARITHMETIC`; `src/transform.ts` passes the compiler's, so that what
+ * rigc has always emitted is what it still emits.
+ */
+export interface WorldArithmetic {
+  /** Degrees to radians: every angle is multiplied by it. */
+  radiansPerDegree: number;
+  /** Radians to degrees — the angle `noRotationOrReflection` takes off a parent's axis. */
+  degreesOf: (radians: number) => number;
+  /** A bone with scale 1 and no shear takes `[cos r, −sin r, sin r, cos r]` instead of the y column at `r + 90`; the general frame everywhere else. */
+  rotationOnlyFrame: boolean;
+}
+
+/** The runtime's arithmetic, as measured (the header's three choices): what the core poses with. */
+export const RUNTIME_ARITHMETIC: WorldArithmetic = {
+  radiansPerDegree: RAD,
+  degreesOf: (radians) => radians * RUNTIME_DEG,
+  rotationOnlyFrame: false,
+};
+
 /** One bone's world transform: the matrix `[a b; c d]` and the origin, y up. */
 export interface CoreWorld {
   a: number;
@@ -114,16 +150,27 @@ export type CoreInheritMode = 'normal' | 'onlyTranslation' | 'noRotationOrReflec
 
 export type M2 = [number, number, number, number];
 
-/** What computes a child's world matrix from its mode, its parent's world and its own fields. */
-export type InheritComputation = (mode: CoreInheritMode, parent: CoreWorld, bone: ModelBone) => M2;
+/** What computes a child's world matrix from its mode, its parent's world, its own fields and the arithmetic in force. */
+export type InheritComputation = (mode: CoreInheritMode, parent: CoreWorld, bone: ModelBone, arithmetic: WorldArithmetic) => M2;
 
 /** The matrix of a rotation, shears and scales, in the column form the header states. */
-function frame(rotation: number, shearX: number, shearY: number, scaleX: number, scaleY: number): M2 {
-  const xAngle = (rotation + shearX) * RAD;
-  const yAngle = (rotation + 90 + shearY) * RAD;
+function frame(rotation: number, shearX: number, shearY: number, scaleX: number, scaleY: number, rad: number = RAD): M2 {
+  const xAngle = (rotation + shearX) * rad;
+  const yAngle = (rotation + 90 + shearY) * rad;
   return [Math.cos(xAngle) * scaleX, Math.cos(yAngle) * scaleY, Math.sin(xAngle) * scaleX, Math.sin(yAngle) * scaleY];
 }
 
+/** A bone's own frame — a root's matrix, and the local factor of `normal` and `onlyTranslation` — under `arithmetic`. */
+function localFrame(arithmetic: WorldArithmetic, rotation: number, shearX: number, shearY: number, scaleX: number, scaleY: number): M2 {
+  const rad = arithmetic.radiansPerDegree;
+  if (arithmetic.rotationOnlyFrame && scaleX === 1 && scaleY === 1 && shearX === 0 && shearY === 0) {
+    const cos = Math.cos(rotation * rad);
+    const sin = Math.sin(rotation * rad);
+    return [cos, -sin, sin, cos];
+  }
+  return frame(rotation, shearX, shearY, scaleX, scaleY, rad);
+}
+
 function times(p: M2, q: M2): M2 {
   return [p[0] * q[0] + p[1] * q[2], p[0] * q[1] + p[1] * q[3], p[2] * q[0] + p[3] * q[2], p[2] * q[1] + p[3] * q[3]];
 }
@@ -135,8 +182,8 @@ function times(p: M2, q: M2): M2 {
  * which builds the frame to read the bone's columns in from the rotation it
  * has just read, through this same arithmetic (issue #966).
  */
-export function noScaleDirection(p: M2, rotation: number): [number, number] {
-  const r = rotation * RAD;
+export function noScaleDirection(p: M2, rotation: number, rad: number = RAD): [number, number] {
+  const r = rotation * rad;
   const cos = Math.cos(r);
   const sin = Math.sin(r);
   const ux = p[0] * cos + p[1] * sin;
@@ -146,19 +193,20 @@ export function noScaleDirection(p: M2, rotation: number): [number, number] {
   return [ux * inverse, uy * inverse];
 }
 
-/** The world matrix of a child under `parent` in `mode`. */
-function modeMatrix(mode: CoreInheritMode, parent: CoreWorld, bone: ModelBone): M2 {
+/** The world matrix of a child under `parent` in `mode`, under `arithmetic` (the runtime's unless a caller passes its own). */
+function modeMatrix(mode: CoreInheritMode, parent: CoreWorld, bone: ModelBone, arithmetic: WorldArithmetic = RUNTIME_ARITHMETIC): M2 {
   const rotation = bone.rotation ?? 0;
   const shearX = bone.shearX ?? 0;
   const shearY = bone.shearY ?? 0;
   const scaleX = bone.scaleX ?? 1;
   const scaleY = bone.scaleY ?? 1;
+  const rad = arithmetic.radiansPerDegree;
   const p: M2 = [parent.a, parent.b, parent.c, parent.d];
   switch (mode) {
     case 'normal':
-      return times(p, frame(rotation, shearX, shearY, scaleX, scaleY));
+      return times(p, localFrame(arithmetic, rotation, shearX, shearY, scaleX, scaleY));
     case 'onlyTranslation':
-      return frame(rotation, shearX, shearY, scaleX, scaleY);
+      return localFrame(arithmetic, rotation, shearX, shearY, scaleX, scaleY);
     case 'noRotationOrReflection': {
       const xLengthSq = p[0] * p[0] + p[2] * p[2];
       let conformal: M2;
@@ -166,23 +214,23 @@ function modeMatrix(mode: CoreInheritMode, parent: CoreWorld, bone: ModelBone):
       if (xLengthSq > COLLAPSED_X_AXIS_SQ) {
         const k = Math.abs(p[0] * p[3] - p[1] * p[2]) / xLengthSq;
         conformal = [p[0], -p[2] * k, p[2], p[0] * k];
-        r = rotation - Math.atan2(p[2], p[0]) * RUNTIME_DEG;
+        r = rotation - arithmetic.degreesOf(Math.atan2(p[2], p[0]));
       } else {
         // A collapsed x axis (issue #979): the parent's y column with its x component negated, and the rotation less 90 plus the y column's angle — see the header.
         conformal = [0, -p[1], 0, p[3]];
-        r = rotation - 90 + Math.atan2(p[3], p[1]) * RUNTIME_DEG;
+        r = rotation - 90 + arithmetic.degreesOf(Math.atan2(p[3], p[1]));
       }
       // The y angle adds the shear before the right angle here, unlike `frame` (issue #966): `(r + 90 + shearY)` reads last-bit off on 81 of 205 sheared or scaled bones at a 1e9 amplifier, `(r + shearY + 90)` on none; `r = rotation − parentAngle` taken first (adding the shear before the parent's angle is taken off reads 102 of 205 off).
-      const xAngle = (r + shearX) * RAD;
-      const yAngle = (r + shearY + 90) * RAD;
+      const xAngle = (r + shearX) * rad;
+      const yAngle = (r + shearY + 90) * rad;
       return times(conformal, [Math.cos(xAngle) * scaleX, Math.cos(yAngle) * scaleY, Math.sin(xAngle) * scaleX, Math.sin(yAngle) * scaleY]);
     }
     case 'noScale':
     case 'noScaleOrReflection': {
-      const [ux, uy] = noScaleDirection(p, rotation);
+      const [ux, uy] = noScaleDirection(p, rotation, rad);
       const flip = mode === 'noScale' && p[0] * p[3] - p[1] * p[2] < 0 ? -1 : 1;
       const turned: M2 = [ux, -uy * flip, uy, ux * flip];
-      return times(turned, frame(0, shearX, shearY, scaleX, scaleY));
+      return times(turned, frame(0, shearX, shearY, scaleX, scaleY, rad));
     }
   }
 }
@@ -205,9 +253,16 @@ function modeOf(bone: ModelBone): CoreInheritMode {
  * world as a skeleton is created — and a bone under it, active or not, is
  * posed from those zeros like any child. `inherit` replaces the mode
  * computation — the core suite's plant passes a copy with one mode's sign
- * flipped, and nothing else does.
+ * flipped, and nothing else does. `arithmetic` is the runtime's unless a
+ * caller states its own: `src/transform.ts` passes the compiler's (issue
+ * #1015), and no posing path does.
  */
-export function worldTransforms(bones: readonly ModelBone[], active: ReadonlySet<string> | null = null, inherit: InheritComputation = modeMatrix): Map<string, CoreWorld> {
+export function worldTransforms(
+  bones: readonly ModelBone[],
+  active: ReadonlySet<string> | null = null,
+  inherit: InheritComputation = modeMatrix,
+  arithmetic: WorldArithmetic = RUNTIME_ARITHMETIC,
+): Map<string, CoreWorld> {
   const out = new Map<string, CoreWorld>();
   for (const bone of bones) {
     if (active !== null && !active.has(bone.name)) {
@@ -217,13 +272,13 @@ export function worldTransforms(bones: readonly ModelBone[], active: ReadonlySet
     const x = bone.x ?? 0;
     const y = bone.y ?? 0;
     if (bone.parent === undefined) {
-      const [a, b, c, d] = frame(bone.rotation ?? 0, bone.shearX ?? 0, bone.shearY ?? 0, bone.scaleX ?? 1, bone.scaleY ?? 1);
+      const [a, b, c, d] = localFrame(arithmetic, bone.rotation ?? 0, bone.shearX ?? 0, bone.shearY ?? 0, bone.scaleX ?? 1, bone.scaleY ?? 1);
       out.set(bone.name, { a, b, c, d, worldX: x, worldY: y });
       continue;
     }
     const parent = out.get(bone.parent);
     if (parent === undefined) throw new Error(`bone "${bone.name}": parent "${bone.parent}" is not posed before it`);
-    const [a, b, c, d] = inherit(modeOf(bone), parent, bone);
+    const [a, b, c, d] = inherit(modeOf(bone), parent, bone, arithmetic);
     out.set(bone.name, { a, b, c, d, worldX: parent.a * x + parent.b * y + parent.worldX, worldY: parent.c * x + parent.d * y + parent.worldY });
   }
   return out;

package/src/deformmeasure.ts

@@ -1610,9 +1610,12 @@ interface PoseOfFrame {
 /**
  * What `Slider.update` stores in `SliderPose.time` for a wanted animation time.
  *
- * The two clamps at the end of its bone branch, transcribed, because the
- * verification below compares against what the runtime STORED and not against
- * what was asked for. ⚠️ `loop` on a zero-length animation gives NaN here exactly
+ * On a slider driven by a bone: the time wrapped into the animation under
+ * `loop`, else held at 0 or above. Not assumed — `poseDial`'s step 3 reads
+ * `SliderPose.time` off the skeleton each time it poses a dial and compares
+ * it with this, and a disagreement is reported, never absorbed. It is stated at all because that
+ * verification compares against what the runtime STORED and not against what
+ * was asked for. ⚠️ `loop` on a zero-length animation gives NaN here exactly
  * as it does there, which is `A37_SLIDER_CONSTRAINT_EFFECTIVE`'s refusal.
  */
 function sliderTimeFor(slider: SliderData, time: number): number {

package/src/emit.ts

@@ -91,7 +91,24 @@ export interface CopyImagesResult {
  */
 export function copyAtlasPages(atlasText: string, outDir: string): CopyImagesResult {
   mkdirSync(outDir, { recursive: true });
+  const planned = plannedPageCopies(atlasText, outDir);
+  for (const page of planned.pages) {
+    const source = resolve(outDir, page.from);
+    const destination = join(outDir, page.to);
+    if (source !== resolve(destination)) copyFileSync(source, destination);
+  }
+  return planned;
+}
 
+/**
+ * What `copyAtlasPages` will do, without doing it: the rewritten atlas text
+ * and each page's source and copy name, from the text and `outDir` alone — no
+ * file is read or written (issue #1016). `build --copy-images` spells the
+ * model document from this text BEFORE the gate, because the document states
+ * where each region sits on its page (`pages`) and the copy renames every
+ * page; `copyAtlasPages` returns exactly this, after copying.
+ */
+export function plannedPageCopies(atlasText: string, outDir: string): CopyImagesResult {
   const parsed = parseAtlasText(atlasText);
   const claimedBy = new Map<string, string>(); // destination filename -> absolute source holding it
   const pages: CopiedPage[] = [];
@@ -113,11 +130,5 @@ export function copyAtlasPages(atlasText: string, outDir: string): CopyImagesRes
     pages.push({ from: page.name, to: name, regions: page.regions.length });
   }
 
-  for (const page of pages) {
-    const source = resolve(outDir, page.from);
-    const destination = join(outDir, page.to);
-    if (source !== resolve(destination)) copyFileSync(source, destination);
-  }
-
   return { atlasText: rewritePageNames(parsed, (_name, index) => pages[index].to), pages };
 }

package/src/ingest.ts

@@ -52,6 +52,7 @@ import {
   SPINE_VERSION,
 } from './compile.ts';
 import { CompileError } from './errors.ts';
+import { physicsDrives } from './core/constraints_physics.ts';
 import { CHANNELS_BY_KIND } from './timelines.ts';
 import {
   LEGACY_BONE_INHERIT_KEY,
@@ -303,13 +304,14 @@ const CONSTRAINT_FIELDS: Record<string, string[]> = {
  * The physics constraints that drive nothing, by name, each with the component
  * fields it DOES state — every one of them at most 0 (issue #731).
  *
- * 🔑 The runtime's own predicate, not a reading of it: `PhysicsConstraint.update`
- * decides what it applies with `this.data.x > 0` and its four siblings
- * (`PhysicsConstraint.js:112`) and nothing else, so a constraint with none of
- * `PHYSICS_COMPONENTS` above 0 moves no bone. `build` refuses exactly that shape
- * by name — `A23_PHYSICS_CONSTRAINT_EFFECTIVE` at the gate — so carrying one
- * through made the decompiled spec of a file an editor exports unbuildable as a
- * whole, over a constraint that did nothing in it.
+ * 🔑 The question is the core's `physicsDrives` (`src/core/constraints_physics.ts`,
+ * issue #1015): a component above 0 drives its part of the step and nothing
+ * else does, so a constraint with none of `PHYSICS_COMPONENTS` above 0 moves no
+ * bone — `PhysicsConstraint.update` applies a part only on that test
+ * (`PhysicsConstraint.js:112`). An unstated component is the parser's 0. `build`
+ * refuses exactly that shape by name — `A23_PHYSICS_CONSTRAINT_EFFECTIVE` at the
+ * gate — so carrying one through made the decompiled spec of a file an editor
+ * exports unbuildable as a whole, over a constraint that did nothing in it.
  *
  * ⚠️ A component that is present and NOT a number is not inert: the parser takes
  * it as written and `"0.5" > 0` is true in the runtime's comparison, so such a
@@ -321,7 +323,10 @@ function inertPhysics(root: JsonObject): Map<string, string[]> {
     const constraint = obj(raw);
     if (constraint.type !== 'physics' || typeof constraint.name !== 'string') continue;
     const stated = PHYSICS_COMPONENTS.filter((field) => constraint[field] !== undefined);
-    if (!stated.every((field) => typeof constraint[field] === 'number' && !((constraint[field] as number) > 0))) continue;
+    if (!stated.every((field) => typeof constraint[field] === 'number')) continue;
+    const value = (field: (typeof PHYSICS_COMPONENTS)[number]): number => (constraint[field] === undefined ? 0 : (constraint[field] as number));
+    const drives = physicsDrives({ x: value('x'), y: value('y'), rotate: value('rotate'), shearX: value('shearX'), scaleX: value('scaleX') });
+    if (drives.x || drives.y || drives.rotateOrShearX || drives.scaleX) continue;
     out.set(
       constraint.name,
       stated.map((field) => `${field} ${String(constraint[field])}`),
@@ -1305,9 +1310,9 @@ function ingestAttachment(
   const type = att.type === undefined ? 'region' : String(att.type);
   const out: JsonObject = {};
 
-  // A LINKED mesh, in either of the format's two spellings. The test is the
-  // parser's own — one branch for `mesh` and `linkedmesh`, and a truthy `source`
-  // decides (`SkeletonJson.js:568-569`, `:582`) — so `type: "mesh"` carrying
+  // A LINKED mesh, in either of the format's two spellings. The format decides
+  // it — one branch of the reader for `mesh` and `linkedmesh`, and a truthy
+  // `source` decides (`SkeletonJson.js:568-569`, `:582`) — so `type: "mesh"` carrying
   // `source` inverts to a link, and a `linkedmesh` with none does NOT: that map
   // is read as an ordinary mesh, whose `uvs` it does not have, and the parser
   // throws on it. Reading the second as a link would be this module inventing a
@@ -1327,8 +1332,8 @@ function ingestAttachment(
     // `buildRigRegion` writes `path` when the image basename differs from the
     // name the attachment carries — its stated `name`, else the placeholder —
     // so naming the image after the region this attachment RESOLVES
-    // (`path ?? name ?? placeholder`, the parser's own defaults at
-    // `SkeletonJson.js:526`, `:529`, `:560`) reproduces the same `path`
+    // (`path ?? name ?? placeholder`, the defaults the format's reader applies
+    // at `SkeletonJson.js:526`, `:529`, `:560`) reproduces the same `path`
     // decision AND the same atlas region name.
     if (opts.art === 'loose') {
       const region = att.path ?? (typeof att.name === 'string' ? att.name : placeholder);

package/src/keyorder.ts

@@ -288,8 +288,8 @@ export function inEditorKeyOrder<T extends object>(skeleton: T, table: KeyOrderT
 // ## Why this is a table and not a parse
 //
 // The parser is the only authority on what a default is, and this table is
-// not a second one: it is a transcription the selftest holds to the parser row
-// by row (`S103` on the in-tree builds, `IG82` on the corpus) by loading an
+// not a second one: it is a table of the parser's readings that the selftest
+// holds to the parser row by row (`S103` on the in-tree builds, `IG82` on the corpus) by loading an
 // object of each kind with the key at the row's value and without it, and
 // comparing everything `SkeletonData` holds — and then one float32 step off,
 // which must differ. It cannot BE a parse: `compile.ts` must not link the

package/src/model.ts

@@ -82,10 +82,12 @@
  * they are the atlas emitter's constants, and the model does not carry them.
  *
  * 📄 **It is written as a document** (issue #922, cut 1f): `modelDocument` below
- * spells it as `rigc-compiled/1`, and `build` writes that text into `--out` as
- * `skeleton.model.json` beside the Spine files, after the gate, like them.
+ * spells it as `rigc-compiled/2` (`/1` until issue #1016 added `pages`), and
+ * `build` writes that text into `--out` as `skeleton.model.json` beside the
+ * Spine files, after the gate, like them.
  */
 import { createHash } from 'node:crypto';
+import { parseAtlasText } from './atlas.ts';
 import { CompileError } from './errors.ts';
 import type { BoneTransform } from './transform.ts';
 import type { RigSkinConstraintKey } from './rig.ts';
@@ -211,10 +213,12 @@ export interface ModelSequence {
  * (#931: the atlas's `rotate` transposed into the corners was exact on 2018 of
  * 3000 probes, ignored on 3000 of 3000). The trim and the original size do not
  * move under either: rigc's packer never trims or rotates (`src/atlas.ts`).
- * The draw, which does need the four — a region's page and page UVs — reads
+ * The draw, which does need the four — a region's page and page UVs — read
  * them off the atlas written beside this document, as a second input
- * (`src/core/uvs.ts`, issue #967): measured at tolerance 0 against the
- * runtime's own arrays on every corpus row with the model unchanged.
+ * (`src/core/uvs.ts`, issue #967), until issue #1016 gave the document a
+ * `pages` section spelled from the atlas text `build` writes (`pagesOfAtlas`
+ * below): the four are still not this record's, because they are the written
+ * arrangement's, and the section moves with it.
  */
 export interface ModelAtlasRect {
   width: number;
@@ -613,11 +617,17 @@ export interface CompiledModel extends CarriedFromCompileResult {
 }
 
 // ---------------------------------------------------------------------------
-// the document: `rigc-compiled/1` (issue #922, cut 1f)
+// the document: `rigc-compiled/2` (issue #922, cut 1f; `pages` and `/2`, issue #1016)
 // ---------------------------------------------------------------------------
 
-/** The document's `spec` value. */
-export const MODEL_DOCUMENT_SPEC = 'rigc-compiled/1';
+/**
+ * The document's `spec` value. `/2` since issue #1016 added the `pages`
+ * section: a `/1` reader (`readModel` of rigc 1.6) refuses a section it does
+ * not know by name, so the same spec over a new section would be refused by
+ * every reader already installed rather than read wrongly — a new spec says so
+ * before the first section is opened. `readModel` reads both.
+ */
+export const MODEL_DOCUMENT_SPEC = 'rigc-compiled/2';
 
 /** The file `build` writes the document to, in `--out` beside `skeleton.json` and `skeleton.atlas`. */
 export const MODEL_DOCUMENT_FILE = 'skeleton.model.json';
@@ -809,7 +819,7 @@ const MODEL_DOCUMENT_FIELDS: readonly string[] = [
 const MODEL_DOCUMENT_LEFT_OUT: readonly string[] = ['setupWorld'];
 
 /**
- * The compiled model as a document: `rigc-compiled/1`, `JSON.stringify(doc,
+ * The compiled model as a document: `rigc-compiled/2`, `JSON.stringify(doc,
  * null, 2)` and a newline — the text `build` writes to `skeleton.model.json`,
  * and the record rigc's own posing core reads (`readModel` in
  * `src/core/index.ts`, issue #380, step 2). Its cost in a build is measured in
@@ -820,7 +830,9 @@ const MODEL_DOCUMENT_LEFT_OUT: readonly string[] = ['setupWorld'];
  * `constraints`, `events`, `animations` — then the fields carried from `CompileResult` in
  * `CarriedFromCompileResult`'s order: `images`, `pageGrids`, `droppedStates`,
  * `absentParts`, `meshBones`, `meshes`, `physics`, `deformTransforms`,
- * `trackDerivations`, `rig`; and last `spine`, the digest of the
+ * `trackDerivations`, `rig`; then `pages`, where each region sits on its page
+ * in the atlas written beside it (`pagesOfAtlas`, issue #1016), which is why
+ * the atlas text is the third argument; and last `spine`, the digest of the
  * `skeleton.json` written beside it (`spineFileSha256`, issue #968), which is
  * why the Spine text is the second argument. Inside a model record, its interface's field
  * order (`ModelBone`, `ModelSlot`, `ModelSkin`, each attachment kind,
@@ -894,7 +906,7 @@ const MODEL_DOCUMENT_LEFT_OUT: readonly string[] = ['setupWorld'];
  * What the Spine emitter adds (`emitSkeleton`'s header, its spellings, its
  * orders and omissions) is not in the model and so not here.
  */
-export function modelDocument(model: CompiledModel, skeletonText: string): string {
+export function modelDocument(model: CompiledModel, skeletonText: string, atlasText: string): string {
   for (const key of Object.keys(model)) {
     if (!MODEL_DOCUMENT_FIELDS.includes(key) && !MODEL_DOCUMENT_LEFT_OUT.includes(key)) {
       throw new CompileError(`internal: the model document has no place for the model's field "${key}"; it writes [${MODEL_DOCUMENT_FIELDS.join(', ')}] and leaves out [${MODEL_DOCUMENT_LEFT_OUT.join(', ')}]`);
@@ -921,11 +933,97 @@ export function modelDocument(model: CompiledModel, skeletonText: string): strin
     deformTransforms: plain(model.deformTransforms, 'deformTransforms'),
     trackDerivations: plain(model.trackDerivations, 'trackDerivations'),
     rig: plain(model.rig, 'rig'),
+    pages: plain(pagesOfAtlas(atlasText), 'pages'),
     spine: { sha256: spineFileSha256(skeletonText) },
   };
   return `${JSON.stringify(doc, null, 2)}\n`;
 }
 
+// --- #1016 where each region sits on its page: begin ---
+/**
+ * One region of a page, as the document's `pages` section states it: the
+ * region's name exactly as the atlas line spells it (untrimmed — the core finds
+ * a region by that spelling, `./core/uvs.ts`), its rectangle's top-left `x`,
+ * `y` on the page (y down) and `width`, `height` in the drawing's orientation,
+ * the trim (`offsetX` from the drawing's left, `offsetY` from its bottom) and
+ * the untrimmed size, its turn in `degrees`, and its `index:` field — every
+ * number in the page's texels, exactly as `parseAtlasText` reads it.
+ */
+export interface ModelPageRegion {
+  name: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  offsetX: number;
+  offsetY: number;
+  originalWidth: number;
+  originalHeight: number;
+  degrees: number;
+  index: number;
+}
+
+/** One page: its name (a path from the directory `build` writes into, trimmed), its `size`, and its regions in file order. */
+export interface ModelPage {
+  name: string;
+  width: number;
+  height: number;
+  regions: ModelPageRegion[];
+}
+
+/** The fields of a page and of a region, in the order the document writes them — `readModel` mirrors both lists. */
+export const MODEL_PAGE_FIELDS = ['name', 'width', 'height', 'regions'] as const;
+export const MODEL_PAGE_REGION_FIELDS = ['name', 'x', 'y', 'width', 'height', 'offsetX', 'offsetY', 'originalWidth', 'originalHeight', 'degrees', 'index'] as const;
+
+/**
+ * The document's `pages` section (issue #1016): every page of `atlasText` and
+ * every region on it, in file order, with the numbers the draw reads — where
+ * each drawing sits, which `./core/uvs.ts` turns into page UVs. `atlasText`
+ * is the atlas `build` writes beside the document, the one that run's gate
+ * last read: after `--pack` the packed text, after `--copy-images` the text
+ * with the copies' page names.
+ *
+ * ⭐ **Why it is a function of the written atlas rather than a model field.**
+ * Issue #939 left the page, `x`, `y` and `rotate` out of `ModelAtlasRect`
+ * because `--pack` moves them after `compile` returns and `--copy-images`
+ * renames every page — a value the model held from `compile` would state a
+ * place the written atlas does not have. The section is spelled from the
+ * atlas text instead, so it moves exactly when that text does, and `build`
+ * spells the document from the text it writes (`cli.ts`): the document a pack
+ * writes is spelled from the packed text and gated by the packed pass, where
+ * `A18` compares it with a second compile's document spelled from a second,
+ * independent pack.
+ *
+ * 🔸 **What it leaves out.** The page's `format`, `filter`, `repeat`, `pma`
+ * and `scale:` lines: nothing that draws reads them (the rasteriser samples
+ * one way, `src/render.ts`'s header; the pose reads only the ratios the
+ * trimmed and original sizes make, #939's decision 2). Every region of every
+ * page is written, drawn or not: which regions a rig draws is the core's
+ * lookup rule (`./core/uvs.ts`, *Which region, on which page*), and a writer
+ * choosing a subset would restate it.
+ */
+export function pagesOfAtlas(atlasText: string): ModelPage[] {
+  return parseAtlasText(atlasText).pages.map((page) => ({
+    name: page.name,
+    width: page.width,
+    height: page.height,
+    regions: page.regions.map((r) => ({
+      name: r.name,
+      x: r.x,
+      y: r.y,
+      width: r.width,
+      height: r.height,
+      offsetX: r.offsetX,
+      offsetY: r.offsetY,
+      originalWidth: r.originalWidth,
+      originalHeight: r.originalHeight,
+      degrees: r.degrees,
+      index: r.index,
+    })),
+  }));
+}
+// --- #1016 where each region sits on its page: end ---
+
 // --- #968 the Spine file the document was written beside: begin ---
 /**
  * The document's last section, `spine`: `{ "sha256": "<64 lowercase hex>" }`,