spine-rigc 1.6.2 → 1.8.0

package/src/deformreport.ts

@@ -49,6 +49,9 @@ function sameKeyTime(specTime: number, loaded: number): boolean {
 export function deformReportBlock(survey: DeformSurvey, deformTransforms: CompileResult['deformTransforms'], exempt: ReadonlySet<string>): string[] {
   if (survey.timelines === 0) return [];
   const out: string[] = ['', 'deform  (what each key does to the geometry — figures with names, never a bar; issue #316)'];
+  // A survey that fell back from the reader it was meant to use says so where it is read (issue #1019): the
+  // figures are the same survey either way, and a fallback nobody can see is a second opinion nobody asked for.
+  if (survey.source.why !== null) out.push(`  ..    read and posed through ${survey.source.used}: ${survey.source.why}`);
   // The legend costs six lines and is worth them exactly once — on a report that
   // has figures in it. A bounding box or a clipping polygon deformed and nothing
   // else gets the reason it has no figures and no essay about them.

package/src/deformstructure.ts

@@ -0,0 +1,335 @@
+/**
+ * What the deform survey reads of a skeleton's STRUCTURE — as opposed to what
+ * it reads off a posed one — behind one interface, and the model document's
+ * implementation of it (issue #1019, step 4b of issue #380).
+ *
+ * ## Why there are two readers
+ *
+ * The survey (`src/deformmeasure.ts`) poses a skeleton and measures what each
+ * deform key does to it, and its posing has run through rigc's own core since
+ * issue #969. Everything else it read was still spine-core's: the animations
+ * and their deform timelines, each key's time and expanded vertex array, the
+ * runtime's curve storage, which slot a timeline names and which other slots it
+ * reaches, which skin holds the mesh, and each slider's settings — so `explain`
+ * on a rigc build parsed the pair through the runtime to learn what the model
+ * document it carries already states. This module states those reads once
+ * (`SurveyStructure`), and gives the model document's reading of them
+ * (`modelStructure`). The runtime's reading stays in `src/deformmeasure.ts`,
+ * which links spine-core; the survey's body is written once, against the
+ * interface, and the survey's record names which pair it ran through.
+ *
+ * ## What the model states, and what is derived from it — each rule measured
+ *
+ * Every read below was compared with spine-core's, value for value at
+ * tolerance 0 (`tools/survey_hashes.ts structure` over the nineteen recipes
+ * `tools/emit_hashes.ts` generates; the deform-core suite's `DM12` over the
+ * gallery's builds and 80 hand-written rigs — sliders, second skins and linked
+ * meshes in slots of their own among them). Where the model holds the
+ * runtime's value as it is, the reader passes it on; where it holds the value
+ * the runtime COMPUTED from, the computation is one rigc already runs — the
+ * core's, measured against the runtime for posing, or the emitter's own order —
+ * and not a second copy. Each derivation, with how often the stated value alone
+ * would have been the runtime's on the nineteen:
+ *
+ * - **A key's time** is the float32 of the stated time (`CoreDeformKey.time`,
+ *   which the core's reader stores) — the runtime's `frames` are a
+ *   `Float32Array`. The stated double was the runtime's on 43 of 88 keys.
+ * - **A key's vertex array** is what the runtime holds for the key, not the
+ *   run the document states: positions unweighted (each the float32 sum of the
+ *   setup coordinate and the offset), offsets weighted (each float32), the run
+ *   placed at its `offset` into the attachment's whole array and zeros (setup
+ *   positions, unweighted) around it — `heldArray` in `./core/deform.ts`. The
+ *   stated run was the runtime's array on 0 of 88.
+ * - **A Bézier segment's polyline** is the nine points the runtime samples into
+ *   its curve storage: the cubic through the key's four handles, from the key's
+ *   stated time at fraction 0 to the next key's at a far end of `0.99999999` —
+ *   `bezierPolyline` with `DEFORM_CURVE_END`, the core's deform curve. The four
+ *   handles are, of course, never the eighteen numbers (0 of 23).
+ * - **The animations' order** is the Spine file's, which is not the model's:
+ *   the emitter keys `animations` in the editor's order over the model's names
+ *   (`editorAnimationOrder` in `src/compile.ts`, the one call `emitAnimations`
+ *   is handed), and the survey iterates the file's order. The model's own order
+ *   was the file's on 14 of 19 rows. Every other order the survey reads — a
+ *   skin's, an animation's deform timelines, the sliders — the file keeps from
+ *   the model.
+ * - **A slider's duration** is the runtime's (`CoreAnimationTimelines.duration`:
+ *   the last key time of every timeline, float32), not the document's declared
+ *   one, which was the runtime's on 1 of 2.
+ * - **The slots a deform reaches besides its own** (`timelineSlots`) are the
+ *   slots of every linked mesh whose source is the deformed record and which
+ *   plays its timelines (`timelines: true`) — the rule `./core/deform.ts`'s
+ *   *Which slot a deform timeline moves* measured. The survey reads them as a
+ *   set: whether any of them draws the mesh, and their slot timelines' key
+ *   times. No corpus row has one; `DM12`'s linked rigs do, on 20 of 20.
+ *
+ * ⛔ Nothing here defaults a value the document does not state: a record the
+ * timeline names that the document does not hold, or an order the editor's
+ * comparator cannot settle, is a `CoreInputError` naming it — and the survey's
+ * seam then falls back to spine-core naming why, as the posing does.
+ *
+ * ## Purity
+ *
+ * Nothing from the Spine runtime package: what the runtime reader needs to
+ * carry beside these handles (the parsed objects themselves) is kept by that
+ * reader, in `src/deformmeasure.ts`.
+ */
+import { CompileError } from './errors.ts';
+import { editorAnimationOrder } from './compile.ts';
+import { bezierPolyline } from './core/animation.ts';
+import { DEFORM_CURVE_END, heldArray, type CoreAttachmentTimeline, type CoreDeformKey } from './core/deform.ts';
+import type { DialBoneField } from './core/hooks.ts';
+import { CoreInputError, type CompiledDocument, type CoreAnimation, type CoreAttachment } from './core/index.ts';
+
+/** The record a mesh is in the model document — the identity a deform timeline keys and the core poses by. */
+export interface SurveyRecord {
+  skin: string;
+  slot: string;
+  placeholder: string;
+}
+
+/** A skin, as the survey wears it. One handle per skin: the survey keys its caches on the handle. */
+export interface SurveySkin {
+  readonly name: string;
+}
+
+/** A mesh a deform timeline moves, as far as the survey reads it. */
+export interface SurveyMesh {
+  /** The attachment's name — the record's stated `name`, else its placeholder. */
+  readonly name: string;
+  readonly triangles: ArrayLike<number>;
+  /** Two numbers per vertex. */
+  readonly worldVerticesLength: number;
+  /** Whether its vertices are bound to bones (`MeshAttachment.bones !== null`). */
+  readonly weighted: boolean;
+  /** The other slots the deform reaches (`Attachment.timelineSlots`), read as a set. */
+  readonly timelineSlots: readonly number[];
+  /** The model record it is, or `null` when no skin holds it — the core then refuses to pose it, by name. */
+  readonly record: SurveyRecord | null;
+}
+
+/** How the runtime gets from one key's geometry to the next. */
+export type SurveyCurve = { kind: 'linear' } | { kind: 'stepped' } | { kind: 'bezier'; points: ArrayLike<number> };
+
+/** One deform timeline of one animation. */
+export interface SurveyDeformTimeline {
+  /** The slot it is filed under, by index into `SurveyStructure.slotName`. */
+  readonly slotIndex: number;
+  /** The mesh it moves, or `null` when the attachment has a vertex array and no triangles (a bounding box, a clipping polygon, a path). */
+  readonly mesh: SurveyMesh | null;
+  /** Each key's time, as the runtime stores it. */
+  readonly frames: ArrayLike<number>;
+  /** Key `frame`'s vertex array, as the runtime holds it. */
+  vertices(frame: number): ArrayLike<number> | undefined;
+  /** The curve from key `frame` to key `frame + 1`. */
+  curve(frame: number): SurveyCurve;
+  /** The skin that holds the mesh, by name and handle (`null` when none does), and the placeholder the timeline names. */
+  placement(): { skin: string; holder: SurveySkin | null; placeholder: string };
+}
+
+/** One animation, as far as the survey reads it. */
+export interface SurveyAnimation {
+  readonly name: string;
+  /** Its deform timelines, in the runtime's order. */
+  readonly deforms: readonly SurveyDeformTimeline[];
+  /** Every key time of every timeline filed under one of `slots` — the times a slot's visibility can change at. */
+  slotKeyTimes(slots: ReadonlySet<number>): number[];
+}
+
+/**
+ * One slider constraint, as far as the survey reads it.
+ *
+ * ⚠️ `stated`, `reader`, `from`, `to` and `scale` are the dial's mapping and are
+ * read only for a slider with a `bone`: a bone-less one's dial is its time. The
+ * two readers part there and nothing reads the difference — spine-core sets no
+ * property on a bone-less slider and leaves its `scale` at 0, where the model
+ * document states the parser's 1 (measured, `tools/survey_hashes.ts structure`).
+ */
+export interface SurveySlider {
+  readonly name: string;
+  /** Its mix at setup. */
+  readonly mix: number;
+  /** The animation it applies, by name. */
+  readonly animation: string;
+  /** That animation's duration, as the runtime computes it. */
+  readonly duration: number;
+  /** Its driving bone, or `null` on the bone-less form. */
+  readonly bone: string | null;
+  readonly local: boolean;
+  /** The bone field its property reads — `null` on a reader this file does not know. */
+  readonly stated: DialBoneField | null;
+  /** What that reader is called, for a report that has to name an unknown one. */
+  readonly reader: string;
+  /** `from` — the property value at which the animation's time is `to`. */
+  readonly from: number;
+  /** `to`. */
+  readonly to: number;
+  readonly scale: number;
+  readonly loop: boolean;
+}
+
+/** Everything the survey reads of a skeleton's structure. */
+export interface SurveyStructure {
+  /** Every skin, one handle each, in the skeleton's order — not read by the survey, which wears the skin a timeline names; the instruments walk it. */
+  readonly skins: readonly SurveySkin[];
+  /** In the runtime's order. */
+  readonly animations: readonly SurveyAnimation[];
+  /** In the skeleton's constraint order. */
+  readonly sliders: readonly SurveySlider[];
+  /** A slot's name, or `#<index>` for an index that is not a slot. */
+  slotName(index: number): string;
+  /** How many skins carry this name — the core wears a skin by its name, so two of one name cannot be posed. */
+  skinsNamed(name: string): number;
+}
+
+/** The bone field each rig-spec property reads. */
+const PROPERTY_FIELD: Record<string, DialBoneField> = { rotate: 'rotation', x: 'x', y: 'y', scaleX: 'scaleX', scaleY: 'scaleY', shearY: 'shearY' };
+
+/** The model document's reading of the survey's structure (the header). */
+export function modelStructure(doc: CompiledDocument): SurveyStructure {
+  const slotIndex = new Map(doc.slots.map((s, i) => [s.name, i] as const));
+  const skinHandles = new Map<string, SurveySkin>();
+  const skinOf = (name: string): SurveySkin | null => {
+    if (!doc.skins.some((k) => k.name === name)) return null;
+    let handle = skinHandles.get(name);
+    if (handle === undefined) {
+      handle = { name };
+      skinHandles.set(name, handle);
+    }
+    return handle;
+  };
+  const recordAt = (skin: string, slot: string, placeholder: string): CoreAttachment | undefined => doc.skins.find((k) => k.name === skin)?.attachments[slot]?.[placeholder];
+  /** The slots of every linked mesh that plays this record's timelines (the header's last rule). */
+  const linkedSlots = (record: SurveyRecord): number[] => {
+    const out: number[] = [];
+    for (const skin of doc.skins) {
+      for (const [slot, table] of Object.entries(skin.attachments)) {
+        for (const entry of Object.values(table)) {
+          const g = entry.geometry;
+          if (g?.kind !== 'linkedmesh' || entry.timelines !== true) continue;
+          if (g.skin !== record.skin || g.slot !== record.slot || g.source !== record.placeholder) continue;
+          const at = slotIndex.get(slot);
+          if (at !== undefined && !out.includes(at)) out.push(at);
+        }
+      }
+    }
+    return out;
+  };
+  const meshes = new Map<string, SurveyMesh>();
+  const meshOf = (t: CoreAttachmentTimeline): SurveyMesh | null => {
+    const key = `${t.skin}/${t.slot}/${t.attachment}`;
+    const already = meshes.get(key);
+    if (already !== undefined) return already;
+    const entry = recordAt(t.skin, t.slot, t.attachment);
+    if (entry === undefined) throw new CoreInputError(`the deform timeline ${key} names no record of the model document`);
+    const g = entry.geometry;
+    if (g?.kind !== 'mesh') return null;
+    const record = { skin: t.skin, slot: t.slot, placeholder: t.attachment };
+    const mesh: SurveyMesh = {
+      name: entry.name ?? t.attachment,
+      triangles: g.triangles,
+      worldVerticesLength: g.vertices.weighted ? 2 * g.vertices.bindings.length : g.vertices.xy.length,
+      weighted: g.vertices.weighted,
+      timelineSlots: linkedSlots(record),
+      record,
+    };
+    meshes.set(key, mesh);
+    return mesh;
+  };
+  const deformOf = (t: CoreAttachmentTimeline, keys: readonly CoreDeformKey[]): SurveyDeformTimeline => {
+    const at = slotIndex.get(t.slot);
+    if (at === undefined) throw new CoreInputError(`the deform timeline ${t.skin}/${t.slot}/${t.attachment} names slot "${t.slot}", which is not a slot of the model document`);
+    const mesh = meshOf(t);
+    const entry = recordAt(t.skin, t.slot, t.attachment);
+    const g = entry?.geometry;
+    const vertices = g !== undefined && g.kind !== 'region' && g.kind !== 'linkedmesh' ? g.vertices : null;
+    const held = new Map<number, number[]>();
+    return {
+      slotIndex: at,
+      mesh,
+      frames: keys.map((k) => k.time),
+      vertices: (frame) => {
+        const key = keys[frame];
+        if (key === undefined || vertices === null) return undefined;
+        let array = held.get(frame);
+        if (array === undefined) {
+          array = heldArray(vertices, key);
+          held.set(frame, array);
+        }
+        return array;
+      },
+      curve: (frame) => {
+        const a = keys[frame];
+        const b = keys[frame + 1];
+        if (a === undefined || b === undefined) throw new CoreInputError(`the deform timeline ${t.skin}/${t.slot}/${t.attachment} has no segment after key ${frame}`);
+        if (a.curve === 'linear') return { kind: 'linear' };
+        if (a.curve === 'stepped') return { kind: 'stepped' };
+        const c = a.curve;
+        return { kind: 'bezier', points: bezierPolyline(a.stated, 0, c[0], c[1], c[2], c[3], b.stated, DEFORM_CURVE_END) };
+      },
+      placement: () => ({ skin: t.skin, holder: skinOf(t.skin), placeholder: t.attachment }),
+    };
+  };
+  const animationOf = (a: CoreAnimation): SurveyAnimation => {
+    const deforms: SurveyDeformTimeline[] = [];
+    for (const t of a.timelines.attachments) if (t.deform !== null) deforms.push(deformOf(t, t.deform));
+    return {
+      name: a.name,
+      deforms,
+      slotKeyTimes: (slots) => {
+        const times: number[] = [];
+        for (const target of a.timelines.slots) {
+          const at = slotIndex.get(target.name);
+          if (at === undefined || !slots.has(at)) continue;
+          for (const tl of target.timelines) for (const k of tl.keys) times.push(k.time);
+        }
+        for (const t of a.timelines.attachments) {
+          const at = slotIndex.get(t.slot);
+          if (at === undefined || !slots.has(at)) continue;
+          for (const k of [...(t.deform ?? []), ...(t.sequence ?? [])]) times.push(k.time);
+        }
+        return times;
+      },
+    };
+  };
+  let order: string[];
+  try {
+    order = editorAnimationOrder(doc.animations.map((a) => a.name));
+  } catch (err) {
+    if (!(err instanceof CompileError)) throw err;
+    throw new CoreInputError(`the animations' order in the Spine file is not settled by the model's names — ${err.message}`);
+  }
+  const animations = order.map((name) => {
+    const a = doc.animations.find((x) => x.name === name);
+    if (a === undefined) throw new CoreInputError(`the editor's order named animation "${name}", which is not in the model document`);
+    return animationOf(a);
+  });
+  const sliders: SurveySlider[] = [];
+  for (const c of doc.constraints) {
+    const r = c.record;
+    if (c.kind !== 'slider' || r?.kind !== 'slider') continue;
+    sliders.push({
+      name: r.name,
+      mix: r.mix,
+      animation: r.animation,
+      duration: r.timelines.duration,
+      bone: r.bone,
+      local: r.local,
+      stated: PROPERTY_FIELD[r.property] ?? null,
+      reader: r.property,
+      from: r.from,
+      to: r.to,
+      scale: r.scale,
+      loop: r.loop,
+    });
+  }
+  return {
+    skins: doc.skins.flatMap((k) => {
+      const handle = skinOf(k.name);
+      return handle === null || doc.skins.find((x) => x.name === k.name) !== k ? [] : [handle];
+    }),
+    animations,
+    sliders,
+    slotName: (index) => doc.slots[index]?.name ?? `#${index}`,
+    skinsNamed: (name) => doc.skins.filter((k) => k.name === name).length,
+  };
+}

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,
@@ -884,8 +896,11 @@ const MODEL_DOCUMENT_LEFT_OUT: readonly string[] = ['setupWorld'];
  *
  *   - `setupWorld` — computed from `bones` by `computeWorldTransforms`
  *     (`src/transform.ts`), so it states nothing `bones` does not, and a core
- *     is to compute it rather than read it; and it is the one field holding a
- *     `-0` (a root bone's `b` is `-sin 0`), which JSON cannot spell.
+ *     is to compute it rather than read it; and it is the one field that can
+ *     hold a `-0` (a bone's `c` is `sin 0 · scaleX`, which is `-0` at a
+ *     `scaleX` of −1), which JSON cannot spell. (A root's `b` was `-sin 0`
+ *     until issue #1021; under the runtime's arithmetic it is `cos 90°` at
+ *     pi = 3.1415927, −2.3e-8.)
  *   - `images[].absPath` — where the part was on this machine's disk, for the
  *     size assertions.
  *   - `droppedStates[].why` — the sentence names the `--atlas-in` file by its
@@ -894,7 +909,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 +936,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>" }`,